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...');
 
@@ -373,8 +372,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 = [];
 
@@ -412,8 +414,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,108 @@
+# `@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&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 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 { vitePluginSvelteImage } from '@sveltejs/image/vite';
+import { sveltekit } from '@sveltejs/kit/vite';
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+	plugins: [
++		vitePluginSvelteImage({ providers: { default: '@sveltejs/image/providers/<choose one>' } }),
+		sveltekit()
+	]
+});
+```
+
+> `<choose one>` refers to chosing one of the ready-to-use providers. We plan to add more providers over time. You can create your own by creating a JavaScript with a `export function getURL({ src, width, height }): string` function inside.
+
+In case of Vercel, adjust `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
+
+### When 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 natural width/height of the referenced image. `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`.
+
+### Static build time optimization:
+
+```svelte
+<script>
+	import Image from '@sveltejs/image';
+    import YourImage from '/path/to/your/image.jpg?generate';
+</script>
+
+<Image src={YourImage} alt="An alt text" />
+```
+
+This optimizes the image at build time using `vite-imagetools`. `width` and `height` are optional as they can be infered from the source image.
+
+### Pros/Cons of the solutions
+
+Using the static provider generates the images at build time, so that 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 setup overhead (configuring the image CDN) and possibly usage cost.
+
+You can mix and match both solutions in one project.
+
+### `Image` component options
+
+There are a few things you can customize:
+
+- `priority`: give this to 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.

packages/image/package.json

@@ -0,0 +1,84 @@
+{
+	"name": "@sveltejs/image",
+	"version": "0.1.0",
+	"description": "Image optimization for your Svelte apps",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/sveltejs/image",
+		"directory": "packages/image"
+	},
+	"license": "MIT",
+	"homepage": "https://kit.svelte.dev",
+	"type": "module",
+	"dependencies": {
+		"esm-env": "^1.0.0",
+		"vite-imagetools": "^4.0.19"
+	},
+	"devDependencies": {
+		"@playwright/test": "1.30.0",
+		"@types/node": "^16.18.6",
+		"@sveltejs/kit": "workspace:^",
+		"rollup": "^3.7.0",
+		"svelte": "^3.56.0",
+		"svelte-preprocess": "^5.0.0",
+		"typescript": "^4.9.4",
+		"uvu": "^0.5.6",
+		"vite": "^4.3.0"
+	},
+	"peerDependencies": {
+		"svelte": "^3.54.0",
+		"vite": "^4.0.0"
+	},
+	"files": [
+		"src",
+		"!src/**/*.spec.js",
+		"types"
+	],
+	"scripts": {
+		"lint": "prettier --check . --config ../../.prettierrc --ignore-path .gitignore",
+		"check": "tsc",
+		"check:all": "tsc && pnpm -r --filter=\"./**\" check",
+		"format": "prettier --write . --config ../../.prettierrc --ignore-path .gitignore",
+		"test": "pnpm test:unit && pnpm test:integration",
+		"test:integration": "pnpm -r --workspace-concurrency 1 --filter=\"./test/**\" test",
+		"test:cross-platform:dev": "pnpm -r --workspace-concurrency 1 --filter=\"./test/**\" test:cross-platform:dev",
+		"test:cross-platform:build": "pnpm test:unit && pnpm -r --workspace-concurrency 1 --filter=\"./test/**\" test:cross-platform:build",
+		"test:unit": "uvu src \"(spec\\.js|test[\\\\/]index\\.js)\""
+	},
+	"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"
+			]
+		}
+	},
+	"engines": {
+		"node": "^16.14 || >=18"
+	}
+}