Shortdark Web Development

Upgrading Gatsby and Fixing Version Mismatches

Development25th Apr 2021.Last Updated: 19th Sep 2021.Time to read: 4 mins

Static WebsiteGatsbyJsNPM

I recently cloned one of my GatsbyJS websites. It was a fresh computer with nothing installed on it, so I originally followed this guide to get everything I needed to run GatsbyJS... Set Up Your Development Environment

However, it soon became clear that not only had I installed Gatsby, but I had also upgraded from version 2.x to 3.3.1. At this stage, I had the decision to downgrade GatsbyJS or to keep the latest version and upgrade all the plugins. I decided to stay as up-to-date as possible, which meant that this guide was now more relevant... Migrating from v2 to v3. Here is another good article on upgrading dependencies.

Upgrading Gatsby to the Next Major Release

Before I found the official guide, I fixed the mismatches by removing various packages from the package.json then installing each one with npm. This updated everything to the latest version that was compatible with Gatsby 3.3.

Once this was done, everything was happier, and I was able to npm update and gatsby build.

I was starting to get deprecated plugin errors on Gatsby version 2.x, so this may have been overdue. It makes me pleased that I upgraded to the latest version, as opposed to downgrading back to 2.x. This is probably the way to fix any future plugin errors where they appear to be deprecated.

Gatsby Version Mismatches

However, even after all this I was still getting version mismatches.

The npm outdated command shows the versions that are currently being used if they are different from the latest version.

Some plugins are not used by Gatsby itself. In this case, they recommend using resolutions in the package.json. The example from the official docs...

  "resolutions": {
    "graphql": "^15.4.0",
    "graphql-compose": "^7.25.0",
    "webpack": "^5.24.2"

I did have problems with warnings for various plugins. Where there were fatal errors, one workaround was to install the dependencies directly so that they appear in the package.json. This leads to a warning instead of an error. Right now, I have the dependencies as up-to-date as possible, but we're not 100% on everything.

Code Fixes for GatsbyJS 3.x

Then, it was just that the updated packages worked a little differently, and I had to modify my code in a couple of places. The errors on the build are pretty good so identifying how to change the code was pretty easy. Here are some examples...


I was importing a package as name "SEO", whereas it should be PascalCase now, so "Seo". I prefer to see SEO in all CAPS but PascalCase is fine.

Anonymous Exports

Instead of exporting anonymous functions...

export default () => (<Layout></Layout>)

Gatsby now wants you to name the function before exporting them, like this...

const Name = () => (<Layout></Layout>);
export default Name;

Ordering by GraphQL arguments

warn The enum value "MarkdownRemarkFieldsEnum.fields___slug" is deprecated.
Sorting on fields that need arguments to resolve is deprecated.

I was sorting the GraphQL results by the "slug". The slug is defined in gatsby-node.js so Gatsby treats it as an argument of "fields" (fields___slug). Now, the new version of Gatsby does not want arguments to be used for sorting. I fixed this by sorting by the date instead as that was in the frontmatter: (frontmatter___date). In future, if you wanted to sort by the slug, you'd have to define the slug in the frontmatter of the markdown then sort by frontmatter___slug in the GraphQL.

Problems with Codeblocks

Using the "gatsby-remark-prismjs" plugin, if you use codeblocks without specifying a language you get a warning when you build. To avoid this warning the obvious thing would be to always specify one of the supported languages. To be able to specify the language for an inline codeblock, you need to specify the character you'll use to separate the language from the code in "gatsby-config.js"...

inlineCodeMarker: '±',

Code blocks do not seem to like some (broken) javascript. It could be open-ended structures, or it could be things like "..." that signify missing code. While these things do not fatally break the build, they can prevent some functionality working. The best thing to do is probably to post simplified snippets of the code that are in the correct format, rather than to post excerpts with parts missing.

Markdown needs a space after hashes in Headings

Whereas, in the past, you could do this: ##Heading. Now, you would need a space, so it would need to be this instead...

## Heading

Update: Gatsby Troubleshooting

After an npm update there may be multiple errors like this...

failed Building production JavaScript and CSS bundles - 3.956s


Generating JavaScript bundles failed

Can't resolve '@gatsbyjs/reach-router/lib/utils' in '.cache'

If you're trying to use a package make sure that '@gatsbyjs/reach-router/lib/utils' is installed. If you're trying to use a local file
make sure that the path is correct.

File: .cache/find-path.js:1:0

From here...

Your npm install didn't work correctly. Rerun npm install --legacy-peer-deps to install the missing packages.

Try deleting node_modules and package-lock.json then and rerun npm install --legacy-peer-deps

There is also the gatsby clean command to delete the .cache and public directories.

Previous: Wordpress Vs Static WebsitesNext: Learning a new Coding Language