Astro releases often, and a site that stays close to the latest version is far easier to look after than one that jumps two majors at a time. The steps are the same whether you run one site or a hundred.
Check what you’re running
Look at the version in your lockfile rather than package.json, because a range like ^5.1.0 doesn’t tell you what’s installed. Check your Node version too: new major Astro releases can raise the minimum.
Read the upgrade guide for major versions
Patch and minor releases are usually routine. Major releases can remove things, so read the upgrade guide on the Astro docs for each major version you’re crossing. If you’re two majors behind, go one at a time, and read both guides.
Use the upgrade tool
Astro’s upgrade tool updates Astro and its official integrations together:
npx @astrojs/upgradeWith pnpm:
pnpm dlx @astrojs/upgradeBuild and check
Run the same checks your CI runs. At a minimum:
astro check
astro buildThen compare the build output. The list of generated pages is a good first test: if a page has disappeared or a URL has changed, you want to find out now.
Ship it through a pull request
Put the upgrade on its own branch, with nothing else in it. If something goes wrong after it ships, you can revert one commit. If your host builds preview deployments, click around the preview before you merge.
Make it routine
The easiest upgrade is a small one. Dependabot or Renovate can open update pull requests for you, and Em Region shows which sites have fallen behind across your fleet.