withastro · ematipico · Apr 14, 2025 · Dec 18, 2024 · Jan 17, 2025 · Jan 21, 2025
diff --git a/.changeset/happy-spies-punch.md b/.changeset/happy-spies-punch.md
@@ -0,0 +1,41 @@
+---
+'astro': minor
+---
+
+Adds a new, experimental Fonts API to provide first-party support for fonts in Astro.
+
+This experimental feature allows you to use fonts from both your file system and several built-in supported providers (e.g. Google, Fontsource, Bunny) through a unified API. Keep your site performant thanks to sensible defaults and automatic optimizations including fallback font generation.
+
+To enable this feature, configure an `experimental.fonts` object with one or more fonts:
+
+```js title="astro.config.mjs"
+import { defineConfig, fontProviders } from "astro/config"
+
+export default defineConfig({
+    experimental: {
+        fonts: [{
+            provider: fontProviders.google(),
+      `      name: "Roboto",
+            cssVariable: "--font-roboto",
+        }]
+    }
+})
+```
+
+Then, add a `<Font />` component and site-wide styling in your `<head>`:
+
+```astro title="src/components/Head.astro"
+---
+import { Font } from 'astro:assets'
+---
+<Font cssVariable='--font-roboto' preload />
+<style>
+body {
+    font-family: var(--font-roboto);
+}
+</style>
+```
+
+Visit [the experimental Fonts documentation](https://docs.astro.build/en/reference/experimental-flags/fonts/) for the full API, how to get started, and even how to build your own custom `AstroFontProvider` if we don't yet support your preferred font service.
+
+For a complete overview, and to give feedback on this experimental API, see the [Fonts RFC](https://github.com/withastro/roadmap/pull/1039) and help shape its future.
diff --git a/package.json b/package.json
@@ -83,6 +83,9 @@
       "workerd",
       "@biomejs/biome",
       "sharp"
-    ]
+    ],
+    "patchedDependencies": {
+      "[email protected]": "patches/[email protected]"
+    }
   }
 }
diff --git a/packages/astro/client.d.ts b/packages/astro/client.d.ts
@@ -2,6 +2,7 @@
 /// <reference path="./types/content.d.ts" />
 /// <reference path="./types/actions.d.ts" />
 /// <reference path="./types/env.d.ts" />
+/// <reference path="./types/fonts.d.ts" />
 
 interface ImportMetaEnv {
 	/**
@@ -54,6 +55,7 @@ declare module 'astro:assets' {
 		inferRemoteSize: typeof import('./dist/assets/utils/index.js').inferRemoteSize;
 		Image: typeof import('./components/Image.astro').default;
 		Picture: typeof import('./components/Picture.astro').default;
+		Font: typeof import('./components/Font.astro').default;
 	};
 
 	type ImgAttributes = import('./dist/type-utils.js').WithRequired<
@@ -73,6 +75,7 @@ declare module 'astro:assets' {
 		imageConfig,
 		Image,
 		Picture,
+		Font,
 		inferRemoteSize,
 	}: AstroAssets;
 }

diff --git a/packages/astro/components/Font.astro b/packages/astro/components/Font.astro
@@ -0,0 +1,32 @@
+---
+import { AstroError, AstroErrorData } from '../dist/core/errors/index.js';
+
+// TODO: remove dynamic import when fonts are stabilized
+const { fontsData } = await import('virtual:astro:assets/fonts/internal').catch(() => {
+	throw new AstroError(AstroErrorData.ExperimentalFontsNotEnabled);
+});
+
+interface Props {
+	/** The `cssVariable` registered in your Astro configuration. */
+	cssVariable: import('astro:assets').FontFamily;
+	/** Whether it should output [preload links](https://web.dev/learn/performance/optimize-web-fonts#preload) or not. */
+	preload?: boolean;
+}
+
+const { cssVariable, preload = false } = Astro.props;
+const data = fontsData.get(cssVariable);
+if (!data) {
+	throw new AstroError({
+		...AstroErrorData.FontFamilyNotFound,
+		message: AstroErrorData.FontFamilyNotFound.message(cssVariable),
+	});
+}
+---
+
+<style set:html={data.css}></style>
+{
+	preload &&
+		data.preloadData.map(({ url, type }) => (
+			<link rel="preload" href={url} as="font" type={`font/${type}`} crossorigin />
+		))
+}
diff --git a/packages/astro/package.json b/packages/astro/package.json
@@ -65,6 +65,7 @@
     "./assets/endpoint/*": "./dist/assets/endpoint/*.js",
     "./assets/services/sharp": "./dist/assets/services/sharp.js",
     "./assets/services/noop": "./dist/assets/services/noop.js",
+    "./assets/fonts/providers/*": "./dist/assets/fonts/providers/entrypoints/*.js",
     "./loaders": "./dist/content/loaders/index.js",
     "./content/runtime": "./dist/content/runtime.js",
     "./content/runtime-assets": "./dist/content/runtime-assets.js",
@@ -113,7 +114,7 @@
     "test:e2e:match": "playwright test -g",
     "test:e2e:chrome": "playwright test",
     "test:e2e:firefox": "playwright test --config playwright.firefox.config.js",
-    "test:types": "tsc --project tsconfig.tests.json",
+    "test:types": "tsc --project test/types/tsconfig.json",
     "test:unit": "astro-scripts test \"test/units/**/*.test.js\" --teardown ./test/units/teardown.js",
     "test:integration": "astro-scripts test \"test/*.test.js\""
   },
@@ -122,6 +123,8 @@
     "@astrojs/internal-helpers": "workspace:*",
     "@astrojs/markdown-remark": "workspace:*",
     "@astrojs/telemetry": "workspace:*",
+    "@capsizecss/metrics": "^3.5.0",
+    "@capsizecss/unpack": "^2.4.0",
     "@oslojs/encoding": "^1.1.0",
     "@rollup/pluginutils": "^5.1.4",
     "acorn": "^8.14.1",
@@ -164,6 +167,7 @@
     "tinyglobby": "^0.2.12",
     "tsconfck": "^3.1.5",
     "ultrahtml": "^1.6.0",
+    "unifont": "^0.1.7",
     "unist-util-visit": "^5.0.0",
     "unstorage": "^1.15.0",
     "vfile": "^6.0.3",

diff --git a/packages/astro/src/actions/plugins.ts b/packages/astro/src/actions/plugins.ts
@@ -4,7 +4,7 @@ import { addRollupInput } from '../core/build/add-rollup-input.js';
 import type { BuildInternals } from '../core/build/internal.js';
 import type { StaticBuildOptions } from '../core/build/types.js';
 import { shouldAppendForwardSlash } from '../core/build/util.js';
-import { getOutputDirectory } from '../prerender/utils.js';
+import { getServerOutputDirectory } from '../prerender/utils.js';
 import type { AstroSettings } from '../types/astro.js';
 import {
 	ASTRO_ACTIONS_INTERNAL_MODULE_ID,
@@ -73,7 +73,7 @@ export function vitePluginActionsBuild(
 					chunk.type !== 'asset' &&
 					chunk.facadeModuleId === RESOLVED_ASTRO_ACTIONS_INTERNAL_MODULE_ID
 				) {
-					const outputDirectory = getOutputDirectory(opts.settings);
+					const outputDirectory = getServerOutputDirectory(opts.settings);
 					internals.astroActionsEntryPoint = new URL(chunkName, outputDirectory);
 				}
 			}

diff --git a/packages/astro/src/assets/fonts/README.md b/packages/astro/src/assets/fonts/README.md
@@ -0,0 +1,11 @@
+# fonts
+
+The vite plugin orchestrates the fonts logic:
+
+- Retrieves data from the config
+- Initializes font providers
+- Fetches fonts data
+- In dev, serves a middleware that dynamically loads and caches fonts data
+- In build, download fonts data (from cache if possible)
+
+The `<Font />` component is the only aspect not managed in the vite plugin, since it's exported from `astro:assets`.
diff --git a/packages/astro/src/assets/fonts/config.ts b/packages/astro/src/assets/fonts/config.ts
@@ -0,0 +1,174 @@
+import { z } from 'zod';
+import { LOCAL_PROVIDER_NAME } from './constants.js';
+
+const weightSchema = z.union([z.string(), z.number()]);
+const styleSchema = z.enum(['normal', 'italic', 'oblique']);
+
+const familyPropertiesSchema = z.object({
+	/**
+	 * A [font weight](https://developer.mozilla.org/en-US/docs/Web/CSS/font-weight). If the associated font is a [variable font](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_fonts/Variable_fonts_guide), you can specify a range of weights:
+	 *
+	 * ```js
+	 * weight: "100 900"
+	 * ```
+	 */
+	weight: weightSchema,
+	/**
+	 * A [font style](https://developer.mozilla.org/en-US/docs/Web/CSS/font-style).
+	 */
+	style: styleSchema,
+	/**
+	 * @default `"swap"`
+	 * 
+	 * A [font display](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-display).
+	 */
+	display: z.enum(['auto', 'block', 'swap', 'fallback', 'optional']).optional(),
+	/**
+	 * A [unicode range](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/unicode-range).
+	 */
+	unicodeRange: z.array(z.string()).nonempty().optional(),
+	/**
+	 * A [font stretch](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-stretch).
+	 */
+	stretch: z.string().optional(),
+	/**
+	 * Font [feature settings](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-feature-settings).
+	 */
+	featureSettings: z.string().optional(),
+	/**
+	 * Font [variation settings](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-variation-settings).
+	 */
+	variationSettings: z.string().optional(),
+});
+
+const fallbacksSchema = z.object({
+	/**
+	 * @default `["sans-serif"]`
+	 *
+	 * An array of fonts to use when your chosen font is unavailable, or loading. Fallback fonts will be chosen in the order listed. The first available font will be used:
+	 *
+	 * ```js
+	 * fallbacks: ["CustomFont", "serif"]
+	 * ```
+	 *
+	 * To disable fallback fonts completely, configure an empty array:
+	 *
+	 * ```js
+	 * fallbacks: []
+	 * ```
+	 *
+
+	 * If the last font in the `fallbacks` array is a [generic family name](https://developer.mozilla.org/en-US/docs/Web/CSS/font-family#generic-name), an [optimized fallback](https://developer.chrome.com/blog/font-fallbacks) using font metrics will be generated. To disable this optimization, set `optimizedFallbacks` to false.
+	 */
+	fallbacks: z.array(z.string()).nonempty().optional(),
+	/**
+	 * @default `true`
+	 *
+	 * Whether or not to enable optimized fallback generation. You may disable this default optimization to have full control over `fallbacks`.
+	 */
+	optimizedFallbacks: z.boolean().optional(),
+});
+
+export const requiredFamilyAttributesSchema = z.object({
+	/**
+	 * The font family name, as identified by your font provider.
+	 */
+	name: z.string(),
+	/**
+	 * A valid [ident](https://developer.mozilla.org/en-US/docs/Web/CSS/ident) in the form of a CSS variable (i.e. starting with `--`).
+	 */
+	cssVariable: z.string(),
+});
+
+const entrypointSchema = z.union([z.string(), z.instanceof(URL)]);
+
+export const fontProviderSchema = z
+	.object({
+		/**
+		 * URL, path relative to the root or package import.
+		 */
+		entrypoint: entrypointSchema,
+		/**
+		 * Optional serializable object passed to the unifont provider.
+		 */
+		config: z.record(z.string(), z.any()).optional(),
+	})
+	.strict();
+
+export const localFontFamilySchema = requiredFamilyAttributesSchema
+	.merge(fallbacksSchema)
+	.merge(
+		z.object({
+			/**
+			 * The source of your font files. Set to `"local"` to use local font files.
+			 */
+			provider: z.literal(LOCAL_PROVIDER_NAME),
+			/**
+			 * Each variant represents a [`@font-face` declaration](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/).
+			 */
+			variants: z
+				.array(
+					familyPropertiesSchema.merge(
+						z
+							.object({
+								/**
+								 * Font [sources](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/src). It can be a path relative to the root, a package import or a URL. URLs are particularly useful if you inject local fonts through an integration.
+								 */
+								src: z
+									.array(
+										z.union([
+											entrypointSchema,
+											z.object({ url: entrypointSchema, tech: z.string().optional() }).strict(),
+										]),
+									)
+									.nonempty(),
+								// TODO: find a way to support subsets (through fontkit?)
+							})
+							.strict(),
+					),
+				)
+				.nonempty(),
+		}),
+	)
+	.strict();
+
+export const remoteFontFamilySchema = requiredFamilyAttributesSchema
+	.merge(
+		familyPropertiesSchema.omit({
+			weight: true,
+			style: true,
+		}),
+	)
+	.merge(fallbacksSchema)
+	.merge(
+		z.object({
+			/**
+			 * The source of your font files. You can use a built-in provider or write your own custom provider.
+			 */
+			provider: fontProviderSchema,
+			/**
+			 * @default `[400]`
+			 *
+			 * An array of [font weights](https://developer.mozilla.org/en-US/docs/Web/CSS/font-weight). If the associated font is a [variable font](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_fonts/Variable_fonts_guide), you can specify a range of weights:
+			 *
+			 * ```js
+			 * weight: "100 900"
+			 * ```
+			 */
+			weights: z.array(weightSchema).nonempty().optional(),
+			/**
+			 * @default `["normal", "italic"]`
+			 *
+			 * An array of [font styles](https://developer.mozilla.org/en-US/docs/Web/CSS/font-style).
+			 */
+			styles: z.array(styleSchema).nonempty().optional(),
+			// TODO: better link
+			/**
+			 * @default `["cyrillic-ext", "cyrillic", "greek-ext", "greek", "vietnamese", "latin-ext", "latin"]`
+			 *
+			 * An array of [font subsets](https://fonts.google.com/knowledge/glossary/subsetting):
+			 */
+			subsets: z.array(z.string()).nonempty().optional(),
+		}),
+	)
+	.strict();
diff --git a/packages/astro/src/assets/fonts/constants.ts b/packages/astro/src/assets/fonts/constants.ts
@@ -0,0 +1,40 @@
+import type { ResolvedRemoteFontFamily } from './types.js';
+
+export const LOCAL_PROVIDER_NAME = 'local';
+
+export const DEFAULTS = {
+	weights: ['400'],
+	styles: ['normal', 'italic'],
+	subsets: ['cyrillic-ext', 'cyrillic', 'greek-ext', 'greek', 'vietnamese', 'latin-ext', 'latin'],
+	// Technically serif is the browser default but most websites these days use sans-serif
+	fallbacks: ['sans-serif'],
+	optimizedFallbacks: true,
+} satisfies Partial<ResolvedRemoteFontFamily>;
+
+export const VIRTUAL_MODULE_ID = 'virtual:astro:assets/fonts/internal';
+export const RESOLVED_VIRTUAL_MODULE_ID = '\0' + VIRTUAL_MODULE_ID;
+
+// Requires a trailing slash
+export const URL_PREFIX = '/_astro/fonts/';
+export const CACHE_DIR = './fonts/';
+
+export const FONT_TYPES = ['woff2', 'woff', 'otf', 'ttf', 'eot'] as const;
+
+// Source: https://github.com/nuxt/fonts/blob/3a3eb6dfecc472242b3011b25f3fcbae237d0acc/src/module.ts#L55-L75
+export const DEFAULT_FALLBACKS: Record<string, Array<string>> = {
+	serif: ['Times New Roman'],
+	'sans-serif': ['Arial'],
+	monospace: ['Courier New'],
+	cursive: [],
+	fantasy: [],
+	'system-ui': ['BlinkMacSystemFont', 'Segoe UI', 'Roboto', 'Helvetica Neue', 'Arial'],
+	'ui-serif': ['Times New Roman'],
+	'ui-sans-serif': ['Arial'],
+	'ui-monospace': ['Courier New'],
+	'ui-rounded': [],
+	emoji: [],
+	math: [],
+	fangsong: [],
+};
+
+export const FONTS_TYPES_FILE = 'fonts.d.ts';