Configuration guide
A project is configured in one of two ways:
- the recommended
dbx()Vite plugin invite.config.*(config inline, nodbx.config.*needed), or - a standalone
dbx.config.tswhen the project does not use Vite.
Both can be combined: dbx.config.* is the base and the plugin options merge on top. The @deltabox/toolchain settings live under the toolchain key:
ts
import { defineConfig } from '@deltabox/toolchain';
export default defineConfig({
toolchain: {
project: {
type: 'monorepo-root',
name: 'myapp',
scope: '@org',
},
ci: {
ci: true,
changelog: {
branches: { main: 'main', dev: 'dev' },
commitlint: { scopes: ['api', 'web', 'deps'] },
},
},
tsconfig: { refs: true },
fmt: { vscode: true, oxc: { semi: true, singleQuote: true } },
lint: { oxc: { ignorePatterns: ['dist/**'] } },
vite: {
test: { include: ['src/**/*.test.ts'] },
},
watch: { debounce: 150 },
},
});A dbx.config.ts can also host other dbx concerns alongside the toolchain section.
Each section has its own guide: Project, CI + Changelog, tsconfig, Formatting & linting, Vite+, Watch, Logger and Providers.
Where to start
- Opt-in by presence — which sections run, and how nested sections like
ci.changelogand the individual workflows opt in. - Nested configs — how a workspace config merges over its root.
defineConfig— object, promise or callback.- Config file names — the file names the loader probes.
- Loader — the
toolchain.loadertsconfig options, path aliases,.js→.tsimports and examples. - Hooks — lifecycle hooks in a
.ts/.jsconfig. - Logging — the logger section and CLI overrides.
- Providers — provider passthrough colour settings.
- Vite+ — the full Vite+ config and the generated shim.
- Programmatic API — load + sync from code.
The generated, exhaustive section reference is dbx.config.