Skip to Content
defold-typescript
Get startedGuidesAPILibraries
CLI

Upgrade

upgrade is the verb that moves a project to the latest toolchain.

bunx @defold-typescript/cli@latest upgrade

Tip

update is a synonym — both spellings run the same verb, so you never have to remember which one this CLI chose.

What it does

upgrade always resolves the latest published @defold-typescript/cli from the npm registry first, then branches on how it compares to the CLI that is running:

  • The running CLI is behind — it hands off to the newer one, which re-scaffolds the project in place. An older binary must never re-scaffold from its own templates: it would exit successfully while moving the project backwards.
  • The running CLI is already the latest — it re-scaffolds in place directly, with no hand-off.

Either entry point therefore lands on the same place — the latest templates and the latest pins — whether you invoke @latest from outside the project or the copy already installed in it. The re-scaffold is init --force, and the verb finishes by running your package manager's install so the refreshed pins are actually on disk.

The summary line reads <from> -> <to>, where <from> is the @defold-typescript/cli version the project had before the run and <to> is the resolved latest. It adds (already latest; re-scaffolded managed files) only when the project was already on <to>, and reads none -> <to> when no earlier version is found.

What it refreshes, and what it never touches

The re-scaffold refreshes the managed files: it re-pins the managed @defold-typescript/types and @defold-typescript/cli devDependencies to the new CLI's version, refreshes the managed mise.toml task block and the managed AGENTS.md block, and reconciles tsconfig.json, adding noEmit: true when the project sets none. Configs are edited in place, so comments, layout and keys such as extends, references and files survive, and a setting inherited through extends counts as set. A project with no src/test/tsconfig.json gets the Bun test config init writes; an existing one that extends the root gains each missing setting and has its include and exclude brought in step with the root's, and src/test joins the root exclude when no entry names it. Each of those edits, an installed Bun that is older than the CLI's bun-types pin or differs from the project's exact pin, and a test/ or tests/ folder holding Bun tests is reported in warnings; see Test with Bun. If .vscode/defold-debug.ts already exists and its normalized checksum matches a generated launcher — including an unmodified legacy launcher whose line endings became CRLF — it is refreshed too. An absent launcher stays absent.

It never clobbers files you authored. An entry script you have written — src/main.ts — is left exactly as it is; the scaffold reports it as skipped rather than overwriting it. Notes you keep outside the AGENTS.md markers, your own [tools] and [tasks.*] entries in mise.toml, and your other tsconfig.json settings all survive the upgrade untouched. Inside a managed mise.toml task the refresh rewrites only the two keys the scaffold authors — description and run — so a key you added there, such as an alias or a depends, survives too. The upgrade never touches defold-typescript.lock either; only resolve writes it.

What it does to your defold-target pin

The upgrade repairs the defold-typescript namespace in package.json rather than resetting it:

  • A valid defold-target pin is left untouched — it round-trips byte for byte, so upgrading the toolchain never silently moves your Defold API surface.
  • A legacy defold-version or channel key is migrated to defold-target, keeping its value, and you get a warning naming the key that moved.
  • If both a legacy key and a valid defold-target are present, the legacy key is dropped and the defold-target pin wins.
  • A project with no pin at all has defold-target seeded with the current stable version.

Upgrading the toolchain and moving the Defold API surface are separate decisions. See Pinning the Defold target for the pin's own lifecycle — how to choose a version or a release channel, and how the surface is materialized.

Flags

  • --json — emit the upgrade result as a single JSON object for agents and scripts. See Agent runbooks.

Pass --json when a script or an agent runs the upgrade:

bunx @defold-typescript/cli@latest upgrade --json
{
  "command": "upgrade",
  "ok": true,
  "written": ["package.json", "tsconfig.json", "..."],
  "from": "0.4.1",
  "to": "0.5.0",
  "handedOff": true
}

from is the @defold-typescript/cli version the project had before the upgrade — the installed copy in node_modules, else the version in its package.json pin — and is absent when neither exists. to is the resolved latest, and handedOff says whether a newer CLI did the re-scaffold.

written lists the managed files the re-scaffold touched. When handedOff is true it is the list the newer CLI reports for the re-scaffold it performed, read back from the delegated run; when handedOff is false it is the running CLI's own list. If a launcher checksum is unknown, the upgrade still succeeds: warnings names .vscode/defold-debug.ts and says it was preserved, and that path is absent from written. Delete the file and run defold-typescript setup-debug to replace a customized launcher explicitly.

Upgrading is the one command that needs the network. If the registry is unreachable, the run fails — ok is false with a non-zero exit — rather than quietly re-scaffolding against the version you already have. See the upgrade runbook for the agent-facing procedure.

As a mise task

The scaffold writes this verb as a mise task, so once your project's mise.toml is on disk the same upgrade is reachable as:

mise run # and pick defold-typescript:upgrade
# or
mise run defold-typescript:upgrade

The task carries no version tag, so mise runs the @defold-typescript/cli that init pinned as a devDependency — the same version bunx would resolve with @latest.

On this page