fonts

Fonts (Astro Fonts API)

Configure performant web fonts with automatic optimization, preloading, and privacy-focused delivery from your own site.

Critical Workflow Order

Font setup MUST follow this exact sequence. The <Font /> component and CSS variables are only available after the dev server processes the config.

Step 1: Configure astro.config.mjs (FIRST)

Add fonts to the top-level fonts array (Astro 6+ promoted from experimental.fonts):

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

export default defineConfig({
  fonts: [{
    provider: fontProviders.google(),
    name: "Crimson Pro",
    cssVariable: "--font-display",
    weights: [400, 600, 700],
    styles: ["normal"]
  }]
});

Note: Astro ≤ 5.x required experimental: { fonts: [...] }. Astro 6.x graduated the API; wrap in experimental only if you're on an older Astro.

Step 2: Restart the dev/preview server

The dev server reads astro.config.mjs once at startup. Without a restart, import { Font } from 'astro:assets' will fail and the CSS variables won't exist yet.

How to restart depends on how the server was started — pick the one that matches your setup:

• Hakuto preview hook (this repo): the preview server is managed externally; ask the user to restart it, or wait for the next file-save hook trigger.
• Manual bun run dev / bun run preview: stop the process (Ctrl-C) and re-run the same command.
• PM2-managed (pm2 list shows it): pm2 restart <process-name> — typical names are preview or the package name.

Don't proceed to Step 3 until the server has restarted — the next step depends on the new config being live.

When invoked from website-builder's style-preview loop, always end by telling the user to restart their dev server before reviewing the preview — and encourage locking fonts early in the iteration, since every font swap repeats this restart cycle while palette/layout tweaks don't.

Step 3: Add Font declarations to .astro files (ONLY AFTER RESTART)