Upgrades

mainsdk upgrade moves an app to the next MainSDK release with one command, so apps built on a 0.x API are not stranded. It runs in your own tooling and is free.

It moves every mainsdk and @mainsdk/* package together, applies the release's codemods and main.yaml key moves, refreshes main.lock, runs check and your tests, and lists the few steps that need a person. During 0.x a minor release may change an API.

npx mainsdk upgrade --to latest --plan    # what would change, and nothing written
npx mainsdk upgrade --to latest           # branch, bump, install, codemods, sync, check, tests, pull request
npx mainsdk upgrade --check               # exit 1 when a security release is not installed

upgrade:
  driver: npm-registry

Quick start

npx mainsdk upgrade --to latest --plan    # what would change; nothing is written
npx mainsdk upgrade --to latest           # branch, bump, install, codemods, sync, check, tests, pull request
npx mainsdk upgrade --check               # exit 1 when a security release is not installed

--plan reads the installed version from your lockfile and the target from the registry's dist-tags. It prints, in version order, every change between the two: each codemod, each manual step, each main.yaml move that applies to your file, and every call site of a call the target removes. With --to <exact version> and release notes the installed CLI already has, it plans offline.

Configuration

upgrade has no main.yaml section. It takes command-line options.

What you get

1. Refuses a dirty working tree or a folder outside git (MAIN-UPGRADE-0001) and changes nothing.
2. Creates the branch chore/upgrade-mainsdk-<version> from the current commit.
3. Sets every MainSDK dependency in every workspace package.json to the exact target version, and runs your package manager's install (the one your lockfile names).
4. Runs the newly installed CLI as mainsdk upgrade --continue --from <old version>, so the target release's notes and codemods do the rest: the main.yaml moves in every layer file (comments and order kept), then the codemods.
5. Runs sync, check and your test script, commits once with the versions, codemods and manual steps in the message, and opens a pull request. A failure gives MAIN-UPGRADE-0006, keeps the branch and opens a draft that lists each failure. The default branch never moves.

Codemods

Codemods run on the TypeScript compiler API loaded from your own typescript; the CLI bundles no compiler. Each is idempotent and touches only your source, never node_modules or generated output. With no typescript, or a file that doesn't parse, the change becomes a manual step with file and line (MAIN-UPGRADE-0003).

Security releases

mainsdk upgrade --check exits 1 with MAIN-UPGRADE-0005 when the registry has a release newer than yours whose notes say security: true. The answer is cached for 24 hours under .mainsdk/cache/. Offline it reports MAIN-UPGRADE-0004 as info and exits 0. mainsdk check shows the cached result and never calls the network for it, and reports MAIN-UPGRADE-0002 when your MainSDK packages are at different versions.

Release notes

Each release of the CLI package ships upgrade/<version>.json for itself and every earlier version:

{
  "version": "0.6.0",
  "security": false,
  "changes": [
    { "id": "share-expires-in", "kind": "breaking", "summary": "share() takes expiresIn instead of expires", "codemod": "share-expires-in" },
    { "id": "realtime-base", "kind": "manual", "summary": "Move custom realtime paths under realtime.base", "steps": "Set realtime.base to the path your proxy forwards" }
  ],
  "main-yaml": [ { "from": "share.expiry", "to": "share.max-expiry" } ]
}

kind is breaking (with a codemod), manual (with steps) or info. A change may list calls it removes and exports it changes. In the MainSDK repository the release gate fails with MAIN-UPGRADE-0010 when a removed or changed export has no breaking or manual entry, or a codemod has no passing before/after fixture.

Errors and checks

Each code's cause and fix is in check codes.

Swapping drivers

upgrade has no driver. It reads the installed version from your lockfile and the target from the registry's dist-tags, and uses the package manager your lockfile names.

Testing

upgrade runs your own test script after the bump. Run npx mainsdk upgrade --to latest --plan first to see every change without writing anything; with an exact --to version and release notes the installed CLI already has, the plan runs offline.

Next

• Upgrade MainSDK walks through a full upgrade.
• Check codes lists every MAIN-UPGRADE-* code.
• Dependencies checks your lockfile, licences and advisories.