Upgrade Kumiko dependencies

ForApp developerFramework developer

LevelAdvanced

Use this workflow when upgrading a Kumiko app. It keeps installed package versions, framework migrations, code changes, and deploy order together.

Applies to: apps that use @cosmicdrift/kumiko-bundled-features.

Before you start

Work from the app directory.
Have a clean Git working tree or know which local changes you are carrying.
Have a local database available if the app’s integration tests need one.
Keep the previous deployed image and a database backup available for rollback.

The app-facing binaries are kumiko-schema and kumiko-upgrade. Run them from the app workspace:

cd <app>
bunx kumiko-schema
bunx kumiko-upgrade --json

kumiko-schema comes from @cosmicdrift/kumiko-dev-server. kumiko-upgrade ships with both @cosmicdrift/kumiko-dev-server and @cosmicdrift/kumiko-cli. The kumiko command from @cosmicdrift/kumiko-cli covers scaffolding and kumiko check; see CLI.

Check the upgrade notes

kumiko-upgrade reads the framework core and bundled-feature changelogs. It reports breaking changes, improvements, and fixes since the installed version. Use --from for an explicit baseline:

bunx kumiko-upgrade --verbose
bunx kumiko-upgrade --json

The CLI normally uses .kumiko/upgrade-state.json as its baseline and falls back to the installed package version when that marker does not exist. Use --from VERSION only when you intentionally want a different review baseline. The JSON form is suitable for CI or an upgrade checklist. Review every breaking entry before changing dependencies.

When the installed framework package includes a codemod, start with a dry run:

bunx kumiko-upgrade --apply --dry-run

Only apply after reviewing the proposed files:

bunx kumiko-upgrade --apply

The command runs codemods in version order and writes .kumiko/upgrade-state.json after a successful apply. Review the codemod diff before committing it together with the marker.

Manual steps

A breaking entry without a codemod is a manual step. --apply records it in the marker under pendingManual and lists it on every run, with an id such as 0.352.0:2abbcda3. Make the change by hand, then close the step with a short note on what you did:

bunx kumiko-upgrade --resolve 0.352.0:2abbcda3 --reason "switched 4 imports to kumiko-types/temporal"

If the change does not affect your app, add --not-applicable. The marker keeps the decision, the reason and a timestamp under resolvedManual. The flags are described on kumiko upgrade.

Example: switch the Temporal import

Since 0.352.0 apps import Temporal from the framework instead of from temporal-polyfill. The module uses the native Temporal when the runtime has it and falls back to the polyfill otherwise. There is no codemod for this step.

Replace every value import of temporal-polyfill:

import { Temporal } from "@cosmicdrift/kumiko-types/temporal";

Remove side-effect imports of temporal-polyfill/global. Type-only imports and /// <reference types="temporal-polyfill/global" /> may stay.

Run bunx @cosmicdrift/kumiko-cli check. Its guards report any direct import that is left:

[temporal-polyfill] direct temporal-polyfill import — use import { Temporal } from "@cosmicdrift/kumiko-types/temporal";

Close the step with --resolve 0.352.0:2abbcda3 --reason "...", or with --not-applicable if the app never imported the polyfill.

Guards that enforce the marker

Once .kumiko/upgrade-state.json exists, the upgrade-state guard checks it. The guard is part of the repository checks that kumiko check runs. It fails in two cases:

The marker is older than the installed packages and breaking entries are pending. Run bunx kumiko-upgrade --apply.

A manual step is still open:

Open manual upgrade step 0.352.0:2abbcda3 (0.352.0): Apps must import Temporal from @cosmicdrift/kumiko-types/temporal … Resolve it with `kumiko-upgrade --resolve 0.352.0:2abbcda3 --reason "<what you did>"` or mark it with `--not-applicable`.

The guard needs the kumiko-upgrade binary. Keep @cosmicdrift/kumiko-cli or @cosmicdrift/kumiko-dev-server in the app’s dependencies. Without a marker the guard does not apply.

If your Git pre-push hook calls kumiko-pre-push from @cosmicdrift/kumiko-guards, the hook runs the same guard whenever the marker exists and refuses the push while it fails:

[pre-push] upgrade-state guard failed — refusing push

Update the dependencies

Keep the Kumiko packages on the same release line. The common set is:

@cosmicdrift/kumiko-framework
@cosmicdrift/kumiko-bundled-features
@cosmicdrift/kumiko-dev-server
@cosmicdrift/kumiko-renderer
@cosmicdrift/kumiko-server-runtime

For 0.x releases, a caret range may not cross a minor version. Update the versions explicitly, then install and inspect the lockfile:

bun install
git diff -- package.json bun.lock

Generate and review the schema migration

The app’s kumiko/schema.ts exports the entity metadata used by the runtime. Generate SQL from that metadata after the dependency and feature changes:

bunx kumiko-schema generate upgrade-YOUR_VERSION
git diff -- kumiko/migrations/

Review the SQL and any .rebuild.json marker. A managed-table recreation can empty a projection and trigger a rebuild. Do not edit an already-applied migration to repair a later change; create a new migration.

Apply the checked-in migration locally:

bunx kumiko-schema apply

schema apply is idempotent. The standalone kumiko-schema command applies the checked-in SQL; the production bundle’s bun /app/kumiko.js schema apply also loads the app feature registry and retries queued projection rebuilds. App boot checks the migration journal and stops on drift; boot does not apply migrations.

Test the app

Run the checks from the app repository:

bun run typecheck
bun run test
bunx @cosmicdrift/kumiko-cli check
bun run build

If the app has browser or integration tests, run the relevant suites as well. Resolve migration, boot, and embed failures before building the production image.

Deploy order

Build and tag the new image immutably.
Apply the checked-in migrations with the same image and production environment values.
Confirm migrations and projection rebuilds completed successfully.
Start the new image and run its health and smoke checks.
Keep the previous image tag and backup until the release is accepted.

A previous application image may not understand a new database shape. Test schema rollback separately; reverting only the image does not undo a database migration.