Update

voltro update upgrades an app to the latest framework release. It does three things in order:

1. Bump every @voltro/* dependency in package.json to the target version.
2. Install with your project's package manager — see Which package manager below.
3. Run the codemods shipped with the target version — automatic source rewrites for any breaking API change, plus printed manual steps for anything that can't be automated.

voltro update                 # bump to the latest published version, install, run codemods
voltro update --to 0.4.0      # pin an explicit target version
voltro update --dry-run       # preview the bump + which codemods would run — writes nothing
voltro update --force         # allow a dirty working tree (not recommended)
voltro update --exact         # pin exact versions (drop the ^ / ~ range prefix)
voltro update --help          # every flag — always answered, even on a dirty tree

# Recover the codemods after a MANUAL version bump (no bump, no install):
voltro update --codemods-only --from 0.3.0            # re-run codemods 0.3.0 → installed
voltro update --codemods-only --from 0.3.0 --to 0.4.0 # explicit delta

#In a workspace, the whole workspace moves

Run voltro update anywhere inside a workspace — a pnpm-workspace.yaml, or a workspaces field in an ancestor package.json — and every member package.json that declares @voltro/* is bumped to the same version, with the install running once at the workspace root.

This is not a convenience. Your api and your web app share generated types (the rpcGroup) and a session cookie shape; if the api moves to 0.6.0 while apps/web and packages/ui-* stay on 0.5.0, the mismatch shows up as a runtime decode error in the browser, not as a build failure. Half-upgraded is the worst state to be in, so voltro update never leaves you there.

The plan output — and --dry-run — lists every file it will touch:

voltro update: 0.5.0 → 0.6.0
  workspace: /repo (4 package.json with @voltro/* deps)
  package.json
    @voltro/cli: ^0.5.0 → ^0.6.0
  apps/api/package.json
    @voltro/cli: ^0.5.0 → ^0.6.0
    @voltro/database: ^0.5.0 → ^0.6.0
  apps/web/package.json
    @voltro/client: ^0.5.0 → ^0.6.0
  packages/ui-admin/package.json
    @voltro/web: ~0.5.0 → ~0.6.0
  package manager: pnpm
  install runs in: /repo

A standalone (non-workspace) project is unaffected: its own package.json, its own install, in place.

#Already bumped by hand? Recover the codemods

If you bump @voltro/* versions in package.json yourself and install first, a plain voltro update sees the installed version already equals the target and reports "already on X — nothing to do" — skipping the codemods AND the printed manual steps for the delta you actually crossed. To re-apply them without touching package.json again:

voltro update --codemods-only --from <version-you-came-from>

--codemods-only (alias --run-codemods) runs the codemods + manual notes for [from, to] against the already-installed tree — no version bump, no install. --to defaults to the installed version; pass it to pin an explicit delta. --from also works on a normal voltro update to override the auto-detected source version.

#The clean-tree guard

Codemods rewrite your source, so you need a clean diff to review afterwards. voltro update refuses to run on a dirty git working tree — commit or stash first. Use --dry-run to preview without touching anything, or --force to override the guard (you accept a mixed diff).

--help / -h is answered before the guard, so voltro update --help prints the flag list even on a dirty tree. The same holds for voltro doctor --help.

#If the install fails

The bump is written before the install runs, so a failed install leaves your package.json on the target version — and no codemods applied. voltro update says so explicitly, because the codemods for a jump ship inside the target version: a failed install never put them on disk, so there is nothing that could have run them. Fix the install, run it, then apply the codemods you are missing with the command the failure message prints for you:

voltro update --codemods-only --from 0.5.0 --to 0.6.0

#What gets bumped

Every @voltro/* entry in dependencies and devDependencies — in every workspace member, see above — with the range style preserved (^0.3.0 stays caret, ~0.3.0 stays tilde) unless you pass --exact. Non-registry specs (workspace:*, catalog:, link:, …) are left untouched — they're already resolved by your monorepo or catalog.

#Which package manager

voltro update never assumes npm. It resolves your project's package manager in this order, starting in the app directory and walking up to the repo root:

1. The packageManager field in a package.json (the corepack standard) — authoritative, wins over any lockfile.
2. A lockfile at that level — pnpm-lock.yaml, yarn.lock, bun.lock / bun.lockb, package-lock.json.
3. npm, only when nothing declares one.

Walking up matters in a workspace: a scaffolded Voltro project keeps its lockfile at the monorepo root, so running voltro update from apps/api still finds pnpm rather than falling back to npm and running npm install against a pnpm workspace.

The same resolved manager is used for the registry lookup of the latest version (pnpm view, yarn npm info, bun pm view), so a private or scoped registry configured in your .npmrc / .yarnrc.yml is honored. npm view is only a last-resort fallback.

#Codemods

Each breaking public-API change in a release ships a codemod. When you update across that release, voltro update applies it:

• A transform codemod rewrites your source automatically — renamed imports, moved modules, changed component props, restructured call signatures. The rewrite is scoped to files that actually import the affected symbol.
• A manual codemod prints written steps during the update, only when your app is affected — for changes that can't be mechanically transformed (a behavior change, a descriptor/executor restructure). Where the affected sites can be found but the fix needs your judgment, a codemod inserts // TODO(voltro-migration): … markers so you can locate every spot.

Codemods that span multiple versions run in order (e.g. upgrading 0.2.0 → 0.4.0 runs the 0.3.0 and 0.4.0 codemods in sequence). Review the resulting diff before committing.

#The database is separate

voltro update does not touch your database. Framework-owned _voltro_* tables (workflow runs, schedules, …) are reconciled by the declarative differ, not by codemods: when a release changes one of those tables, your next voltro db apply (or voltro dev boot, which auto-applies) picks up the change. After an update:

voltro update
voltro db apply        # reconcile any changed framework tables — NOT voltro db migrate
# then run your typecheck to confirm your code compiles against the new API

Use voltro db apply (the declarative diff), not voltro db migrate (the imperative file-runner) — only the former reconciles framework tables.

#Where to read next

• Migrate — schema changes end-to-end
• Build & start — production paths