Nuxt Fontaine

Font metric fallback implementation for Nuxt 3

• ✨  Changelog
• ▶️  Online playground

Features

⚠️ @nuxtjs/fontaine is under active development. ⚠️

• 💪 Reduces CLS by using local font fallbacks with crafted font metrics.
• ✨ Generates font metrics and fallbacks automatically.
• ⚡️ Pure CSS, zero runtime overhead.

On the playground project, enabling/disabling this module makes the following differences rendering /, with no customisation required:

	Before	After
CLS	0.34	0.013
Performance	88	98

What's next

For best performance, you will need to inline all your CSS, not just the font-face fallback rules (which this module does automatically), or there will still be a layout shift when the stylesheet loads (which is why the number above is not zero).

This PR aims to bring that ability to Nuxt itself.

Installation

1npx nuxi@latest module add fontaine

Usage

1export default defineNuxtConfig({
2  modules: ['@nuxtjs/fontaine'],
3  // If you are using a Google font or you don't have a @font-face declaration
4  // for a font you're using, you can declare them here.
5  //
6  // In most cases this is not necessary.
7  //
8  // fontMetrics: {
9  //   fonts: ['Inter', { family: 'Some Custom Font', src: '/path/to/custom/font.woff2' }],
10  // },
11})

That's it!

Tailwind CSS

If you use Tailwind CSS and use your custom font via the config file, you will need to manually add the fallback font.

1import type { Config } from 'tailwindcss'
2import { fontFamily } from 'tailwindcss/defaultTheme'
3
4export default <Partial<Config>> {
5  theme: {
6    extend: {
7      fontFamily: {
8        sans: ['Roboto', 'Roboto fallback', ...fontFamily.sans],
9      },
10    },
11  },
12}

How it works

Nuxt will scan your @font-face rules and generate fallback rules with the correct metrics. For example:

1@font-face {
2  font-family: 'Roboto';
3  font-display: swap;
4  src: url('/fonts/Roboto.woff2') format('woff2'), url('/fonts/Roboto.woff') format('woff');
5  font-weight: 700;
6}
7/* This will be generated. */
8@font-face {
9  font-family: 'Roboto fallback';
10  src: local('Segoe UI'), local('Roboto'), local('Helvetica Neue'), local('Arial'), local('Noto Sans');
11  ascent-override: 92.7734375%;
12  descent-override: 24.4140625%;
13  line-gap-override: 0%;
14}

Then, whenever you use font-family: 'Roboto', Nuxt will add the fallback to the font-family:

1:root {
2  font-family: 'Roboto';
3  /* This becomes */
4  font-family: 'Roboto', 'Roboto fallback';
5}

Using outside of Nuxt

The core of this module will work outside of Nuxt, and has been separated into a separate library: fontaine. Check it out!

💻 Development

• Clone this repository
• Enable Corepack using corepack enable
• Install dependencies using pnpm install
• Stub module with pnpm dev:prepare
• Run pnpm dev to start playground in development mode

Credits

This would not have been possible without:

• amazing tooling and generated metrics from capsizecss
• suggestion and algorithm from Katie Hempenius & Kara Erickson on the Google Aurora team - see notes on calculating font metric overrides.

License

Made with ❤️

Published under the MIT License.