Update Gatsby 2 to 4

After watching the GatsbyConf 2022 presentation Upgrading from Gatsby 2 to Gatsby 4—It's About Time, I don't feel much more ready but I'm ready to try again. One thing I noticed is Khaled never did clear out node_modules.

Initial run of npm outdated

Everything is Green under Wanted but going for Latest!

Update all the things

npm update --save is not working for me like yarn upgrade did in the video. I expected everything to magically change to the newest versions. It's probably better in the long run. I headed back to the official Gatsby site migration articles.

Copy
1git checkout -b update-to-gatsby-4
2npm install gatsby@latest --legacy-peer-deps # to 4.10.0
3npm install gatsby-image@latest # not a thing to do anymore!

What changed?

• gatsby is now 4.10.0 but that is it, with or without the --legacy-peer-deps flag
• gatsby-image is deprecated and I should be using gatsby-plugin-image

Migrate gatsby-image to gatsby-plugin-image

Again, off to the official documentation for this. This is the usual install, configure Gatsby plugin pattern with an added running of the codemod. That is new to me!

• Migrating from gatsby-image to gatsby-plugin-image | Gatsby (gatsbyjs.com)

Copy
1npm install gatsby-plugin-image gatsby-plugin-sharp@latest gatsby-transformer-sharp@latest --legacy-peer-deps

Configure Plugins

Copy
1module.exports = {
2  plugins: [
3    `gatsby-plugin-image`,
4    `gatsby-plugin-sharp`,
5    `gatsby-transformer-sharp`,
6  ],
7}

Run the codemod

Copy
1npx gatsby-codemods gatsby-plugin-image <optional-path>

Message received (codemod)

It appears you're passing a variable to your image component. We haven't changed it, but we have updated it to use the new GatsbyImage component. Please check src/components/CoverImage.js manually.

Lots of little things and I'm not sure if any of them worked. Mainly replacing fluid { ...GatsbyImageSharpFluid} with gatsbyImageData(layout: FULL_WIDTH) in graphql and then in how it is being used by GatsbyImage component, which automatically replaced Img component from old gatsby-image.

In Image, I had originalName in the fluid {} and I just tried moving it out since I needed it. That's not going to work I bet!

I was able to use StaticImage instead.

Manual Changes (codemod)

Not sure if I have any of this, if so, check the site

• Images using static query
• If using src for an SEO component, use getSrc

Finishing up migration

Uninstall gatsby-image as it is no longer used. It is mentioned in a post but that's okay.

Copy
1npm uninstall gatsby-image

All the changes, if any, to npm packages. I ran them all manually one at a time.

Copy
1npm install gatsby-plugin-google-fonts@latest # no update
2npm install gatsby-plugin-manifest@latest # to 4.10.0
3npm install gatsby-plugin-mdx@latest # to 3.10.0
4npm install gatsby-plugin-offline@latest # to 5.10.0
5npm install gatsby-plugin-postcss@latest # to 5.10.0
6npm install gatsby-plugin-react-helmet@latest # to 5.10.0
7npm install gatsby-plugin-styled-components@latest # to 5.10.0
8npm install gatsby-remark-images@latest # to 6.10.0
9npm install gatsby-source-filesystem@latest # to 4.10.0
10npm install mdx-utils@latest # no update
11npm install @mdx-js/mdx@latest --legacy-peer-deps #  to 2.1.0 (gatsby-plugin-mdx requires v1)
12npm install @mdx-js/react@latest --legacy-peer-deps # to 2.1.0 (gatsby-plugin-mdx requires v1)
13npm install @tailwindcss@latest # to 3.0.23
14npm install autoprefixer@latest # to 10.4.4
15npm install styled-components@latest # to 5.3.3
16npm install babel-plugin-styled-components@latest # to 2.0.6
17npm install postcss@latest # to 8.4.12
18npm install react@latest # to 17.0.2
19npm install react-dom@latest # to 17.0.2
20npm install prism-react-renderer@latest # to 1.3.1
21npm install prop-types@latest # to 15.8.1
22npm install react-headroom@latest # to 3.2.0
23npm install react-helmet@latest # no update
24npm install react-live@latest # to 2.4.1
25npm install twin.macro@latest # to 2.8.2
26npm install prettier@latest # to 2.6.0

Somehow, everything is working?

Yes, yes, I'm shocked! Besides all the npm installs, here's what I did.

• Removed gatsby-plugin-image from gatsby-config.js

• Changed purge to content in tailwind.config.js

• Removed Image component as it was only used in Hero component / Removed from components/index.js

• Created a Moog component that displays the main cover image inside of the Hero component

Copy
1import { StaticImage } from 'gatsby-plugin-image'
2
3const Moog = () => (
4  <StaticImage
5    src='../images/steve-harvey-xWiXi6wRLGo-unsplash.jpg'
6    alt='MOOG Modular Synthesizer - photo by Steve Harvey @ Unsplash'
7    className='object-cover h-full min-w-full'
8  />
9)

• Removed absolute in Img when converting to GatsbyImage in PostCard component

Final gatsby-image updates

In: CoverImage.js, PostCard.js, single-post.js

• Convert from Img in gatsby-image to GatsbyImage in gatsby-plugin-image

Copy
1-fluid {
2-  ...GatsbyImageSharpFluid
3-}
4+gatsbyImageData(layout: FULL_WIDTH)
5
6-<Img fluid=
7+<GatsbyImage image=
8
9// In GraphQL
10childImageSharp {
11-  fluid {
12-    ...GatsbyImageSharpFluid
13-  }
14+  gatsbyImageData(layout: FULL_WIDTH)
15}

Final npm outdated run

These are fine, as mentioned previously, v1 is required by gatsby-plugin-mdx

Everything worked locally, but...

When the Github Action ran, it failed! The error related to styled-components.

According to the styled-components FAQ, styled-components now requires react-is@^16.8 (or higher hopefully). I updated that and started building again. That time, it was successful.

Attributions

Image by unDraw

References

• Migrating from v2 to v3 | Gatsby (gatsbyjs.com)
• Migrating from v3 to v4 | Gatsby (gatsbyjs.com)
• styled-components: FAQs