Guide

Update a project

Update Astro with its official tool, review other dependencies, and understand how copied source is maintained.

Choose what you want to update

A generated project has its own dependencies and editable source. There are three separate maintenance tasks:

TaskHow to handle it
Update Astro and installed official integrationsUse Astro’s upgrade tool and migration guides.
Update other dependenciesReview their releases and update the selected packages with your package manager.
Bring in changes to generated components or configurationCompare the source changes and merge them into your project deliberately.

Run dependency commands from the generated project’s root, using the package manager recorded by that project. Choose its matching tab below. Begin with a clean working tree so the resulting changes are easy to review.

Preserve the development server owner

Before changing installed dependencies, record the server’s owner, original command, flags, foreground/background mode and printed local URL. Stop only the instance you are authorized to manage, through its existing terminal, supervisor or Astro background manager. Preserve that launch configuration when restarting after the installation/update. Ordinary source edits use HMR; a build does not inherently require a restart. Do not interrupt a user-owned session without authorization.

For a generated background server, the selected script runner’s run astro dev stop stops that instance, and run dev starts it again. Use the project’s dependency manager for installation/updates; the manager and runtime can differ. After restart, inspect logs and request the exact printed URL with curl --fail --show-error <local-url> (replace the placeholder), or open it and confirm the intended page loads.

A live PID, manager registration, TCP listener and HTTP readiness are separate signals. A port in use alone does not identify this project. If startup reports an existing server but HTTP fails, inspect the owner’s logs, PID command and working directory with adequate process permissions. Restricted PID probes may return EPERM; Astro status can then classify a healthy record as stale and remove it. Status is not guaranteed read-only under restricted process visibility.

Once process visibility is adequate, combine status/logs with the actual HTTP request. Confirm identity before terminating a process. Do not begin with --force, delete/rebuild lock metadata or kill unrelated listeners. Preserve the record and diagnose with the owner when identity remains uncertain. Installing dependencies does not necessarily modify package.json.

Update Astro and its official integrations

Preview the proposed versions first. The tabs show both the dry run and the command to apply the upgrade after review:

npm

Terminal
npx @astrojs/upgrade --dry-run
# After reviewing the proposed versions:
npx @astrojs/upgrade

pnpm

Terminal
pnpm dlx @astrojs/upgrade --dry-run
# After reviewing the proposed versions:
pnpm dlx @astrojs/upgrade

Bun

Terminal
bunx @astrojs/upgrade --dry-run
# After reviewing the proposed versions:
bunx @astrojs/upgrade

Read the relevant Astro upgrade guide before applying changes. @astrojs/upgrade is a temporary executable, not a permanent project dependency. The launcher you use does not change the project’s selected dependency manager.

The latest tool may propose a newer Astro major. This distribution currently starts with Astro 7; review the major-version migration before applying that change. To remain on a particular version, follow Astro’s documented specific-version installation and check compatible official integration versions as well.

Review other dependencies separately

Packages such as Tailwind, Better Auth, Forms and Formatter have their own release notes and APIs. Inspect the project’s installed versions first:

npm

Terminal
npm outdated

pnpm

Terminal
pnpm outdated

Bun

Terminal
bun outdated

Choose the packages to update and review any migration instructions. For example, if Forms is installed, this updates Forms and Formatter within the ranges already declared by the project:

npm

Terminal
npm update @samline/forms @samline/formatter

pnpm

Terminal
pnpm update @samline/forms @samline/formatter

Bun

Terminal
bun update @samline/forms @samline/formatter

Review package.json and your selected manager’s lockfile together. A deliberate major update may need new version ranges and corresponding source changes.

Use a newer generator

Choose the latest generator for a new project or a later addition:

npm

Terminal
npx @samline/astro@latest new-site
npx @samline/astro@latest add themes --dry-run

pnpm

Terminal
pnpm dlx @samline/astro@latest new-site
pnpm dlx @samline/astro@latest add themes --dry-run

Bun

Terminal
bunx @samline/astro@latest new-site
bunx @samline/astro@latest add themes --dry-run

Run the first command from the parent folder for the new site. Run the second inside an existing generated project to inspect a missing feature’s addition. A new generator version affects that operation; previously copied files remain project-owned source.

Review changes to copied source

There is currently no @samline/astro update command. To bring a component or configuration improvement into an existing site, compare the relevant repository change with your current files, merge what applies, and preserve the site’s custom behavior, translations and settings. Re-running add for an installed feature keeps that feature in place.

After any update, run the generated formatter, checks and build with the matching tool:

npm

Terminal
npm run format
npm run verify

pnpm

Terminal
pnpm run format
pnpm run verify

Bun

Terminal
bun run format
bun run verify

Then test the affected page or integration with its actual configuration before publishing the change. The official upgrade tool README and Astro’s documentation remain the references for framework upgrades.