a picture of me upgrading gatsby

Upgrading this very Gatsby blog (v1 => v4)

February 02, 2023

First of all, I'm running such an old version of Gatsby that I can't use any of its newest features. To use SEO tools, I need to upgrade to gatsby@4.19.0.

My notes from performing the upgrade are included in this post.

v1 to v2 upgrade

I'll try just setting package.json version to 2.0.0:

  
  "dependencies": {
    "gatsby": "^2.0.0",
  }

After running npm i, I needed to update all the peers of Gatsby to a higher version too. After doing that, react and react-dom packages were added because in v1 these were bundled inside Gatsby but no longer are.

I was able to finish the installation of new packages and render the site successfully using my package script: npm run develop

However, now I see massive layout issues and I will move on to restructuring my react components so that they no longer use the layout.js as a root component.

After the following steps, which are thankfully documented in the migration guide, I'm up and running again. Had to do the following steps.

Convert layout's children from render prop to normal prop (required)
Mv layouts/index.js to src/components/layout.js (optional, but recommended)
Import then wrap pages with layout component
Pass history, location, and match props to layout (didn't do this actually)
Change the query to use StaticQuery (now getting false positive warn about 'maxWidth' in query)

v2 Done

We made it. Things so far have remained straightforward. Next, I'll continue upgrading to v4 now from v2.

v2 to v4 upgrade

For this migration, I skipped 3 altogether as I saw very few breaking changes that would affect me. Even further migrating to v4 shows no apparent breaking changes I'll need to address.

I updated the package.json to the latest release for v4 according to npm:


    "gatsby": "4.25.2",

After that, I updated all the Gatsby plugin and peers to their latest v4 versions (using npm versions page as my reference):

    
    "gatsby-plugin-catch-links": "^4.25.0",
    "gatsby-plugin-react-helmet": "5.25.0",
    "gatsby-source-filesystem": "^4.25.0",
    "gatsby-transformer-remark": "^5.25.1",

Luckily, not too many packages.

On installing, I faced nothing major except a few warnings. I ended up facing more issues when I tried to run gatsby develop. Errors looked like:


failed Building production JavaScript and CSS bundles - 4.511s

ERROR #98124  WEBPACK

Generating JavaScript bundles failed

Can't resolve '@gatsbyjs/reach-router/lib/utils' in '/Users/nathanphennel/Projects/blog/.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

To overcome these, I found that it's necessary to add Gatsby peer dependencies to the package.json for some unknown reason. I saw there was a bit of chatter about dependencies issues on Gatsby's Github issues. Here, I saw I could just bypass issues with the transient dependencies and just specify compatible versions myself in the package.json like so:


  "gatsby-link": "^4.25.0",
  "gatsby-react-router-scroll": "^5.25.0",
  "@gatsbyjs/reach-router": "1.3.9",
  "gatsby-script": "^1.10.0",

After this update, I ran the following:

  
  rm -rf node_modules/
  rm package-lock.json
  rm -rf .cache
  npm i
  npm run clean
  npm i
  npm run develop

Upon completely resetting all the dependencies for v4, things were back up and running. Only one small issue noticeable in the terminal remains when running gatsby develop:


warn Warning: there are unknown plugin options for "gatsby-source-filesystem": fastHash
Please open an issue at https://ghub.io/gatsby-source-filesystem if you believe this option is valid.

Turns out, this is now handled automatically by the plugin. I don't need to specify fastHash for detecting changes to images any longer. Nice! Now I'm running with no noticeable issues and no major console warnings/errors.

Conclusion