--- url: https://toolchain.dbx.studio/config/reference.md --- # dbx.config A `dbx.config.ts` file exports `{ toolchain: { ...sections } }`: the `@deltabox/toolchain` settings live under the `toolchain` key. Every section is **opt-in by presence** (see [Configuration](/guide/config/opt-in-by-presence)): define it to enable it, omit it to leave that area untouched. ## `enabled` Enable/disable the toolchain. The shorthand is workspace-scoped; the object form is reserved for APIs and the VS Code extension. ## `project` Project metadata: canonical `package.json` fields and template tokens (shared fields are inherited by workspaces). ### `type` * **Type**: `'monorepo-root' | 'monorepo-workspace' | 'project'` The project kind (detected when omitted). ### `regenerate` * **Type**: `boolean` Regenerate this section's managed files during `dbx sync`. When false, existing files are left untouched and are neither written nor drift-checked. ### `name` * **Type**: `string` The unscoped project name (written as `/`). ### `scope` * **Type**: `string` The npm scope, eg. `@org`. ### `author` * **Type**: `string` Package author (`package.json` `author`). ### `license` * **Type**: `string` SPDX license id (`package.json` `license`). ### `homepage` * **Type**: `string` Project homepage (`package.json` `homepage`). ### `repo` * **Type**: `string` Repository URL (`package.json` `repository`). For a workspace it also resolves to the workspace path (`repository.directory`). ### `nodeVersion` * **Type**: `string` Node version for CI/templates, eg. `22` (not `package.json` `engines`). ### `packageManager` * **Type**: `string` * **Default**: `"yarn"` Package manager name, written as `@`. ### `packageManagerVersion` * **Type**: `string` Package manager version, eg. `4.17.1`. ### `description` * **Type**: `string` One-line description (`package.json` `description`). ### `inherit` * **Type**: `boolean` * **Default**: `true` Inherit the parent project metadata. Set false to keep this project metadata independent of the root config (other sections still merge normally). ### `manageConfigless` * **Type**: `boolean` * **Default**: `false` Manage projects that have no dbx.config.\* of their own by inheriting the nearest ancestor config. Disabled by default so configless projects are never touched unless explicitly opted in. ## `ci` GitHub Actions workflows to generate (CI, release, issues, changelog, sync). ### `ci` * **Type**: `WorkflowSetting` The CI checks workflow (`ci.yml`). #### `provider` * **Required** * **Type**: `'github'` * **Default**: `"github"` Workflow vendor for a full `workflow` object. #### `workflow` * **Required** * **Type**: `AzurePipelines` * **See**: https://learn.microsoft.com/en-us/azure/devops/pipelines/yaml-schema/ The complete pipeline object. #### `filename` * **Type**: `string` Override the generated workflow file name (eg. `deploy.yml`). #### `dir` * **Type**: `string` * **Default**: `".github/workflows"` Directory for the workflow file. #### `setup` * **Type**: `boolean` * **Default**: `false` Inject the shared checkout/Node/Corepack/install steps into custom workflow jobs; built-in workflows already include them. #### `enabled` * **Type**: `boolean` Enable/disable this workflow (default: enabled when present). #### `pushBranches` * **Type**: `Array` Replace `on.push.branches`. #### `pullRequestBranches` * **Type**: `Array` Replace `on.pull_request.branches`. #### `triggers` * **Type**: `WorkflowTriggers` Extra `on.*` workflow triggers. ##### `push` * **Type**: `JsonObject` Push trigger (`on.push`). ##### `pull_request` * **Type**: `JsonObject` Pull-request trigger (`on.pull_request`). ##### `pull_request_target` * **Type**: `JsonObject` Pull-request-target trigger (`on.pull_request_target`). ##### `workflow_dispatch` * **Type**: `JsonObject` Manual trigger (`on.workflow_dispatch`). ##### `workflow_call` * **Type**: `JsonObject` Reusable workflow trigger (`on.workflow_call`). ##### `workflow_run` * **Type**: `JsonObject` Triggered by another workflow (`on.workflow_run`). ##### `schedule` * **Type**: `Array` Scheduled trigger list (`on.schedule`). ##### `release` * **Type**: `JsonObject` Release trigger (`on.release`). #### `extra` * **Type**: `WorkflowExtra` Extra top-level workflow keys (`permissions`, `concurrency`, `env`, ...). ##### `permissions` * **Type**: `Record` Workflow permissions. ##### `concurrency` * **Type**: `string | object` Workflow concurrency. ###### `group` * **Required** * **Type**: `string` Concurrency group. ###### `cancel-in-progress` * **Type**: `boolean | string` Cancel in-progress runs (boolean or expression). ##### `env` * **Type**: `Record` Workflow environment variables. ##### `defaults` * **Type**: `object` Default settings for `run` steps. ###### `run` * **Type**: `object` ###### `shell` * **Type**: `string` Default shell. ###### `working-directory` * **Type**: `string` Default working directory. ##### `name` * **Type**: `string` Workflow name. ##### `run-name` * **Type**: `string` Workflow run name. ##### `timeout-minutes` * **Type**: `number` Job timeout in minutes. ##### `container` * **Type**: `JsonObject` Container for the job. ##### `strategy` * **Type**: `JsonObject` Build matrix / strategy. #### `steps` * **Type**: `WorkflowStepsConfig | Array` Extra steps for a job (one group, or per-job groups). ##### `job` * **Type**: `string` Target job id (defaults to the primary/first job). ##### `before` * **Type**: `Array` Steps inserted at the start. ###### `name` * **Type**: `string` Step display name. ###### `id` * **Type**: `string` Step id (for `steps.` outputs). ###### `if` * **Type**: `string` Conditional expression (`if:`). ###### `uses` * **Type**: `string` Action to run (`uses:`), eg. `actions/checkout@v4`. ###### `run` * **Type**: `string` Shell command(s) to run (`run:`). ###### `shell` * **Type**: `string` Shell to run `run` in, eg. `bash`. ###### `working-directory` * **Type**: `string` Directory the step runs in. ###### `with` * **Type**: `Record` Inputs for a `uses` action. ###### `env` * **Type**: `Record` Environment variables for the step. ##### `after` * **Type**: `Array` Steps appended at the end. #### `jobs` * **Type**: `Record` Extra complete jobs merged in. #### `tokens` * **Type**: `WorkflowTokens` Per-workflow token overrides (`nodeVersion`, `packageManager`, ...). ##### `name` * **Type**: `string` Project name {{ name }}. ##### `scope` * **Type**: `string` Package scope {{ scope }}. ##### `author` * **Type**: `string` Author {{ author }}. ##### `license` * **Type**: `string` License {{ license }}. ##### `homepage` * **Type**: `string` Homepage {{ homepage }}. ##### `repo` * **Type**: `string` Repository URL {{ repo }}. ##### `description` * **Type**: `string` Description {{ description }}. ##### `nodeVersion` * **Type**: `string` Node version {{ nodeVersion }}. ##### `packageManager` * **Type**: `string` Package manager {{ packageManager }}. ##### `yarnVersion` * **Type**: `string` Yarn version {{ yarnVersion }}. ##### `packageManagerVersion` * **Type**: `string` Package manager version {{ packageManagerVersion }}. ##### `mainBranch` * **Type**: `string` Main branch {{ mainBranch }}. ##### `devBranch` * **Type**: `string` Dev branch {{ devBranch }}. ##### `vitePlus` * **Type**: `boolean` Use `voidzero-dev/setup-vp` for this workflow (default: detected from the project). ##### `releasePrerelease` * **Type**: `boolean | 'auto'` Whether a version with a prerelease suffix (eg. `3.0.0-beta.2`) should be marked as a GitHub prerelease (`{{ releasePrerelease }}`). `auto` detects the suffix, `true` always marks and `false` never marks. ##### `setupVpVersion` * **Type**: `string` Exact `voidzero-dev/setup-vp` version or commit SHA to pin. #### `regenerate` * **Type**: `boolean` * **Default**: `true` Regenerate this section's managed files during `dbx sync`. When false, existing files are left untouched and are neither written nor drift-checked. ### `changelog` * **Type**: `ChangelogWorkflowSetting` The changelog/version workflow (`changelog.yml`) plus the changelog pipeline config (versioning, VS Code settings, commitlint). #### `provider` * **Type**: `'github'` * **Default**: `"github"` Workflow vendor for a full `workflow` object. #### `pushBranches` * **Type**: `Array` Replace `on.push.branches`. #### `pullRequestBranches` * **Type**: `Array` Replace `on.pull_request.branches`. #### `triggers` * **Type**: `WorkflowTriggers` Extra `on.*` workflow triggers. #### `extra` * **Type**: `WorkflowExtra` Extra top-level workflow keys (`permissions`, `concurrency`, `env`, ...). #### `steps` * **Type**: `WorkflowStepsConfig | Array` Extra steps for a job (one group, or per-job groups). #### `jobs` * **Type**: `Record` Extra complete jobs merged in. #### `tokens` * **Type**: `WorkflowTokens` Per-workflow token overrides (`nodeVersion`, `packageManager`, ...). #### `filename` * **Type**: `string` Override the generated workflow file name (eg. `deploy.yml`). #### `dir` * **Type**: `string` * **Default**: `".github/workflows"` Directory for the workflow file. #### `setup` * **Type**: `boolean` * **Default**: `false` Inject the shared checkout/Node/Corepack/install steps into custom workflow jobs; built-in workflows already include them. #### `enabled` * **Type**: `boolean` Enable/disable the changelog workflow and pipeline (default: enabled when present). #### `regenerate` * **Type**: `boolean` * **Default**: `true` Regenerate this section's managed files during `dbx sync`. When false, existing files are left untouched and are neither written nor drift-checked. #### `branches` * **Type**: `ChangelogBranchesConfig` Branches the generated workflows target. ##### `main` * **Type**: `string | Array` * **Default**: `["main"]` Branch glob(s) the CI + release workflows run on, and the release PR base. ##### `dev` * **Type**: `string | Array` Branch glob(s) the changelog/version workflow runs on. No default: when omitted it reuses `main` (so a single-branch repo needs no `dev`). #### `commitlint` * **Type**: `boolean | ChangelogCommitlintConfig` commitlint config; set `false` to disable the Conventional-Commits pipeline. ##### `dir` * **Type**: `string` Directory the generated `commitlint.config.mjs` is written to (default: the project root). The generated commit hook and CI use `--config` to point at it. ##### `types` * **Type**: `Array` Allowed commit types (commitlint). ##### `scopes` * **Type**: `Array` Allowed commit scopes (commitlint). ##### `enabled` * **Type**: `boolean` Enable commitlint (default true when the changelog is enabled). Set false to generate changelogs without the Conventional-Commits pipeline. ##### `regenerate` * **Type**: `boolean` * **Default**: `true` Regenerate this section's managed files during `dbx sync`. When false, existing files are left untouched and are neither written nor drift-checked. #### `versioning` * **Type**: `ChangelogVersioning` * **Default**: `true` Automatic version bumping on changelog generation. ##### `target` * **Type**: `'uniform' | 'root-only' | 'individual'` * **Default**: `"uniform"` `uniform` bumps the root and every workspace to one shared version; `root-only` bumps the root only; `individual` bumps each changed workspace independently. ##### `workspaces` * **Type**: `Array` Glob patterns selecting the workspaces to version (relative to the root). Defaults to the root `package.json` `workspaces` field; when there is none the root `package.json` is used on its own. ##### `prerelease` * **Type**: `ChangelogTargetedPrerelease | Array | string` The prerelease tag globally, or per-target via `{ target, options }`. ###### `target` * **Type**: `string` A workspace path relative to the repository root (`.` for the root), or a glob such as `apps/*`. When omitted the entry applies to every target. ###### `include` * **Type**: `string | Array` Only apply to workspaces whose repo-relative directory matches one of these globs (tsconfig-style include). ###### `exclude` * **Type**: `string | Array` Skip workspaces whose repo-relative directory matches these globs. ###### `options` * **Required** * **Type**: `string` Opt into a prerelease cycle (eg. `beta`, `rc`). Stable versions bump their core and start at `.0`; existing prereleases keep their core and increment the counter for the same tag, so the suffix is never appended twice. ##### `bump` * **Type**: `object` Custom bump rules for major/minor/patch (matchers or callbacks), globally or per-target via `{ target, options }`. Configuring any level replaces Conventional-Commits detection for that target; the result is at least a patch bump. ###### `major` * **Type**: `ChangelogTargetedBump | Array | ChangelogBumpRule` A bump rule globally, or per-target via `{ target, include, exclude, options }`. ###### `target` * **Type**: `string` A workspace path relative to the repository root (`.` for the root), or a glob such as `apps/*`. When omitted the entry applies to every target. ###### `include` * **Type**: `string | Array` Only apply to workspaces whose repo-relative directory matches one of these globs (tsconfig-style include). ###### `exclude` * **Type**: `string | Array` Skip workspaces whose repo-relative directory matches these globs. ###### `options` * **Required** * **Type**: `ChangelogBumpRule` A bump rule: a matcher/callback or a list of matchers/callbacks. ###### `breaking` * **Type**: `boolean` Match only commits whose breaking state equals this value. ###### `type` * **Type**: `string` Match this Conventional-Commits type. ###### `types` * **Type**: `Array` Match any of these CC types. ###### `scope` * **Type**: `string` Match this Conventional-Commits scope. ###### `scopes` * **Type**: `Array` Match any of these CC scopes. ###### `pattern` * **Type**: `string` Match this regular expression. ###### `match` * **Type**: `string` Match this substring. ###### `minor` * **Type**: `ChangelogTargetedBump | Array | ChangelogBumpRule` A bump rule globally, or per-target via `{ target, include, exclude, options }`. ###### `patch` * **Type**: `ChangelogTargetedBump | Array | ChangelogBumpRule` A bump rule globally, or per-target via `{ target, include, exclude, options }`. ##### `allowOverBump` * **Type**: `ChangelogTargetedAllowOverBump | Array | boolean` Enable over-bumping globally, or per-target via `{ target, options }`. ###### `target` * **Type**: `string` A workspace path relative to the repository root (`.` for the root), or a glob such as `apps/*`. When omitted the entry applies to every target. ###### `include` * **Type**: `string | Array` Only apply to workspaces whose repo-relative directory matches one of these globs (tsconfig-style include). ###### `exclude` * **Type**: `string | Array` Skip workspaces whose repo-relative directory matches these globs. ###### `options` * **Required** * **Type**: `boolean` * **Default**: `false` Apply a bump once per matching change instead of once per run. ##### `commit` * **Type**: `ChangelogTargetedCommit | Array | ChangelogCommitFormatConfig` Commit formatting globally, or per-target via `{ target, options }`. ###### `target` * **Type**: `string` A workspace path relative to the repository root (`.` for the root), or a glob such as `apps/*`. When omitted the entry applies to every target. ###### `include` * **Type**: `string | Array` Only apply to workspaces whose repo-relative directory matches one of these globs (tsconfig-style include). ###### `exclude` * **Type**: `string | Array` Skip workspaces whose repo-relative directory matches these globs. ###### `options` * **Required** * **Type**: `ChangelogCommitFormatConfig` Commit message formatting/credit options (with an optional formatter callback). ###### `author` * **Type**: `boolean` * **Default**: `true` Include the `by ` credit. ###### `commitSha` * **Type**: `boolean` * **Default**: `true` Include the commit hash link. ###### `issues` * **Type**: `boolean` * **Default**: `true` Include issue/fixes links. ###### `authorAvatar` * **Type**: `boolean` * **Default**: `false` Prefix the author with their GitHub avatar. ###### `format` * **Type**: `((ctx: ChangelogCommitFormatContext) => string)` Fully custom commit line formatter (TS/JS configs only; return the bullet body). ###### `details` * **Type**: `ChangelogDetailsConfig` Wrap changelog sections/text in markdown `
` collapsibles. `true` enables descriptions, release notes, breaking changes and type sections; use an object or `false` to opt out. ###### `enabled` * **Type**: `boolean` * **Default**: `true` Enable/disable details wrapping. ###### `lifecycle` * **Type**: `'after' | 'before'` * **Default**: `"after"` Apply details after the changelog formatting pipeline (default `after`, so custom searches regex-match the formatted text) or before it (`before`). ###### `minCommits` * **Type**: `number` Default minimum entries for every details section (a nested minCommits wins; the body defaults to 10). ###### `descriptions` * **Type**: `boolean | ChangelogDetailsOptions` * **Default**: `true` Wrap commit description paragraphs in a nested collapsible. ###### `title` * **Type**: `string` Custom `` text. ###### `expanded` * **Type**: `boolean` Render the collapsible open by default. ###### `minCommits` * **Type**: `number` Minimum entries in the section before wrapping (nested overrides the top-level default). ###### `body` * **Type**: `boolean | ChangelogDetailsOptions` Wrap the version body in a collapsible titled Release notes (default false; enabled by default with release body wrapping; requires 10 commits by default). ###### `releaseNotes` * **Type**: `boolean | ChangelogDetailsOptions` Wrap the release body entry in a collapsible titled Release notes. ###### `intro` * **Type**: `boolean | ChangelogDetailsOptions` Wrap the intro text in a collapsible. ###### `outro` * **Type**: `boolean | ChangelogDetailsOptions` Wrap the outro text in a collapsible. ###### `footer` * **Type**: `boolean | ChangelogDetailsOptions` Wrap the package-changes footer in a collapsible. ###### `breaking` * **Type**: `boolean | ChangelogDetailsOptions` Wrap the breaking-changes section in a collapsible. ###### `types` * **Type**: `boolean | ChangelogDetailsOptions | Array` Wrap these CC type sections (all types when `true`; enabled by default). ###### `custom` * **Type**: `ChangelogDetailsCustom | Array` Wrap matching text (the match or `start` match becomes the summary). ###### `title` * **Type**: `string` Custom `` text. ###### `expanded` * **Type**: `boolean` Render the collapsible open by default. ###### `minCommits` * **Type**: `number` Minimum entries in the section before wrapping (nested overrides the top-level default). ###### `start` * **Type**: `RegExp | string` The opening marker. ###### `end` * **Type**: `RegExp | string` The closing marker. ##### `provider` * **Type**: `ChangelogTargetedProvider | Array string | void)> | string | ChangelogProviderConfig | ((ctx: ChangelogProviderContext) => string | void)` The provider globally, or per-target via `{ target, options }`. The `changesets` provider is repository-wide and runs once when any versioned target selects it. ###### `target` * **Type**: `string` A workspace path relative to the repository root (`.` for the root), or a glob such as `apps/*`. When omitted the entry applies to every target. ###### `include` * **Type**: `string | Array` Only apply to workspaces whose repo-relative directory matches one of these globs (tsconfig-style include). ###### `exclude` * **Type**: `string | Array` Skip workspaces whose repo-relative directory matches these globs. ###### `options` * **Required** * **Type**: `string | ChangelogProviderConfig | ((ctx: ChangelogProviderContext) => string | void)` `default`, `changesets`, a built-in provider id, or a custom provider/callback. ###### `id` * **Required** * **Type**: `string` The provider id. ###### `run` * **Required** * **Type**: `((ctx: ChangelogProviderContext) => string | void)` A custom provider callback returning the changelog body (TS/JS configs only). #### `intro` * **Type**: `ChangelogTextSetting` Opt-in text inserted at the start of the new changelog entry, globally or for matching targets (workspaces/root). ##### `enabled` * **Type**: `boolean` * **Default**: `true` Set false to skip this entry. ##### `target` * **Type**: `string` A workspace path relative to the repository root (`.` for the root), or a glob such as `apps/*`. When omitted the entry applies to every target. ##### `include` * **Type**: `string | Array` Only apply to workspaces whose repo-relative directory matches one of these globs (tsconfig-style include). ##### `exclude` * **Type**: `string | Array` Skip workspaces whose repo-relative directory matches these globs. ##### `content` * **Required** * **Type**: `unknown` Not allowed with `file`. ##### `file` * **Required** * **Type**: `string` Path to a file containing the text (relative to the repository root or absolute). It is read at changelog-generation time. #### `outro` * **Type**: `ChangelogTextSetting` Opt-in text appended to the new changelog entry, globally or for matching targets (workspaces/root). #### `vscode` * **Type**: `boolean` * **Default**: `true` Write the Conventional-Commits VS Code settings. #### `groups` * **Type**: `Array | Record | ((ctx: ChangelogGroupsContext) => ChangelogGroupsSetting)` Conventional-Commits group order/titles: an ordered array of CC types or `{ type, title, order, hidden }`, a type->title/options record, or a callback (TS/JS configs only). ##### `type` * **Type**: `string` The CC type (required for object entries in an array). ##### `title` * **Type**: `string | ((ctx: ChangelogGroupContext) => string)` Custom heading title (or callback; TS/JS configs only). ##### `order` * **Type**: `number | ((ctx: ChangelogGroupContext) => number)` Sort position; lower comes first (or callback; TS/JS configs only). ##### `hidden` * **Type**: `boolean | ((ctx: ChangelogGroupContext) => boolean)` Omit this group from the rendered changelog (or callback; TS/JS only). #### `breaking` * **Type**: `boolean | 'conventional' | 'any' | object | ((commit: ChangelogBreakingCommit) => boolean)` How breaking changes are detected: `conventional` (default: a `!` in the CC subject or a `BREAKING CHANGE:` footer), `any` (legacy loose match), `false` (disable), `{ pattern }` / `{ match }`, or a callback (TS/JS configs only). ##### `pattern` * **Type**: `string` A regular expression matched against the subject and body. ##### `match` * **Type**: `string` A substring matched against the subject and body. #### `release` * **Type**: `ChangelogReleaseConfig` Release-body aggregation options, used by `dbx changelog --release-body` and the generated release workflow. ##### `group` * **Type**: `boolean` * **Default**: `false` Group every changelog version since the previous published release into one release body instead of exposing each intermediate version separately. A stable release skips prerelease versions when it picks that boundary, so all prereleases since the last stable release are part of the same body; a prerelease release still stops at the previous prerelease. ##### `includePrereleases` * **Type**: `boolean` * **Default**: `false` Let a prerelease version bound the grouped body even for a stable release (so the stable body only covers the changes since the latest prerelease). ##### `since` * **Type**: `string` Explicit lower boundary for the grouped body: a version or tag (eg. `1.2.0`, `v1.2.0`, `@scope/pkg@1.2.0`). Overrides the published-release lookup; a missing version falls back to automatic discovery. ### `release` * **Type**: `ReleaseWorkflowSetting` The release workflow (`release.yml`), including prerelease marking. #### `provider` * **Type**: `'github'` * **Default**: `"github"` Workflow vendor for a full `workflow` object. #### `pushBranches` * **Type**: `Array` Replace `on.push.branches`. #### `pullRequestBranches` * **Type**: `Array` Replace `on.pull_request.branches`. #### `triggers` * **Type**: `WorkflowTriggers` Extra `on.*` workflow triggers. #### `extra` * **Type**: `WorkflowExtra` Extra top-level workflow keys (`permissions`, `concurrency`, `env`, ...). #### `steps` * **Type**: `WorkflowStepsConfig | Array` Extra steps for a job (one group, or per-job groups). #### `jobs` * **Type**: `Record` Extra complete jobs merged in. #### `tokens` * **Type**: `WorkflowTokens` Per-workflow token overrides (`nodeVersion`, `packageManager`, ...). #### `filename` * **Type**: `string` Override the generated workflow file name (eg. `deploy.yml`). #### `dir` * **Type**: `string` * **Default**: `".github/workflows"` Directory for the workflow file. #### `setup` * **Type**: `boolean` * **Default**: `false` Inject the shared checkout/Node/Corepack/install steps into custom workflow jobs; built-in workflows already include them. #### `enabled` * **Type**: `boolean` Enable/disable this workflow (default: enabled when present). #### `regenerate` * **Type**: `boolean` * **Default**: `true` Regenerate this section's managed files during `dbx sync`. When false, existing files are left untouched and are neither written nor drift-checked. #### `prerelease` * **Type**: `boolean | 'auto'` * **Default**: `"auto"` Mark a version with a prerelease suffix (eg. `3.0.0-beta.2`) as a GitHub prerelease when a release job creates it. `auto` (default) detects a semver suffix after `-`; `true` always marks; `false` never marks. Custom release jobs can read the `{{ releasePrerelease }}` token. ### `issues` * **Type**: `WorkflowSetting` The issue-title workflow (`issues.yml`). ### `sync` * **Type**: `WorkflowSetting` The toolchain sync workflow (`sync.yml`). ### `dependabot` * **Type**: `boolean | ToolchainDependabotConfig` * **See**: https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file Dependabot version-update automation (`.github/dependabot.yml`). #### `schedule` * **Type**: `'daily' | 'weekly' | 'monthly'` * **Default**: `"weekly"` Dependabot update interval. #### `directories` * **Type**: `Array` * **Default**: `["/"]` Directories to scan. #### `ecosystems` * **Type**: `Array` * **Default**: `["github-actions","npm"]` Package ecosystems. `github-actions` keeps `voidzero-dev/setup-vp` and the other actions up to date. #### `labels` * **Type**: `Array` Labels added to the update PRs. #### `openPullRequestsLimit` * **Type**: `number` * **Default**: `5` Maximum open update PRs per entry. #### `groups` * **Type**: `Record` Dependabot update groups, keyed by group name. #### `security` * **Type**: `boolean | ToolchainDependabotSecurityConfig` Security updates: enable Dependabot security updates, group vulnerability PRs and apply a severity threshold. Requires a repository admin token for the generated workflow. ##### `enabled` * **Type**: `boolean` Enable or disable the security-update automation. ##### `vulnerabilities` * **Type**: `boolean | object` Open PRs for vulnerable dependencies. Enabled by default when `security` is set; set false to disable Dependabot security updates. ###### `severity` * **Type**: `'low' | 'moderate' | 'medium' | 'high' | 'critical' | 'all' | Array<'low' | 'moderate' | 'medium' | 'high' | 'critical' | 'all'>` * **Default**: `"all"` Only keep vulnerability PRs at or above this severity (or exactly the listed severities). `all` keeps every alert. `moderate` is accepted as an alias for GitHub's `medium`. ##### `pr` * **Type**: `object` Pull-request strategy for security updates. ###### `strategy` * **Type**: `'grouped' | 'individual'` * **Default**: `"grouped"` Group security updates into one PR per ecosystem (default) or one PR per update. ##### `workflow` * **Type**: `boolean` * **Default**: `true` Generate the workflow that enables Dependabot security updates and applies the severity threshold. Default true. #### `allow` * **Type**: `Array | Record>` Rules for every ecosystem (an array) or keyed by package ecosystem (eg. `{ npm: [...] }`; `*` is the fallback). ##### `dependency-name` * **Required** * **Type**: `string` Dependency name or `*` pattern. ##### `dependency-type` * **Type**: `'direct' | 'indirect' | 'production' | 'development'` Restrict the rule to a dependency type. ##### `update-types` * **Type**: `Array` Update types (eg. `version-update:semver-major`). ##### `versions` * **Type**: `Array` Version ranges to allow/ignore. #### `ignore` * **Type**: `Array | Record>` Rules for every ecosystem (an array) or keyed by package ecosystem (eg. `{ npm: [...] }`; `*` is the fallback). ##### `dependency-name` * **Required** * **Type**: `string` Dependency name or `*` pattern. ##### `dependency-type` * **Type**: `'direct' | 'indirect' | 'production' | 'development'` Restrict the rule to a dependency type. ##### `update-types` * **Type**: `Array` Update types (eg. `version-update:semver-major`). ##### `versions` * **Type**: `Array` Version ranges to allow/ignore. #### `filename` * **Type**: `string` * **Default**: `"dependabot.yml"` Override the generated file name. #### `dir` * **Type**: `string` * **Default**: `".github"` Directory for the config. #### `enabled` * **Type**: `boolean` Enable/disable this section (default: enabled when defined). #### `regenerate` * **Type**: `boolean` * **Default**: `true` Regenerate this section's managed files during `dbx sync`. When false, existing files are left untouched and are neither written nor drift-checked. ### `custom` * **Type**: `Record` Additional custom workflows, keyed by id (eg. `custom.my-workflow`). Each id writes `/.yml`. ### `enabled` * **Type**: `boolean` Enable/disable this section (default: enabled when defined). ### `regenerate` * **Type**: `boolean` * **Default**: `true` Regenerate this section's managed files during `dbx sync`. When false, existing files are left untouched and are neither written nor drift-checked. ## `changelog` Manual `toolchain.changelog` pipeline config for `dbx changelog`, the VS Code actions and the API; `ci.changelog` inherits these options. ### `commitlint` * **Type**: `boolean | ChangelogCommitlintConfig` commitlint config; set `false` to disable the Conventional-Commits pipeline. #### `dir` * **Type**: `string` Directory the generated `commitlint.config.mjs` is written to (default: the project root). The generated commit hook and CI use `--config` to point at it. #### `types` * **Type**: `Array` Allowed commit types (commitlint). #### `scopes` * **Type**: `Array` Allowed commit scopes (commitlint). #### `enabled` * **Type**: `boolean` Enable commitlint (default true when the changelog is enabled). Set false to generate changelogs without the Conventional-Commits pipeline. #### `regenerate` * **Type**: `boolean` * **Default**: `true` Regenerate this section's managed files during `dbx sync`. When false, existing files are left untouched and are neither written nor drift-checked. ### `versioning` * **Type**: `ChangelogVersioning` * **Default**: `true` Automatic version bumping on changelog generation. #### `target` * **Type**: `'uniform' | 'root-only' | 'individual'` * **Default**: `"uniform"` `uniform` bumps the root and every workspace to one shared version; `root-only` bumps the root only; `individual` bumps each changed workspace independently. #### `workspaces` * **Type**: `Array` Glob patterns selecting the workspaces to version (relative to the root). Defaults to the root `package.json` `workspaces` field; when there is none the root `package.json` is used on its own. #### `prerelease` * **Type**: `ChangelogTargetedPrerelease | Array | string` The prerelease tag globally, or per-target via `{ target, options }`. ##### `target` * **Type**: `string` A workspace path relative to the repository root (`.` for the root), or a glob such as `apps/*`. When omitted the entry applies to every target. ##### `include` * **Type**: `string | Array` Only apply to workspaces whose repo-relative directory matches one of these globs (tsconfig-style include). ##### `exclude` * **Type**: `string | Array` Skip workspaces whose repo-relative directory matches these globs. ##### `options` * **Required** * **Type**: `string` Opt into a prerelease cycle (eg. `beta`, `rc`). Stable versions bump their core and start at `.0`; existing prereleases keep their core and increment the counter for the same tag, so the suffix is never appended twice. #### `bump` * **Type**: `object` Custom bump rules for major/minor/patch (matchers or callbacks), globally or per-target via `{ target, options }`. Configuring any level replaces Conventional-Commits detection for that target; the result is at least a patch bump. ##### `major` * **Type**: `ChangelogTargetedBump | Array | ChangelogBumpRule` A bump rule globally, or per-target via `{ target, include, exclude, options }`. ###### `target` * **Type**: `string` A workspace path relative to the repository root (`.` for the root), or a glob such as `apps/*`. When omitted the entry applies to every target. ###### `include` * **Type**: `string | Array` Only apply to workspaces whose repo-relative directory matches one of these globs (tsconfig-style include). ###### `exclude` * **Type**: `string | Array` Skip workspaces whose repo-relative directory matches these globs. ###### `options` * **Required** * **Type**: `ChangelogBumpRule` A bump rule: a matcher/callback or a list of matchers/callbacks. ###### `breaking` * **Type**: `boolean` Match only commits whose breaking state equals this value. ###### `type` * **Type**: `string` Match this Conventional-Commits type. ###### `types` * **Type**: `Array` Match any of these CC types. ###### `scope` * **Type**: `string` Match this Conventional-Commits scope. ###### `scopes` * **Type**: `Array` Match any of these CC scopes. ###### `pattern` * **Type**: `string` Match this regular expression. ###### `match` * **Type**: `string` Match this substring. ##### `minor` * **Type**: `ChangelogTargetedBump | Array | ChangelogBumpRule` A bump rule globally, or per-target via `{ target, include, exclude, options }`. ##### `patch` * **Type**: `ChangelogTargetedBump | Array | ChangelogBumpRule` A bump rule globally, or per-target via `{ target, include, exclude, options }`. #### `allowOverBump` * **Type**: `ChangelogTargetedAllowOverBump | Array | boolean` Enable over-bumping globally, or per-target via `{ target, options }`. ##### `target` * **Type**: `string` A workspace path relative to the repository root (`.` for the root), or a glob such as `apps/*`. When omitted the entry applies to every target. ##### `include` * **Type**: `string | Array` Only apply to workspaces whose repo-relative directory matches one of these globs (tsconfig-style include). ##### `exclude` * **Type**: `string | Array` Skip workspaces whose repo-relative directory matches these globs. ##### `options` * **Required** * **Type**: `boolean` * **Default**: `false` Apply a bump once per matching change instead of once per run. #### `commit` * **Type**: `ChangelogTargetedCommit | Array | ChangelogCommitFormatConfig` Commit formatting globally, or per-target via `{ target, options }`. ##### `target` * **Type**: `string` A workspace path relative to the repository root (`.` for the root), or a glob such as `apps/*`. When omitted the entry applies to every target. ##### `include` * **Type**: `string | Array` Only apply to workspaces whose repo-relative directory matches one of these globs (tsconfig-style include). ##### `exclude` * **Type**: `string | Array` Skip workspaces whose repo-relative directory matches these globs. ##### `options` * **Required** * **Type**: `ChangelogCommitFormatConfig` Commit message formatting/credit options (with an optional formatter callback). ##### `author` * **Type**: `boolean` * **Default**: `true` Include the `by ` credit. ##### `commitSha` * **Type**: `boolean` * **Default**: `true` Include the commit hash link. ##### `issues` * **Type**: `boolean` * **Default**: `true` Include issue/fixes links. ##### `authorAvatar` * **Type**: `boolean` * **Default**: `false` Prefix the author with their GitHub avatar. ##### `format` * **Type**: `((ctx: ChangelogCommitFormatContext) => string)` Fully custom commit line formatter (TS/JS configs only; return the bullet body). ##### `details` * **Type**: `ChangelogDetailsConfig` Wrap changelog sections/text in markdown `
` collapsibles. `true` enables descriptions, release notes, breaking changes and type sections; use an object or `false` to opt out. ###### `enabled` * **Type**: `boolean` * **Default**: `true` Enable/disable details wrapping. ###### `lifecycle` * **Type**: `'after' | 'before'` * **Default**: `"after"` Apply details after the changelog formatting pipeline (default `after`, so custom searches regex-match the formatted text) or before it (`before`). ###### `minCommits` * **Type**: `number` Default minimum entries for every details section (a nested minCommits wins; the body defaults to 10). ###### `descriptions` * **Type**: `boolean | ChangelogDetailsOptions` * **Default**: `true` Wrap commit description paragraphs in a nested collapsible. ###### `title` * **Type**: `string` Custom `` text. ###### `expanded` * **Type**: `boolean` Render the collapsible open by default. ###### `minCommits` * **Type**: `number` Minimum entries in the section before wrapping (nested overrides the top-level default). ###### `body` * **Type**: `boolean | ChangelogDetailsOptions` Wrap the version body in a collapsible titled Release notes (default false; enabled by default with release body wrapping; requires 10 commits by default). ###### `releaseNotes` * **Type**: `boolean | ChangelogDetailsOptions` Wrap the release body entry in a collapsible titled Release notes. ###### `intro` * **Type**: `boolean | ChangelogDetailsOptions` Wrap the intro text in a collapsible. ###### `outro` * **Type**: `boolean | ChangelogDetailsOptions` Wrap the outro text in a collapsible. ###### `footer` * **Type**: `boolean | ChangelogDetailsOptions` Wrap the package-changes footer in a collapsible. ###### `breaking` * **Type**: `boolean | ChangelogDetailsOptions` Wrap the breaking-changes section in a collapsible. ###### `types` * **Type**: `boolean | ChangelogDetailsOptions | Array` Wrap these CC type sections (all types when `true`; enabled by default). ###### `custom` * **Type**: `ChangelogDetailsCustom | Array` Wrap matching text (the match or `start` match becomes the summary). ###### `title` * **Type**: `string` Custom `` text. ###### `expanded` * **Type**: `boolean` Render the collapsible open by default. ###### `minCommits` * **Type**: `number` Minimum entries in the section before wrapping (nested overrides the top-level default). ###### `start` * **Type**: `RegExp | string` The opening marker. ###### `end` * **Type**: `RegExp | string` The closing marker. #### `provider` * **Type**: `ChangelogTargetedProvider | Array string | void)> | string | ChangelogProviderConfig | ((ctx: ChangelogProviderContext) => string | void)` The provider globally, or per-target via `{ target, options }`. The `changesets` provider is repository-wide and runs once when any versioned target selects it. ##### `target` * **Type**: `string` A workspace path relative to the repository root (`.` for the root), or a glob such as `apps/*`. When omitted the entry applies to every target. ##### `include` * **Type**: `string | Array` Only apply to workspaces whose repo-relative directory matches one of these globs (tsconfig-style include). ##### `exclude` * **Type**: `string | Array` Skip workspaces whose repo-relative directory matches these globs. ##### `options` * **Required** * **Type**: `string | ChangelogProviderConfig | ((ctx: ChangelogProviderContext) => string | void)` `default`, `changesets`, a built-in provider id, or a custom provider/callback. ##### `id` * **Required** * **Type**: `string` The provider id. ##### `run` * **Required** * **Type**: `((ctx: ChangelogProviderContext) => string | void)` A custom provider callback returning the changelog body (TS/JS configs only). ### `intro` * **Type**: `ChangelogTextSetting` Opt-in text inserted at the start of the new changelog entry, globally or for matching targets (workspaces/root). #### `enabled` * **Type**: `boolean` * **Default**: `true` Set false to skip this entry. #### `target` * **Type**: `string` A workspace path relative to the repository root (`.` for the root), or a glob such as `apps/*`. When omitted the entry applies to every target. #### `include` * **Type**: `string | Array` Only apply to workspaces whose repo-relative directory matches one of these globs (tsconfig-style include). #### `exclude` * **Type**: `string | Array` Skip workspaces whose repo-relative directory matches these globs. #### `content` * **Required** * **Type**: `unknown` Not allowed with `file`. #### `file` * **Required** * **Type**: `string` Path to a file containing the text (relative to the repository root or absolute). It is read at changelog-generation time. ### `outro` * **Type**: `ChangelogTextSetting` Opt-in text appended to the new changelog entry, globally or for matching targets (workspaces/root). ### `vscode` * **Type**: `boolean` * **Default**: `true` Write the Conventional-Commits VS Code settings. ### `groups` * **Type**: `Array | Record | ((ctx: ChangelogGroupsContext) => ChangelogGroupsSetting)` Conventional-Commits group order/titles: an ordered array of CC types or `{ type, title, order, hidden }`, a type->title/options record, or a callback (TS/JS configs only). #### `type` * **Type**: `string` The CC type (required for object entries in an array). #### `title` * **Type**: `string | ((ctx: ChangelogGroupContext) => string)` Custom heading title (or callback; TS/JS configs only). #### `order` * **Type**: `number | ((ctx: ChangelogGroupContext) => number)` Sort position; lower comes first (or callback; TS/JS configs only). #### `hidden` * **Type**: `boolean | ((ctx: ChangelogGroupContext) => boolean)` Omit this group from the rendered changelog (or callback; TS/JS only). ### `breaking` * **Type**: `boolean | 'conventional' | 'any' | object | ((commit: ChangelogBreakingCommit) => boolean)` How breaking changes are detected: `conventional` (default: a `!` in the CC subject or a `BREAKING CHANGE:` footer), `any` (legacy loose match), `false` (disable), `{ pattern }` / `{ match }`, or a callback (TS/JS configs only). #### `pattern` * **Type**: `string` A regular expression matched against the subject and body. #### `match` * **Type**: `string` A substring matched against the subject and body. ### `release` * **Type**: `ChangelogReleaseConfig` Release-body aggregation options, used by `dbx changelog --release-body` and the generated release workflow. #### `group` * **Type**: `boolean` * **Default**: `false` Group every changelog version since the previous published release into one release body instead of exposing each intermediate version separately. A stable release skips prerelease versions when it picks that boundary, so all prereleases since the last stable release are part of the same body; a prerelease release still stops at the previous prerelease. #### `includePrereleases` * **Type**: `boolean` * **Default**: `false` Let a prerelease version bound the grouped body even for a stable release (so the stable body only covers the changes since the latest prerelease). #### `since` * **Type**: `string` Explicit lower boundary for the grouped body: a version or tag (eg. `1.2.0`, `v1.2.0`, `@scope/pkg@1.2.0`). Overrides the published-release lookup; a missing version falls back to automatic discovery. ### `enabled` * **Type**: `boolean` Enable/disable this section (default: enabled when defined). ### `regenerate` * **Type**: `boolean` * **Default**: `true` Regenerate this section's managed files during `dbx sync`. When false, existing files are left untouched and are neither written nor drift-checked. ## `fmt` Formatter configuration: Oxc/Biome configs, editor defaults and source-tool options. ### `vscode` * **Type**: `boolean | ToolchainVscodeSettings` * **Default**: `false` Add project-scoped VS Code settings: `true`/`false` or `{ overrides, exclude }` (existing keys are kept). #### `overrides` * **Type**: `JsonObject` Settings deep-merged over the generated editor defaults. #### `exclude` * **Type**: `Array` Exact setting keys (eg. `editor.defaultFormatter`) to omit. ### `oxc` * **Type**: `boolean | OxfmtConfig` * **See**: https://oxc.rs/docs/guide/usage/formatter/config-file-reference.html Oxfmt options (`true` = defaults, `false` = disabled). `toolchain.vite.fmt` overrides these (deep merge). ### `biome` * **Type**: `boolean | BiomeConfig` * **See**: https://biomejs.dev/reference/configuration/ Biome formatter options (`true` = defaults, `false` = disabled); merged into the generated `biome.json` (arrays union; `$remove:`/`$reset` prune or replace them). ### `prettier` * **Type**: `boolean | PrettierConfig` * **See**: https://prettier.io/docs/options Prettier options (`true` = defaults, `false` = disabled). ### `dprint` * **Type**: `boolean | DprintConfig` * **See**: https://dprint.dev/config/ Dprint options (`true` = defaults, `false` = disabled). ### `enabled` * **Type**: `boolean` Enable/disable this section (default: enabled when defined). ### `regenerate` * **Type**: `boolean` * **Default**: `true` Regenerate this section's managed files during `dbx sync`. When false, existing files are left untouched and are neither written nor drift-checked. ## `lint` Linter configuration: Oxc/Biome configs, editor defaults and ESLint options. ### `vscode` * **Type**: `boolean | ToolchainVscodeSettings` * **Default**: `false` Add project-scoped VS Code settings: `true`/`false` or `{ overrides, exclude }` (existing keys are kept). #### `overrides` * **Type**: `JsonObject` Settings deep-merged over the generated editor defaults. #### `exclude` * **Type**: `Array` Exact setting keys (eg. `editor.defaultFormatter`) to omit. ### `oxc` * **Type**: `boolean | OxlintConfig` * **See**: https://oxc.rs/docs/guide/usage/linter/config-file-reference.html Oxlint options (`true` = defaults, `false` = disabled). `toolchain.vite.lint` overrides these (deep merge). ### `biome` * **Type**: `boolean | BiomeConfig` * **See**: https://biomejs.dev/reference/configuration/ Biome linter options (`true` = defaults, `false` = disabled); merged into the generated `biome.json` (arrays union; `$remove:`/`$reset` prune or replace them). ### `eslint` * **Type**: `boolean | EslintConfig` * **See**: https://eslint.org/docs/latest/use/configure/configuration-files ESLint options (`true` = defaults, `false` = disabled). ### `enabled` * **Type**: `boolean` Enable/disable this section (default: enabled when defined). ### `regenerate` * **Type**: `boolean` * **Default**: `true` Regenerate this section's managed files during `dbx sync`. When false, existing files are left untouched and are neither written nor drift-checked. ## `biome` Biome config generation (for consumers that still want a `biome.json`). * **Deprecated**: use `toolchain.fmt.biome` / `toolchain.lint.biome`. Still writes `biome.json`. ### `vscode` * **Type**: `boolean` * **Default**: `true` Write the Biome VS Code settings. ### `overrides` * **Type**: `BiomeConfig` * **See**: https://biomejs.dev/reference/configuration/ Deep-merged over the generated `biome.json` (arrays union; `$remove:`/`$reset` prune or replace them). ### `enabled` * **Type**: `boolean` Enable/disable this section (default: enabled when defined). ### `regenerate` * **Type**: `boolean` * **Default**: `true` Regenerate this section's managed files during `dbx sync`. When false, existing files are left untouched and are neither written nor drift-checked. ## `tsconfig` Workspace tsconfig generation (path aliases + project references). ### `glob` * **Type**: `string | Array` Glob(s) for the workspace default tsconfig files. Defaults to matching every `defaultFile` recursively. ### `exclude` * **Type**: `string | Array` Glob(s) to exclude from `glob`. Defaults to the common ignored paths (`node_modules`, `.dbx`, `dist`, `build`, ...). ### `gitignore` * **Type**: `boolean` * **Default**: `true` Also respect `.gitignore` files (root + nested) when matching `glob`. ### `refs` * **Type**: `boolean` * **Default**: `false` Wire project references. ### `composite` * **Type**: `boolean` * **Default**: `false` Emit `composite: true`. ### `aliases` * **Type**: `boolean` * **Default**: `true` Inject path aliases. ### `flattenRemoteExtends` * **Type**: `boolean` * **Default**: `false` Inline the compiler options inherited from a remote `http(s)` `extends` chain into the generated workspace configs. Useful when a tool cannot follow a remote URL; path-valued options such as `paths`/`baseUrl` are skipped because they describe the remote tree. Settings the generated config already defines always win. ### `auto` * **Type**: `boolean | ToolchainTsconfigAliasAutoSetting` * **Default**: `false` Auto-generate the root workspaces tsconfig paths/references from the project graph. Set true to derive them from the project graph; set false to only use the entries you define yourself. An object additionally accepts `include`/`exclude`, `rewriteAlias`, `modes`, `prefix`, `devMode` and `dist`. #### `include` * **Type**: `Array` Only auto-wire entries matching these globs (`auto`: workspace dirs; `aliasAuto`: rewritten alias keys; `refsAuto`: reference paths). #### `exclude` * **Type**: `Array` Skip entries matching these globs (same targets as `include`). #### `rewriteAlias` * **Type**: `ToolchainTsconfigAliasRewrite` Rewrite the alias keys auto-wiring generates (custom keys are preserved). Patterns are URL-rewrite style: a string is a regular-expression source and replacements support `$1`, `$2`, ... capture groups. Examples: `{ "^@org/(.+)$": "@org/pkg/$1" }` (string patterns), `[{ pattern: /^@org\/(.+)$/, replacement: "@org/pkg/$1" }]` (RegExp patterns), `[{ pattern: ["^@org/a$", "^@org/b$"], replacement: "@org/x" }]` (an array of keys), and an array of such rules (applied in order; the first matching rule wins). `RegExp` patterns are only available from TS/JS configs; JSON configs use string patterns. #### `modes` * **Type**: `'auto' | 'exports' | 'project-structure' | Array<'exports' | 'project-structure'>` Alias discovery: `auto` (exports, then the project structure), `exports` (package.json exports/types/main only), `project-structure` (scan the source tree), or an array combining `exports` and `project-structure`. #### `prefix` * **Type**: `'@' | (string & {})` Prefix for generated aliases instead of the package scope (eg. `@` produces `@/` and `@//`). #### `devMode` * **Type**: `boolean` * **Default**: `true` Resolve generated aliases to source files. Set false to point at the distributed files instead. #### `dist` * **Type**: `string` Output directory used to map source/dist targets (default: the workspace tsconfig's `outDir`, then `dist`). ### `aliasAuto` * **Type**: `boolean | ToolchainTsconfigAliasAutoSetting` Auto-generate path aliases (defaults to `auto`; `aliases` must also be enabled). Accepts the same `include`/`exclude`/`rewriteAlias`/`modes`/`prefix`/`devMode`/`dist` object as `auto`. ### `refsAuto` * **Type**: `boolean | ToolchainTsconfigAutoSetting` Auto-generate project references (defaults to `auto`; `refs` must also be enabled). #### `include` * **Type**: `Array` Only auto-wire entries matching these globs (`auto`: workspace dirs; `aliasAuto`: rewritten alias keys; `refsAuto`: reference paths). #### `exclude` * **Type**: `Array` Skip entries matching these globs (same targets as `include`). ### `autoSrcDir` * **Type**: `'src' | '.' | (string & {})` Source directory used to resolve workspace entry points when `package.json` does not declare `exports`/`main`/`types` (default: the workspace's final tsconfig `rootDir`/`baseUrl`, falling back to `src`). ### `indent` * **Type**: `number` * **Default**: `4` JSON indentation. ### `rootFile` * **Type**: `string` * **Default**: `"tsconfig.workspaces.json"` The workspaces tsconfig file name that holds `paths` + `references`. ### `defaultFile` * **Type**: `string` * **Default**: `"tsconfig.default.json"` The workspace default tsconfig file name that the generator expands. ### `buildFile` * **Type**: `string` * **Default**: `"tsconfig.build.json"` The workspace build tsconfig file name. ### `baseFile` * **Type**: `string` * **Default**: `"tsconfig.base.json"` The root base tsconfig file name. ### `extends` * **Type**: `object` Per-file `extends` overrides for generated/scaffolded tsconfig templates. #### `base` * **Type**: `string | Array | false` `extends` written into scaffolded `tsconfig.base.json` files (or `false` to remove the field). #### `default` * **Type**: `string | Array | false` `extends` written into scaffolded `tsconfig.default.json` files (or `false` to remove the field). #### `build` * **Type**: `string | Array | false` `extends` written into scaffolded `tsconfig.build.json` files. Default `./tsconfig.default.json`; use `./tsconfig.json` to let builds reuse the path aliases (at the cost of pulling workspace source into the build). ### `overrides` * **Type**: `ToolchainTsconfigOverrides` Managed overrides deep-merged into the base/root/default/build tsconfig files during sync. The originals are snapshotted in the manifest, so removing a key reverts it (restoring the original value when the file defined one). #### `base` * **Type**: `TsConfigJson` * **See**: https://www.typescriptlang.org/tsconfig Deep-merged into the root base tsconfig (`baseFile`) during sync. #### `default` * **Type**: `TsConfigJson` * **See**: https://www.typescriptlang.org/tsconfig Deep-merged into every workspace default tsconfig (`defaultFile`) during sync. #### `build` * **Type**: `TsConfigJson` * **See**: https://www.typescriptlang.org/tsconfig Deep-merged into every workspace build tsconfig (`buildFile`) during sync. #### `root` * **Type**: `TsConfigJson` * **See**: https://www.typescriptlang.org/tsconfig Deep-merged into the root workspaces tsconfig (`rootFile`) during sync. ### `enabled` * **Type**: `boolean` Enable/disable this section (default: enabled when defined). ### `regenerate` * **Type**: `boolean` * **Default**: `true` Regenerate this section's managed files during `dbx sync`. When false, existing files are left untouched and are neither written nor drift-checked. ## `loader` How `dbx.config.*` files are imported (tsconfig discovery). * **See**: https://tsx.is ### `tsconfig` * **Type**: `boolean | string` * **Default**: `true` The tsconfig the config loader uses. `true` selects the nearest `tsconfig.json`; a string selects a different file (relative to the project root); `false` disables tsconfig resolution. ### `enabled` * **Type**: `boolean` Enable/disable this section (default: enabled when defined). ### `regenerate` * **Type**: `boolean` * **Default**: `true` Regenerate this section's managed files during `dbx sync`. When false, existing files are left untouched and are neither written nor drift-checked. ## `templates` Template sources / scaffolding. ### `sources` * **Type**: `Array` Extra sources on top of the builtin + registry sources. #### `type` * **Required** * **Type**: `'builtin' | 'local' | 'npm' | 'git' | 'vite-plus' | 'remote'` How to load the source. #### `locate` * **Required** * **Type**: `string` A builtin id, local dir, npm scope, git URL or Vite+ id. #### `id` * **Type**: `string` Stable id (defaults to the basename/scope). #### `name` * **Type**: `string` Display name override. #### `description` * **Type**: `string` Description override. #### `kind` * **Type**: `'project' | 'workspace' | 'application' | 'folder' | 'tooling' | 'pipeline'` What the template produces. #### `ref` * **Type**: `string` Git branch/tag/commit. #### `registry` * **Type**: `string` Custom npm registry URL (default: the project package manager registry). #### `subdir` * **Type**: `string` Subdirectory within the source that holds the template. #### `tags` * **Type**: `Array` Free-form tags. #### `online` * **Type**: `boolean` Whether the source needs network access. ### `enabled` * **Type**: `boolean` Enable/disable this section (default: enabled when defined). ### `regenerate` * **Type**: `boolean` * **Default**: `true` Regenerate this section's managed files during `dbx sync`. When false, existing files are left untouched and are neither written nor drift-checked. ## `registry` Registry source allow/deny policies (templates + providers). ### `templates` * **Type**: `ToolchainRegistryPolicy` Allow/deny globs for template sources and registries. #### `allow` * **Type**: `Array` Allowed host/path globs. When non-empty, only matching sources are used (eg. `*.example.com`, `https://registry.example.com/**`). #### `deny` * **Type**: `Array` Denied host/path globs (checked before `allow`). ### `providers` * **Type**: `ToolchainRegistryPolicy` Allow/deny globs for provider sources and registries. ### `enabled` * **Type**: `boolean` Enable/disable this section (default: enabled when defined). ### `regenerate` * **Type**: `boolean` * **Default**: `true` Regenerate this section's managed files during `dbx sync`. When false, existing files are left untouched and are neither written nor drift-checked. ## `catalogs` Package catalogs written to the package manager catalog file (`catalog:`). ### `packages` * **Type**: `Record` The default catalog: package name -> version range. ### `named` * **Type**: `Record>` Named catalogs (Yarn `catalogs:` / pnpm `catalogs:`): name -> packages. ### `enabled` * **Type**: `boolean` Enable/disable this section (default: enabled when defined). ### `regenerate` * **Type**: `boolean` * **Default**: `true` Regenerate this section's managed files during `dbx sync`. When false, existing files are left untouched and are neither written nor drift-checked. ## `vite` The full Vite+ config; `dbx sync` writes the root `vite.config.ts` from it. ### `config` * **Type**: `boolean | string` * **Default**: `true` Write the managed Vite config. A string sets its file name/path (relative to the project, or an absolute path inside it). ### `shim` * **Type**: `'runtime' | 'static'` * **Default**: `"runtime"` How the generated `vite.config.ts` is rendered. `runtime` loads the config from `dbx.config.*`; `static` serializes it into the file so the shim does not import `@deltabox/toolchain` (it then needs no built `dist`). ### `shimImport` * **Type**: `string` Module specifier used to import `resolveVite` in runtime shims (default `@deltabox/toolchain/vite`; the legacy `vite-plugin-dbx` is still accepted). A relative path is resolved from the repo root and rewritten relative to each generated config - useful for dogfooding a source checkout without a built `dist`. ### `fmt` * **Type**: `boolean | OxfmtConfig` * **See**: https://oxc.rs/docs/guide/usage/formatter/config-file-reference.html Oxfmt options; `true` uses the toolchain defaults. ### `lint` * **Type**: `boolean | OxlintConfig` * **See**: https://oxc.rs/docs/guide/usage/linter/config-file-reference.html Oxlint options; `true` uses the toolchain defaults. ### `enabled` * **Type**: `boolean` Enable/disable this section (default: enabled when defined). ### `regenerate` * **Type**: `boolean` * **Default**: `true` Regenerate this section's managed files during `dbx sync`. When false, existing files are left untouched and are neither written nor drift-checked. ## `watch` Watch behaviour for `dbx watch`. ### `debounce` * **Type**: `number` * **Default**: `150` Debounce window in ms. ### `exclude` * **Type**: `string | Array` Glob(s) excluded from watching. Defaults to the common ignored paths (`node_modules`, `.dbx`, `dist`, `build`, ...). ### `gitignore` * **Type**: `boolean` * **Default**: `true` Also respect `.gitignore` files (root + nested) when watching. ### `enabled` * **Type**: `boolean` Enable/disable this section (default: enabled when defined). ### `regenerate` * **Type**: `boolean` * **Default**: `true` Regenerate this section's managed files during `dbx sync`. When false, existing files are left untouched and are neither written nor drift-checked. ## `sync` `dbx sync` behaviour (formatting of the managed files). ### `format` * **Type**: `boolean | object` Opt-in formatting of the managed files after generation. `true` uses the defaults, `false` disables it, and an object tunes `enabled`/`fix`/`command`/`exclude`. #### `enabled` * **Type**: `boolean` Format the managed files after writing them (default true once enabled). #### `fix` * **Type**: `boolean` Rewrite the managed files with the formatter (default true). Set false to run the formatter in check mode instead. #### `command` * **Type**: `string` Override the formatter command. `{files}` expands to the managed files (space-separated); when it is absent the files are appended. #### `exclude` * **Type**: `Array` Globs of managed files to leave unformatted (per-file opt-out). ### `enabled` * **Type**: `boolean` Enable/disable this section (default: enabled when defined). ### `regenerate` * **Type**: `boolean` * **Default**: `true` Regenerate this section's managed files during `dbx sync`. When false, existing files are left untouched and are neither written nor drift-checked. ## `logger` Logging level, colours and prefix for toolchain output. ### `level` * **Type**: `'debug' | 'info' | 'warn' | 'error' | 'silent'` * **Default**: `"info"` Minimum level to print. ### `color` * **Type**: `boolean` * **Default**: `true` Force colours on/off; `--no-color` disables. ### `name` * **Type**: `string` * **Default**: `"dbx"` Prefix non-indented lines with `:`. ### `suppress` * **Type**: `string | Array` Warning/error id, message substring, or `/regex/` to silence (single value or array). ### `logger` * **Type**: `object` Custom `ToolchainLogger` implementation (TS/JS configs only; JSON cannot carry functions). #### `raw` * **Required** * **Type**: `(message?: string) => void` Write raw stdout. #### `rawError` * **Required** * **Type**: `(message?: string) => void` Write raw stderr. #### `write` * **Required** * **Type**: `(channel: 'out' | 'err', text: string) => void` Write to a specific output channel. #### `debug` * **Required** * **Type**: `(message?: string) => void` Print a debug message. #### `info` * **Required** * **Type**: `(message?: string) => void` Print an info message. #### `success` * **Required** * **Type**: `(message?: string) => void` Print a success message. #### `warn` * **Required** * **Type**: `(message?: string, id?: string) => void` Print a warning. #### `error` * **Required** * **Type**: `(message?: string, id?: string) => void` Print an error. ### `enabled` * **Type**: `boolean` Enable/disable this section (default: enabled when defined). ### `regenerate` * **Type**: `boolean` * **Default**: `true` Regenerate this section's managed files during `dbx sync`. When false, existing files are left untouched and are neither written nor drift-checked. ## `providers` Provider command behaviour (eg. colour for the passthrough commands). ### `color` * **Type**: `boolean` Force provider command colours on/off (default: inherit the logger). ### `enabled` * **Type**: `boolean` Enable/disable this section (default: enabled when defined). ### `regenerate` * **Type**: `boolean` * **Default**: `true` Regenerate this section's managed files during `dbx sync`. When false, existing files are left untouched and are neither written nor drift-checked. ## `mcp` MCP server and skill installation for AI harnesses. ### `skills` * **Type**: `boolean | ToolchainMcpSkillsConfig` Install the official dbx skill into agent harnesses during `dbx sync`. Opt in by defining this section. #### `agents` * **Type**: `'claude' | 'codex' | 'vscode' | 'opencode' | 'pi' | 'custom' | Array<'claude' | 'codex' | 'vscode' | 'opencode' | 'pi' | 'custom'>` Agent harness(es) to install into (default: every builtin provider). `custom` requires `dir`. #### `scope` * **Type**: `'project' | 'global'` * **Default**: `"project"` Write the skill into the project (default) or the user profile. #### `dir` * **Type**: `string` Custom directory to write the skill into (with `agents: ['custom']`). #### `force` * **Type**: `boolean` * **Default**: `false` Overwrite an existing skill file (default: keep it). #### `enabled` * **Type**: `boolean` Enable/disable this section (default: enabled when defined). #### `regenerate` * **Type**: `boolean` * **Default**: `true` Regenerate this section's managed files during `dbx sync`. When false, existing files are left untouched and are neither written nor drift-checked. ### `enabled` * **Type**: `boolean` Enable/disable this section (default: enabled when defined). ### `regenerate` * **Type**: `boolean` * **Default**: `true` Regenerate this section's managed files during `dbx sync`. When false, existing files are left untouched and are neither written nor drift-checked. ## Full example ```ts [dbx.config.ts] import { defineConfig } from '@deltabox/toolchain'; export default defineConfig({ toolchain: { project: { type: 'monorepo-root', name: 'myapp', scope: '@org' }, ci: { ci: true, release: true, changelog: { branches: { main: 'main' } } }, tsconfig: { refs: true }, templates: { sources: [{ type: 'local', locate: './templates', kind: 'application' }] }, vite: { fmt: { semi: true, singleQuote: true }, test: { include: ['src/**/*.test.ts'] } }, watch: { debounce: 150 }, }, }); ```