Upgrade and Migration

Astro treats upgrading as two related workflows: updating installed packages and adapting application code when a release changes behavior. For ordinary patch, minor, and many major-version updates, the supported first step is the temporary command-line package @astrojs/upgrade. It is designed to upgrade Astro together with official integrations, which keeps common projects from drifting into mixed dependency versions. For migrations that include breaking changes, use the command to move package versions first, then read the relevant major-version upgrade guide and changelog to make any required code changes.

Sources: packages/upgrade/README.md, packages/upgrade/package.json

Purpose and Scope

This page documents the repository-backed upgrade surface, not every historical migration step. The @astrojs/upgrade package is the public upgrade helper. Its README describes it as a command-line tool for upgrading Astro integrations and dependencies, and explicitly says it should be run as a temporary executable rather than added as a project dependency. That detail matters because the upgrade tool is not an application runtime library; it is a maintenance command that inspects a project, resolves target versions, and then runs the installation path appropriate for the detected package manager.

The official documentation frames the same workflow as the recommended way to update Astro and official integrations together. Manual upgrading remains valid when you need direct control over exact dependency names or versions, such as installing astro@latest with selected integrations or pinning a specific version. In practice, teams should prefer @astrojs/upgrade for routine version refreshes, then switch to manual commands when release notes require a staged migration, when a nonstandard package manager setup is involved, or when a project intentionally holds an integration at a different version.

Sources: packages/upgrade/README.md

Relevant Source Files

• packages/upgrade/README.md — user-facing documentation for running @astrojs/upgrade, including npm, Yarn, and pnpm commands and the optional release tag argument.
• packages/upgrade/package.json — package metadata for @astrojs/upgrade, including its executable entry point, export map, dependencies, scripts, published files, and Node engine requirement.
• packages/upgrade/src/index.ts — source entry point for the upgrade CLI, including argument cleanup, help handling, the verify/install step sequence, signal handling, and named exports for internal actions.
• .changeset/README.md — repository-level release-management note explaining that Changesets is used to version and publish packages in this multi-package repository.

Supported Upgrade Workflow

Start with the package-manager command that matches the project. The README supports npm through npx, Yarn through yarn dlx, and pnpm through pnpm dlx. These commands execute the package temporarily, so there is no need to commit @astrojs/upgrade into dependencies or devDependencies. That keeps the project manifest focused on runtime and build-time dependencies while still allowing the upgrade tool to be fetched at the moment it is needed.

# npm
npx @astrojs/upgrade
 
# Yarn
yarn dlx @astrojs/upgrade
 
# pnpm
pnpm dlx @astrojs/upgrade

After the command updates package versions, run your project’s normal validation path: install if your package manager did not already do so, start the dev server, build, and run tests. The upgrade command solves dependency selection; it does not replace migration review. Major-version upgrade guides should be read after dependency updates because they explain behavioral changes, removed APIs, minimum Node requirements, and code transformations that cannot be inferred safely from a package manifest alone.

Sources: packages/upgrade/README.md, packages/upgrade/src/index.ts

Version Tags and Migration Targets

By default, @astrojs/upgrade resolves packages against the latest tag. The README also documents a positional tag argument for resolving against another distribution tag. This is useful for testing a beta release before a major version lands, validating an application against upcoming behavior, or preparing migration branches ahead of a scheduled release. Passing beta changes the target release channel without changing the basic command shape.

# Upgrade Astro and official integrations to the beta tag
npx @astrojs/upgrade beta
pnpm dlx @astrojs/upgrade beta
yarn dlx @astrojs/upgrade beta

Treat tag-based upgrades as branch-oriented work. Because beta and prerelease channels can expose future breaking changes, run them in a separate branch, capture build and test failures, and compare results with the matching upgrade guide or release notes. If you only need a specific package version, the official manual-upgrade workflow remains more explicit: install astro@x.y.z and any integration versions directly with your package manager.

Sources: packages/upgrade/README.md

CLI Implementation Details

The source entry point exports an async main() function. It first normalizes command-line arguments by removing a bare --, a compatibility step noted in the source comment for npm behavior. It then calls getContext() with the cleaned arguments. If the context indicates help was requested, the CLI prints help and returns. Otherwise, it runs two steps in order: verify and install. That sequence reflects the expected lifecycle of an upgrade command: gather and validate package information before applying dependency changes.

The same module installs simple SIGINT and SIGTERM handlers that exit the process, and it calls process.exit(0) after the step sequence completes. It also re-exports getContext, install, setStdout, verify, collectPackageInfo, and resolveTargetVersion. These exports make the source entry point more than a black-box binary: adjacent tests or tooling can exercise the context, verification, target-resolution, and install phases individually without invoking the whole command through a shell.

Sources: packages/upgrade/src/index.ts

Package Reference

The package metadata shows that the distributed tool is bundled to upgrade.mjs, while development starts from src/index.ts. The dependency list also describes the tool’s concerns: CLI presentation, package-manager detection, semantic-version handling, and terminal links. When debugging an upgrade issue, this helps narrow the failure domain. A package-manager detection problem, a semver target-resolution problem, and an install-process problem are separate classes of issues even though they appear to the user as one command.

Sources: packages/upgrade/package.json

Release and Migration Context

Astro is a multi-package repository, so migrations often involve more than the astro package alone. Official integrations, scaffolding tools, and supporting packages can move together. The .changeset README identifies Changesets as the release tool used for versioning and publishing in multi-package and single-package repositories. That release-management context explains why the upgrade command focuses on coordinated package updates: the repository publishes a family of packages, and applications frequently depend on several of them at once.

For application maintainers, a safe migration plan is therefore layered. First, choose the target release channel: usually latest, sometimes beta, or a specific version through manual package-manager commands. Second, run @astrojs/upgrade or the equivalent manual install commands for Astro and official integrations. Third, review the changelog and the relevant major-version guide for breaking changes. Finally, validate the application in the same environments that matter for production, including local development, build output, adapter deployment, and any server-side routes or integrations.

Sources: .changeset/README.md, packages/upgrade/README.md

Next Steps

If you are upgrading an existing project today, create a branch, run npx @astrojs/upgrade, pnpm dlx @astrojs/upgrade, or yarn dlx @astrojs/upgrade, and commit the resulting lockfile and manifest changes separately from code migrations. Then read the relevant major-version upgrade guide and make source changes in focused commits. If the project uses official integrations, check their versions alongside astro; if it uses custom integrations or deployment adapters, include those in build and deployment validation before merging.