- Docs
- Update a project
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:
| Task | How to handle it |
|---|---|
| Update Astro and installed official integrations | Use Astro’s upgrade tool and migration guides. |
| Update other dependencies | Review their releases and update the selected packages with your package manager. |
| Bring in changes to generated components or configuration | Compare 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
npx @astrojs/upgrade --dry-run
# After reviewing the proposed versions:
npx @astrojs/upgradepnpm
pnpm dlx @astrojs/upgrade --dry-run
# After reviewing the proposed versions:
pnpm dlx @astrojs/upgradeBun
bunx @astrojs/upgrade --dry-run
# After reviewing the proposed versions:
bunx @astrojs/upgradeRead 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
npm outdatedpnpm
pnpm outdatedBun
bun outdatedChoose 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
npm update @samline/forms @samline/formatterpnpm
pnpm update @samline/forms @samline/formatterBun
bun update @samline/forms @samline/formatterReview 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
npx @samline/astro@latest new-site
npx @samline/astro@latest add themes --dry-runpnpm
pnpm dlx @samline/astro@latest new-site
pnpm dlx @samline/astro@latest add themes --dry-runBun
bunx @samline/astro@latest new-site
bunx @samline/astro@latest add themes --dry-runRun 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
npm run format
npm run verifypnpm
pnpm run format
pnpm run verifyBun
bun run format
bun run verifyThen 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.