Nested configs
A dbx.config.* in a non-root folder (a workspace, an app, a nested project) is merged over the nearest ancestor dbx.config.* found while walking up to the repository root (the walk stops at the .git boundary, so it never picks up a config from outside the repo).
The merge is recursive, but sections are strictly opt-in:
- Only a section the nested config explicitly enables/configures is inherited. If the nested config omits
fmt,lint,biome,changelog,catalogsorlogger, that section stays disabled for that project even when the root defines it. - When the nested config does opt in, objects are merged key by key and leaves (booleans, strings, numbers, arrays) in the child replace the root's value.
truemeans "enabled with the parent's options";falsedisables it. - Repository/workspace-scoped sections are never inherited:
ci,tsconfig,loader,templates,registry,watch,providers, andvite. A workflow, workspace tsconfig tree, config loader, source/registry policy, watch process or Vite config describes the repository or one workspace, so a child starts without the parent's values for them. In particular, the roottsconfigtask already expands every workspacetsconfig.json; inheriting it into each workspace would only re-scan that subtree.loaderis read from the nearest config file to import the nested config, but it is not merged into the child's config. projectmetadata is the exception: shared metadata (author,license,homepage,repo,packageManager, ...) is inherited because it is project metadata, not a task section.
vite.fmt / vite.lint are hoisted into the top-level fmt.oxc / lint.oxcwhen the nested config opts into fmt / lint.
export default defineConfig({
toolchain: {
logger: { level: 'debug', color: false },
fmt: { oxc: { printWidth: 100, singleQuote: true } },
vite: { shim: 'static', resolve: { tsconfigPaths: true } },
},
});
// <root>/packages/web/dbx.config.ts — opts into `fmt` + `logger`; `vite` is local
export default defineConfig({
toolchain: {
logger: { level: 'warn' }, // opts in; leaf overrides the root's level
fmt: true, // opts in; inherits the root's `fmt` options
vite: {
shim: 'static',
resolve: { tsconfigPaths: true },
run: { tasks: { build: { command: 'vp pack' } } },
},
},
});The workspace above ends up with logger: { level: 'warn', color: false } and the root's fmt options (because it opted in with fmt: true). If it omitted fmt, it would have no fmt section at all. Its vite.run holds only the build task it declares — the root's tasks are not merged in.
viteis never inherited. A workspace only has theviteconfig it declares itself; a project with novitesection keeps its hand-writtenvite.config.*alone. Declare the settings it needs (shim,resolve,plugins, ...) in its own config.vite.fmt/vite.lintare hoisted intofmt/lintonly when the workspace opts into those sections.
Arrays replace, so repeat what you need. If a workspace opts into
fmtand setsfmt.oxc.ignorePatterns, that array replaces the root's list (it is not appended). Either keep the root patterns in the workspace array, or put the shared pattern on the root config — for example**/vite.config.tsthere covers every workspace's generated shim.
projectis inherited except its identity fields.name,scope,descriptionandtypeare per-project, so a non-root config keeps its own (or falls back to itspackage.json) and is still detected from its own files — a rootprojectnever renames a workspace. The shared fields (author,license,homepage,repo,packageManager, ...) flow down so theirpackage.jsonvalues and replacement tokens stay shared.project: { inherit: false }disables project inheritance entirely.hooksare not inherited either — a parent's hooks are code and do not run for a nested project's sync.
Configless projects
A project with no dbx.config.* of its own is not managed by the toolchain by default: it does not inherit the ancestor config, dbx sync leaves it alone, and its files are never generated or pruned. This avoids surprising changes in packages that never opted in.
To manage configless projects, opt in explicitly:
- Config: set
toolchain.project.manageConfigless: trueon the ancestor config (it is repository-scoped, so a configless project inherits the choice through the parent config). - CLI: pass
dbx sync --configless(ordbx watch --configless). - VS Code: enable
deltabox.toolchain.manageConfigless.
export default defineConfig({
toolchain: {
project: {
manageConfigless: true,
},
},
});When enabled, a configless project inherits the ancestor config (the configless opt-in is the explicit opt-in for the whole project; repository-scoped sections are still dropped) and dbx sync regenerates its managed files.
Configless projects are still discovered (so the Projects view and the project graph can show them); they are just not managed until you opt in.
Vite plugin mode
A project can also be configured by the dbx() Vite plugin instead of a dbx.config.*:
import { defineConfig } from 'vite-plus';
import { dbx } from '@deltabox/toolchain/vite';
export default defineConfig({
plugins: [dbx({ toolchain: { project: { name: 'app' }, fmt: { oxc: true } } })],
});The loader evaluates vite.config.* and reads the plugin options, so the CLI, sync, watch and the VS Code extension all see the config with no dbx.config.*. When both exist, the dbx.config.* is the base and the plugin options are merged on top (the plugin layer keeps the sections it does not mention). In plugin mode the toolchain never writes or manages vite.config.*, and it watches the plugin config for changes.
In a workspace plugin config, leave fmt and lint out: the root vite.config.* already owns them, and Vite+ applies the root options (including its ignorePatterns) to the workspace. Declaring fmt: true / lint: true there would select the shared defaults instead and shadow the root config.