`upgrade`

Upgrade VexBlocks packages to the latest version

Usage

npx @vexblocks/cli upgrade [packages...] [options]

Description

The upgrade command updates your VexBlocks packages to the latest version from the repository. It intelligently handles file updates while preserving your custom configurations and data.

How It Works

Check Manifest

Reads vexblocks.json to see which packages are currently installed and their versions.

Fetch Latest Version

Queries the GitHub repository to get the latest release version.

Show Changes

Displays a changelog showing what's new in the latest version.

Confirm Upgrade

Prompts you to confirm before proceeding with the upgrade.

Update Files

Downloads and replaces managed files while protecting your custom configurations.

Update Manifest

Updates vexblocks.json with the new version numbers and timestamps.

Options

Option	Type	Description
`--yes`, `-y`	boolean	Skip confirmation prompts
`--force`	boolean	Force upgrade even if already on latest version
`--cwd`	string	Working directory for the command

Examples

Upgrade All Packages

npx @vexblocks/cli upgrade

Checks for updates and upgrades all installed packages.

Upgrade Specific Packages

npx @vexblocks/cli upgrade cms backend

Only upgrades the specified packages.

Skip Confirmation

npx @vexblocks/cli upgrade --yes

Automatically proceeds with the upgrade without prompting.

Force Reinstall

npx @vexblocks/cli upgrade --force

Reinstalls packages even if you're already on the latest version.

Protected Files

During upgrades, the following files are never overwritten to preserve your custom work:

packages/backend/vexblocks.config.ts - Your CMS schema definitions
packages/backend/.env - Environment variables
packages/backend/.env.local - Local environment variables
packages/cms-shared/src/types/generated.ts - Your generated types from schemas
Any files in convex/schema.ts (your custom tables are preserved)

Safe Upgrades: Your content schemas, generated types, and configurations are always protected during upgrades.

Managed Files

Managed files are marked with a header and will be updated during upgrades:

/**
 * @vexblocks-managed
 * This file is managed by VexBlocks CLI.
 * DO NOT EDIT - Changes will be overwritten on upgrade.
 * Version: 1.0.0
 */

These include:

CMS dashboard components and pages
Shared utilities and hooks
Type generator scripts
Core CMS functions in the backend

Important: Avoid editing managed files. If you need custom behavior, extend or override them in non-managed files.

Changelog

Before upgrading, you'll see a changelog of what's new. For example:

Upgrading from v1.0.0 to v1.2.0

Changes in v1.2.0:
  • Added media library with Cloudflare Images support
  • Improved type generation performance
  • Fixed schema validation edge cases

Changes in v1.1.0:
  • Added visual editing capabilities
  • New field types: URL and YouTube URL
  • Better error handling in CMS dashboard

After Upgrading

After a successful upgrade:

Review the changelog to see what's new
Run pnpm install to update dependencies
Regenerate types: pnpm generate-types
Test your CMS locally with pnpm dev
Check for any breaking changes in the changelog

Tip: Always review the diff before upgrading to see exactly what will change.

Rollback

If you need to rollback after an upgrade, the CLI doesn't provide automatic rollback. Instead:

Use version control (git) to restore previous versions
Or reinstall the previous version using npx @vexblocks/cli add --overwrite with the old version

Recommendation: Always commit your changes to git before running upgrades.

Troubleshooting

Already on Latest Version

If you see "Already on the latest version", but want to reinstall:

npx @vexblocks/cli upgrade --force

Conflicts with Local Changes

If you've modified managed files, the upgrade will overwrite them. Save your changes separately before upgrading.

Missing Manifest File

If vexblocks.json is missing, run:

npx @vexblocks/cli init

This will recreate the manifest based on existing packages.

upgrade