gatsby-plugin-preload-fonts/README.md

Gatsby plugin for preloading fonts per page

# gatsby-plugin-preload-fonts

This plugin preloads all necessary fonts per route to decrease time to first
meaningful paint. It works really well with services like Google Fonts that
link to stylesheets that in turn link to font files.

## Install

```shell
npm install gatsby-plugin-preload-fonts
```

Once you've installed the plugin, you'll want to add the included script
to your project's scripts in `package.json`.

```json
{
  "scripts": {
    "preload-fonts": "gatsby-preload-fonts"
  }
}
```

## How to use

In your `gatsby-config.js`:

```javascript
module.exports = {
  plugins: [`gatsby-plugin-preload-fonts`],
}
```

Before building your application, you will need to generate a font asset map
using the included `gatsby-preload-fonts` script.

```shell
npm run preload-fonts
```

You'll need to run this script again after adding routes to your application
(including new dynamic routes generated by source plugins), as well as any time
you add new font assets or stylesheets that link to font assets.

This script outputs a file named `font-preload-cache.json` to the root of your
project. You will want to check this file into your project's source control so
all contributors have the latest version of the cache.

You may pass any additional args to Puppeteer when running this script, like so:

```shell
npm run preload-fonts -- --no-sandbox
```

See [Puppeteer](#puppeteer) for more information.

### Using with CI

If you're planning to use this plugin in CI you can set the environment variable `CI=true` (most CI providers like Travis and CircleCI will set this for you). Please note that in this case `font-preload-cache.json` will only get rebuilt when routes change.

## Explanation of method

A common pattern in modern web development is to link to a remote stylesheet that
in turn links to other remote font assets. If it takes too long for the font to
resolve/download, typography will either not show up or flash in a different
system font before swapping out for the correct font.

This can be avoided by preloading font assets on the initial page load instead of
waiting for them to resolve indirectly. In order to do this, `<link rel="preload">`
tags will need to be added for each font asset required on each route at build time.

To accomplish this, this plugin runs in two steps:

1. Scrape each application route to determine what font assets are ultimately required.
2. Inject `<link rel="preload">` tags for each asset at build time.

The included `gatsby-preload-fonts` script spins up a [puppeteer](https://github.com/GoogleChrome/puppeteer) instance and visits each of your application's
routes to determine the required font assets. Once it has done so, it caches
this mapping and creates a unique scrape hash to help avoid rescraping the same
set of routes in subsequent runs (note that you will still need to re-run the
scraper if your application routes don't change but you add new font assets).

## Configuration options

**`crossOrigin`** [string|function][default: `anonymous`]

Whether or not to include the `cross-origin` attribute on injected `<link>` tags. By default, this will be set to `anonymous` (this is usually correct).

```js
module.exports = {
  plugins: [
    {
      resolve: `gatsby-plugin-preload-fonts`,
      options: {
        crossOrigin: `use-credentials`,
        // OR
        crossOrigin: pathname =>
          pathname.match(/^\/elevated/) ? `use-credentials` : `anonymous`,
      },
    },
  ],
}
```

## Troubleshooting

If an asset isn't showing up, this is likely due to its route not being scraped
properly. To insure that the route in question is being scraped, you have a couple
options. First, routes that don't show up under the `allSitePage` query on your
site's GraphQL server will not be scraped.

If you're still having trouble, you can run `gatsby-preload-fonts` with a lower
log level to view what paths it's visiting in real time.

```shell
# mac/linux
LOG_LEVEL=info npm run preload-fonts

# windows
set LOG_LEVEL=info & npm run preload-fonts
```

Available log levels include `info`, `debug`, `warn`, `error`, and
`silent`, respectively.

### Puppeteer

If you see a huge stack trace that looks like this

```text
(node:30511) UnhandledPromiseRejectionWarning: Error: Failed to launch chrome!
[0705/172123.766471:FATAL:zygote_host_impl_linux.cc(116)] No usable sandbox! Update your kernel or see https://chromium.googlesource.com/chromium/src/+/master/docs/linux_suid_sandbox_development.md for more information on developing with the SUID sandbox. If you want to live dangerously and need an immediate workaround, you can try using --no-sandbox.
...
```

you can pass the `--no-sandbox` flag to Puppeteer when you run the script:

```shell
npm run preload-fonts -- --no-sandbox
```

This comes with [inherent security risks](https://chromium.googlesource.com/chromium/src/+/master/docs/linux_suid_sandbox_development.md),
but you should be alright since you're only running it locally.

### Use different Chrome/Chromium executable

In some cases, you might have to point Puppeteer to an external installation of Chrome/Chromium (e.g., on Alpine Linux, the build-in version of Chromium does not work). You can set the `PUPPETEER_EXECUTABLE_PATH` environment variable to the path of your custom chromium installation. A list with all environment variables to configure Puppeteer can be found [at the official docs](https://pptr.dev/#?product=Puppeteer&version=v1.20.0&show=api-environment-variables).