Nuxt Fonts

Nuxt Fonts is a module designed for optimized custom web font management in Nuxt applications. Key capabilities include:

• Zero Configuration: Manage font optimization with a single font-family: declaration.
• Multiple Providers: Support for over 6 built-in font providers to avoid vendor lock-in, with the ability to create custom providers.
• Local Download Support: Font files are automatically downloaded for production usage, ensuring no external requests are made to font providers at runtime.
• Font Metric Optimization: Built-in optimization using fontaine and capsize to prevent layout shifts.
• Automatic Caching: Build and development time font caching powered by unstorage.

The local provider scans your public/ directories (including those in Nuxt layers) for font files with extensions like ttf, woff, woff2, eot, or otf.

When you use a font-family in CSS, the provider matches it against these files. By default, it expects the 400 weight, normal style, and latin subset. To support different variations, include the metadata in the filename:

• Default: comic-sans-ms.woff2 (400/normal/latin)
• Custom: comic-sans-ms-700-italic-cyrillic.woff2 (700/italic/cyrillic)
• Keywords: You can use light, bold, or black instead of numbers (e.g., comic-sans-ms-bold.woff2).

Note: The local provider only attempts to load styles and weights that were explicitly configured in your Font Options.

The npm provider resolves fonts from packages installed in your node_modules. It automatically detects known font packages like @fontsource/*, @fontsource-variable/*, and cal-sans from your package.json. By default, fonts are resolved locally from disk (remote: false), meaning no CDN requests are made, making it ideal for self-hosting via npm packages.

To use it, specify the npm provider in your nuxt.config.ts for specific font families.

export default defineNuxtConfig({
  modules: ['@nuxt/fonts'],
  fonts: {
    families: [
      // Automatically resolved if @fontsource/roboto is in your package.json
      { name: 'Roboto', provider: 'npm' },
      // Variable fonts are also supported
      { name: 'Inter Variable', provider: 'npm' },
    ],
  },
})

pnpm i @nuxt/fonts

yarn add @nuxt/fonts

npm i @nuxt/fonts

export default defineNuxtConfig({
  modules: [
    '@nuxt/fonts',
  ]
})

Tailwind CSS v4 uses CSS variables for configuration. To use a Nuxt Font, define it within an @theme block in your CSS file using a CSS variable.

Note: If you were previously using processCSSVariables: true for Tailwind v4 support, this option is no longer required or recommended for Nuxt Fonts v0.11.0 and above.

@theme {
  --font-display: "Inter", "sans-serif";
}

To use Nuxt Fonts in standard CSS, declare the font name within a font-family property.

Important details:

• Nuxt Fonts only generates CSS for the first font listed in your font-family declaration. Any subsequent fonts in the list are used solely to generate metrics for font fallbacks.
• Limitation: Inline styles using font-family within Vue <template> blocks are not currently supported. You must use external or project-level CSS stylesheets.

div {
  font-family: 'Inter', sans-serif;
}

To use Nuxt Fonts with UnoCSS, add the font to the theme.fontFamily section of your uno.config.js.

Wind4 (Tailwind4) Preset: If you are using the Wind4 preset, use the font key instead of fontFamily.

import { defineConfig } from 'unocss'

export default defineConfig({
  theme: {
    fontFamily: {
      inter: 'Inter',
    },
  },
})

Nuxt Fonts works out of the box with zero configuration. For finer-grained control, use the fonts property within your nuxt.config.ts file.

export default defineNuxtConfig({
  modules: ['@nuxt/fonts'],
  fonts: {
    // Options
  }
})

To add Nuxt Fonts to your project, use the Nuxt module installation command. This will add @nuxt/fonts as a dependency and register it in your Nuxt configuration.

npx nuxt module add fonts

To add Nuxt Fonts to your Nuxt application, use the Nuxt module addition command. This provides plug-and-play custom web font optimization and configuration.

npx nuxt module add fonts