feat: add experimental @sveltejs/image package

.changeset/little-cameras-guess.md

@@ -0,0 +1,5 @@
+---
+'@sveltejs/image': minor
+---
+
+feat: add experimental `@sveltejs/image` package

packages/adapter-vercel/index.d.ts

@@ -1,7 +1,16 @@
 import { Adapter } from '@sveltejs/kit';
 import './ambient.js';
 
-export default function plugin(config?: Config): Adapter;
+export default function plugin(
+	config?: Config & {
+		/**
+		 * Enable or disable Vercel's image optimization
+		 * https://vercel.com/docs/concepts/image-optimization
+		 * @default false
+		 */
+		images?: boolean | { domains?: string[] };
+	}
+): Adapter;
 
 export interface ServerlessConfig {
 	/**

packages/adapter-vercel/index.js

@@ -6,7 +6,6 @@ import esbuild from 'esbuild';
 import { get_pathname } from './utils.js';
 
 const VALID_RUNTIMES = ['edge', 'nodejs16.x', 'nodejs18.x'];
-
 const DEFAULT_FUNCTION_NAME = 'fn';
 
 const get_default_runtime = () => {
@@ -55,7 +54,7 @@ const plugin = function (defaults = {}) {
 				functions: `${dir}/functions`
 			};
 
-			const static_config = static_vercel_config(builder);
+			const static_config = await static_vercel_config(builder, defaults);
 
 			builder.log.minor('Generating serverless function...');
 
@@ -368,8 +367,11 @@ function write(file, data) {
 }
 
 // This function is duplicated in adapter-static
-/** @param {import('@sveltejs/kit').Builder} builder */
-function static_vercel_config(builder) {
+/**
+ * @param {import('@sveltejs/kit').Builder} builder
+ * @param {Parameters<import('.').default>[0]} config
+ */
+async function static_vercel_config(builder, config) {
 	/** @type {any[]} */
 	const prerendered_redirects = [];
 
@@ -407,8 +409,22 @@ function static_vercel_config(builder) {
 		overrides[page.file] = { path: overrides_path };
 	}
 
+	/** @type {Record<string, any> | undefined} */
+	let images = undefined;
+	if (config.images) {
+		images = {
+			// TODO this is duplicated in @sveltejs/image -> figure out a good way to keep them in sync / make them configurable
+			sizes: [64, 96, 128, 256, 384, 640, 750, 828, 1080, 1200, 1920, 2048, 3840],
+			domains: Array.isArray(config.images?.domains) ? config.images.domains : [],
+			// TODO should we expose the following and some other optional options through the adapter?
+			formats: ['image/avif', 'image/webp'],
+			minimumCacheTTL: 300
+		};
+	}
+
 	return {
 		version: 3,
+		images,
 		routes: [
 			...prerendered_redirects,
 			{

packages/image/CHANGELOG.md

@@ -0,0 +1 @@
+# @sveltejs/image

packages/image/README.md

@@ -0,0 +1,140 @@
+# `@sveltejs/image`
+
+**WARNING**: This package is experimental. It uses pre-1.0 versioning and may introduce breaking changes with every minor version release.
+
+This package aims to bring a plug and play image component to SvelteKit that is opinionated enough so you don't have to worry about the details, yet flexible enough for more advanced use cases or tweaks. It serves a smaller file format like `avif` or `webp` and uses the `srcset` and `sizes` attributes of the `img` tag to provide resized images suitable for various device sizes, which for example results in smaller images downloaded for mobile.
+
+## Setup
+
+Install:
+
+```bash
+npm install --save @sveltejs/image
+```
+
+Adjust `vite.config.js`:
+
+```diff
++import { images } from '@sveltejs/image/vite';
+import { sveltekit } from '@sveltejs/kit/vite';
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+	plugins: [
++		images({
+			runtime: {
+				providers: {
+					default: '@sveltejs/image/providers/<choose one>'
+				}
+			}
+		}),
+		sveltekit()
+	]
+});
+```
+
+> `<choose one>` refers to choosing one of the ready-to-use providers. We plan to add more providers over time. You can create your own by creating a JavaScript file with a `export function getURL({ src, width, height }): string` function inside and then pointing to that file in the config.
+
+In case of Vercel, also adjust your `svelte.config.js`:
+
+```diff
+import adapter from '@sveltejs/adapter-vercel';
+
+/** @type {import('@sveltejs/kit').Config} */
+const config = {
+	kit: {
+-		adapter: adapter()
++		adapter: adapter({ images: true })
+	}
+};
+
+export default config;
+```
+
+## Usage
+
+### Dynamic runtime optimization using one of the providers, i.e. an image CDN:
+
+```svelte
+<script>
+	import Image from '@sveltejs/image';
+</script>
+
+<Image src="/path/to/your/image.jpg" width={1200} height={1800} alt="An alt text" />
+```
+
+`width` and `height` should be the intrinsic width/height of the referenced image - i.e. the dimensions of the image before styling. `alt` should describe the image. All are required. The `src` is transformed by calling `getURL` of the `default` provider provided in the `vite.config.js`.
+
+If you want to optimize an image from an external URL, add its domain to the `domains` config of the plugin. Note that you may also add a corresponding config to the image cdn (how exactly depends on the provider).
+
+### Static build time optimization:
+
+Static build time optimization uses `vite-imagetools`, which comes as an optional peer dependency, so you first need to install it:
+
+```bash
+npm install --save-dev vite-imagetools
+```
+
+> If you have existing image imports like `import SomeImage from './some/image.jpg';` they will be treated differently now. If you want to get back the previous behavior of this import returning a URL string, add `?url` to the end of the import.
+
+Use in your `.svelte` components:
+
+```svelte
+<script>
+	import { Image } from '@sveltejs/image';
+</script>
+
+<Image src="./path/to/your/image.jpg" alt="An alt text" />
+```
+
+This optimizes the image at build time using `vite-imagetools`. `width` and `height` are optional as they can be inferred from the source image.
+
+Note that the `src` prop must start with a `.`. `@sveltejs/image` includes a preprocessor that will convert it to the following:
+
+```svelte
+<script>
+	import { Image } from '@sveltejs/image';
+	import YourImage from './path/to/your/image.jpg';
+</script>
+
+<Image src={YourImage} alt="An alt text" />
+```
+
+You can also write it yourself like this, if you want to.
+
+Note that the generated code is a `picture` tag (not an `img` tag as in the case of dynamic providers) wrapping one `source` tag per image type.
+
+### Choosing static vs dynamic
+
+Using the static provider generates the images at build time, so build time may take longer the more images you transform.
+
+Using an image CDN provides more flexibility with regards to sizes and you can pass image sources not known at build time, but it comes with potentially a bit of setup overhead (configuring the image CDN) and possibly usage cost.
+
+You can mix and match both solutions in one project.
+
+### `Image` component props
+
+There are a few things you can customize:
+
+- `priority`: set this to `true` for the most important/largest image on the page so it loads faster
+- `sizes`: If your image is less than full width on one or more screen sizes, add this info here. When using dynamic providers the widths can be adjusted accordingly to produce a more optimal `srcset`. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/sizes) for more info on the attribute
+- `style`: to style the image
+- `class`: to style the image. Be aware that you need to pass classes that are global (i.e. wrapped in `:global()` when coming from a `<style>` tag)
+- `loading`: loading behavior of the image. Defaults to `lazy` which means it's loaded only when about to enter the viewport. Set to `eager` to load right away (the default when setting `priority`)
+- `provider`: you can pass more than the `default` provider in `vite.config.js`. If you then want to use a different provider than the `default` one, pass it here
+- `providerOptions`: provider-specific image CDN options. For example `quality` for Vercel
+
+## Best practices
+
+- Always provide a good `alt` text
+- Your original images should have a good quality/resolution. Images are easier to size down than up
+- Choose one image per page which is the most important/largest one and give it `priority` so it loads faster. This gives you better web vitals scores (largest contentful paint in particular)
+- Give the image a container or a styling so that it is constrained and does not jump around. `width` and `height` help the browser reserving space while the image is still loading
+
+## Roadmap
+
+This is an experimental MVP for getting initial feedback on the implementation/usability of an image component usable with SvelteKit (can also be used with Vite only). Once the API is stable, we'll want to create a more seamless integration with SvelteKit, i.e. less setup required.
+
+## Acknowledgements
+
+We'd like to thank the authors of the Next/Nuxt/Astro/`unpic` image components for inspiring this work. We'd also like to thank the authors of `vite-imagetools` and `svelte-preprocess-import-assets` which are used in `@sveltejs/image`.

packages/image/package.json

@@ -0,0 +1,75 @@
+{
+	"name": "@sveltejs/image",
+	"version": "0.1.0",
+	"description": "Image optimization for your Svelte apps",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/sveltejs/kit",
+		"directory": "packages/image"
+	},
+	"license": "MIT",
+	"homepage": "https://kit.svelte.dev",
+	"type": "module",
+	"dependencies": {
+		"esm-env": "^1.0.0",
+		"svelte-preprocess-import-assets": "^1.0.0"
+	},
+	"devDependencies": {
+		"@types/node": "^16.18.6",
+		"svelte": "^3.56.0",
+		"typescript": "^4.9.4",
+		"vite": "^4.3.0",
+		"vite-imagetools": "^5.0.2"
+	},
+	"peerDependencies": {
+		"vite-imagetools": "^5.0.2"
+	},
+	"peerDependenciesMeta": {
+		"vite-imagetools": {
+			"optional": true
+		}
+	},
+	"files": [
+		"src",
+		"!src/**/*.spec.js",
+		"types"
+	],
+	"scripts": {
+		"lint": "prettier --check . --config ../../.prettierrc --ignore-path .gitignore",
+		"check": "tsc",
+		"format": "prettier --write . --config ../../.prettierrc --ignore-path .gitignore"
+	},
+	"exports": {
+		"./package.json": "./package.json",
+		".": {
+			"types": "./types/index.d.ts",
+			"import": "./src/index.js"
+		},
+		"./vite": {
+			"import": "./src/vite-plugin.js"
+		},
+		"./providers/cloudflare": {
+			"import": "./src/providers/cloudflare.js"
+		},
+		"./providers/netlify": {
+			"import": "./src/providers/netlify.js"
+		},
+		"./providers/vercel": {
+			"import": "./src/providers/vercel.js"
+		},
+		"./providers/none": {
+			"import": "./src/providers/none.js"
+		}
+	},
+	"types": "types/index.d.ts",
+	"typesVersions": {
+		"*": {
+			"index": [
+				"types/index.d.ts"
+			],
+			"vite": [
+				"types/vite.d.ts"
+			]
+		}
+	}
+}