SveltyCMS is designed to be upgraded easily while preserving your custom collections and configurations. We provide a CLI tool to automate the process, including dependency updates, database migrations, and automated code transformations (codemods).

The Upgrade Process

The upgrade tool performs the following steps:

1. Git Verification: Ensures you are in a valid Git repository.

2. Auto-Stash: If you have uncommitted changes and use the --force flag, the tool automatically stashes them and restores them after the upgrade.

3. Rollback Tag: Creates a local Git tag (e.g., pre-upgrade-2026-04-06-12-00-00) as a safety net before any changes are merged.

4. Upstream Fetch: Fetches the latest changes from the official SveltyCMS repository.

5. Pre-commit Merge: Merges changes into your local branch without committing, allowing you to review.

6. Dependency Refresh: Runs bun install to ensure all new packages are installed. On Windows, npm install is used instead to avoid known bun install corruption issues.

7. SBOM Sync: Runs bun run audit:sbom to regenerate the CycloneDX SBOM (sbom.json) so it matches the updated dependency tree (see Dependency Updates & SBOM below).

8. Codemods: Automatically executes scripts in scripts/codemods/. Scripts starting with an underscore (e.g., _utils.ts) are ignored by the runner.

9. Database & Tests: Runs db:push and test:unit to ensure everything is working correctly.

How to Run the Upgrade

Run the following command in your project root:

bun run scripts/upgrade.ts

Advanced Options

Dependency Updates & SBOM

SveltyCMS ships a dedicated dependency-update flow that keeps the CycloneDX SBOM (sbom.json) in lockstep with the resolved dependency tree:

1. Check for outdated packages: bun outdated
2. Update + regenerate SBOM in one command: bun run update — runs bun update and then bun run audit:sbom, so sbom.json (name + version + SHA-512 hashes per package) always reflects what was actually installed.
3. Safety net: If you change dependencies any other way (native bun update, bun install, bun add, bun remove), the pre-commit hook detects bun.lock/package.json changes and regenerates + stages sbom.json automatically before every commit.

The SBOM feeds vulnerability scanners (e.g., Dependency-Track, Grype) and supports SOC 2 / GDPR Art. 32 supply-chain compliance. See Security Overview.

Note on bun outdated: packages pinned to an exact version (e.g., graphql is pinned to 16.14.2) or released as a new major outside your declared range will appear as “outdated” but are intentionally left untouched by bun update. Review the output and bump package.json deliberately for those.

Codemods

SveltyCMS uses “codemods” to automate the tedious parts of an upgrade. If a new version renames a property in a configuration file or changes a component’s API, a codemod script will automatically update your local files during the upgrade.

Naming Convention

Codemods in scripts/codemods/ follow a specific naming pattern:

• NN-description.ts: Numbered prefix (e.g., 01-migrate-schema.ts) determines the execution order.
• _name.ts: Files starting with an underscore are treated as internal utilities and are not executed by the upgrade runner.

Codemod Utilities (_utils.ts)

The shared utilities module provides reusable helpers used by all codemod scripts:

• MigrationManager — Chains multiple migration rules and tracks which changes were applied per file.
• deepUpsertProperty(obj, path, value) — Inserts or updates a nested property using dot-notation paths, creating intermediate objects as needed.
• validateSchema(obj) — Post-migration validation that checks required fields (name, fields) still exist after transformation.
• upsertProperty / renameProperty — Single-level property insertion, update, and rename operations.

Current Codemods

Best Practices

• Review the Rollback Tag: Before starting, the tool provides a rollback tag. If anything goes wrong, you can return to your previous state using git reset --hard <tag-name>.
• Review Changes: After the script finishes, use git diff to review the changes before committing.
• Resolve Conflicts: If the merge fails, the tool will pause. Resolve conflicts in your editor, git add the changes, then run the upgrade again with --skip-merge.

Troubleshooting

Rolling Back

If the upgrade causes issues, you can roll back to the state before the upgrade started:

# List available rollback tags
git tag --list "pre-upgrade-*"

# Reset to the desired tag
git reset --hard pre-upgrade-YYYY-MM-DD-HH-MM-SS

“bun install” corruption on Windows

If you’re on Windows and bun install produces errors or corrupted node_modules:

1. Delete node_modules (but keep bun.lock)
2. Run npm install instead
3. bun run dev will work normally after npm install

“Merge conflict — manual resolution required”

If conflicts occur:

1. Resolve them in your IDE.
2. git add .
3. Run bun run scripts/upgrade.ts --skip-merge to complete the remaining steps (install, codemods, etc.).

Related

• Getting Started
• Architecture Overview
• Security Overview