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): 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>/<name>).
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 <name>@<version>.
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<string>
Replace on.push.branches.
pullRequestBranches
- Type:
Array<string>
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<JsonObject>
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<string, string>
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<string, string>
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<WorkflowStepsConfig>
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<WorkflowStep>
Steps inserted at the start.
name
- Type:
string
Step display name.
id
- Type:
string
Step id (for steps.<id> 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<string, string | number | boolean>
Inputs for a uses action.
env
- Type:
Record<string, string>
Environment variables for the step.
after
- Type:
Array<WorkflowStep>
Steps appended at the end.
jobs
- Type:
Record<string, WorkflowJob>
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 (). 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<string>
Replace on.push.branches.
pullRequestBranches
- Type:
Array<string>
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<WorkflowStepsConfig>
Extra steps for a job (one group, or per-job groups).
jobs
- Type:
Record<string, WorkflowJob>
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<string> - Default:
["main"]
Branch glob(s) the CI + release workflows run on, and the release PR base.
dev
- Type:
string | Array<string>
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<string>
Allowed commit types (commitlint).
scopes
- Type:
Array<string>
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<string>
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<ChangelogTargetedPrerelease | string> | 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<string>
Only apply to workspaces whose repo-relative directory matches one of these globs (tsconfig-style include).
exclude
- Type:
string | Array<string>
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 <tag>.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<ChangelogTargetedBump | ChangelogBumpRule> | 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<string>
Only apply to workspaces whose repo-relative directory matches one of these globs (tsconfig-style include).
exclude
- Type:
string | Array<string>
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<string>
Match any of these CC types.
scope
- Type:
string
Match this Conventional-Commits scope.
scopes
- Type:
Array<string>
Match any of these CC scopes.
pattern
- Type:
string
Match this regular expression.
match
- Type:
string
Match this substring.
minor
- Type:
ChangelogTargetedBump | Array<ChangelogTargetedBump | ChangelogBumpRule> | ChangelogBumpRule
A bump rule globally, or per-target via { target, include, exclude, options }.
patch
- Type:
ChangelogTargetedBump | Array<ChangelogTargetedBump | ChangelogBumpRule> | ChangelogBumpRule
A bump rule globally, or per-target via { target, include, exclude, options }.
allowOverBump
- Type:
ChangelogTargetedAllowOverBump | Array<ChangelogTargetedAllowOverBump | boolean> | 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<string>
Only apply to workspaces whose repo-relative directory matches one of these globs (tsconfig-style include).
exclude
- Type:
string | Array<string>
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<ChangelogTargetedCommit | ChangelogCommitFormatConfig> | 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<string>
Only apply to workspaces whose repo-relative directory matches one of these globs (tsconfig-style include).
exclude
- Type:
string | Array<string>
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 <author> 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 <details> 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 <summary> 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<string>
Wrap these CC type sections (all types when true; enabled by default).
custom
- Type:
ChangelogDetailsCustom | Array<ChangelogDetailsCustom>
Wrap matching text (the match or start match becomes the summary).
title
- Type:
string
Custom <summary> 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<ChangelogTargetedProvider | string | ChangelogProviderConfig | ((ctx: ChangelogProviderContext) => 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<string>
Only apply to workspaces whose repo-relative directory matches one of these globs (tsconfig-style include).
exclude
- Type:
string | Array<string>
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<string>
Only apply to workspaces whose repo-relative directory matches one of these globs (tsconfig-style include).
exclude
- Type:
string | Array<string>
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<string | ChangelogGroupOptions> | Record<string, string | ChangelogGroupOptions | boolean> | ((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<string>
Replace on.push.branches.
pullRequestBranches
- Type:
Array<string>
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<WorkflowStepsConfig>
Extra steps for a job (one group, or per-job groups).
jobs
- Type:
Record<string, WorkflowJob>
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 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<string> - Default:
["/"]
Directories to scan.
ecosystems
- Type:
Array<string> - Default:
["github-actions","npm"]
Package ecosystems. github-actions keeps voidzero-dev/setup-vp and the other actions up to date.
labels
- Type:
Array<string>
Labels added to the update PRs.
openPullRequestsLimit
- Type:
number - Default:
5
Maximum open update PRs per entry.
groups
- Type:
Record<string, object>
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<object> | Record<string, Array<object>>
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<string>
Update types (eg. version-update:semver-major).
versions
- Type:
Array<string>
Version ranges to allow/ignore.
ignore
- Type:
Array<object> | Record<string, Array<object>>
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<string>
Update types (eg. version-update:semver-major).
versions
- Type:
Array<string>
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<string, CustomWorkflowSettings>
Additional custom workflows, keyed by id (eg. custom.my-workflow). Each id writes <dir>/<filename ?? id>.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<string>
Allowed commit types (commitlint).
scopes
- Type:
Array<string>
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<string>
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<ChangelogTargetedPrerelease | string> | 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<string>
Only apply to workspaces whose repo-relative directory matches one of these globs (tsconfig-style include).
exclude
- Type:
string | Array<string>
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 <tag>.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<ChangelogTargetedBump | ChangelogBumpRule> | 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<string>
Only apply to workspaces whose repo-relative directory matches one of these globs (tsconfig-style include).
exclude
- Type:
string | Array<string>
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<string>
Match any of these CC types.
scope
- Type:
string
Match this Conventional-Commits scope.
scopes
- Type:
Array<string>
Match any of these CC scopes.
pattern
- Type:
string
Match this regular expression.
match
- Type:
string
Match this substring.
minor
- Type:
ChangelogTargetedBump | Array<ChangelogTargetedBump | ChangelogBumpRule> | ChangelogBumpRule
A bump rule globally, or per-target via { target, include, exclude, options }.
patch
- Type:
ChangelogTargetedBump | Array<ChangelogTargetedBump | ChangelogBumpRule> | ChangelogBumpRule
A bump rule globally, or per-target via { target, include, exclude, options }.
allowOverBump
- Type:
ChangelogTargetedAllowOverBump | Array<ChangelogTargetedAllowOverBump | boolean> | 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<string>
Only apply to workspaces whose repo-relative directory matches one of these globs (tsconfig-style include).
exclude
- Type:
string | Array<string>
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<ChangelogTargetedCommit | ChangelogCommitFormatConfig> | 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<string>
Only apply to workspaces whose repo-relative directory matches one of these globs (tsconfig-style include).
exclude
- Type:
string | Array<string>
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 <author> 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 <details> 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 <summary> 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<string>
Wrap these CC type sections (all types when true; enabled by default).
custom
- Type:
ChangelogDetailsCustom | Array<ChangelogDetailsCustom>
Wrap matching text (the match or start match becomes the summary).
title
- Type:
string
Custom <summary> 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<ChangelogTargetedProvider | string | ChangelogProviderConfig | ((ctx: ChangelogProviderContext) => 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<string>
Only apply to workspaces whose repo-relative directory matches one of these globs (tsconfig-style include).
exclude
- Type:
string | Array<string>
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<string>
Only apply to workspaces whose repo-relative directory matches one of these globs (tsconfig-style include).
exclude
- Type:
string | Array<string>
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<string | ChangelogGroupOptions> | Record<string, string | ChangelogGroupOptions | boolean> | ((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<string>
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<string>
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 writesbiome.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<string>
Glob(s) for the workspace default tsconfig files. Defaults to matching every defaultFile recursively.
exclude
- Type:
string | Array<string>
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<string>
Only auto-wire entries matching these globs (auto: workspace dirs; aliasAuto: rewritten alias keys; refsAuto: reference paths).
exclude
- Type:
Array<string>
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 @/<package> and @/<package>/<subpath>).
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<string>
Only auto-wire entries matching these globs (auto: workspace dirs; aliasAuto: rewritten alias keys; refsAuto: reference paths).
exclude
- Type:
Array<string>
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<string> | false
extends written into scaffolded tsconfig.base.json files (or false to remove the field).
default
- Type:
string | Array<string> | false
extends written into scaffolded tsconfig.default.json files (or false to remove the field).
build
- Type:
string | Array<string> | 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<ToolchainTemplateSource>
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<string>
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<string>
Allowed host/path globs. When non-empty, only matching sources are used (eg. *.example.com, https://registry.example.com/**).
deny
- Type:
Array<string>
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<string, string>
The default catalog: package name -> version range.
named
- Type:
Record<string, Record<string, string>>
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<string>
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<string>
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 <name>:.
suppress
- Type:
string | Array<string>
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
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 },
},
});