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.

Font failures fail production builds

throwOnError now defaults to true outside of dev mode, so rather than producing a build with a missing font, the build fails when a provider errors, when a font file cannot be downloaded after retries, or when you set provider on a family and that provider does not contain it.

A family that cannot be found by any provider still warns rather than failing, as does an unknown provider name, so fonts you declare yourself in CSS are unaffected.

Set throwOnError: false to restore the previous behaviour.

Family-level @font-face descriptors now apply to provider fonts

display and unicodeRange set on a family were previously only honoured for families you declared manually with src, and were silently dropped for fonts resolved from a provider. They now apply in both cases. Descriptors other than display, weight and style (such as stretch, featureSettings and variationSettings) are also no longer dropped from manually declared families.

If you set any of these options on a family and (perhaps unknowingly) relied on them being ignored, your generated CSS will change. Note that setting unicodeRange on a family marks it as subsetted, so it is no longer preloaded by default; set preload explicitly if you still want a preload link for it.

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
  },
})