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
tsdownworkspace rename topack. - 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/vitesubpath as usual). - Vite+ (
vite-plus) replacing the separatevite,vitestandtsdowndev dependencies (it bundles those tools behindvp). @deltabox/toolchainpackages releasing independently instead of in lockstep.- Vite+ projects configuring
pack,testandrun.tasksinvite.config.*instead oftsdown.config.*,vitest.config.*andturbo.json. fmt/lintmoving intovite.config.*in Vite+ mode.
Some of the smaller changes
- Improved changelog and release notes formatting.
- Managed
tsconfig.jsonnow declaringinclude/exclude/compilerOptions.typesfrom extended tsconfig. - UTF-8 BOM support (great for shells).
- Dockerfiles that build from a fresh scaffold.
- Scaffold-only Docker generation.
--onlinefor 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-rundbx 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:
-import { baseTsdownConfig } from '@deltabox/toolchain/tsdown';
+import { baseTsdownConfig } from '@deltabox/toolchain/pack';and the workspace dependency for maintainers/contributors:
-"@deltabox/toolchain-tsdown": "workspace:*",
+"@deltabox/toolchain-pack": "workspace:*",createTsdownConfig now takes one options object instead of an (overrides, banner) pair:
-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
-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
-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
-{
- "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.
# 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:
+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):
{
"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:
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(previouslyenv.d.ts). Update theinclude/filesentries in your tsconfigs if you referenced the old file name. - Runtime loading uses
parseConfig,parseEnvConfigandparseCliConfig, pluscollectandloadConfig/loadConfigAsyncfor file-backed configs. The source-specificloadEnvConfig*,loadCliConfig*andloadFileConfig*family (withSync/Asyncvariants) selects the file+env, file+CLI or file-only source set explicitly. The oldparseEnvTree+envString/envInt/envBoolaccessors andapplyOverridesremain available, but are legacy; prefer the parsers so env, CLI and overrides are validated through the schema. - The engine groups its generators:
engine.env(andengine.env.types),engine.types,engine.markdown(.cli,.env,.file),engine.cli(.generate,.options,.program),engine.jsonSchemaandengine.configJson.configCommands({ engine })now also exposesconfig:all, and the standalonegenerateConfig*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 runnableConfigProgram(withcreateCommand()for one command), andcreateConfigProgram(commands, options?)builds one from framework-agnosticCliCommand[].commanderis no longer used or exported. The standalonegenerateConfigProgram(schema, options)returns the generated command descriptors without building a program. - JSON Schema generation can preserve Zod's
$ref/$defsgraph (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:
-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:
-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:
{
"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:
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 toCliCommand/CliOption(s). Wrap inline descriptors indefineCliCommand()from@deltabox/toolchain/shared; this preserves the literaloptionstuple sorunvalues are inferred. TheCliOptionValues<typeof options>type exposes the same shape directly. engine.cli.program.create()builds schema-derived commands with typedrun({ config, values, context });createCommand(scope, spec)builds one config-backed command andcreateCommand('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 nowcreate()and the oldengine.cli.program.command()builder is nowcreateCommand(). The chain's.command()method for subcommands is unchanged. - A built program exposes
invoke()/invokeAsync(),argv(),withContext(),globalOption()/globalOptions(),hook()/hooks(),bin,formatHelp(),formatError()andconfigure().invoke()throws when a handler, hook ordisableColorsresolver is async; useinvokeAsync(). configCommands()remains library-only;dbxdoes not register aconfig:*group because each command needs a consumer-boundConfigEngine.- A command's
binfield executes a relative/absolute binary instead of the in-process handler;argvoverrides the invocation arguments forprogram.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:
-{
- "printWidth": 100,
- "singleQuote": true
-}-{
- "rules": {
- "no-console": "warn"
- }
-} 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:
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:
-const plan: DockerPlan = buildPlan();
+const plan = resolveDockerPlan({
+ cwd: process.cwd(),
+ packageManager: 'yarn',
+}); 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 oftoolchain.fmt.biomeandtoolchain.lint.biome.biome.overridesstill writesbiome.json, andbiome.vscodestill controls the Biome VS Code settings;dbx syncwarns withdeprecated.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 fortokens.packageManagerVersion.packageManagerVersionwins 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; usemeta.envName.meta.path— deprecated; usemeta.envPath.generateEnvTypes— deprecated; usegenerateConfigEnv.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; preferloadConfigAsync({ parser })so env, CLI and overrides are validated through the schema.
Changelog and templates API
main(from@deltabox/toolchain/changelog) — compatibility alias forrunChangelog.ProjectContext.repoUrl— legacy alias forrepo.ProjectContext.yarnVersion— legacy alias forpackageManagerVersion.
Compatibility paths
.dbx/toolchain/providers.jsonand~/.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 typedrun({ config, values, context })handlers. - Typed
CliCommanddescriptors (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
envExposemetadata are supported. - Static schema defaults and generated
toolchain.hooksfrom function schemas. enabled/regeneratecontrols on sections, theloaderconfig section andproject.manageConfigless.dbx enable/dbx disableand thedbx enabledcommand.- A reusable CLI docs generator (
engine.markdown.cli) for command references. - Grouped and sorted help:
grouplabels on options and commands, agroupsprogram option (trueor{ auto, delimiter }) that automatically groups commands by their delimited name path (vite:list->Vite commands:), andsort: 'asc' | 'desc' | falsefor deterministic ordering (ascending by default, including inside groups).dbx --helpgroups its own commands like the docs sidebar. See program options. helpOnErroron the program (and oncreateCli/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 andvp/vp runas the task runner; the shared pack config and workspace aliases no longer need a separatetsdowndependency. dbx fmt/dbx lintroute 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/lintto the root config instead of emitting their own blocks. - Scaffolds opt into the catalog they write, so
dbx synckeeps 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-dockerpackage, wired into the umbrella; Docker plans now expose the exactinstallSourcescopied before installing. --onlinefor 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 --officialinstalls it per agent (--provider) and location (--scope/--dir), checks first and never overwrites unless--force. ThecheckSkill/installSkill/installOfficialSkillAPIs expose the same flow. The skill tells agents to readllms.txtand inspect the project config, graph and managed-file manifest before acting. See Skills. - Opt-in automatic skill installation through
toolchain.mcp.skills;dbx syncadds missing skills for the configured agents.
Changelog and CI
- Opt-in Dependabot security updates and dependency-update workflows.
beforeVersion/afterVersionlifecycle hooks.- Changelog
intro/outro,minCommits, nestedSee 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);falseopts out, and custom release jobs can read thetoken. - 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 andmanageConfiglesssupport. - 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.
export default defineConfig({
toolchain: {
project: { name: 'web' },
+ // v3: a nested config only inherits sections it opts into.
+ fmt: true,
+ lint: true,
},
}); 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:
-dbx create --template @org/template --name app
+dbx create --template @org/template --name app --onlineToolchain enable/disable
A top-level toolchain.enabled switch is available. The boolean shorthand is workspace-scoped:
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.
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.
export default defineConfig({
toolchain: {
- tsconfig: true,
+ tsconfig: { regenerate: false },
},
});Changelog versioning
versioning.target: 'individual'is idempotent. Commits already listed in a workspace'sCHANGELOG.mdare 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 oldfeatas 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 makesdbx changelogfail; the same BOM handling applies to local CLI discovery, providers, Prettier detection and the VS Code extension. - The
### Package changesfooter now reads Yarn (.yarnrc.yml), pnpm (pnpm-workspace.yaml) and Bun (package.jsonworkspaces.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:
versioning: {
target: 'individual',
- workspaces: ['packages/*'],
+ workspaces: ['packages/*', '!packages/private-*'],
},Docker
- Only files that exist when the Dockerfile is generated are copied:
package.jsonplus 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.lockis not paired withbun install). When a Bun-runtime project declares yarn/pnpm/npm, dependencies install in anode:<version>depsstage 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>(andproject:init:monorepo) no longer inherits the current project's name when--nameis omitted; it uses the target directory's basename. The in-place case still inheritsproject.name.dbx migrate --checkresolves the effective (inherited) config, so a workspace inheritingfmt/lintfrom 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-colornow also disables the configured help/error colours. A custom program can implement the same switch with thedisableColorsprogram option.- Invalid argv (unknown command/option, missing value) prints only the error message by default. Pass
helpOnError: trueto aConfigProgram, or tocreateCli/runCliviaRootCliOptions, to append the full help text again. - Help command lists are grouped and sorted alphabetically by default. Use the
groupsandsortprogram options to opt out (groups: false,sort: false) or change the order (sort: 'desc'). dbx sync --jsonalways emits a JSON envelope, including when the config failed to load ({ results: [], upToDate: false, error }).dbx projects --max-depthrejects non-numeric values instead of silently turning the limit intoNaN;--max-depth 0still 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.tsfiles reference bare package specifiers instead of build-machine absolutenode_modulespaths. Packages whose public types reference another package must declare it independencies(orpeerDependencies). - 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_modulespath appears. Configure it with thenodeModulesLeakReporteroption (orfalseto disable it):{ level: 'warn' | 'info' | 'silent', when: 'generateBundle' | 'writeBundle' | 'closeBundle' }.writeBundleis the default; usecloseBundlewhen a later plugin rewrites output inwriteBundle. Non-fatal levels respect tsdown/rolldown's log level. The plugin is also exported ascreateNodeModulesLeakReporterfor use in your own builds.
const config = createTsdownConfig({
overrides: { format: ['cjs'] },
+ nodeModulesLeakReporter: { level: 'warn', when: 'writeBundle' },
});Recommended upgrade steps
- Update
@deltabox/toolchainto v3 and replace the individualvite,vitestandtsdowndev dependencies withvite-plus. - Import the Vite plugin from
@deltabox/toolchain/vite(notvite-plugin-dbx, which is not published yet). - If the project uses Vite+, move
tsdown.config.*,vitest.config.*andturbo.jsonintovite.config.*aspack,testandrun.tasks. - Run
dbx sync --recursiveand commit the regenerated managed files. - Rename generated
env.d.tsreferences todbx-env.d.ts, and switch custom runtime loaders toparseConfig/parseEnvConfig/parseCliConfig(orloadConfigAsyncfor files). - Run
dbx sync --recursive --check,yarn typecheck,yarn lintand your test suite. - Regenerate Docker artifacts created by v2 (or edit the
COPYlines to list only files that exist) and rebuild the image once with Docker available. - Replace imports of the old monolithic template helper with
PROJECT_TEMPLATE_IDS/createProjectTemplateFiles. - If you build a
DockerPlanby hand, add itsinstallSources(or switch toresolveDockerPlan()). - Re-run
dbx migrate --checkin CI; inherited workspace configs may now pass where v2 reported a false drift. - Add
--onlineto anydbx create --template/template:*script that resolves npm/git/Vite+ sources. - If you use
ci.dependabot, opt intosecurityand add theDBX_GITHUB_TOKENsecret (repository admin) before the generated security workflow runs. - If you assemble a custom CLI, rebuild it with
engine.cli.program.create()(or the lower-levelcreateConfigProgram()for engine-agnostic command lists), wrap descriptors indefineCliCommand(), and move anycommanderwiring to the program runtime.