Implement RFC "A core story for images"

.changeset/gold-rocks-cry.md

@@ -0,0 +1,7 @@
+---
+'astro': minor
+'@astrojs/mdx': minor
+'@astrojs/markdown-remark': minor
+---
+
+Add a new `experimental.assets` settings to enable support for an enhanced experience with assets

packages/astro/client-base.d.ts

@@ -1,5 +1,28 @@
 /// <reference path="./import-meta.d.ts" />
 
+declare module 'astro:assets' {
+	// Exporting things one by one is a bit cumbersome, not sure if there's a better way - erika, 2023-02-03
+	type AstroAssets = {
+		getImage: typeof import('./dist/assets/index.js').getImage;
+		Image: typeof import('./components/Image.astro').default;
+	};
+
+	type WithRequired<T, K extends keyof T> = T & { [P in K]-?: T[P] };
+	type Simplify<T> = { [KeyType in keyof T]: T[KeyType] };
+	type ImgAttributes = WithRequired<
+		Omit<import('./types').HTMLAttributes<'img'>, 'src' | 'width' | 'height'>,
+		'alt'
+	>;
+
+	export type LocalImageProps = Simplify<
+		import('./dist/assets/types.js').LocalImageProps<ImgAttributes>
+	>;
+	export type RemoteImageProps = Simplify<
+		import('./dist/assets/types.js').RemoteImageProps<ImgAttributes>
+	>;
+	export const { getImage, Image }: AstroAssets;
+}
+
 type MD = import('./dist/@types/astro').MarkdownInstance<Record<string, any>>;
 interface ExportedMarkdownModuleEntities {
 	frontmatter: MD['frontmatter'];

packages/astro/client-image.d.ts

@@ -0,0 +1,48 @@
+/// <reference path="./client-base.d.ts" />
+
+type InputFormat = 'avif' | 'gif' | 'heic' | 'heif' | 'jpeg' | 'jpg' | 'png' | 'tiff' | 'webp';
+
+interface ImageMetadata {
+	src: string;
+	width: number;
+	height: number;
+	format: InputFormat;
+}
+
+// images
+declare module '*.avif' {
+	const metadata: ImageMetadata;
+	export default metadata;
+}
+declare module '*.gif' {
+	const metadata: ImageMetadata;
+	export default metadata;
+}
+declare module '*.heic' {
+	const metadata: ImageMetadata;
+	export default metadata;
+}
+declare module '*.heif' {
+	const metadata: ImageMetadata;
+	export default metadata;
+}
+declare module '*.jpeg' {
+	const metadata: ImageMetadata;
+	export default metadata;
+}
+declare module '*.jpg' {
+	const metadata: ImageMetadata;
+	export default metadata;
+}
+declare module '*.png' {
+	const metadata: ImageMetadata;
+	export default metadata;
+}
+declare module '*.tiff' {
+	const metadata: ImageMetadata;
+	export default metadata;
+}
+declare module '*.webp' {
+	const metadata: ImageMetadata;
+	export default metadata;
+}

packages/astro/components/Image.astro

@@ -0,0 +1,28 @@
+---
+import { getImage, type LocalImageProps, type RemoteImageProps } from 'astro:assets';
+import { AstroError, AstroErrorData } from '../dist/core/errors/index.js';
+
+// The TypeScript diagnostic for JSX props uses the last member of the union to suggest props, so it would be better for
+// LocalImageProps to be last. Unfortunately, when we do this the error messages that remote images get are complete nonsense
+// Not 100% sure how to fix this, seems to be a TypeScript issue. Unfortunate.
+type Props = LocalImageProps | RemoteImageProps;
+
+const props = Astro.props;
+
+if (props.alt === undefined || props.alt === null) {
+	throw new AstroError(AstroErrorData.ImageMissingAlt);
+}
+
+// As a convenience, allow width and height to be string with a number in them, to match HTML's native `img`.
+if (typeof props.width === 'string') {
+	props.width = parseInt(props.width);
+}
+
+if (typeof props.height === 'string') {
+	props.height = parseInt(props.height);
+}
+
+const image = await getImage(props);
+---
+
+<img src={image.src} {...image.attributes} />

packages/astro/package.json

@@ -32,6 +32,7 @@
     "./types": "./types.d.ts",
     "./client": "./client.d.ts",
     "./client-base": "./client-base.d.ts",
+    "./client-image": "./client-image.d.ts",
     "./import-meta": "./import-meta.d.ts",
     "./astro-jsx": "./astro-jsx.d.ts",
     "./tsconfigs/*.json": "./tsconfigs/*",
@@ -47,6 +48,10 @@
     "./client/*": "./dist/runtime/client/*",
     "./components": "./components/index.ts",
     "./components/*": "./components/*",
+    "./assets": "./dist/assets/index.js",
+    "./assets/image-endpoint": "./dist/assets/image-endpoint.js",
+    "./assets/services/sharp": "./dist/assets/services/sharp.js",
+    "./assets/services/squoosh": "./dist/assets/services/squoosh.js",
     "./content/internal": "./dist/content/internal.js",
     "./debug": "./components/Debug.astro",
     "./internal/*": "./dist/runtime/server/*",
@@ -77,6 +82,7 @@
     "env.d.ts",
     "client.d.ts",
     "client-base.d.ts",
+    "client-image.d.ts",
     "import-meta.d.ts",
     "astro-jsx.d.ts",
     "types.d.ts",
@@ -86,10 +92,10 @@
   ],
   "scripts": {
     "prebuild": "astro-scripts prebuild --to-string \"src/runtime/server/astro-island.ts\" \"src/runtime/client/{idle,load,media,only,visible}.ts\"",
-    "build": "pnpm run prebuild && astro-scripts build \"src/**/*.ts\" && tsc",
+    "build": "pnpm run prebuild && astro-scripts build \"src/**/*.ts\" && tsc && pnpm run postbuild",
     "build:ci": "pnpm run prebuild && astro-scripts build \"src/**/*.ts\"",
-    "dev": "astro-scripts dev --prebuild \"src/runtime/server/astro-island.ts\" --prebuild \"src/runtime/client/{idle,load,media,only,visible}.ts\" \"src/**/*.ts\"",
-    "postbuild": "astro-scripts copy \"src/**/*.astro\"",
+    "dev": "astro-scripts dev --copy-wasm --prebuild \"src/runtime/server/astro-island.ts\" --prebuild \"src/runtime/client/{idle,load,media,only,visible}.ts\" \"src/**/*.ts\"",
+    "postbuild": "astro-scripts copy \"src/**/*.astro\" && astro-scripts copy \"src/**/*.wasm\"",
     "test:unit": "mocha --exit --timeout 30000 ./test/units/**/*.test.js",
     "test:unit:match": "mocha --exit --timeout 30000 ./test/units/**/*.test.js -g",
     "test": "pnpm run test:unit && mocha --exit --timeout 20000 --ignore **/lit-element.test.js && mocha --timeout 20000 **/lit-element.test.js",
@@ -128,6 +134,7 @@
     "github-slugger": "^2.0.0",
     "gray-matter": "^4.0.3",
     "html-escaper": "^3.0.3",
+    "image-size": "^1.0.2",
     "kleur": "^4.1.4",
     "magic-string": "^0.27.0",
     "mime": "^3.0.0",
@@ -173,6 +180,7 @@
     "@types/rimraf": "^3.0.2",
     "@types/send": "^0.17.1",
     "@types/server-destroy": "^1.0.1",
+    "@types/sharp": "^0.31.1",
     "@types/unist": "^2.0.6",
     "astro-scripts": "workspace:*",
     "chai": "^4.3.6",
@@ -187,10 +195,19 @@
     "remark-code-titles": "^0.1.2",
     "rollup": "^3.9.0",
     "sass": "^1.52.2",
+    "sharp": "^0.31.3",
     "srcset-parse": "^1.1.0",
     "undici": "^5.20.0",
     "unified": "^10.1.2"
   },
+  "peerDependencies": {
+    "sharp": "^0.31.3"
+  },
+  "peerDependenciesMeta": {
+    "sharp": {
+      "optional": true
+    }
+  },
   "engines": {
     "node": ">=16.12.0",
     "npm": ">=6.14.0"

packages/astro/src/@types/astro.ts

@@ -18,6 +18,7 @@ import type { PageBuildData } from '../core/build/types';
 import type { AstroConfigSchema } from '../core/config';
 import type { AstroTimer } from '../core/config/timer';
 import type { AstroCookies } from '../core/cookies';
+import type { LogOptions } from '../core/logger/core';
 import type { AstroComponentFactory, AstroComponentInstance } from '../runtime/server';
 import { SUPPORTED_MARKDOWN_FILE_EXTENSIONS } from './../core/constants.js';
 export type {
@@ -28,6 +29,8 @@ export type {
 	RemarkPlugins,
 	ShikiConfig,
 } from '@astrojs/markdown-remark';
+export type { ExternalImageService, LocalImageService } from '../assets/services/service';
+export type { ImageTransform } from '../assets/types';
 export type { SSRManifest } from '../core/app/types';
 export type { AstroCookies } from '../core/cookies';
 
@@ -85,6 +88,7 @@ export interface CLIFlags {
 	port?: number;
 	config?: string;
 	drafts?: boolean;
+	experimentalAssets?: boolean;
 }
 
 export interface BuildConfig {
@@ -696,6 +700,16 @@ export interface AstroUserConfig {
 
 	server?: ServerConfig | ((options: { command: 'dev' | 'preview' }) => ServerConfig);
 
+	/**
+	 * @docs
+	 * @kind heading
+	 * @name Image options
+	 */
+	image?: {
+		// eslint-disable-next-line @typescript-eslint/ban-types
+		service: 'astro/assets/services/sharp' | 'astro/assets/services/squoosh' | (string & {});
+	};
+
 	/**
 	 * @docs
 	 * @kind heading
@@ -918,7 +932,27 @@ export interface AstroUserConfig {
 	 * Astro offers experimental flags to give users early access to new features.
 	 * These flags are not guaranteed to be stable.
 	 */
-	experimental?: object;
+	experimental?: {
+		/**
+		 * @docs
+		 * @name experimental.assets
+		 * @type {boolean}
+		 * @default `false`
+		 * @version 2.1.0
+		 * @description
+		 * Enable experimental support for enhanced images support and ability to optimize and resize images directly in Astro. With this enabled, a new `astro:assets` module will be exposed
+		 *
+		 * To enable this feature, set `experimental.assets` to `true` in your Astro config:
+		 *
+		 * ```js
+		 * {
+		 * 	experimental: {
+		 *		assets: true,
+		 * 	},
+		 * }
+		 */
+		assets?: boolean;
+	};
 
 	// Legacy options to be removed
 
@@ -1432,6 +1466,11 @@ export interface AstroIntegration {
 	};
 }
 
+export interface AstroPluginOptions {
+	settings: AstroSettings;
+	logging: LogOptions;
+}
+
 export type RouteType = 'page' | 'endpoint';
 
 export interface RoutePart {

packages/astro/src/assets/README.md

@@ -0,0 +1,3 @@
+# vite-plugin-assets
+
+This Vite plugin powers the assets story of Astro, allowing users to import helpers from `astro:assets` to generate optimized assets

packages/astro/src/assets/consts.ts

@@ -0,0 +1,14 @@
+export const VIRTUAL_MODULE_ID = 'astro:assets';
+export const VIRTUAL_SERVICE_ID = 'virtual:image-service';
+export const VALID_INPUT_FORMATS = [
+	'heic',
+	'heif',
+	'avif',
+	'jpeg',
+	'jpg',
+	'png',
+	'tiff',
+	'webp',
+	'gif',
+] as const;
+export const VALID_OUTPUT_FORMATS = ['avif', 'png', 'webp', 'jpeg', 'jpg'] as const;

packages/astro/src/assets/image-endpoint.ts

@@ -0,0 +1,66 @@
+import mime from 'mime';
+import type { APIRoute } from '../@types/astro.js';
+import { isRemotePath } from '../core/path.js';
+import { getConfiguredImageService } from './internal.js';
+import { isLocalService } from './services/service.js';
+import { etag } from './utils/etag.js';
+
+async function loadRemoteImage(src: URL) {
+	try {
+		const res = await fetch(src);
+
+		if (!res.ok) {
+			return undefined;
+		}
+
+		return Buffer.from(await res.arrayBuffer());
+	} catch (err: unknown) {
+		return undefined;
+	}
+}
+
+/**
+ * Endpoint used in SSR to serve optimized images
+ */
+export const get: APIRoute = async ({ request }) => {
+	try {
+		const imageService = await getConfiguredImageService();
+
+		if (!isLocalService(imageService)) {
+			throw new Error('Configured image service is not a local service');
+		}
+
+		const url = new URL(request.url);
+		const transform = await imageService.parseURL(url);
+
+		if (!transform || !transform.src) {
+			throw new Error('Incorrect transform returned by `parseURL`');
+		}
+
+		let inputBuffer: Buffer | undefined = undefined;
+
+		// TODO: handle config subpaths?
+		const sourceUrl = isRemotePath(transform.src)
+			? new URL(transform.src)
+			: new URL(transform.src, url.origin);
+		inputBuffer = await loadRemoteImage(sourceUrl);
+
+		if (!inputBuffer) {
+			return new Response('Not Found', { status: 404 });
+		}
+
+		const { data, format } = await imageService.transform(inputBuffer, transform);
+
+		return new Response(data, {
+			status: 200,
+			headers: {
+				'Content-Type': mime.getType(format) || '',
+				'Cache-Control': 'public, max-age=31536000',
+				ETag: etag(data.toString()),
+				Date: new Date().toUTCString(),
+			},
+		});
+	} catch (err: unknown) {
+		return new Response(`Server Error: ${err}`, { status: 500 });
+	}
+};

packages/astro/src/assets/index.ts

@@ -0,0 +1,4 @@
+export { getConfiguredImageService, getImage } from './internal.js';
+export { baseService } from './services/service.js';
+export { type LocalImageProps, type RemoteImageProps } from './types.js';
+export { imageMetadata } from './utils/metadata.js';