How it works

Astrotype installs fonts into your Astro project and wires Astro Fonts API for you. Use pairings for heading and body; add a monospace separately withadd:font if you need one.

Install a font pairing

Each catalog pairing loads heading and body from one source (Google Fonts, Fontshare, or npm)—never a mix of Fontshare with Google/Bunny. For Google-only pairings, pass --cdn google or--cdn bunny sofonts.mjs points at the same catalog host. Fontshare pairings skip CDN flags on the detail page.

npx astrotype add oyster --cdn google

Switch to another pairing

Astrotype keeps only one active pairing import in global.css so pairing styles do not conflict.

npx astrotype add acacia --cdn google

Install one font

This creates a single token file like src/styles/astrotypes/inter.cssand adds that font to Astro Fonts API config.

npx astrotype add:font inter --cdn google

CSS-only mode (no Tailwind required)

Use CSS-only mode if you do not want Astro Fonts API wiring. This works with plain CSS projects too.

npx astrotype add oyster --cdn google --css-only
npx astrotype add:font inter --cdn google --mode css

In CSS-only mode, Astrotype updates onlysrc/styles/astrotypes/*.css andsrc/styles/global.css. It skipssrc/astrotypes/fonts.mjs,src/astrotypes/fonts.state.json, andastro.config.*.

Use the classes

Pairing CSS maps these classes to --font-headingand --font-body.

<Text tag="h1" class="font-heading">Heading</Text>
<Text tag="p" class="font-body">Body</Text>

Preview pairings in the dev toolbar

The astrotype/integration adds an Astrotypes app to the Astro dev toolbar. Open it while runningastro dev to try any catalog pairing live on your own pages, then copy the matching install command. Previews only touch the browser—nothing is written until you run the CLI.

// astro.config.mjs
import astrotype from "astrotype/integration";

export default defineConfig({
  integrations: [astrotype()],
});

Validate your setup

Run astrotype doctor to check project layout, global CSS, astrotypes imports, pairing imports, and Astro Fonts wiring. Use--fix for safe automatic repairs, or--json for CI.

npx astrotype doctor
npx astrotype doctor --fix
npx astrotype doctor --json

Find