fontaine

fontaine

Automatic font fallback based on font metrics

• ✨  Changelog
• ▶️  Online playground

Features

⚠️ fontaine is under active development. ⚠️

• 💪 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

pnpm add -D fontaine

Or, with npm

npm install -D fontaine

Or, with yarn

yarn add -D fontaine

Usage

import { FontaineTransform } from 'fontaine'

const options = {
  fallbacks: ['BlinkMacSystemFont', 'Segoe UI', 'Roboto', 'Helvetica Neue', 'Arial', 'Noto Sans'],
  // You may need to resolve assets like `/fonts/Roboto.woff2` to a particular directory
  resolvePath: (id) => 'file:///path/to/public/dir' + id,
}

// Vite
export default {
  plugins: [FontaineTransform.vite(options)]
}

// Next.js
export default {
  webpack(config) {
    config.plugins = config.plugins || []
    config.plugins.push(FontaineTransform.webpack(options))
    return config
  },
}

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

How it works

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

@font-face {
  font-family: 'Roboto';
  font-display: swap;
  src: url('/fonts/Roboto.woff2') format('woff2'), url('/fonts/Roboto.woff')
      format('woff');
  font-weight: 700;
}
/* This additional font-face declaration will be added to your CSS. */
@font-face {
  font-family: 'Roboto override';
  src: local('BlinkMacSystemFont'), local('Segoe UI'), local('Roboto'), local(
      'Helvetica Neue'
    ), local('Arial'), local('Noto Sans');
  ascent-override: 92.7734375%;
  descent-override: 24.4140625%;
  line-gap-override: 0%;
}

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

:root {
  font-family: 'Roboto';
  /* This becomes */
  font-family: 'Roboto', 'Roboto override';
}

💻 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.

License

Made with ❤️

Published under MIT License.