Upgrade Guide

How to upgrade Notty CMS between versions safely.

For the full distribution and versioning model, see Distribution Model.

General Upgrade Steps

Generated apps do not install @notty/cli by default. Run diagnostics and validation commands on demand with pnpm dlx @notty/cli <command> (or npx @notty/cli <command> if you prefer npm tooling).

1. Check the Changelog

Before upgrading, review the CHANGELOG for breaking changes, deprecations, and migration notes.

2. Update Dependencies

# Update all @notty/* packages to the latest version
pnpm update @notty/server @notty/core

# Or pin a specific version
pnpm add @notty/server@^0.16.0 @notty/core@^0.16.0

Important: Always update @notty/server and @notty/core together — they share the same version line and are designed to work in lockstep.

3. Run the Doctor

pnpm dlx @notty/cli doctor

The doctor command validates your project structure, schema files, config, and dependency versions. It will flag anything that needs attention after an upgrade.

4. Validate Schemas

pnpm dlx @notty/cli check

This checks all JSON schemas in schemas/ and components/ for compatibility with the new version.

5. Start Dev Server

pnpm dev

Notty applies database schema migrations automatically on boot. Watch the console output for migration messages. If a migration fails, the server logs the exact error and rolls back.

6. Test Your API

Verify your custom routes, hooks, and middleware still work. If you have integration tests, run them:

pnpm test

Plugin & Theme Upgrades

Updating Plugins

pnpm update notty-plugin-my-plugin

Check the plugin's changelog for breaking changes. If the plugin targets a newer engines.notty version than your project, you may need to upgrade Notty first.

Validating Plugins

pnpm dlx @notty/cli validate-plugin ./node_modules/notty-plugin-my-plugin

Updating Themes

pnpm update notty-theme-my-theme

Themes follow the same versioning and compatibility rules as plugins.

Version Compatibility

Notty Version	Node.js	Plugin API	Theme API
0.16.x	>= 20	^0.14.0	^0.14.0
0.15.x	>= 20	^0.14.0	^0.14.0
0.14.x	>= 20	^0.14.0	^0.14.0

Breaking Change Policy

Notty follows semantic versioning. During the 0.x pre-release phase:

• Patch versions (0.16.1) — bug fixes only, fully backwards compatible.
• Minor versions (0.17.0) — new features, may include deprecations. Breaking changes are documented and typically accompanied by a migration path.
• Major version (1.0.0) — stable API contract. Breaking changes only in major bumps.

Database Migrations

Notty uses Drizzle ORM with automatic schema synchronization:

• Adding fields to an existing schema — the column is added automatically on next boot.
• Removing fields — the column is kept in the database but ignored by the ORM. To physically drop it, use a custom SQL migration.
• Renaming fields — create the new field, migrate data via a custom script, then remove the old field.

Custom Migrations

For complex data migrations, create a script:

// migrations/001-rename-field.ts
import { drizzle } from 'drizzle-orm/...';

async function migrate() {
  // Your migration logic here
}

migrate();

Run it before starting the server:

npx tsx migrations/001-rename-field.ts
pnpm dev

Rollback

If something goes wrong:

1. Stop the server.
2. Restore your previous package.json and lock file from git.
3. Run pnpm install to restore previous versions.
4. If a database migration has already run, restore from your latest backup.

Tip: Always take a database backup before upgrading in production.

Getting Help

• Check the troubleshooting guide
• Run pnpm dlx @notty/cli diagnose for a detailed project health report
• Open an issue on GitHub with the output of pnpm dlx @notty/cli doctor