feat: image preprocessor

.changeset/eighty-timers-exist.md

@@ -0,0 +1,5 @@
+---
+'@sveltejs/static-img': patch
+---
+
+feat: add experimental `@sveltejs/static-img` package

documentation/docs/30-advanced/60-images.md

@@ -0,0 +1,149 @@
+---
+title: Images
+---
+
+## Caching and inlining
+
+[Vite will automatically process imported assets](https://vitejs.dev/guide/assets.html) for improved performance. This includes assets referenced via the CSS `url()` function. Hashes will be added to the filenames so that they can be cached and assets smaller than `assetsInlineLimit` will be inlined. Vite's asset handling is most often used for images, but is also useful for video, audio, etc.
+
+```svelte
+<script>
+	import logo from '$lib/assets/logo.png';
+</script>
+
+<img alt="The project logo" src={logo} />
+```
+
+To reference assets directly in the markup, you can use a preprocessor such as [`@sveltejs/enhanced-img`](#sveltejs-enhanced-img), which is discussed below and additionally transforms your images.
+
+## Transforming background
+
+You may wish to transform your images to output compressed image formats such as `.webp` or `.avif` or responsive images with different sizes for different devices. There are two approaches to transforming images, which will be discussed below. With either approach, the transformed images may be served via a CDN. CDNs reduce latency by distributing copies of static assets globally.
+
+The `@sveltejs/enhanced-img` package handles images that are located in your project and can be referred to with a static string. It can automatically set the intrinsic `width` and `height` for you, which can't be done with a dynamic approach. It is generated with a hash in the filename so that it can be maximally cached. It generates images at build time, so building may take longer the more images you transform.
+
+Alternatively, using a CDN to do the image transformation 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 in configuring the image CDN and possible usage costs. Some images served from a CDN may require a request to the server to verify that the image has not changed. This will block the browser from using its cache until a [304 response](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/304) is received from the server. Building HTML to target CDNs may result in slightly smaller and simpler HTML because they can serve the appropriate file format for an `img` tag based on the `User-Agent` header whereas build-time optimizations must produce `picture` tags. Finally some CDNs may generate images lazily, which could have a negative performance impact for sites with low traffic and frequently changing images. We do not currently offer any tools for dynamic image transforms, but we may offer such utilities in the future.
+
+You can mix and match both solutions in one project. For example, you may display images on your homepage with `@sveltejs/enhanced-img` and display user-submitted content with a dynamic approach.
+
+## @sveltejs/enhanced-img
+
+> **WARNING**: The `@sveltejs/enhanced-img` package is experimental. It uses pre-1.0 versioning and may introduce breaking changes with every minor version release.
+
+`@sveltejs/enhanced-img` offers plug and play image processing that serves smaller file formats like `avif` or `webp`, automatically sets the intrinsic width and height of the image to avoid layout shift, creates images of multiple sizes for various devices, and strips EXIF data for privacy. It will work in any Vite-based project including, but not limited to, SvelteKit projects.
+
+### Setup
+
+Install:
+
+```bash
+npm install --save-dev @sveltejs/enhanced-img
+```
+
+Adjust `vite.config.js`:
+
+```diff
+import { sveltekit } from '@sveltejs/kit/vite';
++import { enhancedImages } from '@sveltejs/enhanced-img';
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+	plugins: [
++		enhancedImages(),
+		sveltekit()
+	]
+});
+```
+
+### Basic usage
+
+Use in your `.svelte` components by using `enhanced:img` rather than `img` and referencing the image file with a [Vite asset import](https://vitejs.dev/guide/assets.html#static-asset-handling) path:
+
+```svelte
+<enhanced:img src="./path/to/your/image.jpg" alt="An alt text" />
+```
+
+At build time, your `img` tag will be replaced with a `picture` providing multiple image types and sizes. It's only possible to downscale images without losing quality, which means that you should provide the highest resolution image that you need — smaller versions will be generated for the various device types that may request an image. If you're not using the [`sizes` attribute](#sveltejs-enhanced-img-srcset-and-sizes) you should provide your image at 2x resolution for HiDPI displays (a.k.a. retina displays).
+
+Since the `enhanced:img` tag will be replaced with a `picture` tag, you should refer to it as such within your `style` tag. Generally we recommend styling the `img` child of the `picture` tag rather than the `picture` tag itself to make it easier to switch between various solutions such as a dynamic CDN-based solution should you ever need to do so.
+
+### Dynamically choosing an image
+
+You can also manually import an image and then pass it to an `enhanced:img` tag. This is useful when you have a collection of static images and would like to dynamically choose one. You can create a collection of images manually [as we do on the homepage showcase](https://github.com/sveltejs/kit/blob/master/sites/kit.svelte.dev/src/routes/home/Showcase.svelte). In this case you will need to update both the `import` statement and `img` tag as shown below to indicate you'd like process them.
+
+```svelte
+<script>
+	import { MyImage } from './path/to/your/image.jpg?enhancedImg';
+</script>
+
+<enhanced:img src={MyImage} alt="An alt text" />
+```
+
+You can also use [Vite's `import.meta.glob`](https://vitejs.dev/guide/features.html#glob-import). Note that you will have to specify `enhancedImg` via a [custom query](https://vitejs.dev/guide/features.html#custom-queries):
+
+```js
+const pictures = import.meta.glob(
+	'/path/to/assets/*.{avif,gif,heif,jpeg,jpg,png,tiff,webp}',
+	{
+		query: {
+			enhancedImg: true
+		}
+	}
+);
+```
+
+### Intrinsic Dimensions
+
+`width` and `height` are optional as they can be inferred from the source image and will be automatically added when the `<enhanced:img>` tag is preprocessed. These attributes are added because the browser can reserve the correct amount of space when it knows image dimensions which prevents layout shift. If you'd like to use a different `width` and `height` you can style the image with CSS. Because the preprocessor adds a `width` and `height` for you, if you'd like one of the dimensions to be automatically calculated then you will need to specify that:
+
+```svelte
+<style>
+	.hero-image img {
+		width: var(--size);
+		height: auto;
+	}
+</style>
+```
+
+### `srcset` and `sizes`
+
+You may be wondering how to create something that looks like:
+
+```html
+<img
+  srcset="image-small.png 160w, image-medium.png 400w, image-large.png 600w"
+  sizes="(min-width: 60rem) 80vw, (min-width: 40rem) 90vw, 100vw"
+  />
+```
+
+In this example, it would be tedious to have to manually create three versions of your image. Instead, you can specify the widths as a query parameter and we'll generate the `srcset` for you.
+
+```svelte
+<enhanced:img
+  src="./image.png?w=160,400,600"
+  sizes="(min-width: 60rem) 80vw, (min-width: 40rem) 90vw, 100vw"
+  />
+```
+
+If `sizes` is specified directly as a string on the `img` tag then the plugin will automatically generate different width images:
+- If `sizes` is not provided, then a HiDPI/Retina image and a standard resolution image will be generated. The image you provide should be 2x the resolution you wish to display so that the browser can display that image on devices with a high [device pixel ratio](https://developer.mozilla.org/en-US/docs/Web/API/Window/devicePixelRatio).
+- If `sizes` is provided, then a large `srcset` is generated. If some of the `sizes` have been specified as a percentage of the viewport width using the `vw` unit then the `srcset` will filter out any values which are too small to ever be requested by the browser.
+
+> Text expressions like `sizes={computedSizes}` or `sizes={['(min-width: 60rem) 80vw', '(min-width: 40rem) 90vw', '100vw'].join(', ')}` will not be evaluated for the purposes of automatic image generation and will be skipped.
+
+### Per-image transforms
+
+By default, enhanced images will be transformed to more efficient formats. However, you may wish to apply other transforms such as a blur, quality, flatten, or rotate operation. You can run per-image transforms by appending a query string:
+
+```svelte
+<enhanced:img src="./path/to/your/image.jpg?blur=15" alt="An alt text" />
+```
+
+[See the imagetools repo for the full list of directives](https://github.com/JonasKruckenberg/imagetools/blob/main/docs/directives.md).
+
+## Best practices
+
+- Always provide a good `alt` text
+- 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).
+- Your original images should have a good quality/resolution. Image processing can size images down to save bandwidth when serving smaller screens, but cannot invent pixels to size images up any better than browsers can.
+- Give the image a container or 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. `@sveltejs/enhanced-img` will add a `width` and `height` for you.

packages/enhanced-img/README.md

@@ -0,0 +1,17 @@
+# `@sveltejs/enhanced-img`
+
+A Vite plugin which runs a Svelte preprocessor to locate images and then transform them at build-time.
+
+**WARNING**: This package is experimental. It uses pre-1.0 versioning and may introduce breaking changes with every minor version release.
+
+## Docs
+
+[Docs](https://kit.svelte.dev/docs/assets)
+
+## Changelog
+
+[The Changelog for this package is available on GitHub](https://github.com/sveltejs/kit/blob/master/packages/enhanced-img/CHANGELOG.md).
+
+## Acknowledgements
+
+We'd like to thank the author of `svelte-preprocess-import-assets`, which this code is partially based off of. We'd also like to thank the authors of `vite-imagetools` which is used in `@sveltejs/enhanced-img`.

packages/enhanced-img/package.json

@@ -0,0 +1,41 @@
+{
+	"name": "@sveltejs/enhanced-img",
+	"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",
+	"scripts": {
+		"lint": "prettier --check . --config ../../.prettierrc --ignore-path .gitignore",
+		"check": "tsc",
+		"format": "prettier --write . --config ../../.prettierrc --ignore-path .gitignore",
+		"test": "vitest"
+	},
+	"files": [
+		"src",
+		"types"
+	],
+	"exports": {
+		"types": "./types/index.d.ts",
+		"import": "./src/index.js"
+	},
+	"types": "types/index.d.ts",
+	"dependencies": {
+		"magic-string": "^0.30.0",
+		"svelte-parse-markup": "^0.1.1",
+		"vite-imagetools": "^6.0.0"
+	},
+	"devDependencies": {
+		"@types/estree": "^1.0.2",
+		"@types/node": "^16.18.6",
+		"svelte": "^4.0.5",
+		"typescript": "^4.9.4",
+		"vite": "^4.4.2",
+		"vitest": "^0.34.0"
+	}
+}

packages/enhanced-img/src/index.js

@@ -0,0 +1,128 @@
+import path from 'node:path';
+import { image } from './preprocessor.js';
+
+/**
+ * @returns {Promise<import('vite').Plugin[]>}
+ */
+export async function enhancedImages() {
+	const imagetools_plugin = await imagetools();
+	if (!imagetools_plugin) {
+		console.error(
+			'@sveltejs/enhanced-img: vite-imagetools is not installed. Skipping build-time optimizations'
+		);
+	}
+	return imagetools_plugin && !process.versions.webcontainer
+		? [image_plugin(), imagetools_plugin]
+		: [];
+}
+
+/**
+ * Creates the Svelte image plugin which provides the preprocessor.
+ * @returns {import('vite').Plugin}
+ */
+function image_plugin() {
+	const preprocessor = image();
+
+	return {
+		name: 'vite-plugin-enhanced-img',
+		api: {
+			sveltePreprocess: preprocessor
+		}
+	};
+}
+
+/** @type {Record<string,string>} */
+const fallback = {
+	'.avif': 'png',
+	'.gif': 'gif',
+	'.heif': 'jpg',
+	'.jpeg': 'jpg',
+	'.jpg': 'jpg',
+	'.png': 'png',
+	'.tiff': 'jpg',
+	'.webp': 'png'
+};
+
+async function imagetools() {
+	/** @type {typeof import('vite-imagetools').imagetools} */
+	let imagetools;
+	try {
+		({ imagetools } = await import('vite-imagetools'));
+	} catch (err) {
+		return;
+	}
+
+	/** @type {Partial<import('vite-imagetools').VitePluginOptions>} */
+	const imagetools_opts = {
+		defaultDirectives: async ({ pathname, searchParams: qs }, metadata) => {
+			const { imgSizes, imgWidth } = Object.fromEntries(qs);
+			if (!qs.has('enhancedImg')) return new URLSearchParams();
+
+			const { widths, kind } = getWidths(imgWidth ?? (await metadata()).width, imgSizes);
+			return new URLSearchParams({
+				as: 'picture',
+				format: `avif;webp;${fallback[path.extname(pathname)] ?? 'png'}`,
+				w: widths.join(';'),
+				...(kind === 'x' && !qs.has('w') && { basePixels: widths[0].toString() })
+			});
+		}
+	};
+
+	// TODO: should we make formats or sizes configurable besides just letting people override defaultDirectives?
+	// TODO: generate img rather than picture if only a single format is provided
+	//     by resolving the directives for the URL in the preprocessor
+	return imagetools(imagetools_opts);
+}
+
+/**
+ * Derived from
+ * https://github.com/vercel/next.js/blob/3f25a2e747fc27da6c2166e45d54fc95e96d7895/packages/next/src/shared/lib/get-img-props.ts#L132
+ * under the MIT license. Copyright (c) Vercel, Inc.
+ * @param {number | string | undefined} width
+ * @param {string | null | undefined} sizes
+ * @param {number[]} [deviceSizes]
+ * @param {number[]} [imageSizes]
+ * @returns {{ widths: number[]; kind: 'w' | 'x' }}
+ */
+function getWidths(width, sizes, deviceSizes, imageSizes) {
+	width = typeof width === 'string' ? parseInt(width) : width;
+	const chosen_device_sizes = deviceSizes || [640, 750, 828, 1080, 1200, 1920, 2048, 3840];
+	const all_sizes = (imageSizes || [16, 32, 48, 64, 96, 128, 256, 384]).concat(chosen_device_sizes);
+
+	if (sizes) {
+		// Find all the "vw" percent sizes used in the sizes prop
+		const viewport_width_re = /(^|\s)(1?\d?\d)vw/g;
+		const percent_sizes = [];
+		for (let match; (match = viewport_width_re.exec(sizes)); match) {
+			percent_sizes.push(parseInt(match[2]));
+		}
+		if (percent_sizes.length) {
+			const smallest_ratio = Math.min(...percent_sizes) * 0.01;
+			return {
+				widths: all_sizes.filter((s) => s >= chosen_device_sizes[0] * smallest_ratio),
+				kind: 'w'
+			};
+		}
+		return { widths: all_sizes, kind: 'w' };
+	}
+	if (typeof width !== 'number') {
+		return { widths: chosen_device_sizes, kind: 'w' };
+	}
+
+	// Don't need more than 2x resolution.
+	// Most OLED screens that say they are 3x resolution,
+	// are actually 3x in the green color, but only 1.5x in the red and
+	// blue colors. Showing a 3x resolution image in the app vs a 2x
+	// resolution image will be visually the same, though the 3x image
+	// takes significantly more data. Even true 3x resolution screens are
+	// wasteful as the human eye cannot see that level of detail without
+	// something like a magnifying glass.
+	// https://blog.twitter.com/engineering/en_us/topics/infrastructure/2019/capping-image-fidelity-on-ultra-high-resolution-devices.html
+
+	// We diverge from the Next.js logic here
+	// You can't really scale up an image, so you can't 2x the width
+	// Instead the user should provide the high-res image and we'll downscale
+	// Also, Vercel builds specific image sizes and picks the closest from those,
+	// but we can just build the ones we want exactly.
+	return { widths: [Math.round(width / 2), width], kind: 'x' };
+}