Formatting & linting

toolchain.fmt and toolchain.lint select a formatter/linter, hold its options, and optionally add project-scoped VS Code defaults:

dbx.config.ts

export default defineConfig({
    toolchain: {
        fmt: {
            vscode: true, // add missing VS Code formatter settings (default false)
            oxc: { printWidth: 100, singleQuote: true },
            biome: { formatter: { indentWidth: 4 } },
        },
        lint: {
            vscode: true,
            oxc: { rules: { eqeqeq: 'warn' } },
            eslint: { rules: {} },
        },
    },
});

The supported tools are:

• fmt: oxc (Oxfmt), biome, prettier, dprint.
• lint: oxc (Oxlint), biome, eslint.

Each tool accepts true (use the defaults) or false (disable that tool), in addition to its options object. The Oxfmt/Oxlint option types are generated from the tools' official JSON schemas (vendored in the package), so editor completion and the generated config reference match the tool.

The shared ignore lists are exported from @deltabox/toolchain and @deltabox/toolchain/shared: DEFAULT_IGNORE_PATTERNS (build/cache dirs), and DEFAULT_FMT_IGNORE_PATTERNS / DEFAULT_LINT_IGNORE_PATTERNS (the Oxc defaults, layered over DEFAULT_IGNORE_PATTERNS). Import them to extend the defaults rather than re-listing them.

Oxfmt import sorting is enabled in the defaults as well. sortImports includes a workspace group built from every dbx.config.* project's scope/name; resolveFmtCustomGroups() returns that group so you can reuse it in a custom sortImports config. Set sortImports: false to opt out.

Shorthand opt-in

fmt: true / lint: true (or an options object with only vscode) picks a tool automatically. dbx sync resolves it in this order:

1. the project's .vscode/settings.json;
2. the nearest package.json or tooling config file, walking up to the repo root (a workspace-specific tool beats a root-installed one);
3. the VS Code user settings language blocks;
4. the Oxc defaults.

Each level prefers a tool's own config file (.oxfmtrc.json, biome.json, .prettierrc, dprint.json, .eslintrc.*, ...) before its package.json dependency, and honours the formatter/linter precedence. If nothing is found, sync warns (fmt.no-tool / lint.no-tool) and still applies the Oxc defaults.

Existing user-owned config files are not overwritten blindly: the detected tool's options are read into the matching toolchain.fmt.* / toolchain.lint.* entry. Oxc options are merged over the toolchain defaults using the same mapping as dbx migrate.

Running the active tool

dbx fmt / dbx lint run the tool the config (or discovery) selects, even when toolchain.fmt / toolchain.lint is omitted:

• an explicit toolchain.fmt.* / toolchain.lint.* tool wins, in precedence order;
• otherwise the same discovery dbx sync uses picks a tool from the project .vscode/settings.json, the nearest config file/package.json, or the VS Code user settings;
• with nothing configured or installed, they fall back to vp fmt / vp lint (Oxfmt / Oxlint).

Mode flags are translated per tool (--check/--write for formatters, --fix for linters) and other operands are forwarded. Oxc keeps the full Vite+ passthrough, so dbx vite fmt ... still accepts every vp flag.

Precedence

When more than one formatter/linter is configured, editor defaults use:

• formatters: oxc > biome > prettier > dprint.
• linters: oxc > biome > eslint.

dbx sync warns (fmt.conflict / lint.conflict) when this happens; silence it with logger.suppress.

toolchain.vite.fmt / toolchain.vite.lint are the Oxc config written by Vite+, and override fmt.oxc / lint.oxc with a deep merge (scalars, arrays and booleans in vite.* win). With both:

toolchain: {
    fmt: { oxc: { semi: false, singleQuote: true } },
    vite: { fmt: { singleQuote: false } },
}
// effective Oxfmt options: { semi: false, singleQuote: false }

Generated config files

• fmt.oxc / lint.oxc (+ vite.fmt / vite.lint) write managed .oxfmtrc.json / .oxlintrc.json.
• fmt.biome / lint.biome merge into the managed biome.json.
• The deprecated top-level biome section still works; prefer fmt.biome / lint.biome.

Oxc files are root-only unless a nested dbx.config.* defines fmt.oxc / lint.oxc / vite.fmt / vite.lint itself. Biome keeps its existing per-project behaviour.

When more than one formatter or linter is configured, sync warns (fmt.conflict / lint.conflict) because the generated config files and editor defaults may conflict.

VS Code editor defaults

Set fmt.vscode and/or lint.vscode (both default false) to add missing project-scoped settings to .vscode/settings.json. The generated defaults are deliberately small:

• editor.defaultFormatter
• language blocks ([javascript], [typescript], ...)
• editor.codeActionsOnSave (lint only)

Use an options object to override or exclude individual keys:

toolchain: {
    fmt: {
        oxc: {},
        vscode: {
            overrides: {
                'editor.defaultFormatter': 'oxc.oxc-vscode',
                '[typescript]': { 'editor.defaultFormatter': 'esbenp.prettier-vscode' },
            },
            exclude: ['[javascript]'],
        },
    },
    lint: { oxc: {}, vscode: true },
}

These editor defaults are not tracked and existing keys are never overridden. (The separate Conventional Commits/Biome VS Code sync may track .vscode/settings.json when those sections are enabled.) Remove or change the generated keys freely. Setting vscode: false (or omitting it) adds nothing.

A nested project scaffolded below a root that already has .oxfmtrc.json / .oxlintrc.json omits its own Oxc files and fmt.oxc / lint.oxc opt-ins, so dbx fmt / dbx lint keep using the root configuration.

Migrating

dbx migrate --from oxc --write        # .oxfmtrc/.oxlintrc -> fmt.oxc/lint.oxc
dbx migrate --from biome --from prettier --write
dbx migrate --from all --write

Unless --target is given, the migrated formatter/linter options go to toolchain.vite.fmt/toolchain.vite.lint when the existing Vite config already defines fmt/lint; otherwise they go to the top-level toolchain.fmt.oxc/toolchain.lint.oxc. See Migrations.

Biome

Deprecated: prefer toolchain.fmt.biome / toolchain.lint.biome (see above). The top-level biome section still works and still writes biome.json.

The biome section generates a biome.json for consumers that still want a Biome config. The toolchain itself is built on Oxc (Oxfmt + Oxlint) through Vite+, but a repo that runs Biome directly can let the toolchain manage its biome.json from the same dbx.config.*.

dbx.config.ts

export default defineConfig({
    toolchain: {
        biome: true, // or { overrides: { ... } }
    },
});

dbx sync writes biome.json, resolving the / replacement tokens and merging your overrides over the defaults.

If any other formatter/linter is also configured, sync still writes both the Biome and Oxc config files, but warns (fmt.conflict / lint.conflict) that the two tools may conflict. Silencing it is possible with logger: { suppress: ['fmt.conflict'] }; prefer one toolchain per repo.

Options

Option	Type	Default	Description
enabled	boolean	enabled when defined	Master switch.
vscode	boolean	true	Write the Biome VS Code settings/extensions.
overrides	Record<string, unknown>	—	Deep-merged over the generated biome.json.

overrides

Overrides are merged into the generated config recursively, and arrays are unioned (not replaced) — so files.includes can be extended:

biome: {
    overrides: {
        files: { includes: ['!**/generated/**'] },
        formatter: { indentWidth: 2 },
    },
}

Default array entries can be pruned with a $remove: entry (its value is JSON, or a raw string when it is not valid JSON) or replaced wholesale with $reset:

import { BIOME_RESET, removeBiomeEntry } from '@deltabox/toolchain/biome';

biome: {
    overrides: {
        files: {
            includes: [
                removeBiomeEntry('!**/.generated'), // drop a default
                '!**/generated/**',
            ],
        },
        assist: {
            actions: {
                source: {
                    organizeImports: {
                        options: { groups: [BIOME_RESET, ['@/lib/**']] },
                    },
                },
            },
        },
    },
}

removeBiomeEntry(entry) builds the directive, and nested arrays (eg. import groups) are matched deeply. The same directives work in fmt.biome / lint.biome; sources are applied in order, so later ones see earlier results.

vscode

When on (the default), the sync also writes the recommended Biome VS Code settings and the Biome extension recommendation (see VS Code Extension). Set biome: { vscode: false } to skip them.

Programmatic API

import {
    BIOME_RESET,
    biomeConfig,
    biomeSyncTask,
    biomeVscodeSettings,
    mergeBiomeConfig,
    removeBiomeEntry,
    renderBiomeConfig,
    renderBiomeJson,
    resolveBiomeArray,
} from '@deltabox/toolchain/biome';

Export	Description
biomeSyncTask()	The sync task (writes biome.json).
biomeConfig / biomeVscodeSettings	The generic Biome config / recommended VS Code settings.
renderBiomeConfig(tokens, overrides?)	Resolve tokens + merge overrides into an object.
renderBiomeJson(tokens, overrides?)	Serialize the rendered config.
mergeBiomeConfig(base, patch)	The recursive/array-union merge used above.
resolveBiomeArray(base, patch)	Resolve $remove:/$reset directives for one array.
removeBiomeEntry(entry) / BIOME_RESET	Build the array-pruning / array-reset directives.

Migrating from Biome to Oxc is a different concern — see Migrations.