Skip to main content
seanmcp.com

Upgrading from Astro v2 to v4


Update March 19, 2024: I missed some issues with static file endpoints that I needed to fix after the upgrade.

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.