Fonts

Astro 5 added a built-in font subsystem. It downloads and subsets webfonts from common providers, emits CSS to load them, and produces optimized <link rel="preload"> tags. Source: packages/astro/src/assets/fonts/.

Purpose

• Self-host webfonts at build time (no runtime CDN call).
• Subset them so users only download glyphs the project actually uses.
• Generate the boilerplate CSS, fallback metrics, and preload hints automatically.

Key files

File	Purpose
packages/astro/src/assets/fonts/config.ts	The experimental.fonts config schema.
packages/astro/src/assets/fonts/runtime.ts	The astro:fonts runtime — Font.preload, Font.useFont.
packages/astro/src/assets/fonts/sync.ts	Sync logic: downloads + subsets fonts during astro sync/astro build.
packages/astro/src/assets/fonts/types.ts, definitions.ts	Shared types.
packages/astro/src/assets/fonts/constants.ts	Provider URLs, default unicode ranges.
packages/astro/src/assets/fonts/utils.ts	Family parsing, weight handling, fallback CSS.
packages/astro/src/assets/fonts/core/	Provider-agnostic core.
packages/astro/src/assets/fonts/infra/	Concrete I/O (fetcher, file system).
packages/astro/src/assets/fonts/providers/	Adapters for bunny, google, adobe, fontsource.
packages/astro/src/assets/fonts/vite-plugin-fonts.ts	Vite plugin emitting astro:fonts and the per-page CSS.

Configuration

import { defineConfig, fontProviders } from 'astro/config';

export default defineConfig({
  experimental: {
    fonts: [
      {
        provider: fontProviders.google(),
        name: 'Inter',
        cssVariable: '--font-inter',
        weights: [400, 600, 'variable'],
        subsets: ['latin'],
        fallbacks: ['system-ui', 'sans-serif'],
      },
    ],
  },
});

Runtime API

---
import { Font } from 'astro:assets';
---
<Font cssVariable="--font-inter" preload />

<style>
body {
  font-family: var(--font-inter);
}
</style>

feat(fonts): experimental_getFontFileURL() (commit f6f8e80) added a programmatic helper for callers that need to resolve the URL of a specific font file (useful for OG image generation).

How it works

graph TD
    A[astro.config experimental.fonts] --> B[fonts/sync runs at build/dev]
    B --> C[Provider fetches woff2/ttf]
    C --> D[Subset to declared unicode ranges]
    D --> E[(public/_astro/fonts/...)]
    F[Page imports astro:fonts] --> G[Generated CSS @font-face]
    G --> H[<link rel=preload> for declared faces]

The dev server caches subsetted files between runs. CI rebuilds them; the font cache is opaque to user code.

Related pages

• features / image optimization — same assets/ subsystem.
• systems / Vite plugins