--- url: https://toolchain.dbx.studio/guide/migrations/v2-v3.md --- # Migrating from v2 to v3 **v3** is a correctness and cleanup release. Release notes [here](https://github.com/deltabox-studio/toolchain/releases/tag/v3.0.0). Full changelog [here](https://github.com/deltabox-studio/toolchain/blob/main/CHANGELOG.md#300-november-2026). ## Table of contents * [Migrating from v2 to v3](#migrating-from-v2-to-v3) * [The most important breaking changes](#the-most-important-breaking-changes) * [Some of the smaller changes](#some-of-the-smaller-changes) * [Breaking changes](#breaking-changes) * [Deprecations](#deprecations) * [New features](#new-features) * [Behaviour changes](#behaviour-changes) * [Recommended upgrade steps ](#recommended-upgrade-steps) ## The most important breaking changes * The `tsdown` workspace rename to `pack`. * The redesigned config-generator programmatic API. * The config CLI program runtime replacing the commander-based CLI assembly. * The `dbx()` Vite plugin becoming the preferred config path (available from the `@deltabox/toolchain/vite` subpath as usual). * Vite+ (`vite-plus`) replacing the separate `vite`, `vitest` and `tsdown` dev dependencies (it bundles those tools behind `vp`). * `@deltabox/toolchain` packages releasing independently instead of in lockstep. * Vite+ projects configuring `pack`, `test` and `run.tasks` in `vite.config.*` instead of `tsdown.config.*`, `vitest.config.*` and `turbo.json`. * `fmt`/`lint` moving into `vite.config.*` in Vite+ mode. ## Some of the smaller changes * Improved changelog and release notes formatting. * Managed `tsconfig.json` now declaring `include`/`exclude`/`compilerOptions.types` from extended tsconfig. * UTF-8 BOM support (great for shells). * Dockerfiles that build from a fresh scaffold. * Scaffold-only Docker generation. * `--online` for online templates. * Stricter nested/configless inheritance and VS Code discovery. * The `dbx.config.*` format itself is unchanged, so most projects only need to update the dependency and re-run `dbx sync`. * Idempotent CI releases. ## Breaking changes ### The `tsdown` workspace is now `pack` The workspace package `@deltabox/toolchain-tsdown` is renamed to `@deltabox/toolchain-pack`, and the umbrella subpath `@deltabox/toolchain/tsdown` becomes `@deltabox/toolchain/pack`. The workspace directory moves from `packages/tsdown` to `packages/pack` and the commitlint scope changes from `tsdown` to `pack`. The underlying bundler is still tsdown, so `baseTsdownConfig` and `createPostBanner` keep their shape. Replace the import specifier: ```diff [tsdown.config.ts] -import { baseTsdownConfig } from '@deltabox/toolchain/tsdown'; +import { baseTsdownConfig } from '@deltabox/toolchain/pack'; ``` and the workspace dependency for maintainers/contributors: ```diff [package.json] -"@deltabox/toolchain-tsdown": "workspace:*", +"@deltabox/toolchain-pack": "workspace:*", ``` `createTsdownConfig` now takes one options object instead of an `(overrides, banner)` pair: ```diff [tsdown.config.ts] -const config = createTsdownConfig({ format: ['cjs'] }, { name: 'Myapp' }); +const config = createTsdownConfig({ + overrides: { format: ['cjs'] }, + banner: { name: 'Myapp' }, +}); ``` ### Vite+ projects: `pack`, `test` and `run.tasks` live in `vite.config.*` **This only applies when the project uses Vite+** (`vite-plus` and Vite+'s `vite.config.*`). If the project is not on Vite+, keep the standalone `tsdown.config.*`, `vitest.config.*` and `turbo.json` files as they are. In a Vite+ project, the bundler, test runner and task runner read their configuration from `vite.config.*`. Move each standalone config into the matching Vite+ block, then delete the old file: ```diff [tsdown.config.ts → vite.config.ts] # tsdown.config.ts -import { defineConfig } from 'tsdown'; - -export default defineConfig({ - entry: ['src/index.ts'], - dts: true, - format: ['esm', 'cjs'], -}); # vite.config.ts +import { defineConfig } from 'vite-plus'; + +export default defineConfig({ + pack: { + entry: ['src/index.ts'], + dts: true, + format: ['esm', 'cjs'], + }, +}); ``` ```diff [vitest.config.ts → vite.config.ts] # vitest.config.ts -import { defineConfig } from 'vitest/config'; - -export default defineConfig({ - test: { - include: ['src/**/*.test.ts'], - environment: 'node', - }, -}); # vite.config.ts +import { defineConfig } from 'vite-plus'; + +export default defineConfig({ + test: { + include: ['src/**/*.test.ts'], + environment: 'node', + }, +}); ``` ```diff [turbo.json → vite.config.ts] # turbo.json -{ - "tasks": { - "build": { - "dependsOn": ["^build"], - "outputs": ["dist/**"] - } - } -} # vite.config.ts +import { defineConfig } from 'vite-plus'; + +export default defineConfig({ + run: { + tasks: { + build: { + command: 'vp build', + cache: { output: ['dist/**'] }, + }, + }, + }, +}); ``` Vite Task derives cross-package order from `package.json` dependencies, so turbo's `^build` is not needed. A task name cannot also be a `package.json` script: move the script into the task (or keep the script and skip the task definition) so the name is declared once. In a `dbx()` plugin project, add `pack` / `test` / `run.tasks` to the existing `defineConfig` next to the `plugins` field; do not replace the plugin config. In config mode, put the same keys under `toolchain.vite` in `dbx.config.*` and let `dbx sync` write the Vite shim. ### The `dbx()` Vite plugin is the default config path New scaffolds are configured through the `dbx()` Vite plugin. Import it from the `@deltabox/toolchain/vite` subpath: `vite-plugin-dbx` is not published yet, so the standalone package name is not available to install. ```diff # invalid -import { dbx, DBX_TASKS } from '@deltabox/toolchain-vite'; # correct +import { dbx, DBX_TASKS } from '@deltabox/toolchain/vite'; ``` The v2 `@deltabox/toolchain-vite` workspace is now `vite-plugin-dbx`, and the umbrella subpath `@deltabox/toolchain/vite` re-exports it. A managed `vite.config.*` shim is only written when the project declares its own `vite` section. In plugin mode the whole toolchain config lives in `vite.config.*`; there is no `dbx.config.*` to author: ```diff [vite.config.ts] +import { defineConfig } from 'vite-plus'; + +import { dbx } from '@deltabox/toolchain/vite'; + +export default defineConfig({ + plugins: [ + dbx({ + toolchain: { + project: { name: 'app' }, + fmt: true, + lint: true, + }, + }), + ], +}); ``` `dbx.config.*` remains fully supported as the non-Vite fallback, so an existing `dbx.config.*` project does not need to move. If you generate projects programmatically, expect the generated `vite.config.*` to carry the plugin instead of a separate `dbx.config.*`. ### Vite+ is the single dev dependency **v3** no longer installs `vite`, `vitest` or `tsdown` for you. `vite-plus` is the single dev dependency and provides `vp` (Vite, Vitest, Oxfmt, Oxlint, Rolldown and tsdown); it is not bundled into `@deltabox/toolchain` at runtime. Replace the individual dev dependencies with `vite-plus` and use `vp` / `vp run` for those commands (declare it in the monorepo root, not in every single workspace): ```diff [package.json] { "devDependencies": { - "tsdown": "catalog:", - "vite": "catalog:", - "vitest": "catalog:" + "vite-plus": "catalog:" }, "scripts": { - "build": "tsdown", - "test": "vitest run", - "lint": "oxlint .", - "format": "oxfmt ." + "build": "vp build", + "test": "vp test", + "lint": "vp lint", + "fmt": "vp fmt" } } ``` Workspace packages are released **individually** now: each public `packages/*` workspace has its own version and `CHANGELOG.md`, and the release workflow publishes any package whose version is not on npm yet. A consumer that depends on a published subpackage should track that package's version instead of the umbrella's. ### Git hooks use the Vite+ dispatcher When `ci.changelog` is enabled, `dbx sync` writes the `commit-msg` hook to `.vite-hooks/commit-msg` on a Vite+ project (it used to be `.husky/commit-msg`); projects without Vite+ keep the husky fallback. To migrate: ```sh yarn remove husky rm -rf .husky git config --unset core.hooksPath # only if it still points at .husky/_ ``` Replace `"postinstall": "husky"` with `"postinstall": "vp hooks enable"`, then run `vp hooks enable` to install the `.vite-hooks/_` dispatcher. Add `.vite-hooks/* text eol=lf` to `.gitattributes` on Windows. Staged checks move to Vite+ too: add `.vite-hooks/pre-commit` running `vp staged` and a `staged` block in the root `vite.config.ts` (`staged: { '*': 'vp check --fix' }`). ### Config generator programmatic API The engine keeps the v2 `createConfigEngine({ schema })` shape, but v3 reshapes the surrounding API: * The ambient env declarations are now `dbx-env.d.ts` (previously `env.d.ts`). Update the `include`/`files` entries in your tsconfigs if you referenced the old file name. * Runtime loading uses `parseConfig`, `parseEnvConfig` and `parseCliConfig`, plus `collect` and `loadConfig` / `loadConfigAsync` for file-backed configs. The source-specific `loadEnvConfig*`, `loadCliConfig*` and `loadFileConfig*` family (with `Sync`/`Async` variants) selects the file+env, file+CLI or file-only source set explicitly. The old `parseEnvTree` + `envString`/`envInt`/`envBool` accessors and `applyOverrides` remain available, but are legacy; prefer the parsers so env, CLI and overrides are validated through the schema. * The engine groups its generators: `engine.env` (and `engine.env.types`), `engine.types`, `engine.markdown` (`.cli`, `.env`, `.file`), `engine.cli` (`.generate`, `.options`, `.program`), `engine.jsonSchema` and `engine.configJson`. `configCommands({ engine })` now also exposes `config:all`, and the standalone `generateConfig*` functions return content unless you pass an output path. * The high-level CLI program is now part of the public API: `engine.cli.program.create()` returns a runnable `ConfigProgram` (with `createCommand()` for one command), and `createConfigProgram(commands, options?)` builds one from framework-agnostic `CliCommand[]`. `commander` is no longer used or exported. The standalone `generateConfigProgram(schema, options)` returns the generated command descriptors without building a program. * JSON Schema generation can preserve Zod's `$ref`/`$defs` graph (`preserveDefs: true`), and the markdown/CLI generators expose more frontmatter, scope and reference options. Static schema defaults are also new. The `engine.*` generator methods are grouped now: ```diff [scripts/generate-config-reference.ts] -engine.writeConfigTypes({ outputDir: 'types' }); +engine.types.write({ outputDir: 'types' }); -engine.writeEnvTypes({ outputDir: 'types' }); +engine.env.types.write({ outputDir: 'types' }); -engine.writeMarkdown({ outputDir: 'docs/reference/configuration' }); +engine.markdown.write({ outputDir: 'docs/reference/configuration' }); -await engine.writeJsonSchema({ output: 'config.schema.json' }); +await engine.jsonSchema.write({ output: 'config.schema.json' }); -engine.buildConfigJson(); +engine.configJson.build(); ``` The runtime side moves from the `parseEnvTree` + `env*` accessors to the schema parsers: ```diff [src/config.ts] -import { envInt, envString, parseEnvTree } from '@deltabox/toolchain/config'; +import { loadConfigAsync } from '@deltabox/toolchain/config'; -const tree = parseEnvTree(process.env, 'MYAPP_'); -const serverConfig = { - host: envString(tree, 'host', '0.0.0.0'), - port: envInt(tree, 'port', 3000), -}; +const config = await loadConfigAsync({ + cwd: process.cwd(), + parser: serverConfigSchema, + source: 'env', + envPrefix: 'MYAPP_', +}); ``` And the ambient env declarations change file name: ```diff [tsconfig.json] { "include": [ "src", - "types/env.d.ts" + "types/dbx-env.d.ts" ] } ``` If you only consume the generated files, re-run the generators; if you imported the engine, update the calls to the grouped API and the runtime parsers. ### CLI command descriptors and program runtime v3 replaces the commander-based CLI assembly with the config program runtime. Custom CLIs now build the same program the `dbx` binary uses: ```ts import { configCommands } from '@deltabox/toolchain/config'; const program = engine.cli.program.create(() => configCommands({ engine }), { name: 'myapp', version: '1.0.0', globalOptions: [{ flags: '--json', description: 'Print JSON.' }], disableColors: ({ color }) => color === false, }); await program.invokeAsync(process.argv.slice(2)); ``` * Rename `ToolchainCommand` / `ToolchainOption(s)` annotations to `CliCommand` / `CliOption(s)`. Wrap inline descriptors in `defineCliCommand()` from `@deltabox/toolchain/shared`; this preserves the literal `options` tuple so `run` values are inferred. The `CliOptionValues` type exposes the same shape directly. * `engine.cli.program.create()` builds schema-derived commands with typed `run({ config, values, context })`; `createCommand(scope, spec)` builds one config-backed command and `createCommand('name', spec)` builds a runtime-only one. The callback may be async. `engine.cli.generate()` / `.options()` remain the low-level option generators. * If you used the v3 beta program names, `engine.cli.program.generate()` is now `create()` and the old `engine.cli.program.command()` builder is now `createCommand()`. The chain's `.command()` method for subcommands is unchanged. * A built program exposes `invoke()` / `invokeAsync()`, `argv()`, `withContext()`, `globalOption()` / `globalOptions()`, `hook()` / `hooks()`, `bin`, `formatHelp()`, `formatError()` and `configure()`. `invoke()` throws when a handler, hook or `disableColors` resolver is async; use `invokeAsync()`. * `configCommands()` remains library-only; `dbx` does not register a `config:*` group because each command needs a consumer-bound `ConfigEngine`. * A command's `bin` field executes a relative/absolute binary instead of the in-process handler; `argv` overrides the invocation arguments for `program.invoke()`. ### Oxc configs live in `vite.config.*` in Vite+ mode In a Vite+ project, `dbx sync` no longer writes standalone `.oxfmtrc.json` / `.oxlintrc.json` files. The formatter and linter options live in the Vite config (`toolchain.vite.fmt` / `toolchain.vite.lint`, or the root `fmt`/`lint` sections), which Vite+ reads directly. If an existing Vite+ project has standalone `.oxfmtrc.json` / `.oxlintrc.json` files, fold them into the Vite config with `dbx migrate --from oxc --write`; `dbx sync` will no longer write or prune them: ```diff [.oxfmtrc.json] -{ - "printWidth": 100, - "singleQuote": true -} ``` ```diff [.oxlintrc.json] -{ - "rules": { - "no-console": "warn" - } -} ``` ```diff [vite.config.ts] export default defineConfig({ plugins: [ dbx({ toolchain: { + fmt: { oxc: { printWidth: 100, singleQuote: true } }, + lint: { oxc: { rules: { 'no-console': 'warn' } } }, }, }), ], }); ``` ### Project templates are one module per template The monolithic template module is gone. The supported programmatic surface from `@deltabox/toolchain/project` (also re-exported by the umbrella) is: ```ts import { createProjectTemplateFiles, isProjectTemplateId, PROJECT_TEMPLATE_IDS, type ProjectTemplateId, } from '@deltabox/toolchain/project'; ``` Look a template up through `PROJECT_TEMPLATE_IDS` / `createProjectTemplateFiles` instead of importing a shared `qol` helper. ### Docker plans expose their copy sources `resolveDockerPlan()` now returns `installSources` — the exact files the Dockerfile copies before installing dependencies. Code that constructs a `DockerPlan` by hand must provide it; prefer `resolveDockerPlan()` + `dockerFiles()` instead: ```diff -const plan: DockerPlan = buildPlan(); +const plan = resolveDockerPlan({ + cwd: process.cwd(), + packageManager: 'yarn', +}); ``` ```diff const plan: DockerPlan = { runtime: 'node', - // ... + installSources: ['package.json', 'yarn.lock', '.yarnrc.yml'], + // ... }; ``` ## Deprecations These APIs still work in v3, but are deprecated or kept only as compatibility aliases. The explicit schema/type deprecations are `toolchain.biome`, `meta.env`, `meta.path` and `generateEnvTypes`; the rest are legacy aliases kept for existing projects. Prefer the replacement; they may be removed in a future major. ### Configuration * **`toolchain.biome`** — deprecated in favour of `toolchain.fmt.biome` and `toolchain.lint.biome`. `biome.overrides` still writes `biome.json`, and `biome.vscode` still controls the Biome VS Code settings; `dbx sync` warns with `deprecated.section.biome`. See [Formatting](/guide/formatting). * **`vite.shimImport: 'vite-plugin-dbx'`** — the legacy plugin specifier is still accepted, but generated shims use `@deltabox/toolchain/vite`. See [Vite plugin](/guide/vite-plugin). * **`tokens.yarnVersion`** — legacy alias for `tokens.packageManagerVersion`. `packageManagerVersion` wins when both are set; prefer it, especially with a non-Yarn package manager. See [Workflow settings](/guide/ci/settings). * **`vite-plugin-dbx`** — the private legacy package/specifier. New configs and generated shims use `@deltabox/toolchain/vite`; existing plugin configs that still import the old specifier keep working through plugin detection. ### Changelog CLI * `--release-notes ` — deprecated alias for `--release-body `. * `--release` — deprecated alias for `--release-body-wrap`. Both aliases are still parsed for existing scripts, but are not listed in `dbx changelog --help`. See [Changelog CLI](/guide/changelog/cli). ### Config generator * **`meta.env`** — deprecated; use `meta.envName`. * **`meta.path`** — deprecated; use `meta.envPath`. * **`generateEnvTypes`** — deprecated; use `generateConfigEnv`. * **`parseEnvTree` + `envString` / `envInt` / `envBool`** — legacy runtime accessors. They remain exported, but prefer the schema parsers (`parseConfig`, `parseEnvConfig`, `parseCliConfig`, `loadConfigAsync`). See [Config generator programmatic API](#config-generator-programmatic-api). * **`loadConfigAsync({ schema })`** — the object-based form remains for compatibility; prefer `loadConfigAsync({ parser })` so env, CLI and overrides are validated through the schema. ### Changelog and templates API * **`main`** (from `@deltabox/toolchain/changelog`) — compatibility alias for `runChangelog`. * **`ProjectContext.repoUrl`** — legacy alias for `repo`. * **`ProjectContext.yarnVersion`** — legacy alias for `packageManagerVersion`. ### Compatibility paths * **`.dbx/toolchain/providers.json`** and **`~/.dbx/toolchain/.registry/providers.json`** — legacy provider registry files, still read. Add new project providers under `.dbx/toolchain/.registry/providers/` and global providers under `~/.dbx/toolchain/.registry/providers/`. See [Providers](/guide/providers#custom-providers). ## New features The v3 line also adds a large set of capabilities on top of v2, grouped by area: ### Config engine and CLI * Schema-derived CLI programs through `engine.cli.program.create()`, with typed options, subcommands, inherited global options, help formatting and typed `run({ config, values, context })` handlers. * Typed `CliCommand` descriptors (`defineCliCommand`) that infer option values from their flags, plus scoped CLI generation from config schemas. * Source-specific config loaders (file, env and CLI argv) with base-value merging, so env/CLI values override file values without schema defaults replacing them. Multi-source selections and `envExpose` metadata are supported. * Static schema defaults and generated `toolchain.hooks` from function schemas. * `enabled` / `regenerate` controls on sections, the `loader` config section and `project.manageConfigless`. * `dbx enable` / `dbx disable` and the `dbx enabled` command. * A reusable CLI docs generator (`engine.markdown.cli`) for command references. * Grouped and sorted help: `group` labels on options and commands, a `groups` program option (`true` or `{ auto, delimiter }`) that automatically groups commands by their delimited name path (`vite:list` -> `Vite commands:`), and `sort: 'asc' | 'desc' | false` for deterministic ordering (ascending by default, including inside groups). `dbx --help` groups its own commands like the docs sidebar. See [program options](/guide/config-generator/api#program-members-and-options). * `helpOnError` on the program (and on `createCli` / `runCli`) opts back into printing the full help after invalid argv; the default now prints only the error message. * `dbx test:repo`, plus readable spinners and surfaced Vite+ passthrough errors. ### Vite+, formatting and task running * Vite+ (`vite-plus`) as the single dev dependency and `vp` / `vp run` as the task runner; the shared pack config and workspace aliases no longer need a separate `tsdown` dependency. * `dbx fmt` / `dbx lint` route to the active formatter/linter, with better auto-detection of the configured tool. * Oxfmt and Oxlint option types generated from the tools' vendored JSON schemas, and typed tool options plus changelog callbacks. * Nested scaffolds leave `fmt` / `lint` to the root config instead of emitting their own blocks. * Scaffolds opt into the catalog they write, so `dbx sync` keeps the catalog managed. ### Templates, scaffolding and Docker * New quality-of-life builtin templates and project/template generators. * Opt-in containerization for scaffolds (`--containerize`), including scaffold-only Docker generation. * The new `@deltabox/toolchain-docker` package, wired into the umbrella; Docker plans now expose the exact `installSources` copied before installing. * `--online` for online templates, with clearer opt-in behaviour. ### MCP * An MCP server, installers for Claude, Codex, VS Code, OpenCode, Pi and custom directories, and the `dbx mcp:*` commands. * The official dbx docs skill: `dbx skills --official` installs it per agent (`--provider`) and location (`--scope` / `--dir`), checks first and never overwrites unless `--force`. The `checkSkill` / `installSkill` / `installOfficialSkill` APIs expose the same flow. The skill tells agents to read [`llms.txt`](https://toolchain.dbx.studio/llms.txt) and inspect the project config, graph and managed-file manifest before acting. See [Skills](/guide/mcp#skills). * Opt-in automatic skill installation through `toolchain.mcp.skills`; `dbx sync` adds missing skills for the configured agents. ### Changelog and CI * Opt-in Dependabot security updates and dependency-update workflows. * `beforeVersion` / `afterVersion` lifecycle hooks. * Changelog `intro` / `outro`, `minCommits`, nested `See more...` descriptions, release mode and collapsible bodies. * Grouped release bodies (`changelog.release.group`) that roll every prerelease since the previous published release into one stable release entry. * GitHub Releases mark prerelease versions (`3.0.0-beta.2`) as prereleases by default (`ci.release.prerelease: 'auto'` detects the semver suffix); `false` opts out, and custom release jobs can read the `{{releasePrerelease}}` token. * Scoped versioning options and configurable breaking-change detection. * Batched GitHub metadata lookups (commit authors, PR credit, issue titles). * Complete GitHub, GitLab and Azure workflow configs with autocomplete and dispatch through the vendor CLI. ### VS Code extension * A scoped auto-sync mode, the action palette and the Actions view. * Managed-file decorations and a reveal-active-project action. * Plugin-mode projects, MCP install and improved sync UX; sync notifications, `sync all`, a migration target picker and `manageConfigless` support. * The official dbx skill installer (`dbx skills --official`) is available from the action palette, the Command Palette and the Home Quick Actions, with the same agent/location picker as the MCP installer. * A Docker prompt while scaffolding, plus generic format/lint actions and formatting settings. * The workflow provider in the run picker. ## Behaviour changes ### Config inheritance is strictly opt-in A nested `dbx.config.*` only inherits the sections it explicitly enables (`fmt`, `lint`, `biome`, `changelog`, `catalogs`, `logger`); `project` metadata is inherited except its identity fields. Projects without their own `dbx.config.*` (or `dbx()` vite plugin in `vite.config.*`) are unmanaged by default; pass `--configless` or set `project.manageConfigless: true` to inherit the nearest ancestor config. See [Nested configs](/guide/config/nested-configs). ```diff [packages/web/dbx.config.ts] export default defineConfig({ toolchain: { project: { name: 'web' }, + // v3: a nested config only inherits sections it opts into. + fmt: true, + lint: true, }, }); ``` ```diff [dbx.config.ts] export default defineConfig({ toolchain: { project: { + manageConfigless: true, }, }, }); ``` ### Online templates need `--online` `dbx create --template ` and the `template:*` commands only resolve online (npm/git/Vite+) sources when `--online` is passed. Local and builtin templates work without it, and a local-only run never touches the network. Scripts and CI that relied on implicit online resolution must add the flag: ```diff -dbx create --template @org/template --name app +dbx create --template @org/template --name app --online ``` ### Toolchain enable/disable A top-level `toolchain.enabled` switch is available. The boolean shorthand is workspace-scoped: ```ts export default defineConfig({ plugins: [dbx({ toolchain: { enabled: false } })], }); ``` Config files and the inline `dbx()` plugin only accept the workspace scope; the object form (`{ disabled, scope: 'global' | 'workspace' }`) is reserved for the CLI/programmatic API and the VS Code extension. `dbx enable`/`dbx disable` choose the workspace scope by default; pass `--global` to update `~/.dbx/toolchain/cli/config.json`. The project config takes precedence over both the CLI workspace setting and `.vscode/settings.json`. ### Dependabot security updates `toolchain.ci.dependabot` now accepts an opt-in `security` setting. It adds the security-update group to `.github/dependabot.yml` and generates `.github/workflows/dependabot-security.yml` to enable GitHub's native security updates and optionally dismiss alerts below a severity threshold. ```diff [dbx.config.ts] export default defineConfig({ toolchain: { ci: { dependabot: { + security: { + vulnerabilities: { severity: 'high' }, + pr: { strategy: 'grouped' }, + }, }, }, }, }); ``` `security: true` keeps every severity and groups PRs per ecosystem. The workflow needs a `DBX_GITHUB_TOKEN` secret with repository admin access to change the repository setting; `GITHUB_TOKEN` is used for alert dismissal. Set `security: { workflow: false }` to manage the setting yourself, or `security: { vulnerabilities: false }` to disable security updates. No migration is required: without `security`, the generated `dependabot.yml` and behaviour are unchanged. ### Managed-file regeneration Every managed section now accepts `regenerate?: boolean` (default `true`). Set it to `false` to skip that section in `dbx sync`: its files are neither written nor drift-checked, and sync does not prune them. User-owned files (`tsconfig.workspaces.json`, `tsconfig.build.json`) are only seeded when missing; an existing file is never overwritten by the missing-file fallback. ```diff [dbx.config.ts] export default defineConfig({ toolchain: { - tsconfig: true, + tsconfig: { regenerate: false }, }, }); ``` ### Changelog versioning * `versioning.target: 'individual'` is idempotent. Commits already listed in a workspace's `CHANGELOG.md` are filtered out before deriving its bump, and a workspace with no new commits is skipped entirely. Re-running no longer bumps untouched workspaces or re-counts an old `feat` as a new minor. * Workspace glob negation (`['packages/*', '!packages/private-*']`) is honoured. * A UTF-8 BOM in any `package.json` (common with PowerShell/Notepad) no longer makes `dbx changelog` fail; the same BOM handling applies to local CLI discovery, providers, Prettier detection and the VS Code extension. * The `### Package changes` footer now reads Yarn (`.yarnrc.yml`), pnpm (`pnpm-workspace.yaml`) and Bun (`package.json` `workspaces.catalog`) catalogs, including named catalogs. * Running changelog from a nested workspace uses the repository root for the fallback commit/issue links instead of the workspace's own `package.json`. If you version workspaces individually, opt excluded packages out of the glob: ```diff [dbx.config.ts] versioning: { target: 'individual', - workspaces: ['packages/*'], + workspaces: ['packages/*', '!packages/private-*'], }, ``` ### Docker * Only files that exist when the Dockerfile is generated are copied: `package.json` plus the project's lockfile/workspace files. `.node-version*` is never assumed, and a missing lockfile is not copied. * The declared package manager drives both the copy list and the install command. A Bun-runtime project with no declared manager installs with Bun; otherwise the declared manager wins (so `yarn.lock` is not paired with `bun install`). When a Bun-runtime project declares yarn/pnpm/npm, dependencies install in a `node:` `deps` stage and the Bun image only builds. * When there is no lockfile, the install runs without a frozen flag. ### Scaffolding and migrations * `dbx project:init --out ` (and `project:init:monorepo`) no longer inherits the current project's name when `--name` is omitted; it uses the target directory's basename. The in-place case still inherits `project.name`. * `dbx migrate --check` resolves the effective (inherited) config, so a workspace inheriting `fmt`/`lint` from the root is not asked to keep an intermediate `.oxfmtrc.json` / `.oxlintrc.json`. A disabled section (`fmt: false`) does not count as owning the config. ### CLI and VS Code * `--no-color` now also disables the configured help/error colours. A custom program can implement the same switch with the `disableColors` program option. * Invalid argv (unknown command/option, missing value) prints only the error message by default. Pass `helpOnError: true` to a `ConfigProgram`, or to `createCli` / `runCli` via `RootCliOptions`, to append the full help text again. * Help command lists are grouped and sorted alphabetically by default. Use the `groups` and `sort` program options to opt out (`groups: false`, `sort: false`) or change the order (`sort: 'desc'`). * `dbx sync --json` always emits a JSON envelope, including when the config failed to load (`{ results: [], upToDate: false, error }`). * `dbx projects --max-depth` rejects non-numeric values instead of silently turning the limit into `NaN`; `--max-depth 0` still scans only the root. * The VS Code extension walks up to the repository boundary for the project's `dbx`, checks every workspace root in a multi-root workspace, and keeps the project's CLI as the default (the bundled CLI is only the fallback). ### TypeScript declarations * The shared tsdown base config externalizes declaration imports **as written** (`deps.dts.neverBundle: true`), so emitted `.d.ts` files reference bare package specifiers instead of build-machine absolute `node_modules` paths. Packages whose public types reference another package must declare it in `dependencies` (or `peerDependencies`). * The base config also ships a Rolldown leak reporter. It scans emitted JS, declaration and textual asset chunks and fails the build by default when an absolute `node_modules` path appears. Configure it with the `nodeModulesLeakReporter` option (or `false` to disable it): `{ level: 'warn' | 'info' | 'silent', when: 'generateBundle' | 'writeBundle' | 'closeBundle' }`. `writeBundle` is the default; use `closeBundle` when a later plugin rewrites output in `writeBundle`. Non-fatal levels respect tsdown/rolldown's log level. The plugin is also exported as `createNodeModulesLeakReporter` for use in your own builds. ```diff [tsdown.config.ts] const config = createTsdownConfig({ overrides: { format: ['cjs'] }, + nodeModulesLeakReporter: { level: 'warn', when: 'writeBundle' }, }); ``` ## Recommended upgrade steps 1. Update `@deltabox/toolchain` to v3 and replace the individual `vite`, `vitest` and `tsdown` dev dependencies with `vite-plus`. 2. Import the Vite plugin from `@deltabox/toolchain/vite` (not `vite-plugin-dbx`, which is not published yet). 3. If the project uses Vite+, move `tsdown.config.*`, `vitest.config.*` and `turbo.json` into `vite.config.*` as `pack`, `test` and `run.tasks`. 4. Run `dbx sync --recursive` and commit the regenerated managed files. 5. Rename generated `env.d.ts` references to `dbx-env.d.ts`, and switch custom runtime loaders to `parseConfig` / `parseEnvConfig` / `parseCliConfig` (or `loadConfigAsync` for files). 6. Run `dbx sync --recursive --check`, `yarn typecheck`, `yarn lint` and your test suite. 7. Regenerate Docker artifacts created by v2 (or edit the `COPY` lines to list only files that exist) and rebuild the image once with Docker available. 8. Replace imports of the old monolithic template helper with `PROJECT_TEMPLATE_IDS` / `createProjectTemplateFiles`. 9. If you build a `DockerPlan` by hand, add its `installSources` (or switch to `resolveDockerPlan()`). 10. Re-run `dbx migrate --check` in CI; inherited workspace configs may now pass where v2 reported a false drift. 11. Add `--online` to any `dbx create --template` / `template:*` script that resolves npm/git/Vite+ sources. 12. If you use `ci.dependabot`, opt into `security` and add the `DBX_GITHUB_TOKEN` secret (repository admin) before the generated security workflow runs. 13. If you assemble a custom CLI, rebuild it with `engine.cli.program.create()` (or the lower-level `createConfigProgram()` for engine-agnostic command lists), wrap descriptors in `defineCliCommand()`, and move any `commander` wiring to the program runtime.