Upgrade: Beta to v1.0.0 Stable

This guide walks you through upgrading Velocity from any beta release (v0.1.0-beta through v0.5.0-beta) to the v1.0.0 stable release.

Overview

	Beta (latest)	v1.0.0 Stable
Astro	6.0.0-beta.20	6.0.0
@astrojs/mdx	5.0.0-beta.12	5.0.0
@astrojs/react	5.0.0-beta.4	5.0.0
@astrojs/check	0.9.7-beta.1	0.9.7
@astrojs/sitemap	^3.7.0	^3.7.1

Option A: CLI Upgrade (Recommended)

If you have create-velocity-astro installed:

Update the CLI

npm install -g create-velocity-astro@latest

Run the upgrade
Terminal window
```
pnpm create velocity-astro upgrade
```
The CLI will:
- Download the latest template
- Show what files will change
- Update safe files (components, layouts, lib, styles)
- Bump package.json dependencies to stable versions
- Update your .velocity.json version marker
- Show migration notes relevant to your current version
Install and verify
Terminal window
```
pnpm install && pnpm build
```

Option B: Manual Upgrade

Update package.json dependencies

"astro": "6.0.0-beta.20",
"astro": "6.0.0",
"@astrojs/mdx": "5.0.0-beta.12",
"@astrojs/mdx": "5.0.0",
"@astrojs/react": "5.0.0-beta.4",
"@astrojs/react": "5.0.0",
"@astrojs/check": "0.9.7-beta.1",
"@astrojs/check": "0.9.7",
"@astrojs/sitemap": "^3.7.0",
"@astrojs/sitemap": "^3.7.1",

Install and build
Terminal window
```
pnpm install && pnpm build
```

Update .velocity.json

"version": "0.5.0-beta"
"version": "1.0.0"

Notes for Users on Older Betas

If you’re upgrading from a version earlier than v0.5.0-beta, review these additional guides first:

From v0.4.0-beta

Vitest 2 → 3 migration: Astro 6 bundles Vite 7, which requires Vitest 3.2+. If you have a custom vitest.config.ts, review the Vitest 3 migration guide.
Image defaults changed: Cropping is now enabled by default and images are never upscaled. If images appear cropped unexpectedly, add fit: 'contain' to your Image components.
Heading ID changes: The heading ID generation algorithm changed. Verify any internal anchor links (#my-heading) still resolve correctly.

From v0.3.x-beta or earlier

Follow the existing upgrade guides in order:

Then apply the steps in this guide.

Verify the Upgrade

Run the full verification suite:

pnpm lint && pnpm check && pnpm build

All three commands should complete with zero errors. The stable releases are fully compatible with the existing beta.20 codebase.

Next Steps

Changelog — Full release notes for v1.0.0
Quick Start — Setting up a new project