Updating a GatsbyJS website: breaking changes everywhere

What I believed was going to be a quick update to my site, turned out to be a herculean effort grappling with Gatsby and Netlify - encountering bugs, usually unrelated to my task, but having everything to do with conflicting, updating dependencies. As is typical of the Gatsby ecosystem, a "small update" turns into breaking changes, literally everywhere.

The tech stack

• Gatsby v4
• Netlify CMS
• Netlify hosting

The objective

• Gatsby v5
• Replace gatsby-transformer-remark with gatsby-plugin-mdx
• Convert my project files to TypeScript

For the uninitiated, Gatsby is a static site generator based off React. It loads only the the critical JavaScript and CSS while also prefetching resources you are likely to visit. With that said, Gatsby sites are fast.

The developer experience, however, is anything but fast. For a static site generator, there is a lot of overhead and configuration, and the honeymoon quickly ends when you want to do something as trivial as update to the latest version.

At some point in the process, I rage quit and moved on to other things. Had it not been for the valiant efforts of the GitHub issue openers and StackOverflow question askers, I might have quit web dev altogether.

Here is a rundown of some of the bugs I encountered making changes to my website that literally no end user would notice otherwise.

Netlify CMS is not compatible with React 18

React 18 is a major dependency of Gatsby 5. Netlify CMS which does not appear to be actively maintained, is not compatible with React 18. To overcome this, I have these overrides in my package.json with a comment key to remind me why this blocking piece of code exists.

"overrides": {
  "react": "^18.2.0",
  "@types/react": "^18.0.25",
  "react-dom": "^18.2.0"
},
"_comment": "https://github.com/netlify/netlify-cms/issues/6499#issuecomment-1237859875"

I forgot I had this in my package.json when I tried to install Gatsby's TypeScript dependencies. I got an incredibly vague error, leading me to ask my first ever question on StackOverflow (which I answered myself *pats self on back*).

npm ERR! code EOVERRIDE
npm ERR! Override for @types/react@* conflicts with direct dependency

npm ERR! A complete log of this run can be found in:
npm ERR!     /Users/josephmasongsong/.npm/_logs/2022-11-28T22_21_01_949Z-debug-0.log

Still super frustrating that I lost a few hours on this.

This issue makes Netlify CMS virtually unusable in Chrome

A recent update of Chrome, created this annoying bug to the admin panel of Netlify CMS, where the cursor jumps to the end of the text field on key press.

https://github.com/netlify/netlify-cms/issues/5092#issuecomment-1257138396

As mentioned, Netlify CMS is barely being maintained, and the "fix" for this bug is to load up some hacky CSS to the admin panel, as described in the aforementioned thread. It's not a huge deal, but is also not elegant. Anything that is not an official fix is likely to be precarious.

Node 18 is not yet supported by Netlify hosting

https://answers.netlify.com/t/gatsby-5-upgrade-error/80237

Node 18 is another major dependency of Gatsby 5, yet Netlify does not have support for it. If you're using Gatsby 5 with Netlify, your build will fail unless you specify NODE_VERSION as 18 in Netlify's environment variables, in addition to specifying the Node version in an .nvmrc at the root of your repo.

While this will work, you will lose the ability to leverage any of Netlify's build plugins until they start to officially support Node 18. This is unfortunate because the Essential Gatsby plugin uses caching to speed up your builds. SSR and DSG is also completely disabled.

Upgrading to React 18 exposes all kinds of hydration errors

Since React 18's release there has been an uptick in the amount of people getting hydration errors in their production builds. While this may enforce better code in the long run, the consensus is that React's error decoder in production is incredibly vague, and these errors often don't show up in development. This makes debugging a pain.

In my case, the hydration errors were coming from my use of Font Awesome's svg core library.

https://github.com/FortAwesome/Font-Awesome/issues/19348

But I was only able to deduce this by adding this setting to my gatsby-config.ts.

flags: {
  DEV_SSR: true
},

The fix was to replace the library's import statement with require, but because I am using TypeScript with Gatsby, this wasn't an option. I now reluctantly have to import individual icons when I need them as opposed to building an icon library. Extra import statements at the top of each component file... cool, cool. 🙃

The outcome

I replaced Remark with MDX for my blog, and now I can use JSX components directly in Markdown. 🤯

import { Counter } from '../../../src/components'

### The outcome

I replaced Remark with MDX for my blog, and now I can use JSX components directly in Markdown. 🤯

<Counter />

Through all the pain endured, I managed to accomplish most of what I set out to do.

• MDX support? ✅
• Converted my project files to TypeScript? ✅

I am using Gatsby v5, however, and am patiently waiting on official support from Netlify.