Terminal
Terminal/Skill
Walks an existing Strapi app through reviewing breaking changes and upgrading to a new version with the official @strapi/upgrade tool.
By Strapi
Works with
npx skills add strapi/skills --skill strapi-version-upgradeUpgrade a Strapi project to a target version. This skill enforces two hard rules:
@strapi/upgrade tool to perform the upgrade. Never upgrade by manually editing package.json or running npm install @strapi/strapi@x directly.Follow the steps below in order.
Read the project's current Strapi version from package.json (@strapi/strapi under dependencies). If there is no Strapi project in the working directory, stop and tell the user.
Determine the latest published version:
npm view @strapi/strapi dist-tags
The latest tag is the newest stable release. legacy is typically the latest v4.
Establish the target. If the user named a version or release type (major/minor/patch/latest/a specific x.y.z), use it. Otherwise default to latest and confirm with the user.
Classify the jump using semantic versioning: compare the major/minor/patch of current vs. target. Only a change in the major number introduces breaking changes. Minor and patch releases are backward-compatible by definition.
Use the strapi-docs-mcp skill / strapi-docs MCP server if it is available; otherwise fetch the docs directly. Do not skip this step even for patch upgrades.
Query it for the breaking changes between the current and target versions, e.g.:
"What are the breaking changes when upgrading Strapi from
<current>to<target>?"
Quote the exact breaking-change titles and note which are handled by codemods vs. which require manual work.
Fetch the breaking changes page directly (no auth needed). Prefer the flat Markdown form:
https://docs.strapi.io/cms/migration/v4-to-v5/breaking-changes.mdUse WebFetch on the .md URL (append .md to any docs.strapi.io page to get flattened Markdown with nothing hidden in tabs/accordions). If a page 404s as .md, retry the HTML URL.
Do not stop at a generic list from the docs. For each breaking change, grep the project's own source to see which ones actually apply, and turn the summary into a project-specific list. Concretely:
src/index.{js,ts} (the app's register/bootstrap entry) for patterns the breaking changes touch.src/api/**) — the upgrade tool's codemods cover common patterns, but custom logic often uses APIs a breaking change renames or removes.src/api/**/content-types/**/schema.json and src/components/**) for attributes affected by breaking changes — e.g. attribute types that changed, or attribute names that collide with new reserved/system names.package.json and config/plugins.{js,ts} for third-party plugins whose compatibility may be affected.Use each breaking-change title as a search seed (grep for the removed/renamed API, the deprecated option, the reserved name). Report which files match which breaking change so the user sees exactly what the upgrade will touch versus what they'll need to fix by hand.
Remind the user to back up codebase and database before upgrading (default SQLite DB is .tmp/data.db). The upgrade tool also checks for a clean git working tree as an optional requirement, so a committed/clean tree eases rollback.
Offer a dry run first to preview changes without modifying files:
npx @strapi/upgrade <target> --dry
The @strapi/upgrade tool is itself a Node CLI: it runs under whatever Node npx is invoked with, and it declares the same Node requirement as the target Strapi. So the running Node — not just package.json's engines — must satisfy the target's range before you run the tool. If it doesn't, both the upgrade run and the subsequent app boot happen on an unsupported runtime.
Read the currently running Node version (node -v).
Read the Node range the target Strapi supports:
npm view @strapi/strapi@<target-x.y.z> engines
(Cross-check against the docs' recommended Node for that major — Strapi recommends the active LTS.)
If the running Node already satisfies the target's range, continue to Step 5.
If it does not, Node must be upgraded before the upgrade. How you handle this depends on whether the user has a Node version manager — check for one before deciding (look for nvm, fnm, or volta on PATH, and for a .nvmrc / .node-version / Volta field in the repo):
.nvmrc / .node-version / Volta field) so CI and teammates move together.nvm, fnm, or volta), then selecting a Node version inside the target's range. Stop and wait for them to sort the runtime out before continuing.node_modules immediately after switching Node. At that point package.json still pins the old Strapi, so a clean install would rebuild the old dependency tree against the new Node — which, if the ranges are disjoint (below), can fail the engines check or leave native modules built against the wrong ABI, breaking the working state before the tool has moved you forward. The clean reinstall belongs after Step 5, once the tool has rewritten package.json to the target (see Step 7d).npx @strapi/upgrade minor), so that step stays rollback-able; then switch Node into the target's range; then run the major upgrade in Step 5. Only after that upgrade run do you reinstall dependencies.Run the official tool from the project root. Choose the command form that matches the target:
npx @strapi/upgrade latest # newest stable version
npx @strapi/upgrade major # next major (requires being on latest patch of current major first)
npx @strapi/upgrade minor # latest minor+patch in current major
npx @strapi/upgrade patch # latest patch in current minor
npx @strapi/upgrade to <x.y.z> # a specific published version
Notes:
major is gated: the project must already be on the latest patch of its current major. If it isn't, run minor first, then major.to <x.y.z> when latest is blocked by a registry policy (e.g. min-release-age in .npmrc) or when the user wants an exact version. to skips the major-safety check intentionally.--codemods-target <x.y.z>.-y/--yes (auto-confirm prompts), -d/--debug (verbose), -p/--project-path <path> (non-cwd project). Avoid -y/--yes for major jumps — it auto-confirms every prompt, including the major-version safety prompt on latest. Prefer interactive mode (or explicit per-step user approval) unless the user asked for an unattended run.The tool updates dependencies, installs them, and runs codemods for the target version. Do not substitute a manual package.json edit or a bare npm install for this step.
If the install phase fails (e.g. ERESOLVE), first retry with a clean node_modules and lockfile (rm -rf node_modules package-lock.json && npm install) before falling back to any manual dependency edits — a stale lockfile from the old major is the most common cause and a clean reinstall usually resolves it.
engines fieldThe upgrade tool updates dependencies but does not touch package.json's engines field. A stale engines.node range left over from the old major can fail the compatibility check and block install (npm/yarn/pnpm) after the upgrade. (This is the declared range in package.json — distinct from the running Node you checked in Step 4.)
engines from the project's package.json.npm view @strapi/strapi@<target-x.y.z> engines).engines.node is narrower than or incompatible with the target's, offer to replace it with the correct range for the target major, and apply the edit once the user confirms. Leave it alone if it's already compatible.Run these in order. Each destructive or code-changing action pauses for the user to confirm — the user is in charge of every change beyond what the tool applied automatically.
package.json) before restarting the app.If any third-party plugin (from Step 2's package.json/config/plugins scan, or surfaced by install/boot errors) is not compatible with the target Strapi version:
npm view <plugin> versions / its peer-dependency range on @strapi/strapi).If Step 2 found an attribute whose name collides with a new reserved/system name in the target major, a rename is required and renaming a column risks data loss. In that case:
down()). Do not hand-wave this — the ordering and collision rules there prevent both boot failures and silent data loss../database/migrations/ also runs then.package.json to the target, not before: rm -rf node_modules && install. Native modules (better-sqlite3, sharp, …) are compiled against a specific Node ABI; a stale build left over from the old Node is the most common "changed Node and it won't boot" failure and is easily misread as an upgrade bug.