Skip to content

About this page

On this page

Migrating from v2 to v3 ​

v3 is a correctness and cleanup release.

Release notes here. Full changelog here.

Table of contents ​

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:

tsdown.config.ts
diff
-import { baseTsdownConfig } from '@deltabox/toolchain/tsdown';
+import { baseTsdownConfig } from '@deltabox/toolchain/pack';

and the workspace dependency for maintainers/contributors:

package.json
diff
-"@deltabox/toolchain-tsdown": "workspace:*",
+"@deltabox/toolchain-pack": "workspace:*",

createTsdownConfig now takes one options object instead of an (overrides, banner) pair:

tsdown.config.ts
diff
-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:

tsdown.config.ts → vite.config.ts
diff
# 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'],
+    },
+});
vitest.config.ts → vite.config.ts
diff
# 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',
+    },
+});
turbo.json → vite.config.ts
diff
# 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:

vite.config.ts
diff
+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):

package.json
diff
 {
     "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:

scripts/generate-config-reference.ts
diff
-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:

src/config.ts
diff
-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:

tsconfig.json
diff
 {
     "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<typeof options> 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:

.oxfmtrc.json
diff
-{
-    "printWidth": 100,
-    "singleQuote": true
-}
.oxlintrc.json
diff
-{
-    "rules": {
-        "no-console": "warn"
-    }
-}
vite.config.ts
diff
 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.
  • vite.shimImport: 'vite-plugin-dbx' — the legacy plugin specifier is still accepted, but generated shims use @deltabox/toolchain/vite. See 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.
  • 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 <version> — deprecated alias for --release-body <version>.
  • --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.

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.
  • 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.

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.
  • 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 and inspect the project config, graph and managed-file manifest before acting. See 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 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.

packages/web/dbx.config.ts
diff
 export default defineConfig({
     toolchain: {
         project: { name: 'web' },
+        // v3: a nested config only inherits sections it opts into.
+        fmt: true,
+        lint: true,
     },
 });
dbx.config.ts
diff
 export default defineConfig({
     toolchain: {
         project: {
+            manageConfigless: true,
         },
     },
 });

Online templates need --online ​

dbx create --template <id> 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.

dbx.config.ts
diff
 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.

dbx.config.ts
diff
 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:

dbx.config.ts
diff
 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:<version> 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 <dir> (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.
tsdown.config.ts
diff
 const config = createTsdownConfig({
     overrides: { format: ['cjs'] },
+    nodeModulesLeakReporter: { level: 'warn', when: 'writeBundle' },
 });
  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.