fontaine

Automatic font fallback based on font metrics

• ✨  Changelog
• ▶️  Online playground

Features

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

On the playground project, enabling/disabling fontaine makes the following difference rendering /, with no customisation required:

	Before	After
CLS	0.24	0.054
Performance	92	100

Installation

With pnpm

1pnpm add -D fontaine

Or, with npm

1npm install -D fontaine

Or, with yarn

1yarn add -D fontaine

Usage

1import { FontaineTransform } from 'fontaine'
2
3// Astro config - astro.config.mjs
4import { defineConfig } from 'astro/config'
5
6const options = {
7  fallbacks: ['BlinkMacSystemFont', 'Segoe UI', 'Helvetica Neue', 'Arial', 'Noto Sans'],
8  // You may need to resolve assets like `/fonts/Roboto.woff2` to a particular directory
9  resolvePath: id => `file:///path/to/public/dir${id}`,
10  // overrideName: (originalName) => `${name} override`
11  // sourcemap: false
12  // skipFontFaceGeneration: (fallbackName) => fallbackName === 'Roboto override'
13}
14
15// Vite
16export default {
17  plugins: [FontaineTransform.vite(options)]
18}
19
20// Next.js
21export default {
22  webpack(config) {
23    config.plugins = config.plugins || []
24    config.plugins.push(FontaineTransform.webpack(options))
25    return config
26  },
27}
28
29// Docusaurus plugin - to be provided to the plugins option of docusaurus.config.js
30// n.b. you'll likely need to require fontaine rather than importing it
31const fontaine = require('fontaine')
32
33function fontainePlugin(_context, _options) {
34  return {
35    name: 'fontaine-plugin',
36    configureWebpack(_config, _isServer) {
37      return {
38        plugins: [
39          fontaine.FontaineTransform.webpack(options),
40        ],
41      }
42    },
43  }
44}
45
46// Gatsby config - gatsby-node.js
47const { FontaineTransform } = require('fontaine')
48
49exports.onCreateWebpackConfig = ({ stage, actions, getConfig }) => {
50  const config = getConfig()
51  config.plugins.push(FontaineTransform.webpack(options))
52  actions.replaceWebpackConfig(config)
53}
54
55export default defineConfig({
56  integrations: [],
57  vite: {
58    plugins: [
59      FontaineTransform.vite({
60        fallbacks: ['Arial'],
61        resolvePath: id => new URL(`./public${id}`, import.meta.url), // id is the font src value in the CSS
62      }),
63    ],
64  },
65})

Note If you are using Nuxt, check out nuxt-font-metrics which uses fontaine under the hood.

If your custom font is used through the mechanism of CSS variables, you'll need to make a tweak to your CSS variables to give fontaine a helping hand. Docusaurus is an example of this, it uses the --ifm-font-family-base variable to reference a custom font. In order that fontaine can connect the variable with the font, we need to add a {Name of Font} override suffix to that variable. What does this look like? Well imagine we were using the custom font Poppins which is referenced from the --ifm-font-family-base variable, we'd make the following adjustment:

1:root {
2  /* ... */
3-  --ifm-font-family-base: 'Poppins';
4+  --ifm-font-family-base: 'Poppins', 'Poppins override';

Behind the scenes, there is a 'Poppins override' @font-face rule that has been created by fontaine. By manually adding this override font family to our CSS variable, we make our site use the fallback @font-face rule with the correct font metrics that fontaine generates.

How it works

fontaine 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')
5      format('woff');
6  font-weight: 700;
7}
8/* This additional font-face declaration will be added to your CSS. */
9@font-face {
10  font-family: 'Roboto override';
11  src: local('BlinkMacSystemFont'), local('Segoe UI'), local('Helvetica Neue'),
12      local('Arial'), local('Noto Sans');
13  ascent-override: 92.7734375%;
14  descent-override: 24.4140625%;
15  line-gap-override: 0%;
16}

Then, whenever you use font-family: 'Roboto', fontaine will add the override to the font-family:

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

💻 Development

• Clone this repository
• Enable Corepack using corepack enable (use npm i -g corepack for Node.js < 16.10)
• Install dependencies using pnpm install
• Run interactive tests using pnpm dev; launch a vite server using source code with pnpm demo:dev

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
• package name suggestion from @clemcode

License

Made with ❤️

Published under MIT License.