Techniques to Keep Your Gatsby Site Blazing Fast

Published: April 29, 2020 | 6 min read

The 10th Challenge in the 100 Days of Gatsby series. This one provided four ways steps to improve your site's performance.

Auditing with Lighthouse

When auditing with Lighthouse, the issue reported was time to first meaningful paint. The opportunities to take were:

All of the instructions provided on the site were framework agnostic, so I had questions:

  • How would I do this in a Gatsby-based site, knowing the some of the techniques shown may be handled behind the scenes during the Gatsby build process?
  • Considering I'm using gatsby-plugin-typography in this site, would I need to adjust anything there?
  • How could I add that async or defer attribute to a font loaded by the Typography.js package?
  • Should I do something with adjusting the link attribute in the head element with react-helmet?
  • If so, how would that work with Typography.js? What about adding gatsby-plugin-preload-fonts? That should handle preloading, at least. Or… I could move on to part B, and use Guess.js to do intelligent preloading.

Intelligent Preloading using Guess.js

  • Woof, this whole section was a huge challenge to figure out. I started by reading the optimizing site performance with Guess.js page then dug into the gatsby-plugin-guess-js docs and didn’t find those docs clear at all for me. I decided to skip this portion because the instructions assumes you are already familiar with setting up a Google Analytics account, JWTs, and environment variables (if they’re needed here for the JWT token?), and more. The docs on using environment variables were clear once I found them, yet the instructions on JWTs and such were not clear at all.

The questions I had while reading this section were:

  • I already have a Google Analytics account set up for another site, would I need to create a new account? That’s what I did, and it’s now… hanging out, because the whole JWT section was unclear. I stopped work on this section.

In terms of unclear sentences… what did this sentence on getting a JWT token even mean?

Put that file into a directory node_modules that is inside one of the parent directories of the script that we’ll create later. That means that you can keep it out of the repository with analytics.js. For example, the following path is perfectly fine: \$HOME/node_modules/myproject-3126e4caac6a.json

What would happen if you did a clean install of the node modules? Would you need to download that JSON file again? Also, the “inside the parent directories of the script we’ll create later” phrase. Which script was created later? Where?

So far, this entire challenge was the one that’s been challenging to understand, docs-wise. For now, I abandoned this portion of the challenge, and moved onto the CDN for Media Assets section instead. I’ll go about preloading assets in my other site, most likely using something other than Typography.js if I can’t figure this out.

CDN for Media Assets

Exploring gatsby-source-cloudinary

I started out experimenting with gatsby-source-cloudinary to see what I could do with the service. To get started, I had to sign up with Cloudinary and get an account. After that was all set — their onboarding walkthrough was pretty nice, by the way — I read through this excellent tutorial on Handling Images in Gatsby with High Performance and it's worth a read.

The Gatsby docs on this plugin were straightforward to read once you followed the tutorial, and there was a timely reference to how to set up your (development) environment and how to configure your dotenv options for working in a development or production environment. If you are unfamiliar with how to work with .env files, the Gatsby docs are really good explanation article, and this is a really great Medium post on why environment variables are important

gatsby-source-cloudinary takeaways:

I learned that when you set your gatsby-source-cloudinary prefix option to use the sample/ in your Cloudinary Media Library, Cloudinary will return the first 10 images it finds by default, in alphabetical order of both folder and file name, no matter if the images are in a nested folder or not.

So, in my case it returned all the images in the animals directory since the directory started with the letter a, then found the images in the main samples directory beginning with the letters b and c, then the images in the ecommerce directory beginning with the letter a. I learned to be careful with setting the gatsby-source-cloudinary prefix path to a cloudinary directory location that contains subdirectories, or I may not get all the results I wanted… unless I increased the maxResults value in my options.

Exploring gatsby-transformer-cloudinary

The instructions for adding ‘gatsby-tranformer-cloudinary` were straightforward, especially the examples in the gatsby-tranformer-cloudinary demo source. The one part that got a bit sticky for me was loading the environment variables in the gatsby-config.js file. The instructions for this plugin seemed to be at odds with the instructions for gatsby-source-cloudinary.

The gatsby-config environment setup docs for gatsby-transform-cloudinary indicated to import the dotenv dependency like this:

/* Load the environment variables. */

require("dotenv").config({ path: `.env.${process.env.NODE_ENV}` })

The gatsby-source-cloudinary docs indicated a different setup:


Using the former config with the path set would throw an error in the CLI when trying to run the site in develop mode, yet using the setting without assigning the path seemed to work when using both plugins in the site. Once I removed the path from the dotenv config, everything worked as expected.

CDN for media assets takeaways:

I really enjoyed exploring using Cloudinary for my images, and will be looking into pairing these plugins with rendering images sourced from a YAML file and lazy loading components in future projects.

JavaScript Concerns

I skipped this step for now, because I wanted to continue using React rather than Preact. I’ll come back to this section at some point.

What I learned

If you are using Gatsby Cloud for deploying your site, you must add the .env variables into the General environment settings, to make the build work, regardless of which service you use for your hosting integration. I initially added those .env variables in the Netlify environment variables section, and that proved unsuccessful.

Once I removed the variables from the Netlify settings and added them to the Gatsby Cloud environment settings instead, the build worked as expected. I didn’t need to add them to the Netlify environment variables at all.

Also, the bulk secrets upload feature in Gatsby Cloud is pretty sweet.

Back to top