Init
init scaffolds a Defold project with a TypeScript surface — or adds TypeScript
to an existing Defold project. It writes the files and stops; run bun install
afterward (it prints the reminder).
bunx @defold-typescript/cli@latest init path/to/project # new project at that path
bunx @defold-typescript/cli@latest init . # scaffold / add to the current folderUse the @latest tag when you scaffold: bunx caches binaries, and init is
what writes your @defold-typescript/types version pin, so a stale cache would
pin an older release.
Tip
init also writes the agent contract — AGENTS.md + CLAUDE.md — when
the project has none, so a freshly scaffolded project needs no separate
init-agents run. A contract already there is left
untouched by a plain re-init; init . --force re-syncs its managed block, and
so does upgrade.
A destination is required
init takes an explicit destination — there is no implicit "current folder"
default, so it never scaffolds where you did not mean to. Pass a path to create
(or add to) that folder, or . to target the folder you are already in. The same
rule applies to init-agents.
Two modes
init detects whether the destination already holds a game.project:
- New project. In an empty or non-Defold folder it synthesizes a full Defold
project (
game.project,main/main.collection,input/game.input_binding) alongside the TypeScript surface (src/main.ts1,tsconfig.json,package.json,.gitignore,.gitattributes,.defignore,biome.json,mise.toml,.vscode/) and the agent contract (AGENTS.md,CLAUDE.md). The.defignoremakes the Defold editor and bob skipnode_modules,.defold-types, and.vscodewhen they scan the project tree, so tooling and generated-type files are never misread as game resources.game.projectboots the collection and points[input]at the binding, so a fresh scaffold loads in Defold with no missing references. If the target folder already holds both a.collectionand a.tsfile (a--forcesynthesis into a directory you have authored), the startermain/main.collectionand the seededmain.tsare skipped so your entry files are never clobbered. - Add TypeScript. Run inside a folder that already has a
game.projectandinitadds only the TypeScript infrastructure, leaving.script,.collection,.gui_script,.render_script,game.project, and other engine assets untouched. It writes the startermain.ts1 only for a fresh scaffold shape, never dropping one into a project you have already authored. See Add TypeScript to an existing project.
Both modes also write the agent contract — AGENTS.md (a managed block delimited
by HTML-comment markers) and CLAUDE.md (@AGENTS.md) — when it is absent. A
plain re-init leaves a contract you already have untouched; re-syncing the managed
block is the --force path (see the flag below), which is also what
upgrade runs for you. Content you add
above or below the markers always survives. This is the same contract the
standalone init-agents verb
writes.
Both modes also write src/test/tsconfig.json and src/test/env.d.ts, for tests and
helpers that need Bun's runtime, when they are absent;
upgrade adds them to a project that has none. Both modes also add
src/test to the root exclude, unless an entry already names that folder
(./src/test and src/test/ count), so the game program never takes in the folder,
and build skips it. src/test/tsconfig.json extends the
root config and names no types of its own, so a test sees the same Defold types,
.d.ts declarations and pinned surface as the game. It includes src/test/ plus every
root include pattern rebased onto the project folder, and its exclude restates
every other root entry the same way, since inheriting the root's exclude would leave
out its own folder. It sets outDir: null so a root outDir does not break it, and
plugins: [] so the editor plugin reports no build diagnostics on code build never
compiles. src/test/env.d.ts references bun-types, the package init lists at an
exact version, which adds Bun's types (bun:test, node:*, Bun) to that program
only, so they never reach the code build compiles. Type-check the tests with
tsc --noEmit -p src/test/tsconfig.json. A test next to its module instead starts with
/// <reference types="bun-types/test" />, which adds bun:test alone, so the root
tsc --noEmit checks it (see build). An existing
src/test/tsconfig.json that extends the root gains each missing setting, keeps every
value you set, and has its include and exclude replaced only when they select other
files than the rebased root lists, so init --force keeps it in step after a root
include or exclude change; one warning names what changed. init also warns when
the installed Bun is older than its bun-types pin, when your exact bun-types pin
differs from the installed Bun, and when test/ or tests/ holds Bun tests.
Test with Bun explains each setting, each
warning and where a test goes.
Scaffolded config files (tsconfig.json, biome.json, .vscode/, mise.toml)
merge additively into anything you already have, so re-running init refreshes the
managed blocks without disturbing your own entries. For tsconfig.json that means
an existing compilerOptions.typeRoots, types, and include survive — including
the .defold-types root and pinned engine surface that
resolve writes — while the @defold-typescript/tstl-plugin
language-service plugin is unioned in exactly once. The scaffold also sets
noEmit: true when your project sets none, so a bare tsc type-checks without
writing a .js file beside each source, while build still emits Lua; a noEmit
you set yourself is kept. tsconfig.json and the .vscode/ JSON files are read as
JSON with comments and edited in place, one key or list entry at a time, so your
comments, layout and other keys (extends, references, files) survive. Settings
count as TypeScript reads them through extends: a managed default is written only
when no config in the chain sets it, and an inherited include, exclude or
plugins list is restated in the root only when a managed entry is missing from it. For mise.toml it means the
refresh rewrites only description and run inside each managed
defold-typescript:* task, so keys you add to one — an alias, a depends, an
env, a comment of your own — are carried across every re-run. A managed task
the scaffold stops shipping is removed with whatever you added to it.
The file rules the scaffold manages read your layout off tsconfig.json
include1 rather than assuming src/. Generated component output
(.ts.script, .ts.gui_script, .ts.render_script and .ts.editor_script, with
their .map files) is ignored by its .ts. suffix, which no hand-authored Defold
path has, so it needs no folder at all; every .lua.map is ignored anywhere in the
project, since Defold never reads one; biome.json lints exactly the patterns you
compile, skips the generated .defold-types folder, and names the schema of the
Biome version package.json pins exactly, so a fresh biome check is clean; and
Lua.workspace.ignoreDir claims one of your source roots only when nothing under
it is hand-authored Lua, reporting the file it found when it skips. A generated
.lua module is therefore tracked like any other file — set
compilerOptions.outDir to keep build artifacts out of the tree. Re-running
init retires the older src-shaped rules from a project that still carries the
complete set, leaving every entry you added in place. init --force likewise
updates a Biome schema URL, a Biome dependency range and the .defold-types
ignore that an earlier scaffold wrote. An exact Biome pin older than the CLI's,
with a biome.json schema naming the same version, moves to the CLI's Biome
together with that schema; any other Biome version or schema stays as you chose
it. The one exception is a biome.json you have hand-edited to hold comments: it
cannot be rewritten without destroying them, so it is reported and left for you
to update, and its Biome pin stays with it.
The starter follows the same configuration. init derives one starter path from
include and compilerOptions.outDir: the seeded main.ts lands under the
first include pattern that admits it, the generated main/main.collection
names the component build emits for that file, and greenfield
detection looks for the same pair rather than a src literal. A project whose
include is ["game/**/*.ts"] therefore gets game/main.ts and a collection
pointing at /game/main.ts.script, and adding "outDir": "out" moves that
component path to /out/main.ts.script in step with the compiled output. A
tool-added exclude entry for that starter is pruned on every re-run, while an
entry naming a root you have since moved off is left alone as yours. When no
configured pattern reaches a writable main.ts inside the project — an exact
path naming some other file, such as ["foo/bar.ts"], or a pattern that only
points outside it — init writes no starter and leaves the collection with no
component, reporting the patterns it searched; an exact path that names the
starter itself, ["src/main.ts"], seeds one normally.
Flags
--template <name>— pick a starter template when creating a new project (see below). Rejected in add-TypeScript mode, where there is nothing to synthesize.--force— re-scaffold in place: repin the managed@defold-typescript/typesand@defold-typescript/clidependencies to the CLI's own version, migrate a deprecated Biomerecommendedkey, bring forward the Biome schema, pin and.defold-typesignore an earlier scaffold wrote, re-sync the managedAGENTS.mdblock, and refresh an existing.vscode/defold-debug.tsonly when its normalized checksum proves it is generated. An absent launcher stays absent; a customized one stays byte-identical and produces a warning naming the path and checksum mismatch. To upgrade a project, reach forupgraderather than driving this flag by hand — it resolves the latest CLI first, so an older binary cannot re-scaffold the project backwards.--suppress-install-reminder— silence theNext: run <pm> installline when you install through your own tooling.--json— emit the result envelope. See Agent runbooks.
Starter templates
Pick a template with --template <name> when creating a new project:
bunx @defold-typescript/cli@latest init path/to/project --template minimaldefault— the opinionated layout you get when you omit--template: agame.project, amain/main.collection, and asrc/main.tswhoseinitreturns a smallvmath.vector3example state.minimal— the same project layout with an empty-statesrc/main.ts(adefineScriptwhoseinitreturns{}), for starting from a blank script.
Both templates differ only in the synthesized entry script; the shared TypeScript
surface (tsconfig.json, package.json, .gitignore, .gitattributes,
.defignore, biome.json, mise.toml, and the .vscode/ files) is identical.
Omitting --template is equivalent to --template default. An unknown name fails
fast and lists the valid templates:
defold-typescript init: unknown template "foo". Valid templates: default, minimal.