Updating to Gatsby 5 and using FontAwesome properly on Netlify

December 6, 2022

After running my favourite command…

npm outdated

I noticed that once again, I was falling behind on my packages being up to date.

There’s now Gatsby version 5 and all of my other packages needed to be updated as well. So I thought I’d take the time in updating them. Turns out it wasn’t straight forward, not as easy as upgrading to version 4 of Gatsby.

So if you’re running Gatsby on Netlify, be sure to read this post on how I got my site running version 5.

Gatsby 5

So what’s new in version 5 of Gatsby? Well:

GraphQL V2
React V18
Node V18
Head API
Slice API
Performance Improvements

If you want to see the full release notes, click here.

So after updating my packages file and installing with dependencies, my site was running locally with the latest versions!

In case you’re not sure on how to install with dependencies, it’s:

npm install --legacy-peer-deps

But after running it, I noticed that there were plenty of warnings being logged in the terminal. So let’s fix them.

Anonymous arrow functions

Anonymous arrow functions cause Fast Refresh to not preserve local component state. So we need to update each page to use a constant then export it.

Here it is before:

export default () => ()

To…

const about = () => ()

export default about

All the pages are now using this, now the Fast Refresh preserve the local component state.

Head API

To update the header in all of my pages, I was using a package called gatsby-plugin-react-helmet to add attributes to the header on each page that Gatsby builds.

But now there is the Gatsby Head API, a built in Head export. The advantages of using it are:

easier to use
more performant
a smaller bundle size
supports the latest React features

Lots of benefits, so let’s dive in!

Here’s an example:

export function Head() {
  return (
    <>
      <title>Joshua Blewitt - About</title>
      <meta charSet="utf-8" />
      <script
        src="https://kit.fontawesome.com/TEST.js"
        crossorigin="anonymous"
      ></script>
    </>
  )
}

And here is an example of working with results with GraphQL:

export function Head() {
  return (
    <>
      <meta charSet="utf-8" />
      <title>Joshua Blewitt - Blog</title>
      <script
        src="https://kit.fontawesome.com/TEST.js"
        crossorigin="anonymous"
      ></script>
    </>
  )
}

All of the pages are now using the Head API!

One interesting thing I noticed was when I was testing this locally. I had one page using the Head API, and the rest using the react helmet plugin. I found that using both causes some unusual behaviour when viewing pages. The react helmet plugin would override the Head API! So some pages were displaying the incorrect Header data. Weird!

Updated GraphQL queries

Another warning I saw in the Netlify logs was this:

warning Deprecated syntax of sort and/or aggregation field arguments were found in your query (see https://gatsby.dev/graphql-nested-sort-and-aggregate). Query was automatically converted to a new syntax. You should update query in your code.

Makes sense to update it. I only have a few queries running anyway so upgrading them shouldn’t be too difficult. In fact, the only change needed for all the queries was this:

allMarkdownRemark(sort: {fields: [frontmatter___date], order: DESC}, limit: 5)

Easy change to make!

FontAwesome

When I was upgrading Gatsby last time, I noticed that the images were taking a long time to load and that the icons in the footer appeared briefly at a much larger size before being set at the correct size. This was tied to waiting for the images to load.

I thought I solved this issue by making the images smaller in size, so that the icons would appear in the correct size. But this was not the case.

After some investigating, it turns out that I needed to use FontAwesome properly. This means creating a kit that can be used with the icons.

I was using a plugin called ‘fortawesome’ for the icons, so I needed to stop using that.

As you can see above in the Head API example, the FontAwesome kit is being used in the headers of all the pages.

Deploying to Netlify

At this stage, everything was running locally and I was ready to deploy to Netlify. But things did not go smoothly. At first, I needed to reinstall the Gatsby Essentials plugin to get the latest version. Then, I needed some extra packages. And finally, this happened:

10:36:25 PM: Error during NPM install
10:36:25 PM: Build was terminated: Build script returned non-zero exit code: 1
10:36:26 PM: Failing build: Failed to build site
10:36:26 PM: Finished processing build request in 17.719148076s

Well, that’s confusing. Now what?

StackOverflow didn’t return anything and I couldn’t find anything on the Netlify forums. I tried deleting the package lock file, rebuilding everything and so on. If you look at the commits for this branch, you can see that I nearly lost my mind trying to figure out this problem.

I noted that the application was running perfectly fine on my machine. Nothing was wrong. So what could be causing this?

I looked at the logs more closely and found this:

10:36:25 PM: npm ERR! Fix the upstream dependency conflict, or retry
10:36:25 PM: npm ERR! this command with --force, or --legacy-peer-deps
10:36:25 PM: npm ERR! to accept an incorrect (and potentially broken) dependency resolution.

And there it is, legacy dependencies.

So, how can I tell Netlify to install with the legacy dependencies? Netlify makes it easy with environment variables.. And there are plenty of configuration variables to choose from.

We’re interested in the ‘NPM_FLAGS’ variables, and the value will be:

 -—legacy-peer-deps

So now whenever Netlify builds the Gatsby project, it’ll use the legacy dependencies.

And it worked. The preview was successfully deployed. I spent a few hours trying to figure out how to fix it, so I hope this helps someone who uses Netlify.

Anything else?

The node version used is now upgraded to 19.2.0 from 14.15.0. The version of node needed to be upgraded to support the new version of Gatsby.

And that’s the website fully upgraded! The website will now have the icon issue resolved and have improved performance.

If you’re running a Gatsby website on Netlify, I hope you found this blog post helpful!

Joshua Blewitt