Published: January 6, 2023
Double Whammy! Upgrading to Drupal 10 and Gatsby 5 at the same time
Decoupling your frontend (Gatsby) from your backend (Drupal) is the Holy Grail. Change/update one without affecting the other. But what happens when both frameworks release a new version at the same time?
Honestly, this isn't the scare story that the headline and intro make it out to be. And there was about 5 months between the release of Gatsby 5 and Drupal 10, but I didn't have spare time to upgrade this site and also wanted to wait a little bit to make sure the plugins I was using were Gatsby 5-compatible.
Upgrading from Gatsby 4 to 5
There was a lot to upgrade here. Gatsby 5 needs Node 18, React 18, Gatsby Image 3, and lots more. Trying to get them all in position took a bit of trial and error between dependencies being locked in package-lock.json and deeper inside the node_modules directory. The short story is: delete your package-lock.json file, delete your node_modules directory, delete your .cache directory, and run a clean install.
Next issue, I am using esm for imports and running my local npm commands, but esm doesn't work with Gatsby 5, or works natively, or something like that I can't remember exactly. The fix for this was to rename gatsby-config.js and gatsby-node.js to gatsby-config.mjs and gatsby-node.mjs respecitely, then edit the files to work with the new syntax I needed.
Following that, I had issues with embedding images in the body field of my blogs. I use the Drupal media module to add images to my website and the media embed widget to embed them in my body field, however I don't want Gatsby to render the <drupal-media> tag, as that will just be empty in Gatsby land. Rather, I need to find the id of the media item that is being called, then use <GatsbyImage /> to render it (after finding/filtering it via a GraphQl query). The package I had been using for that was called React HTML Parser, but of course that doesn't work with React 18, so I had to remove that and use HTML React Parser (which looks like a much better package).
Finally, with that all working locally, I could push my changes to GitHub and let GitHub actions do it's magic to compile the site for me. Except, GitHub actions uses Node 12 by default. Grand, I'll move my site to Cloudflare pages ... oh no, that uses Node 16. Right, so I'll move it to Netlify. Actually, I probably could have moved it to Netlify, but then someone answered an issue I had replied to on GitHub with a way to use whatever version of Node you want with GitHub actions, and that worked a treat. Now, to upgrade my site from Drupal 9 to Drupal 10!
Upgrading from Drupal 9 to Drupal 10
Right, the easy part. Drupal has this romantic idea of easy updates from 8+. Upgrading from 8 to 9 proved tricky for me, until I eventually removed Devel module, but can't remember the exact issue. I had a similar issue with Drupal 9 to Drupal 10. My custom theme depended on Classy, but that is removed in Drupal 10. The fix for this was a dance around adding Classy/Stable to my composer.json so I'd have the contrib versions of these, running the upgrade, getting lost because there's issues with other things in the vendor directory that specify Twig 2 in their composer.json files. Then backtracking, uninstalling my custom theme (remember, I don't need it since I have a decoupled site), installing Olivero as my default them (it's beautiful, thanks to everyone who worked on it!), deleting composer-lock.json, deleting the vendor directory, removing any modules that were hanging around not being used such as Inline Entity Form and others, and running the update script. Which ... failed ... ouch! The problem this time? It wouldn't add YAML 6 because of an issue with Drush wanting YAML 4, then realising I was using Drush 10, but that doesn't work with PHP 8 (and is EOL in any case). Once I edited composer.json to require Drush 11, the script ran fine, the update when fine, and I, your humble author, had himself a snazzy Drupal 10 website.
And now...
It looks like my original idea behind decoupling this website was a good idea. It meant I could update my frontend Gatsby at my own leisure, with no effect on the backend, and could then update Drupal at my own leisure and even remove the custom theme without the frontend being affected. Win. Win.