Upgrade NocoBase Core

This guide explains how to upgrade the NocoBase Core framework and related dependencies used by your application. Work in the application's source project, verify the result, then deploy your app using your existing deployment method.

What an upgrade changes

A project generated by create-app contains both NocoBase package dependencies and framework source copied into the project, such as application entry points, routing, layouts, configuration, and testing tools. An upgrade merges changes from a newer template while preserving the features you have built.

Updating every @nocobase/* package alone is insufficient, and a newly generated app must not overwrite your existing project. Packages have independent versions; use the dependency combination declared by the target template.

Your application's package.json contains metadata similar to this:

{
  "nocobase": {
    "templateKind": "app",
    "templatePackage": "@nocobase/app-template-default",
    "defaultTemplateVersion": "1.0.0-beta.81"
  }
}

templatePackage identifies the source template. defaultTemplateVersion records the template release already merged into your application. The application's own version identifies your business application release, not its Core version. Changing the metadata alone does not perform an upgrade.

Before you begin

• Review and commit existing changes to Git, record the current commit, and perform the upgrade on a separate branch.
• Identify the target release and read its release notes, including compatibility requirements for Node.js, your package manager, databases, and custom plugins.
• Prepare a restorable database backup. Preserve runtime configuration, secrets, file storage, and the matching previous application build.
• Rehearse in an isolated verification environment. To test retained data, restore database and file backups there, and ensure the environment cannot connect to production databases or send real business notifications.

Starting the new application may apply migrations automatically. Complete backups, migration checks, and required data preparation before its first startup.

Choose one of the following paths, then complete the shared verification and deployment steps.

With an agent

Open your coding agent in the application root. The application carries its upgrade guidance in .agents/skills/nocobase-app-upgrade/SKILL.md, synchronized when dependencies are installed. Check that the agent can read it and AGENTS.md; the request itself can focus on the upgrade target, features to preserve and verification.

If the Skill is missing, install dependencies using the project's lockfile. If installation scripts were disabled, run:

pnpm nocobase skills sync

Use this prompt, replacing the target with an explicit version if needed:

Please upgrade the NocoBase Core used by this application to the newer release on its current release channel.

First inspect the project and give me a concrete plan without editing it:
- State the current and target versions. If already at the target, say no upgrade is needed; do not downgrade.
- Explain affected features, dependencies, configuration and plugins, and which changes need my decision.
- Explain how existing business features, themes, permissions and data will be preserved, and how to recover if something goes wrong.
- Identify irreversible data changes or historical records that need repair, explaining their cause and impact.

After I confirm the plan, follow the project's upgrade guidance and make changes on a separate branch.
Do not overwrite the application, clear the database or treat a version-number change alone as a completed upgrade.
Verify old data, sign-in, ordinary-user permissions and task operations in a separate test environment.
Report the before-and-after versions, adjustments, verification results and remaining work.
This task prepares and verifies the upgraded project; confirm production deployment separately.

When reviewing the plan, check that your features are preserved, removed plugins are no longer needed, and the database can be recovered. Review the actual changes and verification results before deployment.

Without an agent

1. Identify the baseline and target

Run these commands in the application source root. Subsequent commands use variables from the same Bash session:

git status --short
git rev-parse HEAD
node -p "JSON.stringify(require('./package.json').nocobase, null, 2)"

TEMPLATE=$(node -p "require('./package.json').nocobase.templatePackage")
BASE=$(node -p "require('./package.json').nocobase.defaultTemplateVersion")
npm view "$TEMPLATE" dist-tags --json

Review and commit outstanding changes first. If the template source or baseline is missing, establish it from project history before continuing. templateKind: app alone does not distinguish Default from Examples; do not guess a baseline.

Beta applications normally stay on beta; stable applications normally use latest. The latest tag is neither guaranteed to be newer than beta nor guaranteed to point to a stable release. Confirm other prerelease channels individually.

For a beta application, resolve the target once and retain that exact version:

TARGET=$(npm view "$TEMPLATE@beta" version)
printf 'Template: %s\nBase: %s\nTarget: %s\n' "$TEMPLATE" "$BASE" "$TARGET"

For an explicit release, assign its confirmed full version to TARGET instead. Compare versions using semantic version ordering: if equal, no upgrade is needed; if older, stop rather than implicitly downgrading. Once you have confirmed a newer target, create a branch:

git switch -c "chore/upgrade-core-$TARGET"

2. Fetch both template releases

Download into a temporary directory, outside your application source:

WORK=$(mktemp -d)

for VERSION in "$BASE" "$TARGET"; do
  ARCHIVE=$(npm pack "$TEMPLATE@$VERSION" --silent --pack-destination "$WORK")
  mkdir -p "$WORK/$VERSION"
  tar -xzf "$WORK/$ARCHIVE" -C "$WORK/$VERSION" --strip-components=1
done

diff -rq "$WORK/$BASE" "$WORK/$TARGET"

Exit code 1 from diff means differences were found and is expected. Compare the two published templates first: comparing your application directly with the new template cannot distinguish your business changes from upstream changes.

3. Merge source and dependencies individually

For each changed file, read the baseline, target, and application versions. For example, inspect route changes with:

diff -u "$WORK/$BASE/client/routes.ts" "$WORK/$TARGET/client/routes.ts"
diff -u "$WORK/$BASE/client/routes.ts" client/routes.ts

The first comparison shows template changes; the second shows your existing customizations. Integrate the template's new behavior while preserving task routes, settings entries, permission declarations, and other business code.

Before removing a file or dependency dropped by the target, check business code, configuration, and tests for usage. For an approved NocoBase package removal, run pnpm nocobase package remove <package-name> while the dependency is still declared, so dependencies, Skills, and plugin registrations are cleaned up together. You must still handle business references yourself. If an older CLI lacks this command, follow the compatibility procedure in the project's upgrade Skill.

Package updates can also introduce plugin migrations without changes to application migration files. Read the affected packages' upgrade notes for data prerequisites, API changes, and replacements for removed capabilities.

4. Install dependencies and synchronize Skills

After completing the source merge, set nocobase.defaultTemplateVersion to the pinned target version, then run:

pnpm install
pnpm dedupe
pnpm nocobase skills sync

Review and retain lockfile changes. pnpm dedupe consolidates compatible dependency resolutions. Use pnpm why <package-name> to investigate conflicts, then reconcile the target template's constraints with custom dependencies. Do not bypass conflicts by deleting the lockfile or upgrading every dependency to its latest release.

5. Check and apply database migrations

First complete the static checks and automated tests in the next section. Confirm configuration points to the isolated verification environment, then run both read-only checks with the target CLI before starting the new version:

pnpm nocobase db apply --dry-run --json
pnpm nocobase db repair --dry-run --json

The first command lists pending migrations and seeds. The second checks checksum changes for executed tasks. The apply preview neither executes migration bodies nor checks checksums, so these checks do not replace each other. Both use the default connection unless specified otherwise. For multiple connections, add --connection <name> for each relevant connection and keep subsequent execution scoped consistently.

If the checksum preview proposes changes, match each one to the release notes before proceeding. Actual db repair is not a routine upgrade step: it updates all mismatching recorded checksums in the selected connection, without rerunning migrations or repairing business data. Stop on unexplained changes and follow the upgrade Skill's database guidance. Do not edit historical files, reset the database, or ignore the error.

Once backups are restorable, checksum checks are complete, and required data preparation is finished, apply migrations in the isolated verification environment:

pnpm nocobase db apply --json

Production migrations belong to the deployment procedure. Do not point a development checkout at production to run these commands.

Verify the upgrade

Core upgrades can affect the entire application. For this example, review the existing project scripts and include the task suite described in Build your first app:

pnpm typecheck
pnpm lint
pnpm format:check
pnpm test
pnpm build

Run these commands in the source project, with tests using isolated databases. If existing test configuration needs adjustment for newer tooling, fix it while preserving coverage; skipping failing tests is not a passing result.

After database preparation, run pnpm dev and use its printed Local: URL to verify:

• Administrators can sign in; task pages and system settings work; language and custom themes behave as expected.
• Existing tasks retain titles, assignees, completion state, and due dates. Creation, complete/reopen actions, filtering, and pagination still work.
• Ordinary users can access only permitted pages and records. Read-only users still cannot write, including through direct API calls.
• Data survives refreshes and restarts. Affected plugin features, background jobs, and integrations pass their corresponding checks.

Verify the features your application actually implements. Configure a separate test application and credentials, then run pnpm test:e2e for browser tests; see Build your first app for setup. pnpm test does not include browser tests.

Deploy and recover

Commit source and lockfile changes after verification. Record the baseline, target, merge decisions, and verification results. Rebuild and publish through your existing deployment method:

• Deploy with Docker
• Deploy with app-installer
• Deploy to Studio

Keep configuration and data backups that match the previous build. Rolling back code does not undo database migrations. If the previous runtime cannot use the upgraded schema, restore matching database and file backups and account for business writes made since those backups.

If release notes require historical checksum corrections, coordinate backups, repair, migration, and failure recovery in one maintenance procedure. With app-installer, do not run db repair independently before relying on a normal upgrade's automatic recovery: the installer's later backup may already contain the new checksums, which the previous runtime may reject. External databases also require their own backup and recovery arrangements.

Verification scope

This guide explains template merging and upgrade checks. The current getting-started example was reconciled with the npmjs.org-published 1.0.0-beta.81 template dependencies and passed tests and a build. This does not establish an upgrade path from every older version. Verify release-specific changes, existing data, permissions, and recovery in an isolated environment for each actual upgrade.