Fontaine

Automatic font fallback based on font metrics

unjs/fontainefontaine

README

fontaine

[![npm version][npm-version-src]][npm-version-href] [![npm downloads][npm-downloads-src]][npm-downloads-href] [![Github Actions][github-actions-src]][github-actions-href] [![Codecov][codecov-src]][codecov-href]

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:

|After
-----------------
CLS`0.24`
Performance`92`

Installation


With pnpm

  1. ``` sh
  2. pnpm add -D fontaine
  3. ```

Or, with npm

  1. ``` sh
  2. npm install -D fontaine
  3. ```

Or, with yarn

  1. ``` sh
  2. yarn add -D fontaine
  3. ```

Usage


  1. ``` js
  2. import { FontaineTransform } from 'fontaine'

  4. const options = {
  5.   fallbacks: ['BlinkMacSystemFont', 'Segoe UI', 'Helvetica Neue', 'Arial', 'Noto Sans'],
  6.   // You may need to resolve assets like `/fonts/Roboto.woff2` to a particular directory
  7.   resolvePath: (id) => 'file:///path/to/public/dir' + id,
  8.   // overrideName: (originalName) => `${name} override`
  9.   // sourcemap: false
  10. }

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

  17. // Next.js
  18. export default {
  19.   webpack(config) {
  20.     config.plugins = config.plugins || []
  21.     config.plugins.push(FontaineTransform.webpack(options))
  22.     return config
  23.   },
  24. }

  26. // Docusaurus plugin - to be provided to the plugins option of docusaurus.config.js
  27. // n.b. you'll likely need to require fontaine rather than importing it
  28. const fontaine = require('fontaine')

  30. function fontainePlugin(_context, _options) {
  31.   return {
  32.     name: 'fontaine-plugin',
  33.     configureWebpack(_config, _isServer) {
  34.       return {
  35.         plugins: [
  36.           fontaine.FontaineTransform.webpack(options),
  37.         ],
  38.       };
  39.     },
  40.   };
  41. }

  43. // Gatsby config - gatsby-node.js
  44. const { FontaineTransform } = require('fontaine')

  46. exports.onCreateWebpackConfig = ({ stage, actions, getConfig }) => {
  47.   const config = getConfig()
  48.   config.plugins.push(FontaineTransform.webpack(options))
  49.   actions.replaceWebpackConfig(config)
  50. }
  51. ```

Note

If you are using Nuxt, check out nuxt-font-metrics which usesfontaine 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. ```diff
  2. :root {
  3.   /* ... */
  4. -  --ifm-font-family-base: 'Poppins';
  5. +  --ifm-font-family-base: 'Poppins', 'Poppins override';
  6. ```

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

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

  1. ```css
  2. :
  3.   font-family: 'Roboto';
  4.   /* This becomes */
  5.   font-family: 'Roboto', 'Roboto override';
  6. }
  7. ```

💻 Development


- Clone this repository
- Enable Corepack usingcorepack 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](https://github.com/clemcode)

License


Made with ❤️

Published under MIT License.



[npm-version-src]: https://img.shields.io/npm/v/fontaine?style=flat-square
[npm-version-href]: https://npmjs.com/package/fontaine
[npm-downloads-src]: https://img.shields.io/npm/dm/fontaine?style=flat-square
[npm-downloads-href]: https://npmjs.com/package/fontaine
[github-actions-src]: https://img.shields.io/github/workflow/status/unjs/fontaine/ci/main?style=flat-square
[github-actions-href]: https://github.com/unjs/fontaine/actions?query=workflow%3Aci
[codecov-src]: https://img.shields.io/codecov/c/gh/unjs/fontaine/main?style=flat-square
[codecov-href]: https://codecov.io/gh/unjs/fontaine