@nuxt/fonts
Advanced tools
Plug-and-play custom web font optimization and configuration for Nuxt apps.
google, bunny, fontshare, local - more welcome!)nuxt/assets lands)👉 See Nuxt Fonts RFC for full details and discussion.
[!IMPORTANT]
@nuxt/fontsis not yet released and the below step will not yet work. Instead you can manually install@nuxt/fonts-nightly.pnpm i @nuxt/fonts@npm:@nuxt/fonts-nightly
To get started, simply run:
npx nuxi@latest module add 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.
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,
},
}
})
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.
localThe 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).
googleGoogle Fonts is one of the best known public font APIs.
bunnyBunny Fonts is provided by bunny.net and is a drop-in Google Fonts compatible API, focusing on privacy.
fontshareFontshare is a free font service with 100+ professional-grade fonts from the Indian Type Foundry (ITF).
You should read their terms in full before using a font through fontshare.
The provider API is likely to evolve in the next few releases of Nuxt Fonts, but at the moment it looks like this:
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 */
}
})
})
corepack enablepnpm installpnpm dev:prepare to generate type stubs.pnpm dev to start playground in development mode.Published under the MIT License
v0.0.1
local and google providers (ade031f)extractFontFaceData utility (0409ed1)bunny provider (3773a9d)fontshare provider (#4)defineFontProvider helper from ./utils subpath (cf31dbb)@font-face (0cb114b)@font-face declarations (79f9c58)jiti to load custom font providers (a840e4d)@font-face for first font in list (0493d36)data: (0a9bf59)families (d2c9ac1)system-ui fallbacks (b707f62)playwright-core (3e6f82d)unstorage dependency (58ad293)none (ddcc31a)FAQs
Automatic font configuration for Nuxt apps
The npm package @nuxt/fonts receives a total of 45,530 weekly downloads. As such, @nuxt/fonts popularity was classified as popular.
We found that @nuxt/fonts demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 6 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Bybit's $1.46B hack by North Korea's Lazarus Group pushes 2025 crypto losses to $1.6B in just two months, already surpassing all of 2024's $1.49B total.
Security News
OpenSSF has published OSPS Baseline, an initiative designed to establish a minimum set of security-related best practices for open source software projects.
Security News
Michigan TypeScript founder Dimitri Mitropoulos implements WebAssembly runtime in TypeScript types, enabling Doom to run after processing 177 terabytes of type definitions.