Skip to Content
defold-typescript
Get startedGuidesAPILibraries
CLI

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 folder

Use 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 .defignore makes the Defold editor and bob skip node_modules, .defold-types, and .vscode when they scan the project tree, so tooling and generated-type files are never misread as game resources. game.project boots 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 .collection and a .ts file (a --force synthesis into a directory you have authored), the starter main/main.collection and the seeded main.ts are skipped so your entry files are never clobbered.
  • Add TypeScript. Run inside a folder that already has a game.project and init adds only the TypeScript infrastructure, leaving .script, .collection, .gui_script, .render_script, game.project, and other engine assets untouched. It writes the starter main.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/types and @defold-typescript/cli dependencies to the CLI's own version, migrate a deprecated Biome recommended key, bring forward the Biome schema, pin and .defold-types ignore an earlier scaffold wrote, re-sync the managed AGENTS.md block, and refresh an existing .vscode/defold-debug.ts only 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 for upgrade rather 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 the Next: run <pm> install line 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 minimal
  • default — the opinionated layout you get when you omit --template: a game.project, a main/main.collection, and a src/main.ts whose init returns a small vmath.vector3 example state.
  • minimal — the same project layout with an empty-state src/main.ts (a defineScript whose init returns {}), 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.

Footnotes

  1. src/ is this guide's shorthand and the scaffold's default, not a fixed location. Your source roots are the include globs in tsconfig.json — ["src/**/*.ts"] out of the box, and any list of folders you set; build and watch compile exactly what those globs match, and ignore exclude. ↩ ↩2 ↩3

On this page