Upgrading from Astro v2 to v4

In a recent episode of the ShopTalk podcast, Chris Coyier and Dave Rupert interviewed Fred K. Schott about new features in Astro. That reminded me that I need to upgrade this site from 2.6.1 to 4.5.6.

Here is a log of the process:

1. pnpm install astro@latest

2. Peer dependency issues

   1. pnpm install typescript@latest
   2. pnpm install @astrojs/mdx@latest
   3. pnpm install @astrojs/svelte@latest
   4. pnpm install svelte@latest

3. Tried pnpm run build

4. Build error on articles: localStorage is not defined

   1. Found a reference to localStorage in a Svelte component in the last page generated by Astro
   2. Remove all direct references to localStorage
   3. That fixed it
   4. Read client:only documentation
   5. Realized that is what I wanted
   6. Reverted changes to Svelte component
   7. Added client:only to MDX files that referenced the component
   8. That fixed it

5. Tried pnpm run build again

6. It worked

7. Netlify build failed:

   9:32:21 PM: Node.js v18.12.1 is not supported by Astro!
   9:32:21 PM: Please upgrade Node.js to a supported version: ">=18.14.1"
   

   1. Updated NODE_VERSION environment variable to LTS 20.11.1
   2. That fixed it

8. Done

I get a little nervous reading about the complexity of Astro--especially because I'm using it to build this simple site. But in my experience, all of the upgrades have gone smoothly. (Edit: they even have an upgrade tool)

The Astro team deserves a lot of credit for engineering a tool that is feature-rich while managing the complexity for the developer. I hope they can continue that as they grow.

Sean McPherson works as a software engineer at Khan Academy, and enjoys playing games and watching soccer. He lives with family in Pittsburgh, PA.