Skip to content

About this page

On this page

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, catalogs or logger, 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. true means "enabled with the parent's options"; false disables it.
  • Repository/workspace-scoped sections are never inherited: ci, tsconfig, loader, templates, registry, watch, providers, and vite. 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 root tsconfig task already expands every workspace tsconfig.json; inheriting it into each workspace would only re-scan that subtree. loader is read from the nearest config file to import the nested config, but it is not merged into the child's config.
  • project metadata 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.

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

vite is never inherited. A workspace only has the vite config it declares itself; a project with no vite section keeps its hand-written vite.config.* alone. Declare the settings it needs (shim, resolve, plugins, ...) in its own config. vite.fmt / vite.lint are hoisted into fmt / lint only when the workspace opts into those sections.

Arrays replace, so repeat what you need. If a workspace opts into fmt and sets fmt.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.ts there covers every workspace's generated shim.

project is inherited except its identity fields. name, scope, description and type are per-project, so a non-root config keeps its own (or falls back to its package.json) and is still detected from its own files — a root project never renames a workspace. The shared fields (author, license, homepage, repo, packageManager, ...) flow down so their package.json values and replacement tokens stay shared. project: { inherit: false } disables project inheritance entirely. hooks are 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: true on the ancestor config (it is repository-scoped, so a configless project inherits the choice through the parent config).
  • CLI: pass dbx sync --configless (or dbx watch --configless).
  • VS Code: enable deltabox.toolchain.manageConfigless.
<root>/dbx.config.ts
ts
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.*:

vite.config.ts
ts
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.