Upgrading Projects

The upgrade command updates a Velocity project to a newer release. Run it from your project root:

pnpm create velocity-astro@latest upgrade

Moving from 1.x? Follow the v1 to v2 guide, which has manual steps. Moving to 2.4 from an earlier 2.x release? See Upgrading to 2.4, then Upgrading to 2.5.

Flags

Flag	Description
--dry-run	Show what would change without applying it
-y, --yes	Skip confirmation prompts
--ref <tag|branch>	Upgrade to a specific Velocity tag or branch
--template <dir>	Upgrade from a local Velocity checkout

Preview an upgrade first:

pnpm create velocity-astro@latest upgrade --dry-run

With npm, pass flags after --:

npm create velocity-astro@latest upgrade -- --dry-run

What Happens

1. Read .velocity.json. Without it, the CLI stops, because it can’t tell how the project was created.

2. Warn about uncommitted changes. Commit first so you can review the upgrade as a diff.

3. Fetch Velocity and check requirements. Unlike scaffolding, an unsupported Node version stops the upgrade.

4. Rebuild the template with your options. The CLI replays the variants from .velocity.json, so a minimal or i18n project is compared with minimal or i18n files.

5. Compare files and show a summary, then ask you to confirm.

6. Apply changes: back up conflicts, copy files, and update package.json dependencies.

7. Show manual steps for the versions you’re moving across.

Which Files Change

velocity-manifest.json sorts files into two groups.

Safe files are owned by Velocity and updated by upgrades. These include src/components/ui/, src/components/layout/, src/components/seo/, src/components/hero/, src/layouts/, src/lib/, the design tokens and themes, the core i18n files such as src/i18n/ui.ts, src/pages/404.astro, the agent files in .agents/ and .claude/skills/, and scripts/check-agent.mjs.

Protected files are yours and never overwritten. These include:

• astro.config.mjs, .env and AGENTS.md
• src/config/site.config.ts, src/config/nav.config.ts, src/config/consent.config.ts and src/config/collections.ts
• src/styles/theme.css and src/components/site/
• src/pages/ (except 404.astro), src/views/, src/content/, src/assets/ and src/actions/
• src/i18n/locales.mjs and src/i18n/translations/
• src/components/blog/, src/components/landing/ and src/components/patterns/
• tests/

A release can add new files to these folders, but existing files stay as they are. The CLI lists protected files it can’t update so you can merge changes yourself.

Breaking releases can replace or remove specific files once, because the old version can’t work with the new one. These appear in --dry-run, and the CLI saves your versions to .velocity-backup/<old version>/ first.

Conflicts

If you edited a safe file, the CLI detects it from the hashes in .velocity.json. It saves your version to .velocity-backup/<old-version>/, installs the new version, and lists what it backed up. Reapply your changes from the backup.

Tip

To change a built-in UI string, override it in src/i18n/translations/<locale>.ts rather than editing ui.ts. Upgrades won’t touch your override.

The Ownership Baseline

create-velocity-astro 2.1 and later write .velocity/baseline.json when they scaffold or upgrade a project. It records the Velocity-owned files as they are after the upgrade, so check:agent can warn when one is edited later, before the next upgrade replaces the edit. Commit it.

With an older CLI, write it yourself once on a clean checkout:

npm run check:agent -- --write-baseline

After Upgrading

pnpm install
pnpm validate

validate ends with check:agent, which reports anything the upgrade left for you to fix, such as hardcoded text in a page or a form with no delivery configured.