Nuxt Fonts

Plug-and-play custom web font optimization and configuration for Nuxt apps.

👾 Playground

Features

✨ zero-configuration required
🔡 built-in providers (google, bunny, fontshare, local - more welcome!)
💪 custom providers for full control
⏬ local download support (until nuxt/assets lands)
⚡️ automatic font metric optimisation powered by fontaine and capsize
🔥 build/dev time font caching powered by unstorage

👉 See Nuxt Fonts RFC for full details and discussion.

Quick Start

To get started, simply run:

npx nuxi@latest module add @nuxt/fonts

If you don't already have it in your .gitignore, go ahead and add the .data directory:

.data

Then just add a font-family declaration in your CSS:

<template>
  <div>
    Hello Nuxt Fonts!
  </div>
</template>

<style scoped>
div {
  font-family: Roboto, sans-serif;
}
</style>

That's it! Nuxt Fonts will detect this and you should immediately see the web font loaded in your browser. Read more about how it works.

!TIP Even if you're using a preprocessor like TailwindCSS or UnoCSS, Nuxt Fonts should be able to detect and optimize your fonts with no configuration.

Configuration

You do not need to configure Nuxt Fonts but you can do so for finer-grained control.

export default defineNuxtConfig({
  modules: ['@nuxt/fonts'],
  fonts: {
    // You can provide overrides for individual families
    families: [
      // do not resolve this font with any provider from `@nuxt/fonts`
      { name: 'Custom Font', provider: 'none' },
      // only resolve this font with the `google` provider
      { name: 'My Font Family', provider: 'google' },
      // specify specific font data - this will bypass any providers
      { name: 'Other Font', src: 'url(https://example.com/font.woff2)', weight: 'bold' },
    ],
    // The weights, styles, and subsets to generate font face rules for.
    // You can also customize these for a specific family, within `families`.
    defaults: {
      weights: [400],
      styles: ['normal', 'italic'],
      subsets: [
        'cyrillic-ext',
        'cyrillic',
        'greek-ext',
        'greek',
        'vietnamese',
        'latin-ext',
        'latin',
      ]
    },
    // If you use a generic font family like `Roboto, sans-serif`, we will 'translate' that
    // generic family name into one or more font families when generating fallback metrics.
    // You can customize which families we use. (One or two works best.)
    fallbacks: {
      'serif': ['Times New Roman'],
      'sans-serif': ['Arial'],
      'monospace': ['Courier New'],
      // ...
    },
    assets: {
      // The prefix where your fonts will be accessible
      prefix: '/_fonts'
    },
    providers: {
      // you can pass a new custom provider - see 'Writing a custom provider' below
      // for what this file should look like
      custom: '~/providers/custom',
      // Or you can disable a built-in provider
      google: false,
    },
  }
})

How it works

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

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.

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 */

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.
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;
}
```
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.

Font providers are designed to be pluggable and extensible, so no matter your setup you should be able to use an existing provider or write your own, and still benefit from core functionality of Nuxt Fonts.

We ship with four built-in providers.

`local`

The local provider deeply scans your public/ directories (including of your layers) for font files (supporting ttf, woff, woff2, eot or otf extensions).

Then, when you use a font-family in your CSS, we check to see whether it matches one of these files. We also expect font weight, font style and subset to be in the file name, unless they are 'default' values (400 weight, normal style and latin subset).

import { defineFontProvider } from '@nuxt/fonts/utils'

export default defineFontProvider({
  async setup () {
    // do some setup
  },
  async resolveFontFaces (fontFamily, defaults) {
    if (fontFamily === 'My Font Family') {
      return {
        fonts: [
          {
            src: [
              { url: 'https://cdn.org/my-font.woff2', format: 'woff2' },
              'https://cdn.org/my-font.woff', // this will be inferred as a `woff` format file
            ],
            weight: 400,
            style: 'normal',
          }
        ]
      }
    }
  }
})

Module authors can also add their own providers (or remove existing ones) in the fonts:providers hook which is called by Nuxt Fonts after all modules have run.

nuxt.hook('fonts:providers', providers => {
  providers.push({
    async setup () {
      /** some setup */
    },
    async resolveFontFaces (fontFamily, defaults) {
      /** resolve font faces */
    }
  })
})