Upgrade Guide

Upgrading to v0.15

Breaking Changes

Font metadata is cached per project

Font metadata and downloaded font files are now cached in node_modules/.cache/nuxt/fonts/meta relative to your project root rather than to the directory you run Nuxt from. The first build after upgrading will re-resolve and re-download fonts, and you can now configure the location with the new cache option.

Injected @font-face rules are minified with lightningcss

Generated @font-face declarations were previously minified with esbuild unless you had opted into css.lightningcss. They are now always minified with lightningcss, so the exact serialisation of the CSS we inject may differ (for example local(Font Name) rather than local("Font Name")). This is cosmetic, but it will show up in snapshot tests.

New Features

Preloading fonts by subset

The preload option (on defaults and on individual families) now accepts { subsets: [...] } or a filter function, so you can preload just the subsets your app needs.

export default defineNuxtConfig({
  fonts: {
    defaults: {
      preload: { subsets: ['latin'] },
    },
  },
})

See preload for the full set of values.

Configurable cache

You can now point the font cache at a directory of your choice, pass your own unstorage instance, or disable persistent caching with cache: false.

export default defineNuxtConfig({
  fonts: {
    cache: '.cache/fonts',
  },
})

Custom CSS variable prefixes

processCSSVariables now accepts a custom prefix, so processCSSVariables: 'my-app' will process --my-app-* variables only.

Upgrading to v0.14

Breaking Changes

Default font format is now woff2 only

Previously, font providers could return multiple formats (e.g., woff2, woff, truetype). The default behavior now only resolves woff2 format fonts, which is universally supported in all modern browsers.

This means your rendered @font-face declarations will typically have fewer src entries, reducing overall CSS size. In most cases this is a transparent improvement and requires no action.

If you need to support legacy browsers that require other formats, you can configure this in your nuxt.config.ts:

export default defineNuxtConfig({
  fonts: {
    defaults: {
      formats: ['woff2', 'woff', 'ttf'],
    },
  },
})

The available format values are: 'woff2', 'woff', 'ttf', 'otf', 'eot'.

New Features

Font format resolution

You can now control which font formats are resolved via the new defaults.formats option. This defaults to ['woff2'].

export default defineNuxtConfig({
  fonts: {
    defaults: {
      formats: ['woff2'],
    },
  },
})

Provider-specific font family options

You can now pass provider-specific options when configuring individual font families using the new providerOptions property:

export default defineNuxtConfig({
  fonts: {
    families: [
      {
        name: 'My Font',
        provider: 'google',
        providerOptions: {
          google: {
            experimental: {
              variableAxis: {
                wdth: [['75', '100']],
              },
            },
          },
        },
      },
    ],
  },
})

throwOnError option

You can now configure whether font resolution errors should throw or just warn:

export default defineNuxtConfig({
  fonts: {
    throwOnError: true, // default: false
  },
})