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 for more information.

$3

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,
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 tags for each asset at build time.

The included gatsby-preload-fonts script spins up a 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 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.

$3

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,
but you should be alright since you're only running it locally.

$3

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.