Advanced

How it works

Nuxt Fonts processes all your CSS and does the following things automatically when it encounters a font-family declaration.

1. Resolves fonts used in CSS. It starts by looking in your public/ directory for font files that match the name, like Roboto.woff2, RobotoBold.ttf, etc. Then it moves on to web font providers like google, bunny and fontshare. Once a provider is found (in this case, probably Google Fonts), we move on to the next step.
2. Generates and injects @font-face rules for you. We'll generate rules to point your browser to the right source files. They'll be injected into the same CSS where you use the font-family.

   /* If you write something like this: */
   :root {
     font-family: Poppins;
   }
   

   /* Then Nuxt fonts will add declarations that look like this at the beginning of the CSS file: */
   @font-face {
     font-family: 'Poppins';
     src: local("Poppins"), url("/_fonts/<hash>.woff2") format(woff2);
     font-display: swap;
     unicode-range: U+0000-00FF,U+0131, /* ... */;
     font-weight: 400;
     font-style: normal;
   }
   /* ... plus more font-face declarations for other unicode ranges/weights */
   

3. Proxies and caches font requests. Rather than using the original source URLs (to remote servers), we generate rewrites under the /_fonts subpath. When accessed by your browser, we download the font from the remote server and cache it locally.
4. Creates font fallback metrics. If we have access to the font metrics (ascent, descent, line gap, character width, etc.) then we can generate a fallback @font-face declaration as well. The idea is that we 'morph' a local system font (like Arial or Times New Roman) to be as close as possible to the size of the web font, to decrease layout shift (read more about CLS).

   :root {
     /* This will generate fallbacks for local versions of Helvetica and Arial, adjusted to match Roboto's metrics. */
     font-family: Roboto, Helvetica, Arial;
     /* If you provide a generic family (like serif or sans-serif), we will use a system font from that family. */
     font-family: Merriweather, serif;
   }
   

5. Include fonts in build. When you build your project, we'll copy across all the fonts used in your project so you don't need to make any external requests when loading your site. (Any that haven't already been cached in development are downloaded at build time.) Font file names are hashed and Nuxt will serve them with long-lived cache headers.

Caching fonts between builds

Font metadata and downloaded font files are cached on disk in node_modules/.cache/nuxt/fonts/meta, relative to your project root. If you restore that directory in CI, no fonts are downloaded and no provider requests are made at all.

- uses: actions/cache@v4
  with:
    path: node_modules/.cache/nuxt/fonts
    key: nuxt-fonts-${{ hashFiles('nuxt.config.ts') }}
    restore-keys: nuxt-fonts-

A few things to check if the cache doesn't seem to take effect:

• The cache step must run after you install dependencies. Some package managers remove unknown directories inside node_modules, which will delete a cache restored before install.
• actions/setup-node with cache: 'pnpm' (or npm/yarn) caches the package manager store, not node_modules, so it does not cover fonts.
• With an exact key and no restore-keys, a config change means a cache miss and a full re-download.
• In Docker builds, node_modules/.cache lives inside the build container. You need a cache mount (RUN --mount=type=cache,target=/app/node_modules/.cache) or a persistent volume for it to survive.

If a path inside node_modules is awkward to cache, move it with the cache option.

Module Hooks

Nuxt Fonts exposes hooks for module authors to extend functionality.

fonts:providers

Add or modify font providers after all modules have loaded.

nuxt.hook('fonts:providers', (providers) => {
  providers['my-provider'] = defineFontProvider(/* ... */)
})

fonts:public-asset-context

Access the font resolution context, useful for modules that need font URLs during prerender (e.g., OG image generation).

nuxt.hook('fonts:public-asset-context', (context) => {
// context.renderedFontURLs: Map<filename, sourceUrl>
// Populated during vite build
})