--- url: https://toolchain.dbx.studio/guide.md --- # Getting started `@deltabox/toolchain` is a config-driven layer around [Vite+](https://viteplus.dev). It exists to remove the glue work that appears once a project grows beyond a single package: the same settings spread across a dozen files, generated files that drift, and release chores that are easy to get wrong. You describe the project once, and the toolchain keeps the rest in sync. ## Install ::: code-group ```sh [npm] # as a dev dependency in the project you want to manage npm install @deltabox/toolchain --save-dev ``` ```sh [yarn] # as a dev dependency in the project you want to manage yarn add -D @deltabox/toolchain ``` ```sh [pnpm] # as a dev dependency in the project you want to manage pnpm add -D @deltabox/toolchain ``` ```sh [bun] # as a dev dependency in the project you want to manage bun add -D @deltabox/toolchain ``` ::: ```sh # or for global usage npm install -g @deltabox/toolchain ``` The published package exposes one binary, `dbx`: ```sh dbx --help ``` ## Interactive CLI Commands are flag-driven, but in an interactive terminal (a TTY) a few prompt for the values you omit: ```sh dbx create # pick a template, project name, scope, inputs and actions dbx migrate --recursive # pick which projects to migrate ``` `dbx migrate` without `--from` still detects the sources automatically; the prompt is only for the project selection with `--recursive`. Pass `--json`, pipe the command, or supply the flags to run non-interactively. `dbx template:init` also accepts flags (`--name`, `--kind`, ...) for scripted use. ## Create a config Add the `dbx()` plugin to `vite.config.ts` (recommended, no `dbx.config.*` needed): ```ts import { dbx } from '@deltabox/toolchain/vite'; export default { plugins: [dbx({ toolchain: { fmt: true, lint: true } })], }; ``` See [Vite plugin](/guide/vite-plugin) for the install steps and what the plugin does. Or, for a project that does not use Vite, scaffold a standalone config: ```sh dbx project:config # detect + write dbx.config.ts ``` Or start from a template: ```sh dbx template:list dbx create --template project --name my-app --out ./my-app ``` ## Sync `sync` runs every enabled task and writes the managed files (adding a manifest at `.dbx/toolchain/manifest.json`): ```sh dbx sync # write managed files dbx sync --check # CI: fail if files are out of date dbx sync --recursive # every managed project, in dependency order dbx sync --only tsconfig # only refresh tsconfig aliases/references dbx watch # re-sync on change ``` The generated state lives under `.dbx/`. Add it to `.gitignore`, keeping only the manifest (it holds no absolute paths): ```gitignore .dbx/* !.dbx/toolchain .dbx/toolchain/* !.dbx/toolchain/manifest.json ``` `dbx sync` adds this block to an existing `.gitignore` automatically, so you only need to add it by hand when the repo has no `.gitignore` yet. ## What gets managed | Area | Section in the config | | ------------------------------------------------------------------- | ----------------------------- | | GitHub workflows, commitlint, Conventional-Commits VS Code settings | `ci` | | `biome.json` (formatter/linter) | `fmt.biome` / `lint.biome` | | `.oxfmtrc.json` / `.oxlintrc.json` (Oxc) | `fmt.oxc` / `lint.oxc` | | Workspace `tsconfig.json` files (aliases + references) | `tsconfig` | | `vite.config.ts` (Vite+ consumers) | `vite` | | Template sources / scaffolding | `templates` | | Package catalogs (`.yarnrc.yml` / `pnpm-workspace.yaml`) | [`catalogs`](/guide/catalogs) | | Watch behaviour | `watch` | Every section is **opt-in by presence**: define it to enable it, omit it to leave that area untouched. ## Next * [Monorepo guide](/guide/monorepo) * [CLI reference](/guide/cli) * [Configuration reference](/config/reference) * [TypeScript](/guide/typescript) * [Project](/guide/project) * [Package catalogs](/guide/catalogs) * [CI](/guide/ci/) * [Changelog](/guide/changelog/) * [tsconfig](/guide/tsconfig) * [Formatting & linting](/guide/formatting) * [Vite+](/guide/vite) * [Watch](/guide/watch) * [Logger](/guide/logger) * [Config generator](/guide/config-generator/) * [Providers (Vite+)](/guide/providers) * [Package scripts](/guide/scripts) * [Templates](/guide/templates) * [Docker](/guide/docker) * [Migrations](/guide/migrations/) * [Programmatic API](/guide/api/) * [LLMs](/llms) --- --- url: https://toolchain.dbx.studio/guide/why-use-this.md --- # Why use this? `@deltabox/toolchain` is a config-driven layer around [Vite+](https://viteplus.dev). It exists to remove the glue work that appears once a project grows beyond a single package: the same settings spread across a dozen files, generated files that drift, and release chores that are easy to get wrong. You describe the project once, and the toolchain keeps the rest in sync. The open-source [`dbx` toolchain repository](https://github.com/deltabox-studio/toolchain) uses the toolchain itself to maintain its development: sync, config generation, `tsconfig` management, changelog/release automation and the docs site are all driven by the same setup described here. That dogfooding keeps the workflow honest. ## The problems it removes ### Configuration sprawl A typical TypeScript project ends up with separate configs for Vite, Vitest, TypeScript, formatting, linting, CI, changelog automation, editor settings and Docker. They overlap, disagree, and are updated at different times. With dbx, those settings live in one `dbx.config.*` (or inline in the `dbx()` Vite plugin). Each section is opt-in, so you only own the parts you use. ### Monorepo drift Hand-maintained `tsconfig` references, path aliases, workspace dependency ranges, catalogs, scripts and managed files are routine sources of breakage. One package gets a new alias, another keeps an old `tsconfig`, CI starts failing. The project graph, `tsconfig` generation and `dbx sync --check` keep those artifacts consistent and make drift visible before it lands. ### Local and CI differences "Works on my machine" usually means a different formatter version, a missing commit hook, stale generated files or a release step that only runs locally. The toolchain uses it's commands in generated files and hooks locally and in CI, with `sync --check` as a single verification gate. For Vite+ projects it passes through Vite+ commands. ### Release and CI glue Changelog formatting, version bumps, release notes, issue and PR links, Dependabot updates and workflow maintenance are recurring work that has little to do with the product. dbx generates the workflows and the changelog pipeline from the same config, so releases stay repeatable and the release notes stay readable. ### Inconsistent scaffolding Every new package starts from a different copy of "the right setup", and the copy slowly diverges. Builtin templates and generators produce a consistent project shape, including Vite+, Oxc, `tsconfig`, CI, catalogs and Docker when requested. ### Toolchain version skew Keeping `vite`, `vitest`, `tsdown`, Oxfmt and Oxlint aligned across a repo is its own maintenance task. Vite+ already bundles them; dbx leans on that single toolchain instead of installing each tool separately. ## What you get * **One config, opt-in sections.** `project`, `ci`, `tsconfig`, `templates`, `fmt`/`lint`, `vite`, `watch`, `logger`, `providers` and more. * **Sync with drift detection.** `dbx sync` writes managed files; `dbx sync --check` fails when they are stale. * **A Vite+ integration.** The `dbx()` plugin carries the config inline and adds fmt/lint, tasks, hooks and passthrough commands. * **A config generator.** Turn schemas into env docs, TypeScript types, JSON Schema and typed CLI options. * **Project-aware tooling.** Workspace graph, tsconfig refs/aliases, catalogs and per-package releases. * **Scaffolds and templates.** Consistent projects, workspaces, built-in & custom libraries, server templates and Vite apps. * **Automated maintenance.** CI, changelog, releases, issues and Dependabot workflows. * **Editor and agent integration.** A VS Code extension and an MCP server for the same APIs. ## Core features ### VS Code extension The extension turns the same project model into a UI: browse managed files and the project graph, run sync and migrations, scaffold projects, open provider commands and inspect what the toolchain manages. It reads provider and project data from the CLI, so it stays aligned with the terminal workflow instead of being a separate configuration surface. See the [VS Code extension guide](/guide/vscode). ### Config generator and engine The config engine is a schema-first way to describe configuration once and derive the surrounding artifacts from it. It generates TypeScript types, env docs, JSON Schema and typed CLI options/programs, and provides file/env/CLI loaders with predictable precedence. Teams that ship a config format can reuse that machinery instead of hand-writing each output. See the [Config generator guide](/guide/config-generator/). ### Providers Providers describe the external toolchains a project can use, starting with Vite+. The CLI and the VS Code extension consume the same provider descriptors, so commands, availability and metadata do not drift between the terminal and the editor. Providers are not limited to JavaScript. A descriptor can wrap any CLI binary, so the same surface can expose Python (`uv`, `ruff`, `pytest`), C#/.NET (`dotnet`), Java (Maven or Gradle), Rust (`cargo`), Go and other language toolchains. A polyglot repo can use `dbx python:*`, `dbx rust:*`, `dbx dotnet:*` and the rest without teaching the terminal, CI and editor a different command set for every language. See [Providers](/guide/providers#other-language-toolchains). ### MCP The MCP server exposes the public toolchain APIs to AI agents and editors. You can install it for Claude, Codex, VS Code, OpenCode, Pi or a custom directory, then let an agent inspect projects, configs and generated files through the same commands and types a developer uses. See [MCP](/guide/mcp). ## Who it is for It is most useful when at least one of these is true: * you **maintain a monorepo** or several related packages; * you want **one place** for **toolchain, CI and release configuration**; * you use **Vite or Vite+** and want a **consistent project workflow**; * you define **schemas or config formats** and want **types, docs, JSON Schema and typed CLI options** generated from them; * you maintain **many environment variables** and want **documented, typed config** with **file/env/CLI precedence**; * you want **one consistent CLI and task surface** for scripts, tasks and provider toolchains; * you build a **library or internal tool** that needs its own **typed config and CLI** without rebuilding loaders, validation and help; * you work **across languages** and want Python, .NET, Java, Rust and other tools exposed through the **same command surface**; * you **scaffold projects or packages** regularly; * you work in **VS Code or with AI agents** and want them to understand the **same project model**; * you are tired of **generated files and release chores drifting**. ## When it might not fit A tiny single-file project rarely needs the full surface. A team with a very bespoke pipeline may prefer to keep it in-house. Because every section is opt-in, you can also start with only `project` and `tsconfig`, then add automation later. The toolchain is a dev dependency. It does not replace Vite+ at runtime; it makes the project around Vite+ easier to keep consistent. ## Where to go next * [Getting started](/guide/) — install the CLI and create a config. * [Monorepo guide](/guide/monorepo) — project graph, `tsconfig` and tasks. * [Vite+](/guide/vite) — plugin mode, config mode and local CLI usage. * [Package scripts](/guide/scripts) — the recommended `fmt`, `check`, `test` and `sync` scripts. --- --- url: https://toolchain.dbx.studio/config.md --- # Overview There are four ways to configure dbx. They all feed the same toolchain model, so a project can combine them. ## `dbx.config.*` A standalone config file (`dbx.config.ts`, `.mts`, `.cts`, `.js`, `.mjs`, `.cjs` or `.json`) exports `{ toolchain: { ... } }` with `defineConfig`. It is the non-Vite path and is typed as `ToolchainConfig` (see the [TypeScript guide](/guide/typescript)). Every section is opt-in by presence. ## Vite plugin In a Vite or Vite+ project, pass the same `toolchain` object to the `dbx()` plugin in `vite.config.*`. The CLI reads it back from the Vite config, so no `dbx.config.*` is required. See [Vite plugin](/guide/vite-plugin). ## CLI `dbx` command flags configure a command for one run. The available options are generated from the command descriptors. See the [CLI reference](/config/cli). ## Environment variables Schema leaves that declare `.meta({ envName })` can be set through env vars (the toolchain config uses the `DBX_` prefix). See the [environment reference](/config/env) and the [Config Generator](/guide/config-generator/). ## Editor JSON Schema The generated [config.schema.json](https://toolchain.dbx.studio/config.schema.json) gives editors completion and validation for `dbx.config.*`. The exhaustive object reference is [dbx.config](/config/reference). ## Types Find all static types for the configurations [here](https://github.com/deltabox-studio/toolchain/blob/main/packages/shared/src/config-types.ts). ### Fields Every generated config reference page uses the same [ConfigMeta](https://github.com/deltabox-studio/toolchain/blob/main/packages/config/src/types/meta.ts) fields defined in Zod/Untyped schemas: * `description` * `required` * `deprecated` * `example` * `secret` * `scope` * `public` * `defaultValue` * `envName` (the env fields) * `envPath` * `cli` / `cliCommand` (schema-driven CLI flags and commands) * `envExpose` (keep a value CLI-only) and more. --- --- url: https://toolchain.dbx.studio/config/cli.md --- # CLI reference Generated from the same `CliCommand` descriptors the `dbx` binary registers. | Command | Description | | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | | [`dbx projects`](#projects) | Discover projects and write .dbx/toolchain/projects.json. | | [`dbx sync`](#sync) | Regenerate every managed file from dbx.config.*. | | [`dbx watch`](#watch) | Sync once, then watch key files and re-sync on change. | | [`dbx reset`](#reset) | Remove generated files, the .dbx/toolchain manifest and/or the dbx config from a project. | | [`dbx providers`](#providers) | List the tooling providers (Vite+, ...) and their commands. | | [`dbx enabled`](#enabled) | Print whether the toolchain is enabled for this project (and the scope). | | [`dbx enable`](#enable) | Enable the toolchain (workspace scope by default). | | [`dbx disable`](#disable) | Disable the toolchain (workspace scope by default). | | [`dbx project:init`](#project-init) | Scaffold a single-package TypeScript project. | | [`dbx project:init:monorepo`](#project-init-monorepo) | Scaffold a monorepo root (add --example for one example workspace). | | [`dbx project:init:workspace`](#project-init-workspace) | Scaffold a monorepo workspace package into an existing monorepo root. | | [`dbx project:config`](#project-config) | Generate dbx.config.* for existing projects that are missing one. | | [`dbx template:list`](#template-list) | List templates (builtin + local + opted-in online sources). | | [`dbx template:init`](#template-init) | Write a template.json to a directory, making it a local template. | | [`dbx template:add`](#template-add) | Record a template source in .dbx/toolchain/templates.json. | | [`dbx template:remove`](#template-remove) | Remove a source from .dbx/toolchain/templates.json. | | [`dbx template:registry`](#template-registry) | Manage the global template search paths (and sync them to the VS Code setting). | | [`dbx registry`](#registry) | List or manage the template/provider registries. | | [`dbx template:info`](#template-info) | Show one template by id. | | [`dbx create`](#create) | Scaffold a project from a template (builtin, local or Vite+). | | [`dbx tsconfig`](#tsconfig) | Generate workspace tsconfig.json files from the default tsconfig (aliases + references). | | [`dbx cleanup`](#cleanup) | Remove build artifacts (*.tsbuildinfo, dist/). | | [`dbx cleanup:turbo`](#cleanup-turbo) | Remove the turbo cache (.turbo/). | | [`dbx migrate`](#migrate) | Migrate Biome / ESLint / Prettier / Dprint / Oxc config, or fold vite.config.* into dbx.config. | | [`dbx migrate:list`](#migrate-list) | List the registered migrations and whether each is detected. | | [`dbx fmt`](#fmt) | Format with the detected formatter (Vite+ Oxfmt, Prettier, Biome, dprint or Oxc). | | [`dbx lint`](#lint) | Lint with the detected linter (Vite+ Oxlint, ESLint or Biome). | | [`dbx workflow`](#workflow) | Trigger generated workflows with their vendor CLI (`gh`, `glab` or `az`). | | [`dbx changelog`](#changelog) | Scan commits, derive the semver bump and update the CHANGELOG.md files + versions. | | [`dbx mcp:serve`](#mcp-serve) | Run the dbx MCP server over stdio (for MCP clients). | | [`dbx mcp:install`](#mcp-install) | Install the dbx MCP server + skill into an AI harness/editor. | | [`dbx mcp:list`](#mcp-list) | List the builtin MCP providers (Claude, Codex, VS Code, OpenCode, Pi). | | [`dbx skills`](#skills) | Check or install the official dbx toolchain skill for AI agents (docs lookup). | | [`dbx vite`](#vite) | Run any Vite+ command through `vp` (eg. `dbx vite dev`). | | [`dbx vite:create`](#vite-create) | Vite+: Create a new project from a template. | | [`dbx vite:migrate`](#vite-migrate) | Vite+: Migrate an existing project to Vite+. | | [`dbx vite:config`](#vite-config) | Vite+: Configure hooks and agent integration. | | [`dbx vite:hooks`](#vite-hooks) | Vite+: Manage the Git hook dispatcher. | | [`dbx vite:staged`](#vite-staged) | Vite+: Run linters on staged files. | | [`dbx vite:install`](#vite-install) | Vite+: Install dependencies with the detected package manager. | | [`dbx vite:env`](#vite-env) | Vite+: Manage Node.js and package managers. | | [`dbx vite:dev`](#vite-dev) | Vite+: Run the Vite development server. | | [`dbx vite:check`](#vite-check) | Vite+: Run format, lint and type checks. | | [`dbx vite:lint`](#vite-lint) | Vite+: Lint code with the active linter (Oxlint via Vite+). | | [`dbx vite:fmt`](#vite-fmt) | Vite+: Format code with the active formatter (Oxfmt via Vite+). | | [`dbx vite:test`](#vite-test) | Vite+: Run tests through bundled Vitest. | | [`dbx vite:run`](#vite-run) | Vite+: Run package scripts and monorepo tasks. | | [`dbx vite:exec`](#vite-exec) | Vite+: Execute a binary from local node_modules. | | [`dbx vite:node`](#vite-node) | Vite+: Run a Node.js script in the Vite+ env. | | [`dbx vite:dlx`](#vite-dlx) | Vite+: Run a package binary without installing it. | | [`dbx vite:cache`](#vite-cache) | Vite+: Manage the task cache. | | [`dbx vite:build`](#vite-build) | Vite+: Build for production. | | [`dbx vite:pack`](#vite-pack) | Vite+: Build libraries for npm or standalone binaries. | | [`dbx vite:preview`](#vite-preview) | Vite+: Preview the production build. | | [`dbx vite:add`](#vite-add) | Vite+: Add packages to dependencies. | | [`dbx vite:remove`](#vite-remove) | Vite+: Remove packages from dependencies. | | [`dbx vite:update`](#vite-update) | Vite+: Update packages. | | [`dbx vite:dedupe`](#vite-dedupe) | Vite+: Deduplicate dependencies. | | [`dbx vite:outdated`](#vite-outdated) | Vite+: Check for outdated packages. | | [`dbx vite:list`](#vite-list) | Vite+: List installed packages. | | [`dbx vite:why`](#vite-why) | Vite+: Explain why a package is installed. | | [`dbx vite:info`](#vite-info) | Vite+: View package metadata. | | [`dbx vite:link`](#vite-link) | Vite+: Link local packages. | | [`dbx vite:unlink`](#vite-unlink) | Vite+: Unlink local packages. | | [`dbx vite:rebuild`](#vite-rebuild) | Vite+: Rebuild native modules. | | [`dbx vite:pm`](#vite-pm) | Vite+: Forward a command to the package manager. | | [`dbx vite:toolchain`](#vite-toolchain) | Vite+: Show Vite+ tool versions. | | [`dbx vite:upgrade`](#vite-upgrade) | Vite+: Update `vp` itself. | | [`dbx vite:implode`](#vite-implode) | Vite+: Remove `vp` and all related data. | ## `dbx projects` Discover projects and write .dbx/toolchain/projects.json. * `--cwd ‹dir›` — Root to scan (default: cwd). * `--max-depth ‹n›` — Max directory depth. (default: `5`) * `--no-write` — Do not write the graph file. * `--json` — Print the graph as JSON. ## `dbx sync` Regenerate every managed file from dbx.config.\*. * `--no-format` — Do not format the written managed files. * `--no-format-fix` — Run the formatter in check mode instead of rewriting the files. * `--format-command ‹value›` — Override the formatter command. `{files}` expands to the managed files (space-separated); when it is absent the files are appended. * `--format-exclude ‹value...›` — Globs of managed files to leave unformatted (per-file opt-out). * `--check` — Do not write; fail if files are out of date. * `--watch` — Keep running and re-sync on change. * `--recursive` — Sync every managed project in dependency order (nested workspaces included; configless projects only with --configless). * `--force` — Run even when no dbx.config.\* is present. * `--only ‹tasks›` — Only run the named sync task(s), comma-separated (eg. `tsconfig`). * `--json` — Print the sync result (including removed files) as JSON. ## `dbx watch` Sync once, then watch key files and re-sync on change. * `--debounce ‹value›` — Debounce window in ms. (default: `150`) * `--exclude ‹value...›` — Glob(s) excluded from watching. Defaults to the common ignored paths (`node_modules`, `.dbx`, `dist`, `build`, ...). * `--no-gitignore` — Do not respect .gitignore files. * `--force` — Run even when no dbx.config.\* is present. * `--list` — Print the resolved input globs (+ tsconfig file names) instead of watching. * `--json` — With --list: print the inputs as JSON. ## `dbx reset` Remove generated files, the .dbx/toolchain manifest and/or the dbx config from a project. * `--cwd ‹dir›` — Project root (default: cwd). * `--recursive` — Reset every discovered project under the root. * `--include ‹pattern...›` — * `--exclude ‹pattern...›` — * `--generated` — Remove only the generated/managed files. * `--manifest` — Remove only the .dbx/toolchain directory. * `--config` — Also remove dbx.config.\*. * `--all` — Remove generated files, the manifest and the config. * `--dry-run` — Report what would be removed without deleting. * `--json` — Print the result as JSON. ## `dbx providers` List the tooling providers (Vite+, ...) and their commands. * `--json` — Print the providers (with actions) as JSON. ## `dbx enabled` Print whether the toolchain is enabled for this project (and the scope). * `--json` — Print the resolved state as JSON. ## `dbx enable` Enable the toolchain (workspace scope by default). * `--global` — Set the global scope (`~/.dbx/toolchain/cli/config.json`). * `--workspace` — Set the workspace scope (`.vscode/settings.json`). * `--cwd ‹dir›` — Project root (default: cwd). * `--json` — Print the result as JSON. ## `dbx disable` Disable the toolchain (workspace scope by default). * `--global` — Set the global scope (`~/.dbx/toolchain/cli/config.json`). * `--workspace` — Set the workspace scope (`.vscode/settings.json`). * `--cwd ‹dir›` — Project root (default: cwd). * `--json` — Print the result as JSON. ## `dbx project:init` Scaffold a single-package TypeScript project. * `-n, --name ‹name›` — Project name. * `-s, --scope ‹scope›` — npm scope, eg. @org. * `-o, --out ‹dir›` — Output directory (default: cwd). * `--package-manager ‹pm›` — Package manager: yarn (default) | pnpm | npm | bun. * `--tool-version ‹name@range›` — Override a formatter/linter dependency version, eg. `oxfmt@^0.80.0`. * `--containerize` — Also generate Docker artifacts (Dockerfile + .dockerignore). * `--no-project-config` — Skip the generated vite.config.ts file (the project config). * `--type ‹type›` — Project type: project | monorepo-root | monorepo-workspace. * `--force` — Overwrite existing files in the output directory. ## `dbx project:init:monorepo` Scaffold a monorepo root (add --example for one example workspace). * `-n, --name ‹name›` — Project name. * `-s, --scope ‹scope›` — npm scope, eg. @org. * `-o, --out ‹dir›` — Output directory (default: cwd). * `--example` — Also scaffold one example workspace package. * `--package-manager ‹pm›` — Package manager: yarn (default) | pnpm | npm | bun. * `--tool-version ‹name@range›` — Override a formatter/linter dependency version, eg. `oxfmt@^0.80.0`. * `--no-project-config` — Skip the generated vite.config.ts file (the project config). * `--type ‹type›` — Project type: project | monorepo-root | monorepo-workspace. * `--force` — Overwrite existing files in the output directory. ## `dbx project:init:workspace` Scaffold a monorepo workspace package into an existing monorepo root. * `-n, --name ‹name›` — Workspace package name (unscoped). * `-s, --scope ‹scope›` — npm scope, eg. @org. * `-r, --root ‹dir›` — Monorepo root (default: cwd). * `-d, --dir ‹dir›` — Workspace dir relative to the root (default: packages/\). * `--package-manager ‹pm›` — Package manager: yarn (default) | pnpm | npm | bun. * `--tool-version ‹name@range›` — Override a formatter/linter dependency version, eg. `oxfmt@^0.80.0`. * `--no-project-config` — Skip the generated vite.config.ts file (the project config). * `--type ‹type›` — Project type: project | monorepo-root | monorepo-workspace. * `--force` — Overwrite existing files in the output directory. ## `dbx project:config` Generate dbx.config.\* for existing projects that are missing one. * `--cwd ‹dir›` — Root to scan (default: cwd). * `--include ‹pattern...›` — Only projects matching these patterns (glob or substring). * `--exclude ‹pattern...›` — Skip projects matching these patterns (glob or substring). * `--type ‹type›` — Force a project type for every config. * `--language ‹language›` — Config language: ts (default) | js. * `--config-extension ‹ext›` — Config extension: ts | mts | js | mjs | cjs (default inferred from the language and package type). * `--skip-config` — Only write .dbx/toolchain/projects.json; do not create dbx.config.\* files. * `--force` — Overwrite configs that already exist. * `--dry-run` — Report what would be written without writing. * `--json` — Print the result as JSON. ## `dbx template:list` List templates (builtin + local + opted-in online sources). * `--cwd ‹dir›` — Project root (default: cwd). * `--online` — Resolve online sources (npm/git). * `--offline` — Force offline (skip npm/git). * `--global` — Only the global registry templates. * `--kind ‹kind›` — project | workspace | application | folder | tooling | pipeline. * `--registry` — List only the .dbx/toolchain/templates.json sources. * `--json` — Print the templates as JSON. ## `dbx template:init` Write a template.json to a directory, making it a local template. * `[dir]` — Directory (default: cwd). * `--cwd ‹dir›` — Project root (default: cwd). * `--kind ‹kind›` — project | workspace | application | folder | tooling | pipeline. * `--name ‹name›` — Display name (default: folder name). * `--id ‹id›` — Stable template id (default: folder name). * `--description ‹text›` — Description. * `--var ‹pair...›` — Variable name\[:default] (repeatable). * `--tag ‹tag...›` — Tag (repeatable). * `--force` — Overwrite an existing template.json. * `--add` — Also record the folder in .dbx/toolchain/templates.json. * `--no-global` — Do not also store the template in the global registry. * `--json` — Print the manifest as JSON. ## `dbx template:add` Record a template source in .dbx/toolchain/templates.json. * `‹source›` — local path | git URL | @scope/create | type:locate * `--cwd ‹dir›` — Project root (default: cwd). * `--type ‹type›` — Force: builtin | local | npm | git | vite-plus | remote. * `--name ‹name›` — Display name. * `--id ‹id›` — Stable template id (default: inferred). * `--kind ‹kind›` — project | workspace | application | folder | tooling | pipeline. * `--ref ‹ref›` — Git branch/tag/commit. * `--registry ‹url›` — Custom npm registry (default: the project package manager). * `--subdir ‹dir›` — Subdirectory within the source. * `--no-global` — Do not also register the source in the global registry. * `--json` — Print the updated registry as JSON. ## `dbx template:remove` Remove a source from .dbx/toolchain/templates.json. * `‹id›` — Source id or type:locate. * `--cwd ‹dir›` — Project root (default: cwd). * `--global` — Remove the template from the global registry. * `--json` — Print the registry as JSON. ## `dbx template:registry` Manage the global template search paths (and sync them to the VS Code setting). * `--list` — List the resolved search paths (default). * `--add ‹path...›` — Add global search path(s). * `--remove ‹path...›` — Remove global search path(s). * `--set ‹path...›` — Replace the global search paths. * `--clear` — Reset the global search paths to the default. * `--vscode-dir ‹dir›` — Record the VS Code user dir (its settings.json holds the paths). * `--json` — Print the resolved config as JSON. ## `dbx registry` List or manage the template/provider registries. * `--cwd ‹dir›` — Project root (default: cwd). * `--kind ‹kind›` — What --add/--remove manages: templates | providers. * `--add ‹path›` — Add a registry path (or remote URL). * `--remove ‹path›` — Remove a registry path. * `--set ‹path...›` — Replace the registry search paths. * `--clear` — Clear the registry search paths. * `--scope ‹scope›` — project | global (default: global). * `--json` — Print the registries as JSON. ## `dbx template:info` Show one template by id. * `‹id›` — The template id. * `--cwd ‹dir›` — Project root (default: cwd). * `--online` — Resolve online sources. * `--json` — Print the template as JSON (the default). ## `dbx create` Scaffold a project from a template (builtin, local or Vite+). * `-t, --template ‹id›` — Template id (see template:list). * `--kind ‹kind›` — project | workspace | application | folder | tooling | pipeline. * `-n, --name ‹name›` — Project / package name. * `-s, --scope ‹scope›` — npm scope, eg. @org. * `-o, --out ‹dir›` — Output directory (default: cwd). * `--cwd ‹dir›` — Project root (default: cwd). * `--var ‹pair...›` — Template variables as key=value (repeatable). * `--action ‹id...›` — Action id to run after scaffolding (repeatable). * `--tool-version ‹name@range›` — Override a provisioned formatter/linter dependency version (repeatable). * `--online` — Resolve online templates too. * `--force` — Overwrite existing files in the output directory. * `--containerize` — Also generate Docker artifacts (Dockerfile + .dockerignore). * `--json` — Print the result as JSON. ## `dbx tsconfig` Generate workspace tsconfig.json files from the default tsconfig (aliases + references). * `--glob ‹value...›` — Glob(s) for the workspace default tsconfig files. Defaults to matching every `defaultFile` recursively. * `--exclude ‹value...›` — Glob(s) to exclude from `glob`. Defaults to the common ignored paths (`node_modules`, `.dbx`, `dist`, `build`, ...). * `--no-gitignore` — Do not respect .gitignore files. * `--refs` — Wire project references. * `--composite` — Emit `composite: true`. * `--no-aliases` — Skip path aliases. * `--flatten-remote-extends` — 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-src-dir ‹value›` — 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`). * `-i, --indent ‹value›` — JSON indentation. (default: `4`) * `--root-file ‹value›` — The workspaces tsconfig file name that holds `paths` + `references`. (default: `tsconfig.workspaces.json`) * `--default-file ‹value›` — The workspace default tsconfig file name that the generator expands. (default: `tsconfig.default.json`) * `--build-file ‹value›` — The workspace build tsconfig file name. (default: `tsconfig.build.json`) * `--cwd ‹dir›` — Repo root to scan (default: cwd). * `--auto` — Auto-wire the root workspaces tsconfig paths/references from the project graph (default false). * `--no-auto` — Only use the paths/references already in the root workspaces tsconfig. * `--auto-aliases` — Auto-wire path aliases (defaults to --auto). * `--no-auto-aliases` — Do not auto-wire path aliases. * `--auto-refs` — Auto-wire project references (defaults to --auto). * `--no-auto-refs` — Do not auto-wire project references. * `--tsconfig ‹file›` — Resolve this tsconfig instead of \/tsconfig.json. * `--root ‹dir›` — Root used to detect/resolve the tsconfig (default: cwd). * `--json` — Print the resolved { alias, paths, references } object. * `--alias` — Print only the resolved Vite/Vitest aliases. * `--paths` — Print only the resolved compilerOptions.paths. * `--references` — Print only the resolved project references. * `--no-extends` — Do not follow the tsconfig extends chain. * `--restore [kind]` — Remove the applied tsconfig overrides (all, or base|root|default|build) using the manifest snapshots. ## `dbx cleanup` Remove build artifacts (\*.tsbuildinfo, dist/). * `--cwd ‹dir›` — Directory to clean (default: cwd). * `--pattern ‹glob...›` — Override the match globs. ## `dbx cleanup:turbo` Remove the turbo cache (.turbo/). * `--cwd ‹dir›` — Directory to clean (default: cwd). ## `dbx migrate` Migrate Biome / ESLint / Prettier / Dprint / Oxc config, or fold vite.config.\* into dbx.config. * `--from ‹tool›` — Source tool (repeatable): biome | eslint | prettier | dprint | oxc | vite | all. * `--to ‹tool›` — Target tool (default: oxc). (default: `oxc`) * `--cwd ‹dir›` — Project root (default: cwd). * `--recursive` — Also migrate the discovered projects under the root (default: root only). * `--write` — Write the files (default: dry-run). * `--dry-run` — Do not write anything (default). * `--check` — CI: exit non-zero when the oxc config is stale. * `--target ‹target›` — files (default) | vite. * `--online` — Allow network (e.g. @oxlint/migrate). * `--ignore-vite-config-file` — Do not remove the folded `vite.config.*`. * `--ignore-managed-files` — Skip the post-migration sync (leave the toolchain-managed files as-is). * `--ignore-changelog` — Skip the changelog task in the post-migration sync. * `--tool-version ‹name@range›` — Override a provisioned formatter/linter dependency version (repeatable). * `--json` — Print the result as JSON. ## `dbx migrate:list` List the registered migrations and whether each is detected. * `--cwd ‹dir›` — Project root (default: cwd). * `--json` — Print as JSON. ## `dbx fmt` Format with the detected formatter (Vite+ Oxfmt, Prettier, Biome, dprint or Oxc). * `--cwd ‹dir›` — Project root to run `vp` in (default: cwd). ## `dbx lint` Lint with the detected linter (Vite+ Oxlint, ESLint or Biome). * `--cwd ‹dir›` — Project root to run `vp` in (default: cwd). ## `dbx workflow` Trigger generated workflows with their vendor CLI (`gh`, `glab` or `az`). * `[workflows]` — Workflow ids, custom ids, or file names (default: every enabled workflow). * `--cwd ‹dir›` — Project root (default: cwd). * `--ref ‹ref›` — Git ref to run the workflow on. * `--gh ‹cmd›` — The gh executable (default: gh). * `--glab ‹cmd›` — The glab executable (default: glab). * `--az ‹cmd›` — The az executable (default: az). * `--list` — List the enabled workflows (and where they are written). * `--json` — With --list: print the workflows as JSON. ## `dbx changelog` Scan commits, derive the semver bump and update the CHANGELOG.md files + versions. * `--range ‹range›` — Git revision range to scan. * `--dry-run` — Print the proposed entry without writing. * `--version ‹semver›` — Override the version. * `--base-version ‹semver›` — Bump from this version instead. * `--release-body ‹semver›` — Print the release body for this version and exit. * `--release-group` — Group every version since the previous published release into the body. * `--no-release-group` — Disable release grouping configured in the changelog config. * `--release-since ‹version›` — Group from this version/tag instead of the released boundary. * `--release-include-prereleases` — Let prerelease versions bound the grouped release body. * `--processing-method ‹method›` — `latest` (default), `all`, or a git range. * `--format-only` — Only regroup existing changelogs. * `--release-body-wrap` — Wrap the generated entry as a `**Release notes**` details block. * `--intro ‹text›` — Inline intro text for the new changelog entry. * `--intro-file ‹file›` — Read the new entry intro text from a file. * `--outro ‹text›` — Inline outro text for the new changelog entry. * `--outro-file ‹file›` — Read the new entry outro text from a file. * `--no-package-changes-section` — Skip the package-changes footer. ## `dbx mcp:serve` Run the dbx MCP server over stdio (for MCP clients). * `--cwd ‹dir›` — Project root (default: cwd). ## `dbx mcp:install` Install the dbx MCP server + skill into an AI harness/editor. * `--provider ‹id›` — claude, codex, vscode, opencode, pi or custom. * `--scope ‹scope›` — project (default) or global. * `--cwd ‹dir›` — Project root (default: cwd). * `--dir ‹dir›` — Custom directory (for --provider custom). * `--command ‹command›` — Client command (default `dbx`) * `--no-skills` — Do not write the skill/instructions file. * `--json` — Print the written paths as JSON. ## `dbx mcp:list` List the builtin MCP providers (Claude, Codex, VS Code, OpenCode, Pi). * `--cwd ‹dir›` — Project root (default: cwd). * `--json` — Print the providers as JSON. ## `dbx skills` Check or install the official dbx toolchain skill for AI agents (docs lookup). * `--official` — Install the official dbx docs skill (only when missing). * `--provider ‹id›` — claude, codex, vscode, opencode, pi or custom (default: all builtin). * `--scope ‹scope›` — project (default) or global. * `--cwd ‹dir›` — Project root (default: cwd). * `--dir ‹dir›` — Custom directory (for --provider custom). * `--force` — Overwrite an existing skill file. * `--json` — Print the status/results as JSON. ## `dbx vite` Run any Vite+ command through `vp` (eg. `dbx vite dev`). * `--cwd ‹dir›` — Project root to run `vp` in (default: cwd). ## `dbx vite:create` Vite+: Create a new project from a template. * `--cwd ‹dir›` — Project root to run `vp` in (default: cwd). ## `dbx vite:migrate` Vite+: Migrate an existing project to Vite+. * `--cwd ‹dir›` — Project root to run `vp` in (default: cwd). ## `dbx vite:config` Vite+: Configure hooks and agent integration. * `--cwd ‹dir›` — Project root to run `vp` in (default: cwd). ## `dbx vite:hooks` Vite+: Manage the Git hook dispatcher. * `--cwd ‹dir›` — Project root to run `vp` in (default: cwd). ## `dbx vite:staged` Vite+: Run linters on staged files. * `--cwd ‹dir›` — Project root to run `vp` in (default: cwd). ## `dbx vite:install` Vite+: Install dependencies with the detected package manager. * `--cwd ‹dir›` — Project root to run `vp` in (default: cwd). ## `dbx vite:env` Vite+: Manage Node.js and package managers. * `--cwd ‹dir›` — Project root to run `vp` in (default: cwd). ## `dbx vite:dev` Vite+: Run the Vite development server. * `--cwd ‹dir›` — Project root to run `vp` in (default: cwd). ## `dbx vite:check` Vite+: Run format, lint and type checks. * `--cwd ‹dir›` — Project root to run `vp` in (default: cwd). ## `dbx vite:lint` Vite+: Lint code with the active linter (Oxlint via Vite+). * `--cwd ‹dir›` — Project root to run `vp` in (default: cwd). ## `dbx vite:fmt` Vite+: Format code with the active formatter (Oxfmt via Vite+). * `--cwd ‹dir›` — Project root to run `vp` in (default: cwd). ## `dbx vite:test` Vite+: Run tests through bundled Vitest. * `--cwd ‹dir›` — Project root to run `vp` in (default: cwd). ## `dbx vite:run` Vite+: Run package scripts and monorepo tasks. * `--cwd ‹dir›` — Project root to run `vp` in (default: cwd). ## `dbx vite:exec` Vite+: Execute a binary from local node_modules. * `--cwd ‹dir›` — Project root to run `vp` in (default: cwd). ## `dbx vite:node` Vite+: Run a Node.js script in the Vite+ env. * `--cwd ‹dir›` — Project root to run `vp` in (default: cwd). ## `dbx vite:dlx` Vite+: Run a package binary without installing it. * `--cwd ‹dir›` — Project root to run `vp` in (default: cwd). ## `dbx vite:cache` Vite+: Manage the task cache. * `--cwd ‹dir›` — Project root to run `vp` in (default: cwd). ## `dbx vite:build` Vite+: Build for production. * `--cwd ‹dir›` — Project root to run `vp` in (default: cwd). ## `dbx vite:pack` Vite+: Build libraries for npm or standalone binaries. * `--cwd ‹dir›` — Project root to run `vp` in (default: cwd). ## `dbx vite:preview` Vite+: Preview the production build. * `--cwd ‹dir›` — Project root to run `vp` in (default: cwd). ## `dbx vite:add` Vite+: Add packages to dependencies. * `--cwd ‹dir›` — Project root to run `vp` in (default: cwd). ## `dbx vite:remove` Vite+: Remove packages from dependencies. * `--cwd ‹dir›` — Project root to run `vp` in (default: cwd). ## `dbx vite:update` Vite+: Update packages. * `--cwd ‹dir›` — Project root to run `vp` in (default: cwd). ## `dbx vite:dedupe` Vite+: Deduplicate dependencies. * `--cwd ‹dir›` — Project root to run `vp` in (default: cwd). ## `dbx vite:outdated` Vite+: Check for outdated packages. * `--cwd ‹dir›` — Project root to run `vp` in (default: cwd). ## `dbx vite:list` Vite+: List installed packages. * `--cwd ‹dir›` — Project root to run `vp` in (default: cwd). ## `dbx vite:why` Vite+: Explain why a package is installed. * `--cwd ‹dir›` — Project root to run `vp` in (default: cwd). ## `dbx vite:info` Vite+: View package metadata. * `--cwd ‹dir›` — Project root to run `vp` in (default: cwd). ## `dbx vite:link` Vite+: Link local packages. * `--cwd ‹dir›` — Project root to run `vp` in (default: cwd). ## `dbx vite:unlink` Vite+: Unlink local packages. * `--cwd ‹dir›` — Project root to run `vp` in (default: cwd). ## `dbx vite:rebuild` Vite+: Rebuild native modules. * `--cwd ‹dir›` — Project root to run `vp` in (default: cwd). ## `dbx vite:pm` Vite+: Forward a command to the package manager. * `--cwd ‹dir›` — Project root to run `vp` in (default: cwd). ## `dbx vite:toolchain` Vite+: Show Vite+ tool versions. * `--cwd ‹dir›` — Project root to run `vp` in (default: cwd). ## `dbx vite:upgrade` Vite+: Update `vp` itself. * `--cwd ‹dir›` — Project root to run `vp` in (default: cwd). ## `dbx vite:implode` Vite+: Remove `vp` and all related data. * `--cwd ‹dir›` — Project root to run `vp` in (default: cwd). --- --- url: https://toolchain.dbx.studio/config/env.md --- # Environment variables The toolchain config is file/CLI backed; a schema leaf opts into an environment variable with `.meta({ envName: "..." })` (see the [Config Generator](/guide/config-generator/describe-a-scope)). | Variable | Scope | Default | Description | | ----------------------------------- | --------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `DBX_PROJECT_REGENERATE` | toolchain | — | Regenerate this section's managed files during `dbx sync`. When false, existing files are left untouched and are neither written nor drift-checked. | | `DBX_PROJECT_NAME` | toolchain | — | The unscoped project name (written as `<scope>/<name>`). | | `DBX_PROJECT_SCOPE` | toolchain | — | The npm scope, eg. `@org`. | | `DBX_PROJECT_AUTHOR` | toolchain | — | Package author (`package.json` `author`). | | `DBX_PROJECT_LICENSE` | toolchain | — | SPDX license id (`package.json` `license`). | | `DBX_PROJECT_HOMEPAGE` | toolchain | — | Project homepage (`package.json` `homepage`). | | `DBX_PROJECT_REPO` | toolchain | — | Repository URL (`package.json` `repository`). For a workspace it also resolves to the workspace path (`repository.directory`). | | `DBX_PROJECT_NODEVERSION` | toolchain | — | Node version for CI/templates, eg. `22` (not `package.json` `engines`). | | `DBX_PROJECT_PACKAGEMANAGER` | toolchain | `yarn` | Package manager name, written as `<name>@<version>`. | | `DBX_PROJECT_PACKAGEMANAGERVERSION` | toolchain | — | Package manager version, eg. `4.17.1`. | | `DBX_PROJECT_DESCRIPTION` | toolchain | — | One-line description (`package.json` `description`). | | `DBX_PROJECT_INHERIT` | toolchain | `true` | Inherit the parent project metadata. Set false to keep this project metadata independent of the root config (other sections still merge normally). | | `DBX_PROJECT_MANAGECONFIGLESS` | toolchain | `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. | | `DBX_CI` | toolchain | `{}` | GitHub Actions workflows to generate (CI, release, issues, changelog, sync). | | `DBX_CHANGELOG` | toolchain | `{}` | Manual changelog pipeline options for `dbx changelog`, the VS Code actions and the API. `ci.changelog` inherits these options. | | `DBX_FMT` | toolchain | `{}` | Formatter configuration: Oxc/Biome options, editor defaults and tools. | | `DBX_LINT` | toolchain | `{}` | Linter configuration: Oxc/Biome/ESLint options and editor defaults. | | `DBX_BIOME` | toolchain | `{}` | Biome config generation (for consumers that still want a `biome.json`). | | `DBX_TSCONFIG` | toolchain | `{}` | Workspace tsconfig generation (path aliases + project references). | | `DBX_LOADER` | toolchain | `{}` | How `dbx.config.*` files are imported (tsconfig discovery). | | `DBX_TEMPLATES` | toolchain | `{}` | Template sources / scaffolding. | | `DBX_REGISTRY` | toolchain | `{}` | Allow/deny host and path globs for template/provider registries. | | `DBX_CATALOGS` | toolchain | `{}` | Package catalogs written to the package manager catalog file (`catalog:`). | | `DBX_VITE` | toolchain | `{}` | The full Vite+ config; `dbx sync` writes the root `vite.config.ts` from it. | | `DBX_WATCH` | toolchain | `{}` | Watch behaviour for `dbx watch`. | | `DBX_SYNC` | toolchain | `{}` | `dbx sync` behaviour (formatting of the generated managed files). | | `DBX_LOGGER` | toolchain | `{}` | Logging level, colours and prefix for toolchain output. | | `DBX_PROVIDERS` | toolchain | `{}` | Provider command behaviour (eg. colour for the passthrough commands). | | `DBX_MCP` | toolchain | `{}` | Install the official dbx skill (and MCP helpers) into AI agent harnesses. | --- --- 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 }, }, }); ``` --- --- url: https://toolchain.dbx.studio/guide/config-generator.md --- # Config generator `@deltabox/toolchain/config` is a configuration engine. **A Zod, untyped or plain-value schema is the single source of truth**. 1. Attach metadata with `.meta()` (or use the untyped/plain input) 2. Then generate the: * Env/config TypeScript types * JSON Schema * markdown reference * config metadata JSON * CLI commands/option definitions * CLI reference All from that one schema. ## Where to start * [Describe a scope](/guide/config-generator/describe-a-scope) — write the Zod, untyped or plain schema and its `.meta()`. * [Create the engine](/guide/config-generator/create-the-engine) — bind the schema, prefix, base group(s) and root. * [Generate](/guide/config-generator/generate) — the generator methods. * [CLI commands](/guide/config-generator/cli-commands) — the `config:*` command descriptors. * [CLI program](/guide/config-generator/generate#cli-program) — build schema commands into a runnable program with `invoke`, hooks and formatting. * [Load the config](/guide/config-generator/load-the-config) — the runtime parsers and `loadConfig*` (which already parse the loaded file). * [Generated outputs](/guide/config-generator/generated-outputs) — types, markdown, env files, JSON Schema, CLI docs and formatting. * [Client and server](/guide/config-generator/client-and-server) — split browser and server schemas/engines so bundled code never crosses contexts. * [Real-world shape](/guide/config-generator/real-world-shape) — how a consumer binds the engine end-to-end. ```ts import { createConfigEngine } from '@deltabox/toolchain/config'; ``` ## API reference Every export, option and code example can be found in the full [API reference](/guide/config-generator/api). --- --- url: https://toolchain.dbx.studio/guide/config-generator/describe-a-scope.md --- # Describe a scope Each top-level key is a **scope**; its value is a Zod schema, an untyped (JSON-Schema-shaped) schema, a plain object, a primitive, or an array of schema parts. A single schema (not keyed by scope) is treated as one `config` scope. * [Zod](#zod) * [Untyped](#untyped) * [Plain objects](#plain-objects) * [Primitives](#primitives) * [Arrays](#arrays) * [Base groups](#base-groups) A schema must satisfy `ConfigSchema`: ```ts import type { Schema as SchemaType } from 'untyped'; import type { ZodType } from 'zod'; /** A resolved untyped schema carrying the config metadata. */ export type ConfigSchemaType = SchemaType & ConfigMeta; /** A plain JSON-ish value used as a schema default (`{ port: 3000 }`). */ export type ConfigPlainValue = | string | number | boolean | bigint | null | undefined | ConfigPlainValue[] | { [key: string]: ConfigPlainValue }; /** A Zod schema, a resolved untyped schema, or a plain value/default. */ export type ConfigSchemaInput = ZodType | ConfigSchemaType | ConfigPlainValue; /** A single schema, a list of schemas, or scoped schemas keyed by scope name. */ export type ConfigSchema = | ConfigSchemaInput | ConfigSchemaInput[] | Record; ``` A scope map is the usual shape: ```ts export const scopes = { server: serverConfig, // Zod frontend: frontendConfig, // untyped or plain cli: 3000, // primitive }; ``` and is used to create the [config engine](/guide/config-generator/create-the-engine). ## Zod Zod is the richest input: it validates, supplies defaults and carries `.meta()` metadata for the generated env/CLI/types/docs. ```ts import { z } from 'zod'; export const serverConfig = z.object({ base: z.object({ port: z.number().default(3000).meta({ // ConfigMeta envName: 'MYAPP_PORT', description: 'HTTP port', }), host: z.string().default('0.0.0.0').meta({ // ConfigMeta envName: 'MYAPP_HOST', description: 'Bind address', }), }), auth: z.object({ password: z.string().meta({ // ConfigMeta envName: 'MYAPP_AUTH_PASSWORD', description: 'Admin password', required: true, secret: true, }), tokenTtl: z.number().default(3600).meta({ // ConfigMeta envName: 'MYAPP_AUTH_TOKEN_TTL', description: 'Session lifetime (seconds)', }), }), }); ``` `z.toJSONSchema` is used internally, so unions, enums, tuples, records and nullable values keep their shape in the generated types, markdown and JSON Schema. Values JSON Schema cannot represent (functions) can declare `.meta({ tsType: '...' })`. ## Untyped An untyped schema is the resolved JSON-Schema-like shape. It is useful when the schema comes from a JSON file, a remote source or hand-written definitions. ```ts export const serverConfig = { type: 'object', properties: { base: { type: 'object', properties: { port: { type: 'number', default: 3000, envName: 'MYAPP_PORT', description: 'HTTP port', }, host: { type: 'string', default: '0.0.0.0' }, }, }, auth: { type: 'object', properties: { password: { type: 'string', required: true, secret: true, envName: 'MYAPP_AUTH_PASSWORD', }, }, }, }, }; ``` Untyped leaves support the same `ConfigMeta` keys as Zod leaves (`envName`, `description`, `required`, `secret`, `cliFlag`, ...), plus `type`, `properties`, `required`, `default`, `items`, `enum`, `anyOf`/`oneOf` and `$ref`/`$defs`. ## Plain objects A plain object uses its values as defaults. The generator infers the leaf types: ```ts export const serverConfig = { port: 3000, host: 'localhost', debug: false, tags: ['api', 'web'], auth: { tokenTtl: 3600, }, }; ``` This is equivalent to an untyped schema whose leaves have `type` and `default` set. It is the quickest way to scaffold a config, but it carries no validation metadata — use Zod when you need strict validation. > A plain object inside a scope is read as that scope's **fields**. To declare > explicit schema keywords (`type`, `properties`, `envName`, ...) use an untyped > schema instead, so the keys are not mistaken for defaults. ## Primitives Primitive values become defaults inside a plain object: ```ts export const serverConfig = { port: 3000, // number host: 'localhost', // string debug: false, // boolean }; ``` A whole scope can also be a primitive when it has a single value: ```ts const engine = createConfigEngine({ schema: { version: '1.0.0' }, }); ``` The value is exposed under the scope's `config` leaf (`{ version: { config: '1.0.0' } }`). For named fields, prefer a plain object or an untyped/Zod schema. ## Arrays An array of schemas is merged into one scope. This is useful when a scope is split across modules: ```ts export const serverConfig = [ z.object({ host: z.string().default('localhost') }), z.object({ port: z.number().default(3000) }), ]; ``` Arrays of **plain values** are defaults for a leaf; declare them as an untyped schema when you need an array default at the scope root: ```ts const tags = { type: 'array', items: { type: 'string' }, default: ['api'] }; ``` ## Base groups The `baseGroup` option hoists a schema's flat fields out of the nested groups in the generated outputs. It defaults to `base`: ```ts const engine = createConfigEngine({ schema: scopes, baseGroup: 'base', }); ``` The generated types expose `...Base` and the main interface extends it; the markdown and JSON Schema flatten the base fields into the top level. ### Hoist multiple groups Pass an array to hoist more than one group. The groups are merged in declaration order: ```ts const engine = createConfigEngine({ schema: scopes, baseGroup: ['base', 'server'], }); ``` Both `base.port` and `server.host`, for example, become top-level fields in the generated `...Base` interface. Use `flatten: true` (or `flatten: { level }`) when you want all top-level keys flattened instead of selecting groups. ## Meta **Only Zod and Untyped can define metadata.** [Plain objects](#plain-objects), [primitives](#primitives) and [arrays](#arrays) therefore does **not** support metadata because they're too simplistic. > Use Zod or Untyped (JSON-Schema-shaped) schemas to add metadata to config options. ### Description Descriptions can be used to inline JSDocs, `.env` comments, markdown docs etc. for a single configuration in the generated config types/env/cli/markdown/schema. #### Zod description They can be defined for a config option in a Zod schema with `.describe()` or `.meta({ description: })`: ```ts export const serverConfig = z.object({ base: z.object({ // using .describe() port: z.number().default(3000).describe('HTTP port'), // using .meta() host: z.string().default('0.0.0.0').meta({ description: 'Bind address', }), }), }); ``` #### Untyped description An untyped schema carrying the [config metadata](#other-meta-fields)'s description field: ```ts export const serverConfig = { type: 'object', properties: { base: { type: 'object', properties: { port: { type: 'number', default: 3000, description: 'HTTP port', // the description }, host: { type: 'string', default: '0.0.0.0' }, }, }, }, }; ``` ### Other meta fields The [ConfigMeta](https://github.com/deltabox-studio/toolchain/blob/main/packages/config/src/types/meta.ts) fields used in the Zod/Untyped schemas: * `id` (override the name of the generated type) * `typeName` (same as `id`) * `public` (safe to expose as public API, true by default) * `description` * `envName` * `env` (deprecated, use `envName` instead) * `envPath` (dotted config path) * `path` (deprecated, use `envPath` instead) * `envExpose` (set `false` to keep a value out of env output) * `required` * `deprecated` * `deprecationMessage` * `example` * `since` * `see` * `remarks` * `experimental` * `alpha` * `beta` * `secret` * `scope` * `defaultValue` (when the resolved default differs) * `cli` (`false`, or `ConfigCliOptionMeta`: `flag`, `short`, `description`, `type`, `parse`, `default`, `choices`, `multiple`, `required`, `hidden`) * `cliCommand` (`false`, or `ConfigCliCommandMeta`: `name`, `description`, `aliases`, `hidden`, `passthrough`, `args`) * `cliFlag` / `cliFlagShort` (legacy aliases for `cli.flag` / `cli.short`) ### Annotations | Field | Adds | Notes | | --------------------------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | | `required: true` | **JSDocs:**`@required`**Markdown:**`- **Required**` above the `- **Type**` line | | | `deprecated: true` | **JSDocs:**`@deprecated`**Markdown:**`- **Deprecated**` | `deprecationMessage: ` supplies the text. | | `example` (string or array) | **JSDocs:**One `@example` tag per value **Markdown:**One `**Example(s):**` entry per value | | | `since` | **JSDocs:**`@since`**Markdown:**`- **Since**` | | | `see` | **JSDocs:**`@see`**Markdown:**`- **See**` links | | | `remarks` | **JSDocs:**`@remarks`**Markdown:**`**Remarks:**` | | | `experimental` / `alpha` / `beta` | Their stability tags | | #### Include or exclude annotations Each generator accepts the matching `include*` option (all defaults `true`) to keep or suppress an annotation: * `includeRequired` * `includeDeprecated` * `includeExamples` * `includeSince` * `includeSee` * `includeRemarks` * `includeExperimental` * `includeAlpha` * `includeBeta` Markdown and type output shows env/CLI equivalents by default. Disable them with `includeEnv: false` or `includeCli: false` in the [config engine](/guide/config-generator/create-the-engine)'s generator options: ```ts engine.markdown.generate({ includeCli: false, includeEnv: false }); engine.types.generate({ includeEnv: false }); ``` ## API reference See the [API reference](/guide/config-generator/api) for the complete list of exports and every generator option. --- --- url: https://toolchain.dbx.studio/guide/config-generator/create-the-engine.md --- # Create the engine Bind the schema, an env prefix, the base group(s) and the project root once. The schema may be a Zod schema, an untyped schema, a plain object/primitive, an array or a record keyed by scope: ```ts import { createConfigEngine } from '@deltabox/toolchain/config'; export const engine = createConfigEngine({ schema: { server: serverConfig, frontend: frontendConfig, cli: cliConfig, }, envPrefix: 'MYAPP_', // One group or several; hoisted into the generated `...Base` interface. baseGroup: ['base', 'server'], root: process.cwd(), // Optional: custom env-name -> dotted-path derivation (eg. dual prefixes). envPathOf: env => env .replace(/^(MYAPP_|VITE_)/, '') .toLowerCase() .replace(/_/g, '.'), }); ``` The engine keeps the exact schema type: ```ts engine.schema; // typeof mySchema engine.envPrefix; // 'MYAPP_' engine.baseGroup; // ['base', 'server'] engine.root; // process.cwd() ``` ## Options | Option | Description | | ----------- | -------------------------------------------------------------------------------------- | | `schema` | Zod, untyped, plain object/primitive, an array or a scoped record. | | `envPrefix` | Env-var prefix (default `APP_`). | | `baseGroup` | A group name or an array of names to hoist into the `...Base` output (default `base`). | | `flatten` | `true` or `{ level }` / `{ maxDepth }` to flatten top-level keys instead. | | `root` | Project root for default output paths (defaults to the nearest project). | | `envPathOf` | Custom env-name -> dotted-path derivation. | ## Base groups With the default `baseGroup: 'base'`, a `base` object is hoisted: ```ts const schema = { server: { base: { port: 3000, host: 'localhost' }, auth: { tokenTtl: 3600 }, }, }; ``` `port` and `host` become fields of `ServerConfigBase`; `auth` stays a nested group. Pass an array to hoist several groups; they are merged in order: ```ts createConfigEngine({ schema, baseGroup: ['base', 'auth'], }); ``` Now `port`, `host` and `tokenTtl` are all top-level `...Base` fields. The same flattening is applied to the markdown and JSON Schema outputs. ## Collect from the engine ```ts engine.collect(); // every ConfigDef (env/cli metadata included) engine.requiredVars(); // required definitions engine.requiredVars('server'); // required definitions in one scope ``` See the [API reference](/guide/config-generator/api) for every member and generator option. --- --- url: https://toolchain.dbx.studio/guide/config-generator/generate.md --- # Generate Every generator has two forms: * **Bound engine** — `engine.types.generate()` injects the engine's `envPrefix`, `baseGroup`, `root` and `envPathOf`. * **Standalone** — `generateConfigTypes(schema, options)` takes those options explicitly, for one-off scripts and tests. The grouped `.write` methods write to disk and return the written paths. The grouped `.generate` methods return the content and only write when you pass `outputDir`/`output` (a string); `false` disables writing. ## At a glance | Output | Engine | Standalone | | -------------- | ------------------------------------------------------------ | --------------------------------------------------------- | | `.env.example` | `engine.env.generate()` / `engine.env.write()` | `generateEnvFile()` | | Env types | `engine.env.types.generate()` / `engine.env.types.write()` | `generateConfigEnv()` | | Config types | `engine.types.generate()` / `engine.types.write()` | `generateConfigTypes()` | | Markdown | `engine.markdown.generate()` / `engine.markdown.write()` | `generateConfigMarkdown()` | | JSON Schema | `engine.jsonSchema.generate()` / `engine.jsonSchema.write()` | `generateConfigJsonSchema()` / `generateJsonSchemaFile()` | | Metadata JSON | `engine.configJson.build()` | `buildConfigJson()` | | CLI options | `engine.cli.generate()` / `engine.cli.write()` | `generateCliOptions()` | | Scoped CLI | `engine.cli.options()` | `generateConfigCliOptions()` / `configCliCommand()` | | Program | `engine.cli.program.create()` | `generateConfigProgram()` | | CLI docs | `engine.markdown.cli.generate()` / `.write()` | `generateCliDocs()` | | Env docs | `engine.markdown.env.generate()` / `.write()` | `generateEnvMarkdown()` | | Markdown page | `engine.markdown.file.generate()` / `.write()` | `generateMarkdownFile()` | | Formatting | — | `formatGenerated()` | ## Env file — `.env.example` ```ts engine.env.write({ output: '.env.example' }); ``` Standalone, with the common options: ```ts import { generateEnvFile } from '@deltabox/toolchain/config'; const content = generateEnvFile(schema, { envPrefix: 'MYAPP_', header: 'Copy to .env and fill the blanks.', scopes: ['server', 'cli'], exclude: ['MYAPP_INTERNAL_TOKEN'], values: { MYAPP_PORT: '8080' }, extra: { MYAPP_FEATURE_FLAG: 'true' }, }); ``` Options: `include`/`exclude` (env names), `values` (default overrides), `scopes`, `bare`, `extra` (raw `NAME=value` lines), `header`, `scopeSeparator`. Secrets are emitted commented out. ## Env types — `env.ts` + `dbx-env.d.ts` ```ts engine.env.types.write({ outputDir: 'types' }); // types/env.ts, types/dbx-env.d.ts ``` ```ts import { generateConfigEnv } from '@deltabox/toolchain/config'; const files = generateConfigEnv(schema, { envPrefix: 'MYAPP_', outputDir: 'types', envInterfaceName: 'AppEnv', viteEnvInterfaceName: 'AppViteEnv', importPath: './env.js', augmentVite: true, envComment: 'Runtime configuration.', }); // files: { 'env.ts': '...', 'dbx-env.d.ts': '...' } ``` Options: `envFile`/`dtsFile` (file names), `header`, `envHeader`, `dtsHeader`, `augmentVite` (a `declare module 'vite'` augmentation). ## Config types ```ts engine.types.write({ outputDir: 'types' }); ``` Standalone, with hand-written overrides and aliases: ```ts import { generateConfigTypes } from '@deltabox/toolchain/config'; const files = generateConfigTypes(schema, { baseGroup: 'base', outputDir: 'types', interfaceNames: { server: 'ServerConfig' }, aliases: { server: 'export type ServerOptions = ServerConfig;' }, imports: ["import type { FastifyServerOptions } from 'fastify';"], overrides: { ServerConfig: `export interface ServerConfig { host?: string; port?: number; }`, }, header: '// Generated — do not edit.', extension: 'ts', includeEnv: false, }); ``` Options: `interfaceNames` (per scope), `aliases` (per scope, appended), `overrides` (full declaration text, keyed by type name), `imports` (emitted once at the top), `extension`, `header`, and the `include*` annotation flags. `baseGroup` accepts a string or an array of strings; multiple groups are merged into the generated `...Base` interface in declaration order. ## Markdown ```ts engine.markdown.write({ outputDir: 'docs/reference/configuration' }); ``` ```ts import { generateConfigMarkdown } from '@deltabox/toolchain/config'; const files = generateConfigMarkdown(schema, { baseGroup: 'base', envPrefix: 'MYAPP_', outputDir: 'docs/reference/configuration', title: 'Configuration', frontmatter: ctx => `title: ${ctx.options.title ?? 'Configuration'}`, combined: true, // one index.md instead of one file per scope includeEnv: false, }); ``` `frontmatter: false` omits the frontmatter, a string replaces the body, and a callback builds it from the generator options. `combined: true` renders every scope into one file. `cliScope`, `shortFlags` and `references` control the CLI equivalents and footer links. ## JSON Schema ```ts const doc = await engine.jsonSchema.generate(); await engine.jsonSchema.write({ output: 'config.schema.json' }); ``` ```ts import { generateConfigJsonSchema, generateJsonSchemaFile } from '@deltabox/toolchain/config'; const doc = await generateConfigJsonSchema(schema, { baseGroup: 'base', id: 'https://myapp.dev/schemas/config.json', title: 'Myapp configuration', description: 'Every env-backed setting.', }); const path = await generateJsonSchemaFile(schema, { output: 'config.schema.json' }); ``` Both functions are async. `generateConfigJsonSchema` returns the document; `generateJsonSchemaFile` writes it and returns the path. `preserveDefs: true` keeps Zod's document-level `$ref`/`$defs` graph instead of inlining every scope (the `$defs` tables are hoisted to the document root). `scopeDescriptions` adds a description to a generated scope property, and `additionalProperties` sets the root constraint: ```ts const doc = await engine.jsonSchema.generate({ preserveDefs: true, additionalProperties: false, scopeDescriptions: { server: 'Server settings.' }, }); ``` ## Config metadata JSON ```ts const metadata = engine.configJson.build(); fs.writeFileSync('config.json', `${JSON.stringify(metadata, null, 4)}\n`); ``` ```ts import { buildConfigJson } from '@deltabox/toolchain/config'; const metadata = buildConfigJson(schema, { envPrefix: 'MYAPP_', comment: 'Generated from the config schemas.', }); ``` The document contains `$comment`, `version`, and `env[]` entries with the name, path, scope, description, default, `required`, `secret` and `public` flags. Secrets never include a default. ## CLI options ```ts const defs = engine.cli.generate({ scope: 'cli' }); ``` ```ts import { createCliArgsParser, generateCliOptions } from '@deltabox/toolchain/config'; const defs = generateCliOptions(schema, { envPrefix: 'MYAPP_', scope: 'cli', output: 'cli-options.json', }); const parser = createCliArgsParser(defs); parser.parse(['--base-url', 'http://localhost:8080']); ``` Options: `scope` (default `cli`), `output`, `shortFlags`, `envPathOf`. ## CLI program The preferred entry point is `engine.cli.program.create()`. It derives options from the engine schema, infers `run` values and accepts the full program options: ```ts const program = engine.cli.program.create( cmd => [ cmd('serve') .description('Run the server.') .option({ flags: '--json', description: 'Print JSON.' }) .run(({ config, values, context }) => { // config: the validated `serve` section // values: the explicit CLI values // context: the host command context }), ], { name: 'myapp', globalOptions: [{ flags: '--json', description: 'Print JSON.' }], disableColors: ({ color }) => color === false, } ); await program.invokeAsync(); ``` `engine.cli.program.create()` accepts `argv`, `name`, `description`, `version`, `globalOptions`, `context`, `disableColors`, `helpOnError`, `groups`, `sort`, `writeOut`, `writeErr` and `format`. See the [API reference](/guide/config-generator/api#program-members-and-options) for `invoke`/`invokeAsync`, hooks, help/error formatting and `bin`. Without an engine, `generateConfigProgram(schema, options)` returns the same `CliCommand[]`; each command spec runs with the validated scope config. It requires `envPrefix`; `envPathOf`, `commands`, `includePaths`, `excludePaths`, `flags`, `descriptions` and `types` shape the generated commands. When `commands` is omitted, one command is generated per command-eligible scope (`cliCommand: false` opts a scope out). ```ts import { generateConfigProgram } from '@deltabox/toolchain/config'; const commands = generateConfigProgram(schema, { envPrefix: 'MYAPP_', includePaths: ['server', 'server.port'], }); ``` Use the lower-level `createConfigProgram(commands, options?)` only when you already have a command list that is not tied to an engine; it accepts the same program options. ## CLI docs `generateCliDocs(commands, options?)` renders a markdown reference from `CliCommand` descriptors. It is standalone because it does not read a config schema: ```ts import { builtinCommands } from '@deltabox/toolchain/cli'; import { generateCliDocs } from '@deltabox/toolchain/config'; const markdown = generateCliDocs([...builtinCommands(), ...myCommands], { title: 'CLI reference', intro: 'Generated from the registered commands.', prefix: 'my-cli', outline: [2, 3], }); ``` Hidden commands are omitted, duplicate names keep the first descriptor, and args/options/defaults are rendered like the `dbx` reference. Pass the result through `formatGenerated(..., { fileName: 'cli.md' })` to format it. ## Formatting ```ts import { formatGenerated } from '@deltabox/toolchain/config'; const formatted = await formatGenerated(source, { fileName: 'config.ts', // infers the language options: { printWidth: 100 }, // merged over GENERATED_FORMAT_OPTIONS }); ``` `formatGenerated` is best-effort: it returns the input unchanged when no formatter is available. ## Advanced ### Post-process generated output Generators return strings or records, so you can transform them before writing: ```ts import fs from 'node:fs'; import { formatGenerated, generateConfigTypes } from '@deltabox/toolchain/config'; const files = generateConfigTypes(schema, { baseGroup: 'base' }); for (const [scope, source] of Object.entries(files)) { const withBanner = `// Generated from schemas/${scope}.ts — do not edit.\n${source}`; const formatted = await formatGenerated(withBanner, { fileName: `${scope}.ts` }); fs.mkdirSync('types', { recursive: true }); fs.writeFileSync(`types/${scope}.ts`, formatted); } ``` ### Custom headers, imports and overrides ```ts generateConfigTypes(schema, { header: '/* eslint-disable */', imports: ["import type { AppEnv } from './env.js';"], overrides: { ServerConfig: 'export interface ServerConfig extends BaseServer {}', }, }); ``` `overrides` is keyed by the generated type name and replaces the whole declaration, so keep the `imports`/`header` options handy for types the schema cannot express. ### Dry runs Every generator accepts `outputDir: false` / `output: false`: ```ts generateConfigTypes(schema, { outputDir: false }); await generateConfigJsonSchema(schema, { output: false }); ``` The grouped `.write()` methods always write; use the `.generate()` methods when you only need the content. ### Engine vs standalone The engine form injects the bound options; the standalone form takes them explicitly. They produce the same output: ```ts const engine = createConfigEngine({ schema, envPrefix: 'MYAPP_', baseGroup: 'base', }); engine.markdown.generate(); // uses the bound options generateConfigMarkdown(schema, { envPrefix: 'MYAPP_', baseGroup: 'base', }); ``` See [Generated outputs](/guide/config-generator/generated-outputs) for the shape of each file, [CLI commands](/guide/config-generator/cli-commands) for the `config:*` descriptors, and the [API reference](/guide/config-generator/api) for the complete export list. --- --- url: https://toolchain.dbx.studio/guide/config-generator/cli-commands.md --- # CLI commands docs `configCommands({ engine, defaults })` returns typed `CliCommand[]`; register them on the engine program with `engine.cli.program.create()` (preferred), or on a program built with the lower-level `createConfigProgram()` if the command list is not tied to an engine. They generate config artifacts: | Command | Writes | | ----------------- | -------------------------------------------- | | `config:env` | `.env.example` | | `config:types` | config types (`--env` also writes env types) | | `config:json` | `config.json` (metadata) | | `config:schema` | `config.schema.json` | | `config:markdown` | the markdown reference | | `config:cli` | `cli-options.json` | | `config:all` | everything, under one output directory | ```ts import { configCommands } from '@deltabox/toolchain/config'; const commands = configCommands({ engine, defaults: { typesDir: 'packages/shared/src/types', docsDir: 'docs/reference' }, }); const program = engine.cli.program.create(() => commands, { name: 'myapp' }); await program.invokeAsync(); ``` > These commands are library-only: `dbx` itself does not register a `config:*` > group, because each command needs a `ConfigEngine` bound to your schema. Add > the returned commands to your own program. The `config:*` commands generate config artifacts; they do not write the CLI reference. For that, pass the command descriptors your CLI registers to [`generateCliDocs()` or `engine.markdown.cli.write()`](/guide/config-generator/generate#cli-docs). ## Deriving flags from config fields When a command flag maps to a config field, generate the option from the schema instead of hand-writing its flag, description and default. The recommended entry point is `engine.cli.program.create()`: ```ts const { commands } = engine.cli.program.create(cmd => [ cmd('tsconfig') .description('Generate workspace tsconfig files.') // Genuine runtime flags stay explicit (the escape hatch). .options([ { flags: '--cwd ', description: 'Repo root.' }, { flags: '--json', description: 'Print the resolved config.' }, ]) .run(({ config }) => { // `config` is the validated `tsconfig` section. }), ]); ``` Config-backed flags are derived recursively: objects and union object branches expand to dotted paths (`sync.format` → `--format-*`), scalar arrays become list flags, and arrays of objects/records/maps are skipped unless the field defines `cli` metadata. Use `engine.cli.program.createCommand(scope, spec)` when you want the runtime `values` object inferred from the command's `options` list; `createCommand('name', spec)` / `cmd('name', spec)` build a runtime-only command with no config scope. Metadata lives in the schema: ```ts port: z.number().default(3000).meta({ cli: { short: 'p' } }), aliases: z.boolean().default(true).meta({ cli: { flag: '--no-aliases', type: 'boolean', description: 'Skip path aliases.' }, }), internal: z.string().meta({ cli: false }), format: z.union([z.boolean(), z.object({ fix: z.boolean() })]).meta({ cliCommand: { name: 'format', description: 'Format the managed files.' }, }), ``` `cli: false` removes a field (and its subtree) from generated flags without hiding it from env/types/docs. `cliCommand: false` opts a scope out of automatic command generation. Env exposure still comes from `envName`/`envPath`; set `envExpose: false` for CLI-only values. Runtime-only flags (`--cwd`, `--json`, `--force`, `--dry-run`, output selectors) always stay in the command spec; an option with a `path` intentionally maps a runtime flag back to a config field. The lower-level helpers remain available for existing descriptors: ```ts import { configCliOptions } from '@deltabox/toolchain/config'; const options = [ { flags: '--json', description: 'Print the resolved config.' }, ...configCliOptions(tsconfigConfigSchema), ]; ``` Config defaults are applied by the command context, so only explicitly typed flags are forwarded. `configCliCommand` wraps the same generation with parsing and validation when the whole command is config-shaped. Use `includePaths` / `excludePaths` only as a narrow escape hatch; a flag that is not a config field (output mode, `--cwd`, `--restore`, provider options) stays hand-written and documented as runtime-only. --- --- url: https://toolchain.dbx.studio/guide/config-generator/load-the-config.md --- # Load the config at runtime Generation is only half of it: the same schema loads the value back. The runtime parsers read the `envName` / `cli` metadata, coerce env and CLI strings, merge overrides and validate the result through the schema, so the returned object matches the generated types. ```ts import { parseCliConfig, parseConfig, parseEnvConfig } from '@deltabox/toolchain/config'; // MYAPP_HOST, MYAPP_PORT, ... -> { host: '0.0.0.0', port: 3000 } const fromEnv = parseEnvConfig(serverConfig, process.env, { envPrefix: 'MYAPP_' }); // env + CLI (argv defaults to `process.argv.slice(2)`), overrides merged on top const config = parseConfig(serverConfig, { host: '127.0.0.1' }, { envPrefix: 'MYAPP_' }); // CLI only: `--port 8080 --host localhost` const fromCli = parseCliConfig(serverConfig, process.argv.slice(2), { envPrefix: 'MYAPP_' }); ``` | Export | Sources | | ------------------------------------------------------- | -------------------------------------------------------- | | `parseConfig(schema, overrides?, opts?)` | env + CLI, with `overrides` merged last and validated | | `parseEnvConfig(schema, env?, opts?)` | env only | | `parseCliConfig(schema, argv?, opts?)` | CLI only | | `collect(schema, opts?)` | env + CLI, no overrides (pass `validate: true` to check) | | `loadConfig(options)` / `loadConfigAsync(options)` | file + env + CLI, then `overrides`, then validation | | `loadEnvConfig*` / `loadCliConfig*` / `loadFileConfig*` | file plus env, CLI or neither | | `loadConfigSync(options)` | the sync subset (JSON/YAML/CJS and sync loaders) | `source` accepts one source or an ordered array (`['env', 'cli']`) on both the parsers and the loaders. A loader always reads its file; the remaining sources layer over it. The precedence is **file -> env -> CLI -> overrides -> validation**. Parsers are the pure API: `parseConfig` starts from the value you pass as `overrides`, not from a file. Async variants (`parseConfigAsync`, `parseEnvConfigAsync`, `parseCliConfigAsync`) accept a promise for the env source, argv or overrides; the `*Sync` aliases keep the synchronous call shape. ## Scopes Parsing the engine's `schema` returns the nested `{ server, frontend }` object; parsing one scope's schema returns that scope's fields directly: ```ts const scoped = parseEnvConfig(engine.schema, process.env, { envPrefix: 'MYAPP_' }); // { server: { port: 8080, host: '0.0.0.0' } } const server = parseEnvConfig(serverConfig, process.env, { envPrefix: 'MYAPP_' }); // { port: 8080, host: '0.0.0.0' } ``` The same works for untyped and plain/primitive schemas: ```ts const untyped = { type: 'object', properties: { port: { type: 'number', default: 3000, envName: 'MYAPP_PORT' }, host: { type: 'string', default: 'localhost' }, }, }; parseEnvConfig(untyped, { MYAPP_PORT: '4000' }); // { port: 4000, host: 'localhost' } const plain = { server: { port: 3000, host: 'localhost' } }; parseEnvConfig(plain, { APP_SERVER_PORT: '4000' }); // { server: { port: 4000, host: 'localhost' } } ``` ## Common options Every parser shares the collect options: * `envPrefix` — the prefix stripped from env names (default `APP_`, `null` disables it). * `envSource` / `argv` — the env record and argument list to read (defaults to `process.env` and `process.argv.slice(2)`). * `include` / `exclude` — path globs (`server.*`, `**.port`) or presence kinds (`required`, `defined`, `undefined`, `null`). * `validate` — parse the resolved value through the schema (the `parse*` family defaults to `true`). * `errorOptions` — `errorLevel` (`throw`/`warn`/`silent`), `logger`, `rewriteMessage`, `defaultMessage` and `trigger` for validation problems. A thrown problem is a `ConfigParseError`. * `envPathOf` — override env-name -> dotted-path derivation (eg. dual prefixes). Env names come from `.meta({ envName })`; without it, the prefix plus the field path is used (`MYAPP_SERVER_PORT`). CLI flags come from `.meta({ cli: { flag } })` (or the legacy `cliFlag`), falling back to `--server-port`. ## Load from a file `loadConfig` / `loadConfigAsync` discover a config file (plus JSON/YAML/custom loaders), import it, layer env vars and CLI args over the file value, merge `overrides`, and validate through the passed `parser` (or `schema`). The loaders are the preferred loading API; you do **not** need to call `parseConfig`, `parseEnvConfig` or `parseCliConfig` afterwards. ```ts import { loadConfigAsync } from '@deltabox/toolchain/config'; const loaded = await loadConfigAsync({ parser: serverConfig, cwd: process.cwd(), // Discovery (flat fields; `configFileOptions` also works) locations: ['.', '.myapp'], names: ['dbx.config.ts', 'dbx.config.js'], envPrefix: 'MYAPP_', // Sources: file -> env -> CLI -> overrides -> validation source: ['file', 'env', 'cli'], overrides: { host: '127.0.0.1' }, validate: true, }); if (loaded) { console.log(loaded.path, loaded.config); // the file and the parsed value } ``` The source-specific loaders make the intent explicit: ```ts import { loadCliConfig, loadEnvConfig, loadFileConfig } from '@deltabox/toolchain/config'; await loadFileConfig({ parser: serverConfig }); // file only await loadEnvConfig({ parser: serverConfig }); // file + env await loadCliConfig({ parser: serverConfig }); // file + CLI ``` Each loader also has `*Sync` and `*Async` variants. Pass `source: 'env'` (or `['env', 'cli']`) to `loadConfig*` when you want a custom combination. Unknown sources are ignored by the collector, so the loaders remain safe when an application only enables one. Without a `parser`/`schema` the raw file value is returned unchanged (there is no schema to map env or CLI names onto): ```ts const raw = await loadConfig({ cwd: process.cwd() }); ``` ### Default file names The generic config package looks for neutral names: `config.ts`, `config.mts`, `config.cts`, `config.js`, `config.mjs`, `config.cjs` and `config.json` in `.`, `config` and `configs`. It never defaults to `dbx.config.*`. An application that owns a filename passes `names` or `configFileOptions: { filename: 'myapp.config' }` explicitly. Options include `configFileOptions` (filename, extensions, locations, `packageJson`, ancestor search), `required`, `overrides`, `source`, `fresh` (re-import in watch mode), `tsconfig` (path-alias resolution for TS configs) and `loader`. `loadConfigSync` supports JSON/YAML/CJS and synchronous loaders; `loadConfigAsync` also supports ESM and TypeScript. > The dotted path is the env name with the prefix removed and `_` folded to `.`, > so `MYAPP_AUTH_TOKEN_TTL` reads as `auth.token.ttl`. Env names live on the > schema as `.meta({ envName })`, so the generated `.env` file and the runtime > parser stay in step. --- --- url: https://toolchain.dbx.studio/guide/config-generator/generated-outputs.md --- # Generated outputs Every generator reads from the same Zod, untyped or plain-value schema. The engine's own config model is the living example: its types are committed at [packages/shared/src/config-types.ts](https://github.com/deltabox-studio/toolchain/blob/main/packages/shared/src/config-types.ts). For the engine/standalone call forms and the full option list per generator, see [Generate](/guide/config-generator/generate). For every export and option, see the [API reference](/guide/config-generator/api). ## Config types — `engine.types` / `generateConfigTypes()` Named `interface`s (and `type` aliases for enums/unions) with jsdoc taken from `.describe()`. Unions and refs stay named, so nested objects are referenced rather than inlined: ```ts // engine.types.generate() -> { server: "...", cli: "..." } engine.types.write({ outputDir: 'types' }); // types/server.ts, types/cli.ts ``` ```ts // types/server.ts export interface ServerConfig { /** Bind host. */ host?: string; port?: number; auth?: { password?: string; enabled?: boolean }; } ``` An object schema that also accepts arbitrary keys (Zod `.catchall(...)`, `.loose()` or `z.looseObject(...)`, ie. `additionalProperties` in the JSON Schema) generates an open interface with an index signature, so the extra keys stay typed as `unknown` instead of being rejected: ```ts export interface ServerConfig { /** Bind host. */ host?: string; [key: string]: unknown; } ``` ## Markdown — `engine.markdown` / `generateConfigMarkdown()` One reference page per scope plus an index listing the required/core env vars: ```ts engine.markdown.write({ outputDir: 'docs/reference/configuration' }); // docs/reference/configuration/server.md, .../index.md ``` See a real full example at [config/reference.md](../../config/reference.md). Markdown frontmatter is enabled by default. Set `frontmatter: false` to omit it, pass a raw string to replace the body, or pass a callback to build it from the generator options. The returned string is wrapped in `---` automatically. ```ts generateConfigMarkdown(schema, { frontmatter: ctx => `title: ${ctx.options.title ?? 'Configuration'}`, }); ``` Use `combined: true` to render every scope into one file instead of one file per scope. `generateConfigTypes`, `generateConfigMarkdown` and `generateConfigEnv` return file contents and only write when `outputDir`/`output` is a string; `false` explicitly disables writing. ## Env — `engine.env` / `generateEnvFile()` A `.env.example`; secrets are emitted commented out so operators fill them in: ```ts engine.env.write({ output: '.env.example' }); ``` ```sh # ---- SERVER ---- MYAPP_HOST=localhost # MYAPP_AUTH_PASSWORD= ``` ## JSON Schema — `engine.jsonSchema` / `generateConfigJsonSchema()` The resolved untyped JSON Schema for every scope, for editor autocomplete: ```ts await engine.jsonSchema.write({ output: 'config.schema.json' }); ``` ## CLI docs - `engine.markdown.cli` / `generateCliDocs()` `generateCliDocs` reads `CliCommand` descriptors rather than the config schema: it renders a markdown reference from the commands your CLI actually registers. The engine exposes the same generator as `engine.markdown.cli.generate()` (and `.write()`): ```ts import { builtinCommands } from '@deltabox/toolchain/cli'; const markdown = engine.markdown.cli.generate([...builtinCommands(), ...myCommands], { prefix: 'my-cli', title: 'CLI reference', intro: 'Generated from the registered commands.', }); engine.markdown.cli.write(builtinCommands(), { output: 'docs/cli.md' }); ``` The standalone `generateCliDocs(commands, options)` export is equivalent when you do not already have an engine. Hidden commands are omitted and duplicate names keep the first descriptor. The `dbx` reference itself is generated this way, so a custom command no longer has to be added to `builtinCommands()` to be documented. ## Env docs - `engine.markdown.env` / `generateEnvMarkdown()` `engine.markdown.env.generate()` renders the environment-variable table from `engine.collect()`, using the engine's `envPrefix`. `write({ output })` writes the page: ```ts engine.markdown.env.write({ output: 'docs/env.md' }); ``` ## Single pages - `engine.markdown.file` / `generateMarkdownFile()` `engine.markdown.file` renders one page with frontmatter and a `#` title. The body is supplied by the caller, so it is useful for overview/index pages: ```ts engine.markdown.file.write({ output: 'docs/index.md', title: 'Config types', body: 'The toolchain has three configuration surfaces...', }); ``` ## Post-processing The `generate*` functions return their content, so you can transform it before writing (the grouped `.write()` methods write immediately): ```ts const files = generateConfigTypes(schema); for (const [scope, source] of Object.entries(files)) { const sourceWithBanner = `// Generated — do not edit.\n${source}`; await fs.promises.writeFile(`types/${scope}.ts`, sourceWithBanner); } ``` If the transform changes the formatting, run the result through [`formatGenerated()`](#formatting--formatgenerated) before writing. ## Formatting — `formatGenerated()` Generated text is formatted **at generation time**, so a written file is already formatted instead of relying on a separate `yarn fmt` pass. `formatGenerated` runs source through Oxfmt, preferring the project-local `vite-plus/fmt` (Oxfmt ships with Vite+), then `oxfmt`, and returns the input untouched when no formatter is resolvable, so generation never fails on a missing formatter. ```ts import { formatGenerated, GENERATED_FORMAT_OPTIONS } from '@deltabox/toolchain/config'; const source = 'export const config={a:1}'; const formatted = await formatGenerated(source, { fileName: 'config.ts', // infers the language (default `generated.ts`) options: { printWidth: 100 }, // merged over GENERATED_FORMAT_OPTIONS }); ``` `GENERATED_FORMAT_OPTIONS` is the baseline Oxfmt config matching the toolchain's own `vite.config.ts` (4-space indent, single quotes, `trailingComma: 'es5'`, `jsdoc: true`, ...). Pass `options.fileName` to format JSON, markdown or another language, and `options.options` to override any single option. For a full, real example of the generated config types, see `packages/shared/src/config-types.ts`. --- --- url: https://toolchain.dbx.studio/guide/config-generator/client-and-server.md --- # Client and server configs Config code is often shared between an API and a browser app. The schemas can share primitives, but for best-practice the **engines**, loaders and runtime imports must stay in their own context. A client bundle should never pull in `node:*` (unless your bundler handles them), a server secret, or the server config engine; a server process should not depend on browser-only globals. The safest structure is one folder per context, each with its own schema entry, engine and public import path. Do not put a single barrel `index.ts` above both contexts that re-exports their engines or schemas. ## Project layout ```tree - name: packages/shared/src/config children: - name: common description: Context-free primitives only children: - name: primitives.ts - name: meta.ts - name: client description: Browser-safe config children: - name: schema children: - name: index.ts description: Client schemas only - name: api.ts - name: telemetry.ts - name: engine.ts description: createConfigEngine(client schemas) - name: index.ts description: Public client entry - name: server description: Server-only config children: - name: schema children: - name: index.ts description: Server schemas only - name: database.ts - name: http.ts - name: engine.ts description: createConfigEngine(server schemas) - name: index.ts description: Public server entry - name: index.ts status: deleted description: Never re-export both contexts ``` `common/` may be imported by either side, but it must stay free of runtime dependencies such as `node:fs`, database clients or browser APIs. Everything else is context-specific. ## Server context ### Server schemas Keep each server schema module focused, and export only server schemas from the server schema entry: ```ts // packages/shared/src/config/server/schema/database.ts import { z } from 'zod'; export const databaseConfig = z.object({ url: z.string().meta({ envName: 'APP_DATABASE_URL', required: true, secret: true, }), poolSize: z.number().default(10).meta({ envName: 'APP_DATABASE_POOL_SIZE' }), }); ``` ```ts // packages/shared/src/config/server/schema/http.ts import { z } from 'zod'; export const httpConfig = z.object({ port: z.number().default(3000).meta({ envName: 'APP_HTTP_PORT' }), trustProxy: z.boolean().default(false).meta({ envName: 'APP_HTTP_TRUST_PROXY' }), }); ``` ```ts // packages/shared/src/config/server/schema/index.ts export { databaseConfig } from './database.js'; export { httpConfig } from './http.js'; ``` ### Server engine The server engine imports the server schema entry only: ```ts // packages/shared/src/config/server/engine.ts import { createConfigEngine } from '@deltabox/toolchain/config'; import * as serverSchema from './schema/index.js'; export const serverConfig = createConfigEngine({ schema: { database: serverSchema.databaseConfig, http: serverSchema.httpConfig, }, envPrefix: 'APP_', }); ``` The public server entry is the only module the server application imports: ```ts // packages/shared/src/config/server/index.ts export { serverConfig } from './engine.js'; export * from './schema/index.js'; ``` ### Loading server config Read files and `process.env` in the server process: ```ts import { serverConfig } from '@org/shared/config/server'; // apps/api/src/config.ts import { loadConfigAsync, parseEnvConfig } from '@deltabox/toolchain/config'; export async function loadServerConfig() { // load config from file, cli and env const loaded = await loadConfigAsync({ parser: serverConfig.schema, cwd: process.cwd(), names: ['dbx.config.ts', 'dbx.config.js'], }); if (loaded) return loaded.config; // fallback to env config return parseEnvConfig(serverConfig.schema, process.env, { envPrefix: 'APP_', }); } ``` `loadConfigAsync` can import TypeScript and read the filesystem, so it must not appear in a client module graph. ## Client context ### Client schema Client schemas may only describe browser-visible values. Prefix public values with the client-visible prefix (`PUBLIC_`), and keep secrets out entirely: ```ts // packages/shared/src/config/client/schema/api.ts import { z } from 'zod'; export const apiConfig = z.object({ baseUrl: z.string().default('/api').meta({ envName: 'PUBLIC_API_BASE_URL' }), timeout: z.number().default(10_000).meta({ envName: 'PUBLIC_API_TIMEOUT' }), }); ``` ```ts // packages/shared/src/config/client/schema/telemetry.ts import { z } from 'zod'; export const telemetryConfig = z.object({ enabled: z.boolean().default(false).meta({ envName: 'PUBLIC_TELEMETRY_ENABLED' }), }); ``` ```ts // packages/shared/src/config/client/schema/index.ts export { apiConfig } from './api.js'; export { telemetryConfig } from './telemetry.js'; ``` ### Client engine The client engine imports only the client schema entry: ```ts // packages/shared/src/config/client/engine.ts import { createConfigEngine } from '@deltabox/toolchain/config'; import * as clientSchema from './schema/index.js'; export const clientConfig = createConfigEngine({ schema: { api: clientSchema.apiConfig, telemetry: clientSchema.telemetryConfig, }, envPrefix: 'PUBLIC_', // or VITE_, NEXT_ }); ``` ```ts // packages/shared/src/config/client/index.ts export { clientConfig } from './engine.js'; export * from './schema/index.js'; ``` ### Loading client config The browser has `import.meta.env`, not `process.env`, and it must not import the server engine or `node:fs`: ```ts import { clientConfig } from '@org/shared/config/client'; // apps/web/src/config.ts import { parseEnvConfig } from '@deltabox/toolchain/config'; export const webConfig = parseEnvConfig( clientConfig.schema, import.meta.env as Record, { envPrefix: 'PUBLIC_' } ); ``` Vite/Vite+ only exposes env vars with the configured public prefix; the schema above uses `PUBLIC_` consistently. Never put a server secret in a client schema. ## Bundlers Treeshaking depends on what a module **imports**, not on which exports you happen to use. A top-level barrel defeats the split: ```tree - name: packages/shared/src/config children: - name: index.ts status: deleted description: Re-exports client + server; every importer pulls both - name: client/index.ts description: Client-only entry - name: server/index.ts description: Server-only entry ``` Import the context entry explicitly: ```ts // Bad: // the barrel can load both engines into the same module graph import { clientConfig } from '@org/shared/config'; // Good: // the client graph only sees the client engine import { clientConfig } from '@org/shared/config/client'; ``` Expose separate package subpaths instead of one mixed entry: ```json [package.json] { "exports": { "./config/client": "./dist/config/client/index.js", "./config/server": "./dist/config/server/index.js" }, "sideEffects": false } ``` ### Side effects and boundaries Treeshaking cannot remove a module with import-time side effects. Keep the config modules declarative: * Do not open database connections, read files or start servers at module load. * Do not import `node:*` from the client schema or client engine (unless your bundler handles them). * Do not import the client engine from the server engine, or vice versa. * Keep `createConfigEngine` calls in the context's `engine.ts`; import that file only from the matching side. * If a package needs a server-only guard, make the server entry the only one that imports the server dependencies. A client import of the server entry should fail at build time, not silently bundle it. ### A correct import graph ```tree - name: apps/web/src/config.ts description: imports @org/shared/config/client only status: added - name: apps/api/src/config.ts description: imports @org/shared/config/server only status: added ``` The client bundle never reaches `server/engine.ts`, `server/schema/*` or `node:*` (unless your bundler handles them); the server process never reaches `client/schema/*` or `import.meta.env` parsing. ## Checklist * One schema folder and one engine per context. * No `config/index.ts` that re-exports both context engines. * Client code imports only `config/client`; server code imports only `config/server`. * Shared `common` modules are context-free. * Client schemas use only public config options and no secrets. * Server-only modules are never imported from client code. * `sideEffects: false` plus no import-time side effects, so unused context modules are actually removed. See [Load the config](/guide/config-generator/load-the-config) for the parser and loader options, and the [API reference](/guide/config-generator/api) for the full API. --- --- url: https://toolchain.dbx.studio/guide/config-generator/real-world-shape.md --- # Real-world shape A real project usually has **two engines**, one per runtime context, rather than one engine that mixes server and browser settings: * a server engine with database, HTTP and secret-bearing schemas; * a client engine with public API URLs, feature flags and other browser-safe values. Keeping them in separate folders and entry points is what lets bundlers drop the server engine from the browser bundle (and vice versa). See [Client and server](/guide/config-generator/client-and-server) for the full layout and bundler guidance. ## Server engine ```ts // packages/shared/src/config/server/engine.ts import { createConfigEngine } from '@deltabox/toolchain/config'; import * as serverSchema from './schema/index.js'; export const serverConfig = createConfigEngine({ schema: { database: serverSchema.databaseConfig, http: serverSchema.httpConfig, }, envPrefix: 'APP_', baseGroup: ['base', 'http'], root: monorepoRoot(), }); ``` ## Client engine ```ts // packages/shared/src/config/client/engine.ts import { createConfigEngine } from '@deltabox/toolchain/config'; import * as clientSchema from './schema/index.js'; export const clientConfig = createConfigEngine({ schema: { api: clientSchema.apiConfig, telemetry: clientSchema.telemetryConfig, }, envPrefix: 'PUBLIC_', }); ``` ## Generation Run the generators against each engine so each context's `.env.example`, types, JSON Schema and markdown reference stay scoped to its own schema: ```ts import { configCommands } from '@deltabox/toolchain/config'; import { clientConfig } from './client/engine.js'; import { serverConfig } from './server/engine.js'; export const commands = [ ...configCommands({ engine: serverConfig, defaults: { envDir: 'config/server' }, }), ...configCommands({ engine: clientConfig, defaults: { envDir: 'config/client' }, }), ]; ``` If the project exposes one `config:all` command, call the generators for both engines explicitly. Do not build a single engine whose schema imports both `server/` and `client/` modules. ## Loading At runtime, each context loads its own engine: ```ts import { serverConfig } from '@org/shared/config/server'; // apps/api/src/config.ts (server) import { loadConfigAsync } from '@deltabox/toolchain/config'; const loaded = await loadConfigAsync({ parser: serverConfig.schema }); ``` ```ts import { clientConfig } from '@org/shared/config/client'; // apps/web/src/config.ts (client) import { parseEnvConfig } from '@deltabox/toolchain/config'; export const webConfig = parseEnvConfig( clientConfig.schema, import.meta.env as Record, { envPrefix: 'PUBLIC_' } ); ``` `loadConfig*` loads a file and layers env/CLI over it (`loadEnvConfig*` and `loadCliConfig*` select one explicitly). Use `parseEnvConfig`/`parseCliConfig`/ `parseConfig` when there is no file and you are parsing a pure source. ## Keep the boundaries clean * Import `@org/shared/config/client` from browser code and `@org/shared/config/server` from server code. * Never create a `packages/shared/src/config/index.ts` that re-exports both engines. * Keep shared `common` modules context-free (no `node:*` unless your bundler handles them, no secrets, no browser-only globals). * Mark config packages as side-effect free and avoid import-time connections or file reads. * Client schemas use public config options only; server secrets never enter the client schema. These `config:*` commands belong to the consumer's own CLI; `dbx` itself does not expose them. See [Client and server](/guide/config-generator/client-and-server) for the complete folder layout, import graph and bundler checklist, and the [API reference](/guide/config-generator/api) for every generator and runtime export. --- --- url: https://toolchain.dbx.studio/guide/config-generator/api.md --- # API reference Everything is exported from the `@deltabox/toolchain/config` subpath. The engine and the standalone functions share the same schemas and options, so you can start with the engine and drop to a single generator when you only need one artifact. ```ts import { ConfigProgramError, createConfigEngine, createConfigProgram, generateConfigProgram, generateConfigTypes, parseConfig, parseEnvConfig, loadConfigAsync, } from '@deltabox/toolchain/config'; ``` ## Schemas A schema is a Zod schema, a resolved untyped schema, or a plain value. Plain objects and primitives are supported through their defaults. ```ts import { z } from 'zod'; // Zod (the richest form: validation + defaults + metadata) const zodSchema = z.object({ port: z.number().default(3000).meta({ envName: 'MYAPP_PORT' }), }); // Untyped/JSON-Schema shape const untypedSchema = { type: 'object', properties: { port: { type: 'number', default: 3000, envName: 'MYAPP_PORT' }, host: { type: 'string', default: 'localhost' }, }, }; // Plain object (values become defaults) const plainObject = { port: 3000, host: 'localhost', }; // A primitive scope (the value becomes the default) const plainPrimitive = 3000; ``` A **scope map** keys each top-level entry by scope name: ```ts const scopes = { server: zodSchema, frontend: { apiUrl: 'http://localhost:8080' }, cli: 3000, }; ``` A single schema (Zod or untyped) is treated as one runtime scope named `config`. Arrays of schemas are merged into one scope. ```ts const engine = createConfigEngine({ schema: scopes, baseGroup: ['base', 'server'] }); ``` The `baseGroup` option accepts a string or an array of strings. Each named group is hoisted into the generated `...Base` interface (types) and the flattened markdown/JSON Schema shape. Multiple groups are merged in declaration order. ## Engine `createConfigEngine(options)` binds the schema once and exposes the generators. ```ts const engine = createConfigEngine({ schema: scopes, envPrefix: 'MYAPP_', baseGroup: ['base', 'server'], root: process.cwd(), envPathOf: env => env .replace(/^MYAPP_/, '') .toLowerCase() .replace(/_/g, '.'), }); engine.schema; // the exact schema passed in engine.envPrefix; // 'MYAPP_' engine.baseGroup; // ['base', 'server'] engine.root; // process.cwd() ``` | Member | Returns | | ----------------------- | ---------------------------------------------- | | `engine.collect()` | every collected `ConfigDef` | | `engine.requiredVars()` | the `required` definitions (optionally scoped) | ### `engine.env` ```ts const envFile = engine.env.generate({ envPrefix: 'MYAPP_' }); // MYAPP_PORT=3000 const envTypes = engine.env.types.generate({ outputDir: 'types' }); // { 'env.ts': '...', 'dbx-env.d.ts': '...' } engine.env.write({ output: '.env.example' }); engine.env.types.write({ outputDir: 'types' }); // returns the written paths ``` ### `engine.types` ```ts const files = engine.types.generate({ outputDir: 'types' }); // { server: 'export interface ServerConfig...', cli: '...' } engine.types.write({ outputDir: 'types', extension: 'mts' }); ``` ### `engine.markdown` ```ts const commands = [/* your CliCommand descriptors */]; const pages = engine.markdown.generate({ outputDir: 'docs/reference' }); // { 'server.md': '...', 'cli.md': '...', 'index.md': '...' } // One combined page instead of one per scope engine.markdown.generate({ combined: true }); // { 'index.md': '...' } // A CLI command reference engine.markdown.cli.generate(commands); engine.markdown.cli.write(commands, { output: 'docs/cli.md' }); // The environment-variable reference engine.markdown.env.generate(); engine.markdown.env.write({ output: 'docs/env.md' }); // One generic page engine.markdown.file.generate({ title: 'Docs', body: 'Hello.' }); ``` ### `engine.cli` ```ts // Env-backed `cli` scope options const options = engine.cli.generate({ scope: 'cli' }); // [{ flag: '--port', env: 'MYAPP_PORT', type: 'number', ... }] engine.cli.write({ output: 'cli-options.json' }); // Scoped config commands + options from every config field const scoped = engine.cli.options(); // { // command: { server: { name: 'server', type: 'object', options: [...] }, ... }, // commandEntries: [['server', {...}], ...], // options: [...], // optionsEntries: [['--port', {...}], ...], // diagnostics: [...], // } // The high-level program: chained commands with schema-derived flags + typed config const { commands } = engine.cli.program.create(cmd => [ cmd('server') .option({ flags: '--json', description: 'Print JSON.' }) .run(({ config, values, context }) => { // `config` is the resolved `server` section. }), ]); ``` ### `engine.jsonSchema` `jsonSchema` is async because Zod's JSON Schema lowering is async. ```ts const doc = await engine.jsonSchema.generate({ preserveDefs: true }); await engine.jsonSchema.write({ output: 'config.schema.json' }); ``` ### `engine.configJson` ```ts const metadata = engine.configJson.build(); // { env: [...], cli: [...], config: [...] } ``` ## Standalone generators Every engine method has a standalone equivalent. They return content unless you pass an output path/directory. ```ts import { collectDefinitions, formatGenerated, generateCliDocs, generateCliOptions, generateConfigEnv, generateConfigJsonSchema, generateConfigMarkdown, generateConfigProgram, generateConfigTypes, generateEnvFile, generateEnvMarkdown, generateJsonSchemaFile, generateMarkdownFile, } from '@deltabox/toolchain/config'; generateEnvFile(schema, { envPrefix: 'MYAPP_' }); generateConfigEnv(schema, { envPrefix: 'MYAPP_', outputDir: 'types' }); generateConfigTypes(schema, { outputDir: 'types' }); generateConfigMarkdown(schema, { outputDir: 'docs/reference' }); generateEnvMarkdown(collectDefinitions(schema, { envPrefix: 'MYAPP_' })); generateMarkdownFile({ title: 'Docs', body: 'Hello.' }); generateCliOptions(schema, { envPrefix: 'MYAPP_', scope: 'cli' }); generateCliDocs(commands, { output: 'docs/cli.md' }); const generated = generateConfigProgram(schema, { envPrefix: 'MYAPP_' }); await generateConfigJsonSchema(schema, { baseGroup: ['base', 'server'] }); await generateJsonSchemaFile(schema, { output: 'config.schema.json' }); const formatted = await formatGenerated(source, { fileName: 'config.ts' }); ``` ## Runtime collection `collect` resolves env vars and CLI args into a config object. It does not validate unless `validate: true`. ```ts import { collect, collectDefinitions, collectRequired } from '@deltabox/toolchain/config'; const config = collect(schema, { envPrefix: 'MYAPP_', envSource: process.env, argv: process.argv.slice(2), validate: true, }); const definitions = collectDefinitions(schema, { envPrefix: 'MYAPP_' }); const required = collectRequired(schema, 'server'); ``` ## Runtime parsers The parsers merge the enabled sources, apply overrides and validate by default. `source` accepts `'file' | 'env' | 'cli'` or an ordered array such as `['env', 'cli']`. All of them accept Zod, untyped and plain/primitive schemas. ```ts import { parseCliConfig, parseConfig, parseEnvConfig, parseConfigAsync, } from '@deltabox/toolchain/config'; // env + CLI + overrides const config = parseConfig(schema, { port: 4000 }, { envPrefix: 'MYAPP_' }); // env only parseEnvConfig(schema, process.env, { envPrefix: 'MYAPP_' }); // CLI only: --port 4000 --host localhost parseCliConfig(schema, process.argv.slice(2), { envPrefix: 'MYAPP_' }); // An explicit source set parseConfig(schema, {}, { source: ['env', 'cli'], envPrefix: 'MYAPP_' }); // Async variants accept promise inputs await parseConfigAsync(schema, Promise.resolve({ port: 4000 })); ``` `ConfigParseError` is thrown when validation fails and `errorOptions.errorLevel` is `throw` (the default). Its `issues` array contains the validated paths and messages. ## Loaders `loadConfig*` discover a config file, import it, layer env vars and CLI args over the file value, merge `overrides` and validate through the passed `parser` (or `schema`). The precedence is **file -> env -> CLI -> overrides -> validation**. You do **not** need to call `parseConfig`/`parseEnvConfig`/`parseCliConfig` after `loadConfig*`: it already did that for you. Use the parsers when you have no file to load. ```ts import { loadConfig, loadConfigAsync, loadConfigSync } from '@deltabox/toolchain/config'; const loaded = await loadConfigAsync({ parser: z.object({ port: z.number().default(3000), host: z.string().default('localhost'), }), cwd: process.cwd(), names: ['dbx.config.ts', 'dbx.config.js'], locations: ['.', 'config'], envPrefix: 'MYAPP_', source: ['file', 'env', 'cli'], // the default validate: true, // default when a parser is provided }); loaded?.config; // the parsed + validated value loaded?.path; // the file that was loaded ``` The source-specific family makes the selection explicit: | Loader | Sources | | ----------------- | -------------------------- | | `loadConfig*` | file + env + CLI (default) | | `loadEnvConfig*` | file + env | | `loadCliConfig*` | file + CLI | | `loadFileConfig*` | file only | Each has `Sync` and `Async` variants. `source` also accepts a union on the loaders, so `source: ['env', 'cli']` is equivalent to the default. Without a `parser`/`schema`, the raw loaded value is returned: ```ts const raw = await loadConfig({ cwd: process.cwd() }); ``` The parser-based loader also accepts the flat discovery fields (`cwd`, `names`, `locations`, `packageJsonKeys`, `parent`, `accept`, `tsconfig`, `fresh`) as well as `configFileOptions` when you need the full discovery shape. The default discovery names are neutral (`config.ts`, `config.js`, `config.json`, ...), never `dbx.config.*`. Pass `names` or `configFileOptions.filename` for an application-specific name. `loadConfigSync` supports JSON/YAML/CJS and custom synchronous loaders; `loadConfigAsync` also supports ESM and TypeScript. `createConfigFile({ cwd, name?, content?, imports?, overwrite? })` writes a starter `dbx.config.ts`. ## Schema utilities ```ts import { compileZodSchema, flattenBaseSchema, isSchemaType, isZodSchema, metaOf, normalizeBaseGroups, normalizeConfigSchema, resolveUntypedSchema, splitBaseSchema, toSchemaType, zodToJsonSchema, zodToSchemaMap, } from '@deltabox/toolchain/config'; isZodSchema(value); // Zod schema? isSchemaType(value); // resolved untyped schema? toSchemaType(schema); // Zod/plain value -> resolved untyped schema resolveUntypedSchema({ port: 3000 }); // -> { properties: { port: { type: 'number', default: 3000 } } } normalizeConfigSchema(schema); // -> { [scope]: resolvedSchema } zodToJsonSchema(zodSchema); // -> untyped JSON Schema zodToSchemaMap(zodSchema); // -> { [typeName]: resolvedSchema } compileZodSchema(zodSchema); // best-effort Zod compile normalizeBaseGroups(['base', 'server']); // ['base', 'server'] splitBaseSchema(schema, ['base', 'server']); // { base, groups, hasBase } flattenBaseSchema(schema, ['base', 'server']); // base fields hoisted metaOf(schema); // ConfigMeta | undefined ``` `renderTsType(node)` and `normalizeJsonSchemaMetadata(node)` are lower-level helpers for custom JSON Schema pipelines. ## Environment helpers ```ts import { envBool, envInt, envList, envMap, envPathOf, envString, envVarNameOf, parseEnvTree, readEnvPath, } from '@deltabox/toolchain/config'; const tree = parseEnvTree(process.env, 'MYAPP_'); envString(tree, 'host', 'localhost'); envInt(tree, 'port', 3000); envBool(tree, 'debug', false); envList(tree, 'tags', []); envMap(tree, 'headers.map'); readEnvPath(tree, 'auth.token'); envPathOf('MYAPP_AUTH_TOKEN', 'MYAPP_'); // auth.token envVarNameOf('auth.token', 'MYAPP_'); // MYAPP_AUTH_TOKEN ``` ## CLI generation `generateConfigCliOptions(schema)` walks the config fields (not just env-backed values) and treats each **schema scope as a CLI command**, with its fields as options. It returns scoped and flat views: ```ts import { configCliCommand, generateConfigCliOptions, toToolchainOptions, } from '@deltabox/toolchain/config'; const result = generateConfigCliOptions(scopes, { includePaths: ['server', 'frontend.origin'], // optional path filter excludePaths: ['frontend.secrets'], flags: { 'auto.aliases': '--aliases' }, // optional custom mapping types: { auto: 'boolean' }, // override an ambiguous schema type }); result.command.server; // { name: 'server', type: 'object', options: [...] } result.commandEntries; // [['server', {...}], ['frontend', {...}]] result.options; // every option across every command result.optionsEntries; // [['--port', {...}], ...] const options = toToolchainOptions(result.options); // [{ flags: '--port ', description: 'HTTP port', default: '3000' }, ...] ``` `configCliCommand` builds a complete `CliCommand` from the schema, parses the provided flags into a validated config and passes it to `run`: ```ts import { configCliCommand } from '@deltabox/toolchain/config'; export const serveCommand = configCliCommand({ name: 'serve', description: 'Run the API server.', schema: serverConfig, // Extra command-specific options that are not config fields. options: [{ flags: '--json', description: 'Print JSON.' }], run: (values, config, context) => { // `config` is already parsed/validated from `values`. console.log(config, context.config); }, }); // Build it into the engine program like any other CliCommand: const program = engine.cli.program.create(() => [serveCommand]); await program.invokeAsync(); ``` For an existing command, prefer `engine.cli.program.create()` and keep only genuinely non-config flags (output modes, `--cwd`, `--json`, `--restore`) hand-written. The low-level `configCliOptions` one-liner remains available when you already have a command descriptor: ```ts import { configCliOptions } from '@deltabox/toolchain/config'; const command = { name: 'tsconfig', description: 'Generate workspace tsconfig files.', options: [ // The escape hatch: runtime selectors that are not config fields. { flags: '--cwd ', description: 'Project root.' }, { flags: '--json', description: 'Print the resolved config.' }, // Config-backed options, generated recursively from the schema. ...configCliOptions(tsconfigConfigSchema), ], run: (values, context) => { // values from generated flags are available alongside custom flags }, }; ``` ### `engine.cli.program` `engine.cli.generate()` and `engine.cli.options()` keep their low-level behavior; `engine.cli.program.create()` is the command-level entry point: ```ts const program = engine.cli.program.create(cmd => [ cmd('serve') .description('Run the server.') .option({ flags: '--json', description: 'Print JSON.' }) .option({ flags: '--listen ', path: 'port', type: 'number' }) .command('serve', status => status .name('status') .description('Print the resolved status.') .option({ flags: '--short', description: 'Short output.' }) .run(({ config, values }) => { // typed `serve` config + `short` value }) ) .run(({ config, values, context }) => { // config: the validated `serve` section // values: the explicit CLI values // context: the host CliCommandContext (dbx widens it to ToolchainCommandContext) }), ]); await program.invokeAsync(); ``` `create()` returns a built program: `program.commands` is the normalized command list (a single command stays a single command; an empty list generates one command per eligible scope). `createCommand(scope, spec)` builds one config-backed command without a program; `cmd('name', spec)` / `createCommand('name', spec)` build a runtime-only command without a config scope. The callback may be async; `create()` then returns a promise. `ConfigScopeCommand` chains support `name`, `description`, `version`, `argv`, `bin`, `option`/`options`, `globalOption`/`globalOptions`, `inherit`, `command`/`commands`, `subcommand`/`subcommands`, `onError` and terminal `run`. `onError(error, context)` receives the loaded host context. Omit `run` for a grouping command; it registers with its subcommands. #### Program members and options A `ConfigProgram` exposes the runtime surface: | Member | Description | | ---------------------------------------- | ----------------------------------------------------------------------- | | `commands` | The normalized commands (single command stays single). | | `globals` | The program-level global options. | | `helpOnError` | Whether to print help after an invalid-argv error (`false` by default). | | `groups` | Option/command grouping setting (`true` by default). | | `sort` | Command ordering within each section (`'asc'` by default). | | `name()` / `description()` / `version()` | Set the metadata shown in help/version output. | | `output(writeOut, writeErr?)` | Route help/version output; `writeErr` is reserved for error rendering. | | `globalOption()` / `globalOptions()` | Append program-level globals. | | `argv(values)` | Set the explicit argv used by `invoke()`. | | `withContext(context)` | Set the default host context. | | `configure(format)` | Merge help/error formatting options. | | `formatHelp(command?)` | Render program or command help. | | `formatError(error)` | Render an error with the configured template. | | `invoke(argv?, context?)` | Run synchronously (async handlers/resolvers throw). | | `invokeAsync(argv?, context?)` | Run and await async handlers, hooks and resolvers. | | `hook()` / `hooks()` | Register inferred before/after hooks. | Build the program through the engine — this is the preferred entry point because it infers the config/values types and accepts the full program options: ```ts const program = engine.cli.program.create( cmd => [ cmd('serve', { name: 'serve', description: 'Serve.', run: ({ config, values, context }) => {}, }), ], { name: 'myapp', description: 'Myapp tooling.', version: '1.0.0', globalOptions: [{ flags: '--json', description: 'Print JSON.' }], context: { cwd: process.cwd() }, disableColors: ({ color }) => color === false, writeOut: text => process.stdout.write(text), writeErr: text => process.stderr.write(text), } ); ``` `argv` defaults to `process.argv.slice(2)`, `name` defaults to `'program'`, and `disableColors` defaults to `false`. Commands are sorted ascending by name in each help section by default; pass `sort: 'desc'` to reverse it or `sort: false` to keep declaration order (including inside groups). `program.configure()` merges formatting; `program.argv()`, `program.withContext()` and `program.output()` set the runtime pieces. `helpOnError` defaults to `false`, so invalid argv throws a `ConfigProgramError` without printing help. Pass `helpOnError: true` and append `program.formatHelp()` in your catch handler when you want the full help text: ```ts program.invokeAsync().catch(error => { console.error(error instanceof Error ? error.message : String(error)); if (error instanceof ConfigProgramError && program.helpOnError) { console.error(program.formatHelp()); } process.exitCode = 1; }); ``` `groups` defaults to `true`, so help groups both option and command lists. Commands are grouped by their delimited name path (`vite:list` -> `Vite commands:`), while options use their explicit `group` labels. Set `groups: false` for flat lists, or `groups: { auto: false }` to only honor explicit `group` labels on commands. `delimiter` accepts one string or an array (default `':'`). Command entries within every section (including groups) are sorted by `sort` (`'asc'` by default; `'desc'` or `false` to change/disable). ```ts const program = engine.cli.program.create( cmd => [ cmd('sync', { name: 'sync', run: syncHandler }), cmd('vite:list', { name: 'vite:list', run: listHandler }), // -> Vite commands: cmd('serve:status', { name: 'serve:status', group: 'Server', run: statusHandler, }), ], { groups: { delimiter: [':', '/'] } } ); ``` Use the lower-level `createConfigProgram(commands, options?)` only when you already have a command list that is not tied to an engine. It accepts the same options and is what `engine.cli.program.create()` calls internally. Program types: `ConfigProgram`, `ConfigProgramOptions`, `ConfigProgramFormatOptions`, `ConfigProgramGroupsOptions`, `ConfigProgramCommand`, `ConfigScopeCommand`, `ConfigCommandBuilder`, `ConfigEngineCliProgram` and `ConfigProgramError`. The standalone equivalent is `generateConfigProgram(schema, { envPrefix, ... })`: it returns `CliCommand[]` with schema-derived options. Use `engine.cli.program.create()` when you want the typed `run({ config, values, context })` callback. See [Generate → CLI program](/guide/config-generator/generate#cli-program). #### `ConfigProgramError` Invalid argv throws a `ConfigProgramError` with `code` (for example `unknownCommand`, `unknownOption`, `missingOptionValue`, `invalidValue`, `missingCommand`), `input` and an optional misspelling `suggestion`. Use `format.error.messages` to override the messages and `program.formatError()` to render one. Help is only printed when `helpOnError` is enabled (see [Program members and options](#program-members-and-options)). Options and subcommands have commander-style shorthands as well as array forms: ```ts engine.cli.program.create(cmd => [ cmd('serve') .description('Run the server.') .option('--json', 'Print JSON.') .options([ ['--out ', 'Output directory.', 'dist'], '--check', { flags: '--tag ', description: 'Tags.' }, ]) .command('serve', 'Status.', status => status .name('status') .option('--short', 'Short output.') .run(({ values }) => { // values.short?: boolean }) ) .commands([['serve', 'Info.', info => info.name('info').run(() => {})], ['build']]) .run(({ config, values }) => { // typed serve config + values }), ]); ``` `.options(...list)` and `.commands(...list)`/`.subcommands(...list)` accept the same inputs spread as separate arguments. A subcommand definition may be an already-built `CliCommand`, a `[scope, setup]` / `[scope, description, setup]` tuple, or `{ scope, description?, setup? }`. #### Grouped options Give an option a `group` label to render it under its own heading. Ungrouped options stay in the default `Options:` section; groups appear in first-appearance order, merge case-insensitively and render as ` options:`. Grouping applies to program globals and command options alike, and `groups: false` flattens option groups too. ```ts cmd('sync') .options([ { flags: '--check', description: 'Check only.' }, { flags: '--trace', description: 'Trace resolution.', group: 'Diagnostics' }, { flags: '--profile', description: 'Write a profile.', group: 'Diagnostics' }, ]) .run(syncHandler); ``` `formatHelp` prints: ```text Options: --check Check only. Diagnostics options: --trace Trace resolution. --profile Write a profile. ``` #### Global options Define options once at program level and every command parses them: ```ts const program = engine.cli.program.create( cmd => [ cmd('sync').option('--check', 'Check only.').run(syncHandler), cmd('build').run(buildHandler), ], { globalOptions: [{ flags: '--json', description: 'Print JSON.' }] } ); // Or after creation: program .globalOption('--verbose', 'Verbose output.') .globalOptions([['--cwd ', 'Project root.']]); ``` Commands can declare their own global options too. A subcommand only receives the parent command's globals when it opts in with `.inherit()` (or `inherit: true` in a command definition). Program globals always apply. ```ts cmd('serve') .globalOptions([['--root ', 'Project root.'], '--verbose']) .command('serve', status => status .name('status') .inherit() .run(({ values }) => { // values.root / values.verbose are typed and parsed }) ) .run(({ values }) => { // the parent sees its own globals too }); ``` Resolution order is loaded config section → env vars → explicit CLI values → command-spec `overrides` → schema validation. Return an empty array (`create(() => [])`) to generate one command per eligible scope; `cliCommand: false` opts a scope out. Command metadata (`cliCommand`) supplies `name`, `description`, `aliases`, `hidden`, `passthrough` and `args` when a chain omits them. `scope` is a literal union of the schema's scopes, and `run.config` is inferred from that scope (via `ConfigOf`), so no explicit generic is needed. A single-schema engine infers the whole schema. `ConfigProgramCommand` stays exported as the base shape for custom program generators and wrappers. The host context is generic: `ConfigProgramRunContext` and `ConfigCliCommandOptions` default to the minimal `{ cwd }` context. Use the callback form to select a wider context and build commands with both `config` and `values` inferred: ```ts engine.cli.program.create(cmd => [ cmd('sync') .description('Regenerate managed files.') .option({ flags: '--check', description: 'Check only.' }) .option({ flags: '--only ', description: 'Task names.' }) .option({ flags: '--json', description: 'Print JSON.' }) .run(({ config, values, context }) => { // config: boolean | ToolchainSyncConfig // values.check?: boolean, values.only?: string, values.json?: boolean // context: ToolchainCommandContext }), ]); ``` Because `cmd()` is called directly, its literal `scope` and chained `option()` calls drive the inference; `create()` only fixes the host context. The engine itself stays schema-inferred. Chained commands are self-contained; use `.command(scope, setup)` for typed subcommands. Return an empty array (`create(() => [])`) to generate one command per command-eligible scope. #### Running a built program A built program is commander-like: `invoke()` runs synchronously and `invokeAsync()` awaits async handlers. `argv` defaults to `process.argv.slice(2)` unless the program or one of its commands sets `argv: [...]`. ```ts const program = engine.cli.program.create(cmd => [ cmd('sync').option({ flags: '--check', description: 'Check only.' }).run(handler), cmd('build').option({ flags: '--out ', description: 'Output.' }).run(handler), ]); program.argv(['sync', '--check']); program.withContext({ cwd: process.cwd() }); await program.invokeAsync(); // or pass both explicitly: await program.invokeAsync(['build', '--out', 'dist'], { cwd: process.cwd() }); ``` Options are scoped per command: a subcommand never receives its parent's or a sibling's flags. A sole command with no subcommands is treated as the root command, so `invokeAsync(['--check'])` runs it without repeating the name. Invalid argv throws a `ConfigProgramError` whose message includes a misspelling suggestion; override the messages or render it with `program.formatError()`. ```ts program.configure({ error: { messages: { unknownCommand: input => `no such command: ${input}` } }, }); ``` #### Help, errors, hooks and binaries Help and error output are colourless by default. Supply colour hooks (for example `picocolors`) to opt in; the defaults merge recursively into subcommands and can be overridden per command, option, value, description and usage. The default help template is `'plain'`; the default error template is `'message'`. ```ts import pc from 'picocolors'; program.configure({ colors: { command: pc.cyan, option: pc.yellow, value: pc.green, description: pc.gray, usage: pc.bold, }, options: { '--json': pc.magenta }, commands: { sync: { colors: { command: pc.green } } }, help: { template: 'box', // 'plain' (default) | 'box' | (model) => string box: { corners: { topLeft: '┌', topRight: '┐', bottomLeft: '└', bottomRight: '┘' }, padding: 1, }, }, error: { // 'message' (default) | 'box' (message + stack) | custom formatter template: 'box', showStack: false, messageColor: pc.red, }, }); program.formatHelp('sync'); program.formatError(error); ``` `help.template: 'box'` wraps the commander-style content in the rounded box. `error.template: 'box'` renders one box per error; `'message'` prints only the message. Error formatting also exposes `messageColor`, `stackColor`, `showStack`, `messageOnly`, `box` and `messages` (the invalid-argv message overrides). Custom formatters receive the resolved `ConfigHelpModel` (`name`, `description`, `usage`, `options`, `commands`, `command`) or `ConfigErrorModel` (`errors[]`). Per-command overrides live under `commands[name]` and per-option colors under `options['--flag']`. Set `disableColors` when the host has its own colour switch. A function receives the parsed program globals and the invocation context, so a `--no-color` flag can turn every configured hook off at runtime: ```ts const program = engine.cli.program.create( cmd => [ cmd('serve', { name: 'serve', description: 'Serve.', run: () => {}, }), ], { globalOptions: [{ flags: '--no-color', description: 'Disable colours.' }] as const, disableColors: ({ color }) => color === false, } ); ``` The callback may be async. `invoke()` requires a synchronous resolver; use `invokeAsync()` (the normal CLI path) for async predicates. Hooks run around the selected action and infer every declared command's context, scope, name and runtime `values`: ```ts program .hook('before', 'all', ({ name, scope, values, context }) => {}) .hook('after', 'sync', ({ values }) => { // values is typed from the `sync` command's options }) .hooks({ phase: 'before', target: 'build', handler: async payload => {} }); ``` Set `bin` on a command to execute a relative or absolute binary instead of the in-process handler; the arguments after the command name are forwarded verbatim. ```ts cmd('deploy') .bin('./scripts/deploy.mjs') .run(() => {}); ``` The same inference applies to `configCliCommand({ options: [...] })`: its `run`/`parse` values are typed from the extra runtime options, while schema-derived values remain addressable through the index signature. ### Schema metadata for CLI ```ts const serveConfig = z.object({ port: z .number() .default(3000) .meta({ cli: { short: 'p', description: 'HTTP port.' }, }), aliases: z .boolean() .default(true) .meta({ cli: { flag: '--no-aliases', type: 'boolean', description: 'Skip aliases.' }, }), internal: z.string().meta({ cli: false }), // never a generated flag format: z.union([z.boolean(), z.object({ fix: z.boolean(), command: z.string() })]), }); ``` `cli: false` prunes a field and its subtree from generated flags (env/types/docs still include it). Arrays of scalars become list flags; arrays of objects, records, maps and sets are skipped unless a field defines `cli` explicitly. Ambiguous union paths are omitted and reported through the generator `diagnostics`. Env exposure stays on `envName`/`envPath`; set `envExpose: false` to keep a value CLI-only. `configCommands` returns the library `config:*` generator commands; it does not add commands to the `dbx` binary. ### `CliOptionDef` `CliOptionDef` carries the config metadata a CLI builder needs: | Field | Purpose | | ------------- | ------------------------------------------------ | | `flag` | Long flag (`--auto-aliases`). | | `short` | Optional shorthand (`-a`). | | `env` | Env var, for env-backed options. | | `type` | `string`, `number`, `boolean`, `array`, ... | | `description` | Config description. | | `default` | Stringified default. | | `required` | Config value is required. | | `multiple` | Repeated occurrences collect into an array. | | `choices` | Allowed enum values, when available. | | `hidden` | Registered but omitted from generated docs. | | `scope` | Config scope. | | `path` | Dotted config path (`auto.aliases`). | | `parse` | Coerce one raw CLI string into the config value. | ## Root helpers ```ts import { findProjectRoot, monorepoRoot } from '@deltabox/toolchain/config'; findProjectRoot(process.cwd()); // nearest project root monorepoRoot(process.cwd()); // nearest workspace root ``` ## Types All types can be found at [packages/config/src/types](https://github.com/deltabox-studio/toolchain/tree/main/packages/config/src/types). --- --- url: https://toolchain.dbx.studio/guide/config.md --- # Configuration guide A project is configured in one of two ways: * the recommended `dbx()` **Vite plugin** in `vite.config.*` (config inline, no `dbx.config.*` needed), or * a standalone `dbx.config.ts` when the project does not use Vite. Both can be combined: `dbx.config.*` is the base and the plugin options merge on top. The `@deltabox/toolchain` settings live under the `toolchain` key: ```ts [dbx.config.ts] import { defineConfig } from '@deltabox/toolchain'; export default defineConfig({ toolchain: { project: { type: 'monorepo-root', name: 'myapp', scope: '@org', }, ci: { ci: true, changelog: { branches: { main: 'main', dev: 'dev' }, commitlint: { scopes: ['api', 'web', 'deps'] }, }, }, tsconfig: { refs: true }, fmt: { vscode: true, oxc: { semi: true, singleQuote: true } }, lint: { oxc: { ignorePatterns: ['dist/**'] } }, vite: { test: { include: ['src/**/*.test.ts'] }, }, watch: { debounce: 150 }, }, }); ``` A `dbx.config.ts` can also host other dbx concerns alongside the `toolchain` section. Each section has its own guide: [Project](/guide/project), [CI + Changelog](/guide/changelog/), [tsconfig](/guide/tsconfig), [Formatting & linting](/guide/formatting), [Vite+](/guide/vite), [Watch](/guide/watch), [Logger](/guide/logger) and [Providers](/guide/providers). ## Where to start * [Opt-in by presence](/guide/config/opt-in-by-presence) — which sections run, and how nested sections like `ci.changelog` and the individual workflows opt in. * [Nested configs](/guide/config/nested-configs) — how a workspace config merges over its root. * [`defineConfig`](/guide/config/defineconfig) — object, promise or callback. * [Config file names](/guide/config/config-file-names) — the file names the loader probes. * [Loader](/guide/config/loader) — the `toolchain.loader` tsconfig options, path aliases, `.js` → `.ts` imports and examples. * [Hooks](/guide/config/hooks) — lifecycle hooks in a `.ts`/`.js` config. * [Logging](/guide/config/logging) — the logger section and CLI overrides. * [Providers](/guide/config/providers) — provider passthrough colour settings. * [Vite+](/guide/config/vite) — the full Vite+ config and the generated shim. * [Programmatic API](/guide/config/programmatic-api) — load + sync from code. The generated, exhaustive section reference is [dbx.config](/config/reference). --- --- url: https://toolchain.dbx.studio/guide/config/config-file-names.md --- # Config file names A `dbx.config.*` file is **optional**: the recommended setup carries the config inline in the `dbx()` Vite plugin inside `vite.config.*`. When a project uses a config file, the loader looks for, in order: ``` dbx.config.ts dbx.config.mts dbx.config.js dbx.config.mjs dbx.config.cjs dbx.config.json ``` A TS/JS config is imported through `tsx` with the nearest `tsconfig.json`, so it can use the project's path aliases and `.js` specifiers that point at `.ts` sources. See [Loader](/guide/config/loader) for the `toolchain.loader` section, custom tsconfigs and examples. --- --- url: https://toolchain.dbx.studio/guide/config/defineconfig.md --- # `defineConfig` `defineConfig` is an identity helper that gives the file full type-checking and autocomplete (it mirrors Vite's `defineConfig`). Like Vite, the argument may be a plain object, a promise, or a sync/async callback — the loader resolves it, so a config can do async work before returning `{ toolchain }`: ```ts [dbx.config.ts] export default defineConfig(async () => { const { readFile } = await import('node:fs/promises'); const version = (await readFile('./VERSION', 'utf-8')).trim(); return { toolchain: { project: { name: 'myapp', nodeVersion: version }, }, }; }); ``` --- --- url: https://toolchain.dbx.studio/guide/config/hooks.md --- # Hooks `.ts`/`.js` configs can declare lifecycle hooks (JSON cannot): ```ts [dbx.config.ts] export default defineConfig({ toolchain: { hooks: { afterLoad: ({ tokens }) => console.log(tokens), beforeSync: ctx => ctx.log('syncing...'), afterTask: ({ task, files }) => console.log(task.name, files?.length), afterSync: ({ result }) => console.log(result.written.length), beforeVersion: ({ previousVersion, version }) => console.log(`${previousVersion} -> ${version}`), afterVersion: ({ version }) => console.log('released', version), onChange: ({ path }) => console.log('changed', path), }, }, }); ``` Return values are awaited. ## `beforeVersion` `beforeVersion` runs after the bump is planned and **before** `dbx changelog` writes the new versions or changelogs. It receives the repository root, the planned `version` and the `previousVersion`: ```ts [dbx.config.ts] hooks: { beforeVersion: async ({ cwd, previousVersion, version }) => { await assertReleaseAllowed(previousVersion, version, cwd); }, }, ``` Throwing (or a rejected async hook) aborts the run before any files are written. It does not run for `--dry-run`, `--release-body` or `--format-only`. ## `afterVersion` `afterVersion` runs after `dbx changelog` writes the new versions and changelogs (it does not run for `--dry-run`, `--release-body` or `--format-only`). It receives the repository root and the new version: ```ts [dbx.config.ts] hooks: { afterVersion: async ({ cwd, version }) => { console.log('released', version); await updateScaffoldCatalog(cwd); }, }, ``` Async hooks are awaited by the CLI and `runChangelogAsync`; the synchronous `runChangelog` wrapper rejects async hooks. A failing `beforeVersion` hook aborts the run before any files are written (a failing `afterVersion` hook runs after the writes). The changelog workflow stages `.yarnrc.yml` together with `package.json`/`CHANGELOG.md`, so hooks that update a scaffold catalog are committed in the same version-bump commit. --- --- url: https://toolchain.dbx.studio/guide/config/loader.md --- # Loader The `toolchain.loader` section controls how `dbx.config.*` files are imported. A TS/JS config is loaded through [`tsx`](https://tsx.is), so it can use the project's TypeScript path aliases and import `.ts` sources with a `.js` specifier. ## Options | Option | Type | Default | Description | | ---------- | ------------------- | ------- | ----------------------------------------------------------------------- | | `tsconfig` | `boolean \| string` | `true` | The tsconfig used to resolve imports. `true` = nearest `tsconfig.json`. | * `true` (default) — use the nearest `tsconfig.json` above the config file (the workspace's own). * `"path/to/tsconfig.json"` — use a different tsconfig. The path is resolved from the project root. * `false` — disable tsconfig resolution. Relative `.js` → `.ts` rewriting still works, but tsconfig `paths` aliases do not. ```ts [dbx.config.ts] import { defineConfig } from '@deltabox/toolchain'; export default defineConfig({ toolchain: { loader: { tsconfig: 'tsconfig.loader.json' }, }, }); ``` `loader` is repository-scoped: it is **not merged into a nested workspace's config**. A nested config uses its parent's loader choice when it does not set one itself. ## Path aliases and source extensions With the default loader, imports resolve the way the project's TypeScript does: ```ts [dbx.config.ts] import { shared } from '@org/shared/config.js'; // shared/config.ts import { defineConfig } from '@deltabox/toolchain'; export default defineConfig({ toolchain: { project: shared.project, }, }); ``` The loader rewrites these specifiers when the target exists: | Import | Resolves to | | -------------- | ------------------------------ | | `./helper.js` | `helper.ts`, `helper.tsx`, ... | | `./helper.mjs` | `helper.mts` | | `./helper.cjs` | `helper.cts` | | `./helper.jsx` | `helper.tsx` | It also follows a tsconfig's relative `extends` chain for `baseUrl` / `paths`. A genuinely missing package or module is still an error: the loader does not silently turn it into an empty module. ## Programmatic API `loadToolchainConfig` accepts the same override directly: ```ts import { loadToolchainConfig } from '@deltabox/toolchain'; const loaded = await loadToolchainConfig(process.cwd(), { loaderTsconfig: 'tsconfig.loader.json', // or false }); ``` The option takes precedence over the config's own `loader.tsconfig` and over the parent config's choice. When omitted, the loader uses the config's `loader.tsconfig`, then the parent config's, then the nearest `tsconfig.json`. ## Notes * The loader reads `loader.tsconfig` from the config it is loading, so the first import must already be resolvable. Put a shared choice on the root config (it is used for nested configs) or point the nearest `tsconfig.json` at it. * `.json` configs are parsed directly and do not use a tsconfig. ## Reusing the loader in another project `@deltabox/toolchain/config` exposes the same building blocks for consumers with their own config format: ```ts import { collect, createConfigFile, loadConfig, loadConfigSync, parseCliConfig, parseConfig, parseEnvConfig, } from '@deltabox/toolchain/config'; // Discover + validate a config (JSON, CJS, ESM or TypeScript). const loaded = await loadConfig({ packageJsonKeys: ['myapp'], schema }); // Or parse a specific source. const fromEnv = parseEnvConfig(schema, process.env, { envPrefix: 'MYAPP_' }); const fromCli = parseCliConfig(schema, process.argv.slice(2)); const fromFile = parseConfig(schema, loaded?.config); // Scaffold a starter config file. createConfigFile({ name: 'myapp.config.ts', content: '{ enabled: true }' }); ``` The loader also accepts the same tsconfig, ancestor and filter options as the built-in one: ```ts const loaded = await loadConfig({ parser: schema, configFileOptions: { filename: 'myapp.config', commonLocation: [{ path: '.' }, { cwd: 'packages', path: '*/' }], // Resolve TS imports through this tsconfig (`false` disables it). tsconfig: 'tsconfig.loader.json', // Search ancestors when nothing is found at cwd (stops at `.git`). parent: true, // Skip files that are not valid candidates for this loader. accept: file => !file.endsWith('.shim.ts'), }, }); ``` The object API accepts `tsconfig`, `parent` and `accept` directly instead of nesting them in `configFileOptions`. `findConfigFile` and `findParentConfigFile` run the same discovery without loading anything. Discovery defaults to `.`, `config` and `configs`, matching the built-in loader. `commonLocation.path` globs support `*`, `**`, `?`, simple `[...]` character classes and `{a,b}` alternatives. A function export is resolved when a `parser`/`schema` is passed; without one the raw export is returned, so a caller can supply its own environment (as the dbx plugin probe does). `collect(schema, options)` lists every config leaf (env/CLI metadata) and accepts `envPrefix`, `include`/`exclude`, `maxDepth`, and `validate` with `errorOptions` for required/empty values. `loadConfigSync` handles JSON and CommonJS only; use `loadConfigAsync` (or a custom `loader`) for TypeScript. ### Scaffolding formats `createConfigFile` infers the format from the file name (or takes an explicit `type`): `file` (TypeScript/JavaScript `defineConfig`), `json`, `yaml`, `env` (`KEY=value` lines) and `cli` (`--flag=value` lines). Object `content` is serialized for the chosen format, and `defaults`/`overrides` merge under/over it: ```ts createConfigFile({ name: 'myapp.config.yaml', content: { project: { name: 'myapp' } }, defaults: { project: { license: 'MIT' } }, }); createConfigFile({ name: '.env.example', content: { APP_HOST: 'localhost' } }); ``` --- --- url: https://toolchain.dbx.studio/guide/config/logging.md --- # Logging Every toolchain message goes through one logger. Configure it in the config: ```ts [dbx.config.ts] export default defineConfig({ toolchain: { logger: { level: 'debug', color: false, name: 'dbx' }, }, }); ``` | Option | Values | Default | | ---------- | -------------------------------------------------- | ------- | | `level` | `debug` | `info` | `warn` | `error` | `silent` | `info` | | `color` | `true` | `false` | `true` | | `name` | prefix for non-indented lines | `dbx` | | `suppress` | id, message substring or `/regex/` (single/array) | none | | `logger` | custom `ToolchainLogger` implementation | none | `suppress` silences matching warnings/errors. A string matches an emitted id exactly or a message substring; a `/pattern/flags` string is treated as a regex. Ids are rendered in uppercase in the output (eg. `[FMT_CONFLICT]`), but match the lowercase id when suppressing. It accepts one value or an array: ```ts [dbx.config.ts] toolchain: { logger: { suppress: ['fmt.conflict', 'deprecated option', '/^Could not .* globally/'], }, } ``` Colour is **on by default** (the toolchain forces it rather than relying on TTY autodetection); `--no-color` or `logger: { color: false }` turn it off. Human output is rendered with [`@clack/prompts`](https://bombshell.dev/clack) — level symbols (`•` info, `◆` success, `▲` warn, `■` error) and a guide. ### Custom logger Pass any object implementing the agnostic `ToolchainLogger` interface (`raw`, `rawError`, `write`, `debug`, `info`, `success`, `warn`, `error`) to `logger.logger`. Level/suppression checks still apply before your methods run. ```ts [dbx.config.ts] const custom = { raw: (message = '') => process.stdout.write(`${message}\n`), rawError: (message = '') => process.stderr.write(`${message}\n`), write: () => {}, debug: () => {}, info: (message = '') => mySink.info(message), success: (message = '') => mySink.info(message), warn: (message = '') => mySink.warn(message), error: (message = '') => mySink.error(message), }; export default defineConfig({ toolchain: { logger: { logger: custom } }, }); ``` On the CLI, `--log-level ` and `--no-color` override the config (see the [CLI reference](/guide/cli)); `--no-color` also disables the program's configured help/error colours. Machine output (`--json`) is written unprefixed through the same logger. --- --- url: https://toolchain.dbx.studio/guide/config/nested-configs.md --- # Nested configs A `dbx.config.*` in a **non-root** folder (a workspace, an app, a nested project) is merged over the nearest ancestor `dbx.config.*` found while walking up to the repository root (the walk stops at the `.git` boundary, so it never picks up a config from outside the repo). The merge is recursive, but **sections are strictly opt-in**: * **Only a section the nested config explicitly enables/configures is inherited.** If the nested config omits `fmt`, `lint`, `biome`, `changelog`, `catalogs` or `logger`, that section stays disabled for that project even when the root defines it. * When the nested config **does** opt in, objects are merged key by key and leaves (booleans, strings, numbers, arrays) in the child replace the root's value. `true` means "enabled with the parent's options"; `false` disables it. * **Repository/workspace-scoped sections are never inherited**: `ci`, `tsconfig`, `loader`, `templates`, `registry`, `watch`, `providers`, and `vite`. A workflow, workspace tsconfig tree, config loader, source/registry policy, watch process or Vite config describes the repository or one workspace, so a child starts without the parent's values for them. In particular, the root `tsconfig` task already expands every workspace `tsconfig.json`; inheriting it into each workspace would only re-scan that subtree. `loader` is read from the nearest config file to import the nested config, but it is not merged into the child's config. * **`project` metadata is the exception**: shared metadata (`author`, `license`, `homepage`, `repo`, `packageManager`, ...) is inherited because it is project metadata, not a task section. `vite.fmt` / `vite.lint` are hoisted into the top-level `fmt.oxc` / `lint.oxc` **when the nested config opts into `fmt` / `lint`**. ```ts [/dbx.config.ts] export default defineConfig({ toolchain: { logger: { level: 'debug', color: false }, fmt: { oxc: { printWidth: 100, singleQuote: true } }, vite: { shim: 'static', resolve: { tsconfigPaths: true } }, }, }); // /packages/web/dbx.config.ts — opts into `fmt` + `logger`; `vite` is local export default defineConfig({ toolchain: { logger: { level: 'warn' }, // opts in; leaf overrides the root's level fmt: true, // opts in; inherits the root's `fmt` options vite: { shim: 'static', resolve: { tsconfigPaths: true }, run: { tasks: { build: { command: 'vp pack' } } }, }, }, }); ``` The workspace above ends up with `logger: { level: 'warn', color: false }` and the root's `fmt` options (because it opted in with `fmt: true`). If it omitted `fmt`, it would have no `fmt` section at all. Its `vite.run` holds only the `build` task it declares — the root's tasks are not merged in. > **`vite` is never inherited.** A workspace only has the `vite` config it > declares itself; a project with no `vite` section keeps its hand-written > `vite.config.*` alone. Declare the settings it needs (`shim`, `resolve`, > `plugins`, ...) in its own config. `vite.fmt` / `vite.lint` are hoisted into > `fmt` / `lint` only when the workspace opts into those sections. > **Arrays replace, so repeat what you need.** If a workspace opts into `fmt` > and sets `fmt.oxc.ignorePatterns`, that array replaces the root's list (it is > not appended). Either keep the root patterns in the workspace array, or put > the shared pattern on the root config — for example `**/vite.config.ts` there > covers every workspace's generated shim. > **`project` is inherited except its identity fields.** `name`, `scope`, > `description` and `type` are per-project, so a non-root config keeps its own (or > falls back to its `package.json`) and is still detected from its own files — a > root `project` never renames a workspace. The shared fields (`author`, > `license`, `homepage`, `repo`, `packageManager`, ...) flow down so their > `package.json` values and replacement tokens stay shared. > `project: { inherit: false }` disables project inheritance entirely. `hooks` > are not inherited either — a parent's hooks are code and do not run for a > nested project's sync. ## Configless projects A project with **no `dbx.config.*` of its own** is not managed by the toolchain by default: it does not inherit the ancestor config, `dbx sync` leaves it alone, and its files are never generated or pruned. This avoids surprising changes in packages that never opted in. To manage configless projects, opt in explicitly: * **Config:** set `toolchain.project.manageConfigless: true` on the ancestor config (it is repository-scoped, so a configless project inherits the choice through the parent config). * **CLI:** pass `dbx sync --configless` (or `dbx watch --configless`). * **VS Code:** enable `deltabox.toolchain.manageConfigless`. ```ts [/dbx.config.ts] export default defineConfig({ toolchain: { project: { manageConfigless: true, }, }, }); ``` When enabled, a configless project inherits the ancestor config (the configless opt-in is the explicit opt-in for the whole project; repository-scoped sections are still dropped) and `dbx sync` regenerates its managed files. > Configless projects are still **discovered** (so the Projects view and the > project graph can show them); they are just not managed until you opt in. ## Vite plugin mode A project can also be configured by the `dbx()` Vite plugin instead of a `dbx.config.*`: ```ts [vite.config.ts] import { defineConfig } from 'vite-plus'; import { dbx } from '@deltabox/toolchain/vite'; export default defineConfig({ plugins: [dbx({ toolchain: { project: { name: 'app' }, fmt: { oxc: true } } })], }); ``` The loader evaluates `vite.config.*` and reads the plugin options, so the CLI, sync, watch and the VS Code extension all see the config with no `dbx.config.*`. When both exist, the `dbx.config.*` is the base and the plugin options are merged on top (the plugin layer keeps the sections it does not mention). In plugin mode the toolchain never writes or manages `vite.config.*`, and it watches the plugin config for changes. In a **workspace** plugin config, leave `fmt` and `lint` out: the root `vite.config.*` already owns them, and Vite+ applies the root options (including its `ignorePatterns`) to the workspace. Declaring `fmt: true` / `lint: true` there would select the shared defaults instead and shadow the root config. --- --- url: https://toolchain.dbx.studio/guide/config/opt-in-by-presence.md --- # Opt-in by presence Every section under `toolchain` is **opt-in by presence**: the toolchain only touches an area you actually ask for. * Omit a section — that area is left completely alone. * `section: true` — enable it with defaults (when the section has defaults). * `section: false` — explicitly disable it. * `section: { ...options }` — enable and configure it. This applies to nested sections too. `ci` is opt-in, and every workflow inside it (`ci.ci`, `ci.release`, `ci.issues`, `ci.changelog`, `ci.sync`) is opt-in as well: omit a workflow (or set it to `false`) and the toolchain will not generate or manage its file. Setting `ci: false` or `ci: { enabled: false }` disables the whole section, including every nested workflow and the changelog pipeline. The same rule backs `ci.changelog`: it is only managed when you declare it, and `ci.changelog: false` (or `enabled: false`) disables both its workflow and the changelog pipeline. Helpers `sectionEnabled(section)` and `sectionConfig(section)` implement this and are exported for programmatic use. The top-level `changelog` section configures the manual pipeline for `dbx changelog`/the API. It does not enable CI by itself; `ci.changelog` inherits its options when they are not overridden. See [Manual `toolchain.changelog`](/guide/changelog/#manual-toolchainchangelog). --- --- url: https://toolchain.dbx.studio/guide/config/programmatic-api.md --- # Programmatic config API ```ts import { loadToolchainConfig, runSync, defaultSyncTasks } from '@deltabox/toolchain'; const { config, tokens, projectType } = await loadToolchainConfig(process.cwd()); await runSync({ tasks: defaultSyncTasks(), cwd: process.cwd(), config, tokens, projectType }); ``` `loadToolchainConfig` accepts `loaderTsconfig` to override the tsconfig used to import the config (the same option as [`toolchain.loader.tsconfig`](/guide/config/loader)): ```ts const loaded = await loadToolchainConfig(process.cwd(), { loaderTsconfig: 'tsconfig.loader.json', // or false }); ``` The result also reports `configless` and `managed`, which tell whether the project has no config of its own and whether the toolchain should manage it. Full section reference: [dbx.config](/config/reference). --- --- url: https://toolchain.dbx.studio/guide/config/providers.md --- # Provider config Provider passthrough commands (Vite+) follow the logger's colour setting. The `providers` section can force provider colours on or off on its own: ```ts [dbx.config.ts] export default defineConfig({ toolchain: { providers: { color: false }, }, }); ``` | Option | Values | Default | | ------- | ----------------- | -------------- | | `color` | `true` | `false` | inherit logger | `color: false` runs the wrapped binary with `NO_COLOR=1` and `FORCE_COLOR=0`, so it emits plain output even on a colour terminal. The global CLI `--no-color` flag turns provider colour off too. See [Providers](/guide/providers#colour). --- --- url: https://toolchain.dbx.studio/guide/config/vite.md --- # Vite+ config The whole Vite+ config lives in `toolchain.vite`. Every key is passed through verbatim to Vite+, so `dbx.config.*` stays the only hand-authored root config: ```ts [dbx.config.ts] export default defineConfig({ toolchain: { vite: { test: { include: ['src/**/*.test.ts'], environment: 'node' }, lint: { ignorePatterns: ['dist/**'] }, fmt: { semi: true, singleQuote: true }, }, }, }); ``` `dbx sync` writes a thin root `vite.config.ts` that resolves that config at load time, so the generated file never duplicates (or drifts from) `dbx.config.*`: ```ts [vite.config.ts] import { defineConfig, type ViteUserConfig } from 'vite-plus'; // Generated by @deltabox/toolchain — edit the vite section in dbx.config and run `dbx sync`. import { resolveVite } from '@deltabox/toolchain/vite'; export default defineConfig(resolveVite({ cwd: import.meta.dirname })); ``` The shim imports `defineConfig` from whichever Vite package the project installs (`vite` or `vite-plus`, detected from `package.json`), so a plain `vite` project gets `import { defineConfig, type UserConfig } from 'vite'` and `resolveVite(...)`. `resolveVite(options?)` resolves the **same-directory** `dbx.config.*` (so a nested `vite.config.ts` uses the nested config it sits next to), or the `toolchain` you pass, then returns `toolchain.vite`. Pass `vite` inline to merge overrides over the loaded section (`resolveVite({ vite: { ... } })`). It is exported from `@deltabox/toolchain/vite` for programmatic use too. The single toolchain opt-out is `config`. Set `vite: { config: false }` to leave a hand-written `vite.config.ts` alone; set `config` to a string (relative to the project, or absolute) to write the managed shim at a different path instead. Everything else under `vite` is Vite+ config (plugins, `test`, `lint`, `fmt`, `run.tasks`, ...), so `toolchain.vite` is the full Vite+ configuration. The section is typed as Vite+'s own config (`ToolchainViteConfig` = Vite's `UserConfig` as augmented by Vite+), so the whole Vite+ surface autocompletes in `dbx.config.ts`. ### Nested workspaces `vite` is **never inherited**. A workspace only has the `vite` config it declares itself; a project with no `vite` section keeps its hand-written `vite.config.*` untouched. Declare the settings the workspace needs in its own config: ```ts [packages/web/dbx.config.ts] export default defineConfig({ toolchain: { vite: { shim: 'static', resolve: { tsconfigPaths: true }, run: { tasks: { build: { command: 'vp pack' } } }, }, }, }); ``` `vite.fmt` / `vite.lint` are the exception: when the workspace **opts into `fmt` / `lint`**, they are hoisted into the top-level `fmt.oxc` / `lint.oxc` before inheritance, so shared formatter/linter settings flow down. ### Static shims By default the shim calls `resolveVite` at load time (`shim: 'runtime'`). Set `vite: { shim: 'static' }` to serialize the resolved config into the shim instead: ```ts [vite.config.ts] import { defineConfig, type ViteUserConfig } from 'vite-plus'; export default defineConfig({ resolve: { tsconfigPaths: true }, run: { tasks: {/* ... */} }, }); ``` A static shim imports only `defineConfig`, so Vite+ can load it without a built `@deltabox/toolchain` (useful for source-first monorepos and bootstrapping). It must stay serializable: functions, regexps and class instances are rejected at sync time (plugins still work with `shim: 'runtime'`). Runtime shims import `@deltabox/toolchain/vite` by default. Set `vite.shimImport` to change that specifier, for example to a local wrapper that re-exports `resolveVite`. Relative values are resolved from the repository root and rewritten relative to each generated config: ```ts [dbx.config.ts] export default defineConfig({ toolchain: { vite: { shimImport: './scripts/local-vite-resolver.ts', }, }, }); ``` This only affects `shim: 'runtime'` (the default); static shims have no toolchain import. Vite 8 resolves TypeScript `paths` through `resolve.tsconfigPaths`. Set it in `toolchain.vite.resolve` (and in Vitest configs) to reuse the tsconfig aliases: ```ts [dbx.config.ts] export default defineConfig({ toolchain: { vite: { resolve: { tsconfigPaths: true } }, }, }); ``` For explicit aliases (or Vite versions without built-in `paths` support), use `resolveTsconfig()` from `@deltabox/toolchain/tsconfig` (see the [tsconfig guide](/guide/tsconfig#resolving-a-tsconfig)). Add the shim to `vite.fmt.ignorePatterns` so Oxfmt leaves the generated file alone - without it `vp fmt` would rewrite the shim and `dbx sync --check` would report drift. In a monorepo put `**/vite.config.ts` on the root config: workspace `fmt` settings are inherited, but a workspace's `ignorePatterns` array replaces the root's list. The default fmt ignores already include `**/vite.config.ts`; `dbx migrate --from vite` adds `/vite.config.ts` to `vite.fmt` only when the folded config already owns `fmt`. ## Format and lint defaults Opt in with `vite: { fmt: true }` / `vite: { lint: true }` to use the toolchain defaults (`DEFAULT_FMT_RULES` / `DEFAULT_LINT_RULES`, exported from `@deltabox/toolchain`). An options object is merged over those defaults, so `fmt: { semi: false }` keeps the shared ignores and print width and only changes `semi`. Shared ignore lists live in `DEFAULT_FMT_IGNORE_PATTERNS` / `DEFAULT_LINT_IGNORE_PATTERNS`, both layered over `DEFAULT_IGNORE_PATTERNS`. All three are exported (readonly) from `@deltabox/toolchain` and `@deltabox/toolchain/shared`, so you can compose your own list instead of repeating the defaults: ```ts [dbx.config.ts] import { DEFAULT_FMT_IGNORE_PATTERNS, defineConfig } from '@deltabox/toolchain'; export default defineConfig({ toolchain: { vite: { fmt: { ignorePatterns: [...DEFAULT_FMT_IGNORE_PATTERNS, '**/fixtures/**'], }, }, }, }); ``` Import sorting is enabled by default too. `sortImports` uses the usual groups (`builtin`, `external`, `internal`/`subpath`, relatives, styles) plus a `workspace` group whose patterns come from every `dbx.config.*` project in the repository, so consumer packages sort together without a hand-written `customGroups` entry. Override `sortImports: false` to disable it, or set your own groups — the resolved workspace group is still appended (and listed in `groups`) unless you disable sorting. To reuse the workspace group in your own `sortImports`, import the resolver: ```ts import { resolveFmtCustomGroups } from '@deltabox/toolchain'; const customGroups = await resolveFmtCustomGroups(); // [{ groupName: 'workspace', elementNamePattern: ['@org/**', 'app', 'app/**', ...] }] ``` `resolveFmtCustomGroups()` reads the project graph, so it is safe to call from inside `dbx.config.*`. Pass `{ config: 'path/to/dbx.config.ts' }` to resolve a specific config instead of the discovered one, or an inline `project` to add a project the graph does not know about. In VS Code, set `deltabox.toolchain.enableFormatImportGroupDefaults` to `false` (user or workspace settings) to stop the extension from adding the workspace group. ## Oxc config files Vite+ reads `fmt`/`lint` from `vite.config.ts`, but the Oxc VS Code extension reads `.oxfmtrc.json` / `.oxlintrc.json`. When `vite.fmt` / `vite.lint` are defined, `dbx sync` writes those files as managed files so the editor picks up the same configuration. Only the root gets them by default; a nested `dbx.config.*` gets its own pair only when it defines `vite.fmt` / `vite.lint` itself (an inherited root config does not create per-workspace files). To adopt an existing hand-written `vite.config.ts`, fold it in with the migration (see [Migrations](/guide/migrations/#vite-config)): ```sh dbx migrate --from vite --write # folds the object into toolchain.vite (routes fmt/lint) dbx sync # writes the managed vite.config.ts shim ``` --- --- url: https://toolchain.dbx.studio/guide/monorepo.md --- # Monorepo guide ## Project graph `dbx projects` discovers every workspace package and writes a dependency graph to `.dbx/toolchain/projects.json`. The VS Code extension and the `sync --recursive` command consume it. ## tsconfig generation Enable the `tsconfig` section and the toolchain generates each workspace's `tsconfig.json` (extending `tsconfig.default.json`) and, for a monorepo root, a `tsconfig.workspaces.json` wiring project references and path aliases: ```ts [dbx.config.ts] export default defineConfig({ toolchain: { project: { type: 'monorepo-root', name: 'myapp', scope: '@org' }, tsconfig: { refs: true, aliases: true, indent: 4 }, }, }); ``` See the [tsconfig guide](/guide/tsconfig) for every option and why the toolchain splits the config across several files. ## Scaffolding a monorepo ```sh dbx project:init:monorepo --name myapp --scope @org --out . dbx project:init:workspace --name utils --scope @org --root . --dir packages/utils ``` ## Tasks `deltabox toolchain` (and Vite+ consumers) use **Vite Task** (`vp run`, exposed as `dbx run`) instead of Turbo. The package graph orders execution via each package's `package.json` dependencies. Run tasks from the workspace root. `vp run -r ` runs every package's task in dependency order; `vp run --filter ./apps/web ` narrows it. For the built-in app commands, Vite+ resolves the target package from the root and prints the direct `vp -C ` form, so you never need to `cd` between packages. Use `-C` when a command must behave as if it ran inside a package. To always target one app from the root, set `defaultPackage: './apps/web'` (a per-command object also works) in the root `vite.config.ts`. Each package can declare `build`, `typecheck` and `test` in its own `vite.config.ts` `run.tasks` (or in `dbx.config.ts` under `toolchain.vite`) with explicit cache input/output, so `vp run` reports cache hits (a `package.json` script cannot carry cache config). Use `vp pack` / `vp test` instead of the individual `tsdown` / `vitest` binaries: ```ts [packages//vite.config.ts] import { defineConfig } from 'vite-plus'; export default defineConfig({ run: { tasks: { build: { command: 'vp pack', cache: { input: [{ auto: true }, '!dist/**', '!**/*.tsbuildinfo'], output: ['dist/**'], }, }, typecheck: { command: 'tsc -p tsconfig.build.json --noEmit', cache: { input: [{ auto: true }, '!**/*.tsbuildinfo'], output: [] }, }, test: { command: 'vp test run', cache: { input: [{ auto: true }, '!**/*.tsbuildinfo'], output: [] }, }, }, }, }); ``` The root `package.json` orchestrates them and adds the umbrella build: ```json [package.json] { "scripts": { "build": "dbx run --filter \"./packages/*\" build && dbx run build:root", "test": "dbx run --filter \"./packages/*\" test && dbx run test:root" } } ``` `dbx run --filter "./packages/*" build` runs each package's `build` in dependency order (excluding the root, which avoids recursion), then `build:root` builds the umbrella dist. ## Shared formatting and linting Define `fmt` and `lint` once in the root `vite.config.ts`, and run `vp fmt`, `vp lint` and `vp check` from the root. Vite+ does not apply nested configs to individual files, and `vp check` always uses the root blocks, so package-level `fmt` / `lint` blocks are not recommended. Use `overrides` for package- or file-specific settings: ```ts [vite.config.ts] export default defineConfig({ lint: { overrides: [ { files: ['apps/api/**'], env: { node: true } }, { files: ['**/*.test.ts'], plugins: ['vitest'] }, ], }, fmt: { overrides: [{ files: ['**/*.md'], options: { proseWrap: 'always' } }], }, }); ``` Globs resolve from the root config, so use workspace paths such as `apps/web/**`; do not add per-package formatter/linter blocks. --- --- url: https://toolchain.dbx.studio/guide/project.md --- # Project The `project` section is a package's **canonical metadata**. It is the single place to declare who a package is, and it does three jobs: 1. **Defines `package.json` fields.** On `dbx sync`, the fields the section defines are written into the project's `package.json` (everything else is left untouched). 2. **Feeds the {{ token }} replacements.** Every template (`biome.json`, workflows, tsconfigs, READMEs, ...) reads these values. 3. **Drives scaffolding.** `dbx project:init*` uses the section as its defaults (and `project.type` picks the kind of project to generate). ```ts [dbx.config.ts] export default defineConfig({ toolchain: { project: { type: 'monorepo-root', name: 'myapp', scope: '@org', author: 'Myapp Inc. ', license: 'MIT', homepage: 'https://myapp.dev', repo: 'https://github.com/myapp/myapp', description: 'The myapp monorepo', nodeVersion: '22', packageManager: 'yarn', packageManagerVersion: '4.17.1', }, }, }); ``` ## `package.json` mapping A sync writes only the fields the config **defines**; a field you omit is never touched. The mapping: | `project` field | `package.json` field | Notes | | ---------------- | -------------------- | -------------------------------------------------- | | `name` + `scope` | `name` | `@org/app` when a scope is set, else `app`. | | `description` | `description` | | | `author` | `author` | | | `license` | `license` | | | `homepage` | `homepage` | | | `repo` | `repository` | `{ type: 'git', url }` (+ `directory`, see below). | | `packageManager` | `packageManager` | `yarn@4.17.1` when `packageManagerVersion` is set. | | `type` | — | Project kind for detection/scaffolding. | | `nodeVersion` | — | Node version for CI/templates (not `engines`). | `nodeVersion` is intentionally **not** written to `engines`: it is the Node version the generated workflows run on (`node-version: '{{nodeVersion}}'`), which is a different concern from the published `engines.node` range. ## Workspace inheritance A non-root `dbx.config.*` is merged over the nearest ancestor config (see [Configuration → Nested configs](/guide/config/nested-configs)). Tooling sections are strictly opt-in for nested configs; `project` metadata is the exception because it is metadata, not a task section. For `project` specifically: * **Identity fields are never inherited**: `name`, `scope`, `description` and `type` are per-project. A workspace keeps its own values, falling back to its `package.json` for `name`/`scope`/`description`, and is still detected from its own files — a root `project` never renames or rescopes a workspace. The scope therefore comes from the workspace's own `package.json` name (eg. `@org/web`); an unscoped name stays unscoped unless the workspace config sets `scope`. * **Shared metadata is inherited** (`author`, `license`, `homepage`, `repo`, `packageManager`, ...), so those `package.json` values and replacement tokens stay shared. * **`inherit: false`** opts out entirely: the project keeps only its own `project` and ignores the parent's (useful for an unrelated package inside the tree). * **`manageConfigless: true`** opts into managing projects that have no `dbx.config.*` of their own. It is repository-scoped (set it on the root config) and is **disabled by default**: configless projects are discovered but never synced or generated for unless you opt in. See [Configless projects](/guide/config/nested-configs#configless-projects). ```ts [packages/web/dbx.config.ts] export default defineConfig({ toolchain: { // `name`/`scope` are identity; here the scope comes from the package's // `@org/web` name. `author`/`license`/`repo` still inherit from the root. project: { name: 'web' }, // ... }, }); ``` ### `repo` resolves to the workspace path For a non-root project, `repo` also resolves to the workspace's location in the repository, written as `repository.directory`: ```json [package.json] { "repository": { "type": "git", "url": "https://github.com/myapp/myapp", "directory": "packages/web" } } ``` The directory is computed relative to the repository root (the nearest ancestor with a `.git`), exactly like npm expects for a monorepo workspace. ## When the section is absent If `project` is not defined, nothing is written to `package.json` — and the replacement tokens fall back to the project's **own `package.json`** values (`name`/`scope` from `name`, plus `description`, `author`, `license`, `homepage`, `repository`, `engines.node`, `packageManager`). So a repo with no `project` section still generates correct tokens from its existing metadata. ## Scaffolding `dbx project:init`, `dbx project:init:monorepo` and `dbx project:init:workspace` read `project` as their defaults, and: * **`name`** comes from `--name`, or from `project.name` when the scaffold writes **into** the current project. A scaffold `--out` elsewhere never inherits the parent project's name — it uses the target directory's basename instead (pass `--name` to override). A workspace always needs an explicit `--name` (the root's name is not the workspace name). * **`--type` must be valid** (`project`, `monorepo-root` or `monorepo-workspace`) when passed explicitly; an invalid value is rejected. A `project.type` in the config still drives `dbx sync` detection, but scaffolding deliberately ignores it (a scaffold launched from a monorepo root must not tag a workspace with the root's type). ```sh dbx project:init --name my-app --scope @org --type project --out ./my-app dbx project:init:monorepo --name myapp --scope @org --out . dbx project:init:monorepo --name myapp --scope @org --example --out . dbx project:init:workspace --name web --root . --dir packages/web ``` The scaffolded `dbx.config.ts` spells the resolved `project` fields out, so a generated project is self-describing from day one. Existing files in the output directory are never overwritten (pass `--force` to replace them), and a scaffold refuses to write outside its output directory. A nested `project:init` below a root that already has `.oxfmtrc.json` / `.oxlintrc.json` skips its own Oxc files and `fmt.oxc` / `lint.oxc` opt-ins, so it uses the root formatting/linting setup. Pass `--package-manager ` (`yarn` default, or `pnpm` / `npm` / `bun`) to choose the manager the scaffold targets. ## Package manager and catalogs The scaffold and `dbx sync` write a **catalog** (`package -> version range`) into the file the package manager reads it from, so dependencies can be declared with `catalog:`: | Manager | Catalog file | Notes | | ------- | --------------------- | -------------------------------------------- | | `yarn` | `.yarnrc.yml` | `catalog:` / `catalogs:` (default + named). | | `pnpm` | `pnpm-workspace.yaml` | `catalog:` / `catalogs:`. | | `bun` | `package.json` | `workspaces.catalog`. | | `npm` | — | No catalog support; dependencies are pinned. | Scaffolding resolves the manager from the `packageManager` input, writes the catalog of the packages the project depends on, and **opts into it in the generated `dbx.config.*`**, so `dbx sync` owns the file. To manage catalogs in an existing project, add a `catalogs` section (see [Package catalogs](/guide/catalogs)): ```ts [dbx.config.ts] export default defineConfig({ toolchain: { project: { packageManager: 'yarn' }, catalogs: { packages: { react: '^19.0.0', lodash: '^4.17.21' }, named: { legacy: { react: '^18.0.0' } }, }, }, }); ``` `dbx sync` writes (and keeps in sync) `catalog:` / `catalogs:` in `.yarnrc.yml` (Yarn) or `pnpm-workspace.yaml` (pnpm). A catalog file is only written when it is absent or already toolchain-managed (it carries a marker comment); a hand-written one is left untouched. Bun catalogs live in `package.json` and npm has no catalog support — both emit a warning. ## Programmatic API ```ts import { projectFromPackageJson, projectToPackageJson, projectSyncTask } from '@deltabox/toolchain'; // Seed a config from an existing package.json. const project = projectFromPackageJson(require('./package.json')); // Map the defined fields onto package.json fields. const pkgFields = projectToPackageJson(project, { directory: 'packages/web' }); // The sync task itself. projectSyncTask(); ``` | Export | Description | | ----------------------------- | ------------------------------------------------------------------- | | `projectFromPackageJson(pkg)` | Derive project metadata from a `package.json`. | | `projectToPackageJson(p, o?)` | Map defined project fields onto `package.json` fields. | | `projectSyncTask()` | The sync task that applies the `project` section to `package.json`. | --- --- url: https://toolchain.dbx.studio/guide/typescript.md --- # TypeScript `@deltabox/toolchain` is written in TypeScript and ships the config model, the generated `.d.ts` files and the ambient Zod metadata types. This page covers the type-safety story for consumers. ## `dbx.config.ts` `defineConfig` is an identity helper that gives the config file full autocomplete and type-checking, including the opt-in `toolchain.ci` workflows: ```ts [dbx.config.ts] import { defineConfig } from '@deltabox/toolchain'; export default defineConfig({ toolchain: { project: { name: 'myapp', scope: '@org' }, ci: { ci: true, changelog: { commitlint: { scopes: ['api', 'web'] }, versioning: { target: 'individual' }, }, }, }, }); ``` It accepts an object, a promise, or a sync/async callback — the loader resolves it (see [`defineConfig`](/guide/config/defineconfig)). ## Config types The `toolchain` shape is exported as `ToolchainConfig` (and the individual sections as `ToolchainCiConfig`, `ChangelogConfig`, ...): ```ts import type { ToolchainConfig, ToolchainCiConfig } from '@deltabox/toolchain'; const ci: ToolchainCiConfig = { ci: true, changelog: true }; const config: ToolchainConfig = { project: { name: 'myapp' }, ci }; ``` The same types are available from `@deltabox/toolchain/shared`, and each subpath re-exports the types it owns. ## Ambient schema metadata Zod's `.meta()` is typed by default, but the toolchain adds its own fields (`env`, `path`, `required`, `deprecated`, `deprecationMessage`, `example`, `since`, `see`, `remarks`, `experimental`, `alpha`, `beta`, `secret`, `scope`, `public`, `defaultValue`). Add the ambient declaration once in a project-wide `.d.ts`: ```ts [globals.d.ts] /// ``` Now a schema used with the [config generator](/guide/config-generator/) is fully typed: ```ts import { z } from 'zod'; export const serverConfig = z.object({ port: z.number().default(3000).meta({ env: 'MYAPP_PORT', description: 'HTTP port', example: '3000', }), password: z.string().meta({ env: 'MYAPP_AUTH_PASSWORD', required: true, secret: true, }), }); ``` `ConfigMeta` is `ConfigBaseMeta & ConfigEnvMeta`: * `ConfigBaseMeta`: `description`, `required`, `deprecated`, `deprecationMessage`, `example`, `since`, `see`, `remarks`, `experimental`, `alpha`, `beta`, `secret`, `scope`, `public`, `defaultValue`. * `ConfigEnvMeta`: `envName` and `envPath` (both optional, so non-env configs can use metadata too). `.describe()` is still the primary description and is rendered into the generated types, JSON Schema and markdown reference; `.meta({ description })` is used as a fallback and adds env/docs metadata. ## Programmatic API The loader and sync runner are typed end-to-end: ```ts import { defineConfig, defaultSyncTasks, loadToolchainConfig, runSync, type ToolchainConfig, } from '@deltabox/toolchain'; const loaded = await loadToolchainConfig(process.cwd()); const config: ToolchainConfig = loaded.config; await runSync({ tasks: defaultSyncTasks(), cwd: process.cwd(), config, tokens: loaded.tokens, projectType: loaded.projectType, }); // Run only a named task (eg. refresh the tsconfig aliases after a build). await runSync({ tasks: defaultSyncTasks(), only: ['tsconfig'], cwd: process.cwd(), config, tokens: loaded.tokens, projectType: loaded.projectType, }); ``` `only` implies `prune: false`, so a subset never deletes files owned by the tasks it skipped. See the [Programmatic API](/guide/api/) guide for the package-by-package reference. ## Vite+ The generated `vite.config.ts` shim is typed against the project's Vite package (`vite` or `vite-plus`) and `resolveVite` is generic, so `resolveVite({ cwd: import.meta.dirname })` keeps the full Vite+ surface (see [Vite+](/guide/vite)). ## JSON Schema / editor autocomplete [config.schema.json](/config.schema.json) is generated from the same Zod model and published at the site root, so a `dbx.config.json` gets editor completion. For a TypeScript config, `defineConfig` already provides the same information. --- --- url: https://toolchain.dbx.studio/guide/tsconfig.md --- # tsconfig The `tsconfig` section generates every workspace's `tsconfig.json` from a workspace default tsconfig (`tsconfig.default.json`), layering path aliases and project references from a single root workspaces tsconfig (`tsconfig.workspaces.json`). It runs only at a **monorepo root** (`project.type: 'monorepo-root'`); a single project keeps its hand-written tsconfig untouched. ```ts [dbx.config.ts] export default defineConfig({ toolchain: { project: { type: 'monorepo-root', name: 'myapp', scope: '@org' }, tsconfig: { aliases: true, refs: true, indent: 4 }, }, }); ``` `dbx sync` regenerates the managed `tsconfig.json` files and tracks them in `.dbx/toolchain/manifest.json`; `dbx sync --check` is the CI gate. A scaffolded monorepo root enables `tsconfig` by default; single-project and workspace scaffolds leave it opt-in. See [Configuration](/guide/config/opt-in-by-presence) for the opt-in-by-presence shorthand (`tsconfig: true` enables the defaults). ## Why so many tsconfig files? TypeScript's language service (IntelliSense, diagnostics, autocomplete, "go to definition", project references, ...) **always** picks up the file literally named `tsconfig.json`. It offers no way to point the editor at a different file, and it only understands the options it can express in a single config. That single-file constraint is painful in practice: * **Builds need different options than the editor.** `tsc` for a build wants `declaration`/`composite`/`emitDeclarationOnly`, a wider `include` and no `noEmit`, while the editor wants fast, no-emit checking of `src`. Cramming both into one `tsconfig.json` makes one of the two slower or wrong. * **A monorepo has many projects with different options.** Each workspace wants its own `include`/`lib`/`types`/`jsx`, but the editor only reads the nearest `tsconfig.json`. * **The language service can get slow.** For TypeScript (especially ≤ 7) the editor loads and type-checks whatever the `tsconfig.json` includes; a config that pulls in every workspace (or the whole build graph) can noticeably slow IntelliSense. Keeping the editor config small and correct matters. * **Hand-managing the graph is tedious.** Path aliases and project references have to stay in sync with the workspace list, and a stale reference silently degrades the editor. The toolchain splits the concerns so each file has one job, and `dbx sync` keeps the generated `tsconfig.json` (the file the LSP actually reads) in sync with a shared workspaces tsconfig that declares the `paths` + `references`. **NOTE:** the `paths` + `references` in `tsconfig.workspaces.json` automatically resolves relative paths in each workspace's generated tsconfig. ## The files The generator reads two hand-authored inputs (`tsconfig.default.json`, `tsconfig.workspaces.json`) and writes one managed output (`tsconfig.json`): | File | Owner | Role | | -------------------------- | ---------- | --------------------------------------------------------------------------------- | | `tsconfig.base.json` | you | Shared compiler options that every workspace config extends. | | `tsconfig.default.json` | you | A workspace's own options — the **input** the generator reads. **Optional.** | | `tsconfig.build.json` | you | Build/emit options (`tsc -p tsconfig.build.json`). **Optional, never rewritten.** | | `tsconfig.workspaces.json` | you (root) | The root `paths` + `references` the generator expands. **Optional.** | | `tsconfig.json` | generated | Extends `tsconfig.default.json` + the workspaces aliases/references. | Only `tsconfig.json` must keep its name — that is the file TypeScript's LSP reads. Everything else is optional and, if you prefer, renameable (see [Renaming the files](#renaming-the-files)): * **No `tsconfig.default.json`**: there is nothing to expand (the task logs a message and, when workspaces are expected, warns — see [Warnings](#warnings)). * **No `tsconfig.build.json`**: builds simply use another config; it is never required or rewritten. * **No `tsconfig.workspaces.json`**: each workspace still gets a `tsconfig.json` that extends its own default. When the project graph has workspaces, a missing workspaces file is regenerated from the graph (aliases + references); with no workspaces there is nothing to wire. The {{ envTypesFile }} token in the templates (default `src/dbx-env.d.ts`) is resolved when a project is scaffolded, so a generated config's `include` points at the project's env types file. ## Development vs build configs `tsconfig.json` is the **editor/development** config: it extends `tsconfig.default.json` and layers the workspace `paths` aliases on top, so imports such as `@org/core` resolve directly to `packages/core/src`. That is what gives go-to-definition, inline diagnostics and fast editor feedback against the real workspace source. `tsconfig.build.json` layers the managed `tsconfig.json` by default, so it inherits the workspace `paths` aliases. A build (`tsc -p tsconfig.build.json`, `tsdown`, ...) can therefore resolve sibling workspaces directly to source instead of through `node_modules` / project references. That keeps build and editor resolution consistent. If you do **not** want sibling source in the build graph, point the build config back at the source default: ```json [tsconfig.build.json] { "extends": "./tsconfig.default.json", "include": ["src"] } ``` That treats sibling workspaces as packages only, which can reduce bundle size. Only do it when that is what you want. ## Options | Option | Type | Default | Description | | ---------------------- | ------------------------------------ | -------------------------- | ------------------------------------------------------------------- | | `enabled` | `boolean` | enabled when defined | Master switch (only meaningful with `project.type: monorepo-root`). | | `aliases` | `boolean` | `true` | Inject `compilerOptions.paths` from the workspaces config. | | `refs` | `boolean` | `false` | Wire project references between workspaces. | | `composite` | `boolean` | `false` | Fallback `composite` value when `refs`/`refsAuto` are both off. | | `flattenRemoteExtends` | `boolean` | `false` | Inline compiler options inherited from a remote `extends` chain. | | `auto` | `boolean \| object` | `false` | Auto-generate the workspaces paths/references from the graph. | | `aliasAuto` | `boolean \| object` | `auto` | Auto-generate aliases (`modes`, `prefix`, `devMode`, `dist`, ...). | | `refsAuto` | `boolean \| object` | `auto` | Auto-generate project references. | | `autoSrcDir` | `string` | `src` | Source dir used when resolving package entry points. | | `glob` | `string \| string[]` | `**/tsconfig.default.json` | Glob(s) for the workspace default tsconfig files to expand. | | `exclude` | `string \| string[]` | common ignored paths | Glob(s) excluded from `glob`. | | `gitignore` | `boolean` | `true` | Respect `.gitignore` files (root + nested). | | `defaultFile` | `string` | `tsconfig.default.json` | The workspace default tsconfig file name. | | `buildFile` | `string` | `tsconfig.build.json` | The workspace build tsconfig file name. | | `indent` | `number` | `4` | JSON indentation of the generated files. | | `rootFile` | `string` | `tsconfig.workspaces.json` | The workspaces tsconfig file name. | | `baseFile` | `string` | `tsconfig.base.json` | The root base tsconfig file name (the `overrides.base` target). | | `extends` | `{ base?, default?, build? }` | template defaults | Per-file `extends` overrides for scaffolded tsconfig templates. | | `overrides` | `{ base?, default?, build?, root? }` | none | Managed deep-merge overrides applied to the user-owned tsconfigs. | ### `aliases` When on (the default), each generated `tsconfig.json` gets a `compilerOptions.paths` block derived from the workspaces tsconfig's `paths`. The generator rewrites every alias relative to the workspace it is writing, and **drops** any alias that resolves to the workspace itself (or into its own subtree) so a package never maps its own import back to a self-reference. ### `refs` When on, the workspaces `references` are merged with each workspace's own `references`, deduplicated, rewritten relative to the workspace, and pruned whenever the target config is not `composite` (a reference to a non-composite project is invalid). This is what lets `tsc -b` build the graph in order. ### `composite` Every generated `tsconfig.json` copies the workspaces tsconfig's `compilerOptions` (for example `types`, `declaration`, `noEmit`, `paths`). `composite` is the exception: it is derived from `refs` / `refsAuto` because a project must be composite when it is referenced. When both are off, the workspaces tsconfig's `composite` value is copied instead. Leave it off unless you build the graph with `tsc --build`; `composite` requires every imported file to be part of a referenced project, so `tsc -p --noEmit` is happier without it. ### `auto` / `aliasAuto` `auto` derives both the workspaces `paths` and `references` from the project graph. `aliasAuto` controls only the aliases and defaults to `auto`; `refsAuto` controls only the references. Every one is opt-in (`false` by default for `auto`) and preserves keys you wrote yourself: only entries a previous auto run managed are updated or removed. The alias object accepts: | Option | Type | Default | Description | | --------------------- | ------------------------------------------------------------------------------------ | ------------------------- | --------------------------------------------------------------------------- | | `modes` | `'auto' \| 'exports' \| 'project-structure' \| ('exports' \| 'project-structure')[]` | `auto` | How aliases are discovered. | | `prefix` | `string` (eg. `@`) | package name | Base key for generated aliases (`@` → `@/` and `@//*`). | | `devMode` | `boolean` | `true` | Resolve `exports` to source files; `false` points at the distributed files. | | `dist` | `string` | tsconfig `outDir`, `dist` | Output directory used for the source/dist mapping. | | `rewriteAlias` | `Record \| Rule[]` | none | Rewrite generated alias keys (`$1`, `$2`, ... capture groups). | | `include` / `exclude` | `string[]` | none | Filter aliases by their generated keys. | `modes` values: * **`auto`** — use `exports`/`types`/`main` when they resolve to usable source, otherwise scan the project structure. * **`exports`** — only `package.json` `exports` (falling back to `types`/`main` for the package root). * **`project-structure`** — scan the workspace source tree (`index.*` files and a wildcard). * **an array** — combine both; an earlier mode wins when keys collide. #### Visual example: input → generated paths Given `packages/core/package.json`: ```json { "name": "@org/core", "exports": { ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" }, "./utils": { "types": "./dist/utils.d.ts", "import": "./dist/utils.js" } } } ``` and `packages/core/tsconfig.default.json`: ```json { "compilerOptions": { "rootDir": "src", "outDir": "dist" } } ``` this config: ```ts tsconfig: { auto: { modes: 'exports', devMode: true }, } ``` produces these entries in `tsconfig.workspaces.json` (then rebased into each workspace's generated `tsconfig.json`): ```json { "compilerOptions": { "paths": { "@org/core": ["./packages/core/src/index.ts"], "@org/core/utils": ["./packages/core/src/utils.ts"], "@org/core/*": ["./packages/core/src/*"] } } } ``` With `devMode: false` the same exports resolve to the distributed files instead: ```json { "@org/core": ["./packages/core/dist/index.js"], "@org/core/utils": ["./packages/core/dist/utils.js"], "@org/core/*": ["./packages/core/dist/*"] } ``` With `prefix: '@'` the keys become `@/core`, `@/core/utils` and `@/core/*` (the prefix replaces the package scope, not the package name). `rewriteAlias` runs against those final generated keys, so `{ "^@/core/utils$": "@/core/helpers" }` renames that one alias. ### `refsAuto` `refsAuto` derives the workspaces `references` from the project graph. It defaults to `auto`; `refs` must also be enabled. Wired workspaces get `composite: true` automatically. References are only followed by `tsc --build` (`tsc -b`); **`tsc -p --noEmit` ignores them**. If your typecheck runs `tsc -p --noEmit` (as this repo's does), keep `refsAuto: false` and maintain the `references` in `tsconfig.workspaces.json` by hand, or switch the check to `tsc -b`. ### `glob` The glob(s) selecting the workspace default tsconfig files to expand. A single string or an array: ```ts tsconfig: { glob: '**/tsconfig.default.json'; } tsconfig: { glob: ['packages/*/tsconfig.default.json', 'apps/*/tsconfig.default.json']; } ``` It defaults to `**/`, so setting `defaultFile` alone is usually enough. ### `exclude` / `gitignore` `exclude` drops paths from `glob`; it adds to the common ignored paths the toolchain already skips (`node_modules`, `.dbx`, `dist`, `build`, `coverage`, `.turbo`, `.git`, `.yarn`, ...). `gitignore` (on by default) additionally honours the repo's `.gitignore` files — **root and nested**, each scoped to its own directory, like git — so an ignored workspace is never scanned: ```ts tsconfig: { glob: '**/tsconfig.default.json', exclude: ['**/legacy/**'], gitignore: true, } ``` Set `gitignore: false` to scan ignored paths anyway. The base list is exported as `DEFAULT_IGNORE_PATTERNS` from `@deltabox/toolchain` and `@deltabox/toolchain/shared`, so you can compose your own excludes from it. ### Renaming the files `defaultFile`, `buildFile`, `rootFile` and `baseFile` rename the files the generator reads and the [`overrides`](#overrides) patch: ```ts tsconfig: { defaultFile: 'tsconfig.src.json', // expanded into tsconfig.json buildFile: 'tsconfig.dist.json', // read, never rewritten by the generator rootFile: 'tsconfig.graph.json', // the workspaces paths + references baseFile: 'config/tsconfig.shared.json', // the shared base (`overrides.base`) } ``` Only `tsconfig.json` is fixed (TypeScript's LSP requirement). `rootFile` and `baseFile` are paths relative to the repo root; `defaultFile` and `buildFile` are file names inside each workspace. The custom names are honoured everywhere the sync task looks: the generator, the overrides, the watched inputs (`dbx watch`) and the files it keeps. Project detection looks for `tsconfig.workspaces.json` / `tsconfig.default.json` by default, but honours `rootFile` / `defaultFile` when they are set in the config. Scaffolding (`dbx project:init*`) always writes the default names. ### `indent` The JSON indentation of every generated file (default `4`). ### `extends` Overrides the `extends` field written into **scaffolded** tsconfig templates (`dbx project:init*`). This is separate from the `tsconfig.workspaces.json` `extends` chain used by the resolver. Set a value to add/replace the field, or `false` to remove it: ```ts tsconfig: { extends: { base: '@tsconfig/node22', // tsconfig.base.json currently has no extends default: './tsconfig.base.json', // keep/customize the normal default chain build: './tsconfig.json', // opt into path aliases during builds }, } ``` Existing projects are user-owned by default: edit their `tsconfig.base.json`, `tsconfig.default.json` and `tsconfig.build.json` directly. `dbx sync` only rewrites the generated `tsconfig.json` unless you opt into `overrides`. ### `overrides` Deep-merges managed options into the **user-owned** tsconfigs during `dbx sync`, so a config can define those files programmatically: ```ts tsconfig: { overrides: { base: { compilerOptions: { target: 'ES2022' } }, root: { compilerOptions: { composite: true, types: ['node'] } }, default: { compilerOptions: { strict: true } }, build: { compilerOptions: { declaration: true } }, }, } ``` | Key | Target | | --------- | ---------------------------------------------------------------- | | `base` | the root base tsconfig (`baseFile`, `tsconfig.base.json`) | | `root` | the workspaces tsconfig (`rootFile`, `tsconfig.workspaces.json`) | | `default` | every workspace's default tsconfig (`defaultFile`) | | `build` | every workspace's build tsconfig (`buildFile`) | Overrides are **deep-merged**: objects merge key by key, while arrays and scalars replace the target value. Keys the override does not mention are left alone. The patched files stay yours: they are not added to the manifest's managed `files`, so a sync never deletes them and `dbx reset` never removes them. #### Snapshots The first time an override touches a file, its original content is saved in `.dbx/toolchain/manifest.json` under a top-level `snapshots` field. The tree mirrors the repository with **relative** paths (the manifest is the tracked file under `.dbx`, so it never holds an absolute path), and the applied override per file is recorded under `tsconfigOverrides`: ```json [.dbx/toolchain/manifest.json] { "files": ["packages/core/tsconfig.json"], "snapshots": { "tsconfig.workspaces.json": { "compilerOptions": { "composite": false } }, "packages": { "core": { "tsconfig.build.json": { "extends": "./tsconfig.default.json" } } } }, "tsconfigOverrides": { "tsconfig.workspaces.json": { "kind": "root", "override": { "compilerOptions": { "composite": true, "types": ["node"] } } } } } ``` #### Removing an override Removing an override (or one of its keys) reverts it on the next sync. For every key the override no longer sets, the sync compares the target file with the snapshot: * the snapshot **defines** the key: the original value is restored (eg. dropping `composite: true` above brings back the original `composite: false`); * the snapshot **does not define** it: the key is removed, along with any parent object the override created that is now empty (eg. `types`); * the key holds **another value** than the override wrote: it was edited after the override applied it, so it is kept and a `tsconfig.override-edited` warning is logged. Once no override targets a file anymore, its snapshot and `tsconfigOverrides` entry are dropped. A file is never deleted, even when nothing else is left in it: other tooling may depend on it. #### Restoring `dbx tsconfig --restore` removes the applied override content right away (with the same snapshot comparison), optionally for one kind only: ```sh dbx tsconfig --restore # every kind dbx tsconfig --restore default # base | root | default | build ``` If the overrides are still configured, the command warns (`tsconfig.restore-reapply`): the next `dbx sync` applies them again, so remove them from `toolchain.tsconfig.overrides` to keep the restored files. `dbx reset` does the same restore before it removes the manifest, so resetting a project never strands override content without its snapshots. #### Notes * A target that does not exist is **not created**: the sync warns (`tsconfig.missing-file`) and skips that file. A target outside the project root warns with `tsconfig.outside-root`. * The user-owned files are read as JSONC but written back as plain JSON, so comments are dropped from a file the first time an override changes it. A file whose content would not change is never rewritten. * `dbx sync --check` reports pending override changes (and reverts) as drift without writing them. ## How generation works For each workspace matched by `glob`, the generator: 1. reads its default tsconfig and, when present, the workspaces tsconfig; 2. writes a sibling `tsconfig.json` that `extends: './'`, layering the workspaces `compilerOptions` (aliases/types) and `references` on top; 3. seeds a missing `tsconfig.build.json` with `extends: './tsconfig.json'`, but leaves an existing build config alone — it is a user-owned input, like the default tsconfig. Because the output only ever `extends` the default and adds the workspaces wiring, your workspace-specific options stay in the default tsconfig (the file the generator reads, not the one it writes). A missing or unparseable local/package config anywhere in the default, workspaces, or build `extends` chain fails the sync with a clear error (for example `Cannot resolve tsconfig "extends": "./tsconfig.base.json"` or `Cannot parse tsconfig ".../tsconfig.base.json": ...`). Remote `http(s)` extends are fetched (see below); `data:` URLs are not supported. ### Remote extends A local config may extend an `http(s)` URL. `dbx sync`, `dbx tsconfig` and `dbx tsconfig --json` prefetch the remote chain first, resolving nested relative `extends` paths against the remote URL. Extends-array precedence and per-field inheritance match local configs. Generated workspace configs keep `extends: './tsconfig.default.json'` by default; the resolver still follows the remote chain for the paths, references and shared compiler options it infers. Set `flattenRemoteExtends: true` (or pass `--flatten-remote-extends`) to inline the `compilerOptions` inherited from the remote chain instead. Path-valued options such as `paths` / `baseUrl` are always skipped because they describe the remote tree, and every setting the generated config already defines wins, so flattening never overrides local defaults, workspaces options or managed overrides. Package specifiers inside a remote config resolve from the local project. Programmatic callers using the synchronous resolver must call `prefetchTsconfigExtends()` first, or use `resolveTsconfigAsync()` / `assertTsconfigChainAsync()`; an unprefetched remote reference fails with a clear error. ## Warnings | Id | When | | -------------------------- | ------------------------------------------------------------------ | | `tsconfig.missing-file` | An override targets a file that does not exist (it is skipped). | | `tsconfig.outside-root` | An override target resolves outside the project root. | | `tsconfig.override-edited` | A reverted key was edited after the override set it (it is kept). | | `tsconfig.restore-reapply` | `--restore` ran while the restored overrides are still configured. | Silence any of them with [`logger.suppress`](/guide/config/logging). When a sync finds **no** workspace tsconfig files, it warns (in the CLI logs and as a VS Code notification) if either: * `refs` or `composite` is enabled, or * a `tsconfig.workspaces.json` is present, because in those cases workspaces are clearly expected. Otherwise it logs a quiet "nothing to do" message. ``` no workspace tsconfig files found (looked for **/tsconfig.default.json), but project references + tsconfig.workspaces.json have nothing to wire. ``` ## The workspaces config `tsconfig.workspaces.json` holds the `paths` and `references` the generator expands. Scaffold it with `project:init:monorepo`, or build it programmatically from a workspace list: ```ts import { buildMonorepoTsconfig, renderMonorepoTsconfig } from '@deltabox/toolchain/tsconfig'; const config = buildMonorepoTsconfig({ scope: '@org', workspaces: [ { alias: 'core', dir: 'packages/core' }, { alias: 'cli', dir: 'packages/cli' }, ], }); // -> { compilerOptions: { composite, paths: { '@org/core': ['./packages/core/src/index.ts'], ... } }, // references: [{ path: './packages/core/tsconfig.json' }, ...] } renderMonorepoTsconfig({ scope: '@org', workspaces: [{ alias: 'core', dir: 'packages/core' }] }); ``` ## CLI ```sh dbx tsconfig # regenerate every workspace tsconfig.json dbx tsconfig --no-aliases # skip the workspaces path aliases dbx tsconfig --refs # wire project references dbx tsconfig --composite # emit composite: true dbx tsconfig -i 2 # JSON indentation dbx tsconfig --glob "packages/*/tsconfig.default.json" "apps/*/tsconfig.default.json" dbx tsconfig --exclude "**/legacy/**" # exclude paths (on top of the defaults) dbx tsconfig --no-gitignore # do not respect .gitignore files dbx tsconfig --default-file tsconfig.src.json dbx tsconfig --build-file tsconfig.dist.json dbx tsconfig --root-file tsconfig.workspaces.json dbx tsconfig --restore [kind] # remove applied overrides (base|root|default|build) ``` Every flag overrides the matching `tsconfig` option; with no flags the command uses the config defaults (including in-memory `overrides`, so the output matches `dbx sync`). `dbx tsconfig --restore [kind]` removes applied overrides instead (see [Restoring](#restoring)). `dbx sync` runs the same generator through the [tsconfig sync task](#sync--ci). ### Resolving a tsconfig The same command can inspect a config instead of generating files. It follows `extends` per field, so a child can define `paths` while inheriting `references` (or the reverse): ```sh dbx tsconfig --json # { alias, paths, references } dbx tsconfig --alias # Vite/Vitest resolve.alias entries dbx tsconfig --paths # resolved compilerOptions.paths dbx tsconfig --references # resolved project references dbx tsconfig --tsconfig tsconfig.build.json dbx tsconfig --root packages/app # root used for detection + relative tsconfig dbx tsconfig --no-extends # only the selected file ``` The output is machine-clean JSON (absolute paths). Aliases are anchored regular expressions by default (`strict`, from exact keys to wildcards), so `@org/core` never captures `@org/core-utils`; they serialize as `{ source, flags }` so JSON keeps the pattern. With `strict: false`, exact keys stay plain strings (wildcards remain regexes). Use `deserializeTsconfigAlias` to turn an alias back into a `RegExp`. Aliases and `paths` keys are sorted descending, so the longest/most specific entry comes first. ### Visual example: resolved aliases Input `tsconfig.json`: ```json { "compilerOptions": { "paths": { "@org/core": ["./packages/core/src/index.ts"], "@org/core-utils": ["./packages/core-utils/src/index.ts"], "@org/core-utils/deep": ["./packages/core-utils-deep/src/index.ts"], "@org/core.lib": ["./packages/core-lib/src/index.ts"], "@org/*": ["./packages/*/src/index.ts"] } } } ``` `dbx tsconfig --json` output (shortened replacements): ```json { "alias": [ { "find": { "source": "^@org\\/core\\.lib$", "flags": "" }, "replacement": ".../core-lib/src/index.ts" }, { "find": { "source": "^@org\\/core-utils\\/deep$", "flags": "" }, "replacement": ".../core-utils-deep/src/index.ts" }, { "find": { "source": "^@org\\/core-utils$", "flags": "" }, "replacement": ".../core-utils/src/index.ts" }, { "find": { "source": "^@org\\/core$", "flags": "" }, "replacement": ".../core/src/index.ts" }, { "find": { "source": "^@org\\/(.*)$", "flags": "" }, "replacement": ".../packages/$1/src/index.ts" } ], "paths": { "@org/core.lib": [".../core-lib/src/index.ts"], "@org/core-utils/deep": [".../core-utils-deep/src/index.ts"], "@org/core-utils": [".../core-utils/src/index.ts"], "@org/core": [".../core/src/index.ts"], "@org/*": [".../packages/*/src/index.ts"] }, "references": [] } ``` Exact keys are escaped (`core.lib` → `core\\.lib`) and anchored, and the prefix-extended keys sort before their shorter prefix. The same order applies to `paths`, so consumers that iterate it see the most specific key first. ## Programmatic API ```ts import { generateTsconfigs, runTsconfigCli, resolveTsconfig, serializeTsconfigAlias, deserializeTsconfigAlias, serializeResolvedTsconfig, readTsconfig, renderTsconfigBase, renderTsconfigDefault, renderTsconfigBuild, renderTsconfigTemplates, buildMonorepoTsconfig, renderMonorepoTsconfig, tsconfigSyncTask, tsconfigFileNames, restoreTsconfigOverrides, } from '@deltabox/toolchain/tsconfig'; ``` | Export | Description | | ---------------------------------------------------------------------- | ----------------------------------------------------------------- | | `generateTsconfigs(options)` | Expand every default tsconfig (dry-run-able). | | `runTsconfigCli(argv?)` | The `dbx tsconfig` entry point. | | `resolveTsconfig(options?)` | Resolve `{ alias, paths, references }` (extends-aware). | | `serializeTsconfigAlias(alias)` / `deserializeTsconfigAlias(alias)` | Convert aliases to/from their JSON-safe `{ source, flags }` form. | | `serializeResolvedTsconfig(resolved)` | Serialize a whole resolved config for JSON transport. | | `readTsconfig(file)` | Read a JSONC tsconfig (comments + trailing commas). | | `renderTsconfigBase` / `renderTsconfigDefault` / `renderTsconfigBuild` | Render a template with replacements. | | `renderTsconfigTemplates(replacements?)` | Render every template keyed by file name. | | `buildMonorepoTsconfig(options)` / `renderMonorepoTsconfig(options)` | The workspaces config (object / JSON text). | | `tsconfigSyncTask()` | The sync task wired into `dbx sync`. | | `tsconfigFileNames(config)` | The configured base/root/default/build file names. | | `restoreTsconfigOverrides(options)` | Remove applied overrides (`{ cwd, kind?, dryRun? }`). | | `applyOverride` / `mergeOverride` / `revertOverride` | The deep-merge + snapshot-aware revert helpers. | | `getSnapshot` / `setSnapshot` / `deleteSnapshot` | Read/write the manifest snapshot tree by relative path. | `resolveTsconfig` accepts `{ tsconfig, cwd, root, relativePaths, strict, extends, overrides }`: `tsconfig` is resolved from `root` (default `cwd`), `extends` defaults to `true`, and `relativePaths` (default `false`) returns paths relative to the config that defines them. `strict` (default `true`) anchors exact aliases as `^...$` regexes; `false` keeps exact aliases as plain strings. `paths` are resolved against the defining config's `baseUrl` (or its directory), matching TypeScript. `generateTsconfigs` returns one result per workspace (with `newTsconfig`, `originalConfig`, ...); pass `write: false` for a dry run. The task-level options are documented in the [Programmatic API](/guide/api/package-reference#deltaboxtoolchaintsconfig) reference. `renderTsconfigBase` / `renderTsconfigDefault` / `renderTsconfigBuild` accept an optional second `extends` argument (`string | string[] | false`), and `renderTsconfigTemplates` accepts `{ base, default, build }` as its second argument. ## Sync & CI At a monorepo root with the section enabled, `dbx sync` runs the tsconfig task and reports the regenerated files: ``` tsconfig: regenerated 6 workspace tsconfig(s). ``` The task watches the workspaces tsconfig and every default tsconfig (custom `rootFile` / `defaultFile` names included), keeps the build tsconfigs, and only applies to `monorepo-root` projects. Run `dbx sync --check` in CI to fail when a generated `tsconfig.json` drifts from its inputs. ### Refresh aliases after builds Auto-wired aliases and references are derived from each workspace's `package.json` (`exports`, then `types`/`main`, then a source scan). If a build step can change a workspace manifest (a generated `package.json`, a rewritten export map, ...), run the tsconfig-only sync once **after all workspace builds**: ```sh dbx sync --only tsconfig ``` This regenerates the workspaces tsconfig and every managed `tsconfig.json` without running the other sync tasks, and it does not prune files owned by those tasks. Add it to the end of your root build script so the aliases always reflect the final `package.json` exports: ```json [package.json] { "scripts": { "build": "yarn workspaces foreach -A run build && dbx sync --only tsconfig" } } ``` The task is skipped when `toolchain.tsconfig` is omitted or `false` — including `dbx tsconfig` and `dbx sync --only tsconfig` — so a disabled section never generates files. A nested workspace that defines its own `tsconfig` section owns its generated file: the root still aliases/references it, but does not rewrite it. ## Per-project configs `toolchain.tsconfig` is repository-scoped: the root sync task expands every workspace `tsconfig.json`, so nested configs **do not inherit** it — inheriting it would make `dbx tsconfig` re-scan a workspace's own subtree. A nested config may still declare its own `tsconfig` section when it manages its own workspace tree (a nested monorepo); otherwise add the workspace's `tsconfig.default.json` and run `dbx tsconfig` / `dbx sync` from the root. Other sections still inherit as usual; see [Configuration → Nested configs](/guide/config/nested-configs) for the rules. ## Scaffolding `dbx project:init:monorepo` writes `tsconfig.base.json` + a `tsconfig.workspaces.json`; `dbx project:init:workspace` writes the workspace's `tsconfig.default.json` / `tsconfig.build.json` / `tsconfig.json` (and a `dbx.config.ts`). See the [Monorepo Guide](/guide/monorepo#tsconfig-generation) for the full flow. --- --- url: https://toolchain.dbx.studio/guide/catalogs.md --- # Package catalogs A **catalog** is a shared `package -> version range` map. Workspaces declare a dependency as `catalog:` and the package manager resolves it from the catalog, so a version lives in one place instead of being repeated (and drifting) across every `package.json`. `toolchain.catalogs` writes that map into the file the package manager reads it from. Like every section it is **opt-in by presence** and root-only: a workspace never inherits it. ## Configuration ```ts [dbx.config.ts] export default defineConfig({ toolchain: { catalogs: { // The default catalog (`catalog:`). packages: { react: '^19.0.0', 'react-dom': '^19.0.0', lodash: '^4.17.21', }, // Named catalogs (`catalogs.`). named: { legacy: { react: '^18.0.0' }, }, }, }, }); ``` | Option | Type | Description | | ---------- | ---------------------------------------- | ---------------------------------------------- | | `packages` | `Record` | The default catalog: package -> version range. | | `named` | `Record>` | Named catalogs: name -> (package -> range). | | `enabled` | `boolean` | Master switch (default: enabled when defined). | A section with neither `packages` nor `named` writes nothing. ### Visual example: config → generated catalog ```ts [dbx.config.ts] toolchain: { catalogs: { packages: { react: '^19.0.0', 'react-dom': '^19.0.0' }, named: { legacy: { react: '^18.0.0' } }, }, } ``` With Yarn this writes `.yarnrc.yml`: ```yaml nodeLinker: node-modules catalog: react: ^19.0.0 react-dom: ^19.0.0 catalogs: legacy: react: ^18.0.0 ``` A workspace then references the default catalog with `"react": "catalog:"` (or `"react": "catalog:legacy"` for a named catalog); the package manager resolves the actual version from this file. ## Supported package managers | Manager | Catalog file | Notes | | ------- | --------------------- | --------------------------------------------------- | | `yarn` | `.yarnrc.yml` | `catalog:` / `catalogs:` (default + named). | | `pnpm` | `pnpm-workspace.yaml` | `catalog:` / `catalogs:`. | | `bun` | `package.json` | `workspaces.catalog`; declare it there. | | `npm` | — | No catalog support; dependencies are pinned inline. | The manager is read from the resolved `project.packageManager` (falling back to the root `package.json`'s `packageManager`, then `yarn`). ## Managed files `dbx sync` writes the catalog file only when it is: * **absent**, or * **already toolchain-managed** — it carries the `# Managed by @deltabox/toolchain (catalogs)` marker. A hand-written catalog file is never clobbered. The file is also marked as `keep`: removing the `catalogs` section (or replacing the file with your own) never deletes it, because the package manager reads it and it may hold hand-written keys. For Yarn the generated file also sets `nodeLinker: node-modules`; for pnpm it declares the `packages/*` globs on a monorepo root. Bun catalogs live in `package.json` `workspaces.catalog` and npm has no catalog support, so both warn instead of writing a separate file. ## Scaffolding `dbx project:init` and `dbx project:init:monorepo` write the catalog for the packages the scaffold depends on **and opt into it in the generated `dbx.config.*`**, so `dbx sync` owns and keeps the file in sync: ```ts [dbx.config.ts] toolchain: { project: { packageManager: 'yarn' }, catalogs: { packages: { '@deltabox/toolchain': '^2.5.0', typescript: '^6.0.3', // ... }, }, } ``` A single Bun project pins its dependencies (there is nowhere to declare a catalog); a Bun monorepo root writes the catalog into `package.json`. ## Keeping it in sync ```sh dbx sync # regenerate the catalog file dbx sync --only catalogs # just the catalog task dbx sync --check # CI: fail on drift ``` ## Programmatic API ```ts import { CATALOG_MARKER, CATALOG_PACKAGE_MANAGERS, catalogFileFor, catalogsSyncTask, hasCatalog, renderPnpmWorkspace, renderYarnrc, scaffoldCatalog, supportsCatalogs, } from '@deltabox/toolchain/project'; ``` | Export | Description | | ---------------------------- | -------------------------------------------------------------------- | | `catalogsSyncTask()` | The sync task that writes the managed catalog file. | | `catalogFileFor(pm)` | The file a manager reads its catalog from (`undefined` for npm/bun). | | `hasCatalog(root, pm, req?)` | Whether a default catalog exists (optionally covering `req`). | | `supportsCatalogs(pm)` | Whether the manager supports catalogs at all. | | `renderYarnrc(catalog)` | Render a `.yarnrc.yml` (node-modules linker + catalog(s)). | | `renderPnpmWorkspace(c)` | Render a `pnpm-workspace.yaml` (optional globs + catalog(s)). | | `scaffoldCatalog(pm, ex?)` | The catalog a scaffold writes (`undefined` when it writes none). | | `CATALOG_MARKER` | The marker line that identifies a toolchain-managed catalog file. | | `CATALOG_PACKAGE_MANAGERS` | The managers with catalog support (`yarn`, `pnpm`, `bun`). | --- --- url: https://toolchain.dbx.studio/guide/templates.md --- # Templates Templates scaffold projects, workspaces, applications, folders, tooling or pipelines. They can be **offline** (builtin, or a local `template.json` directory) or **online** (npm `@scope/create` manifests, git repos, and Vite+ templates). ## Kinds Every template declares a `kind`, used by `template:list --kind` and `create --kind`: | Kind | Produces | | ------------- | -------------------------------------- | | `project` | A single-package project. | | `workspace` | A package inside an existing monorepo. | | `application` | A runnable application package. | | `folder` | A bare folder of files. | | `tooling` | Toolchain config/pipeline files. | | `pipeline` | A CI/pipeline template. | ## List + create ```sh dbx template:list dbx template:list --kind application # filter by kind dbx template:list --online # also resolve npm/git sources dbx template:list --registry # only the .dbx/toolchain sources dbx template:list --json # machine-readable (used by the editor) dbx create --template project --name my-app --out ./my-app dbx create --kind folder --name scratch --out ./scratch dbx create --template mytpl --name myapp --var port=4000 ``` With no `--template`, `create --kind ` picks the first matching template. An unlisted `--template` id is treated as a Vite+ template (`vp create `). On an interactive terminal, a bare `dbx create` (no `--template`/`--kind`/`--name`) prompts for the template, name and scope instead (Ctrl-C cancels). ## Builtin templates See [Template and registry structures](/guide/template-structures) for a rendered directory tree of every builtin template (including the Vite+ provider templates) and for the layout of custom templates, providers and registries. | id | Kind | Description | | ----------------------- | ------------- | ---------------------------------------------- | | `project` | `project` | A single-package TypeScript project. | | `application` | `application` | A runnable application package. | | `folder` | `folder` | A bare folder (a README). | | `monorepo` | `project` | A monorepo root (no example workspace). | | `monorepo-example` | `project` | A monorepo root + one example workspace. | | `workspace` | `workspace` | A workspace package into an existing monorepo. | | `vitepress` | `project` | A VitePress documentation site. | | `express` | `application` | An Express 5 API server. | | `bun` | `application` | A Bun HTTP server (`Bun.serve`). | | `fastify` | `application` | A Fastify 5 API server. | | `orpc` | `application` | A type-safe oRPC API server. | | `file-server` | `application` | A dependency-free local file server. | | `file-server-s3` | `application` | An AWS S3 file server. | | `file-server-bun-s3` | `application` | A Bun S3 file server. | | `file-server-minio` | `application` | A MinIO / S3-compatible file server. | | `file-server-rclone` | `application` | An rclone-backed file server. | | `ollama-chat` | `application` | A local chat UI for Ollama. | | `vite-plus` | `project` | `vp create` (interactive or templated). | | `vite-plus-monorepo` | `project` | `vp create vite:monorepo`. | | `vite-plus-application` | `application` | `vp create vite:application`. | | `vite-plus-library` | `project` | `vp create vite:library`. | | `vite-plus-generator` | `project` | `vp create vite:generator` (monorepo only). | The offline builtins (`project`, `application`, `folder`, `monorepo`, `monorepo-example`, `workspace`) scaffold a generic, current project: a `dbx.config.ts` with `project` metadata, a runnable `src/index.ts` + smoke test, and a `package.json` that depends on the same `@deltabox/toolchain` version as the CLI. There is no Turbo (Vite Task replaces it). They ask for a **package manager** (default `yarn`) and write that manager's catalog file (see [Package catalogs](/guide/catalogs)). The `vite-plus*` builtins delegate to `vp create` and need network access. The root-oriented builtins (`project`, `application`, `monorepo`, `monorepo-example`, and the quality-of-life templates) write the Oxc `fmt` / `lint` defaults into `vite.config.ts` (the Vite+ configuration surface) and opt in with `fmt.oxc` / `lint.oxc`. A nested `project`/`application` scaffold instead detects an ancestor that already owns those settings and inherits them. `folder` and `workspace` never create Oxc config. Existing files are never overwritten unless `dbx create --force` is passed. ## Quality-of-life builtins The quality-of-life templates are fully offline and layer a working app on top of the same project scaffold (package manager, catalogs, `vite.config.ts` with `dbx()`, formatter/linter). They all accept the standard `name`, `scope`, `packageManager` and `includeConfig` inputs and an opt-in install action. Pass `--containerize` (or use the [Docker](/guide/docker) section) to also write a multi-stage `Dockerfile`, `.dockerignore` and `docker-compose.yaml` for local development. | Template | Stack | Notes | | -------------------- | ----------- | ---------------------------------------------------------- | | `vitepress` | VitePress | `docs/` site; `yarn build` writes the static output. | | `express` | Express 5 | `GET /` and `GET /health`; `tsx watch` dev server. | | `bun` | Bun | `Bun.serve`; needs the `bun` binary (any package manager). | | `fastify` | Fastify 5 | `GET /` and `GET /health`; `tsx watch` dev server. | | `orpc` | oRPC + Zod | Typed router served at `/rpc` over Node HTTP. | | `file-server` | Node `http` | Serves `FILE_ROOT` (default `public`), rejects traversal. | | `file-server-s3` | AWS SDK v3 | List/download/upload; `S3_BUCKET` + AWS credentials. | | `file-server-bun-s3` | Bun S3 | Same endpoints through Bun's built-in S3 client. | | `file-server-minio` | AWS SDK v3 | MinIO defaults (`localhost:9000`, `minioadmin`). | | `file-server-rclone` | rclone CLI | Exposes an `RCLONE_REMOTE` over HTTP; needs `rclone`. | | `ollama-chat` | Vite+ app | Streaming chat UI; talks to `http://127.0.0.1:11434`. | The S3/MinIO file servers expose `GET /files` (list), `GET /files/` (download) and `PUT /files/` (upload). The Express, Fastify, Bun and oRPC templates include a small test that exercises the generated handler/config. ## Inputs (variables) A template can declare **inputs** — values prompted for (and substituted) when it is scaffolded. Declare them in `template.json`: ```json [template.json] { "variables": [ { "name": "name", "prompt": "Project name", "default": "app", "required": true }, { "name": "port", "prompt": "Dev port", "default": "4000" }, { "name": "includeDocker", "prompt": "Include a Dockerfile?", "options": ["yes", "no"] } ] } ``` * `name` — the token name (also {{ name }} in files). * `prompt` — the prompt text (defaults to the name). * `default` — the value used when nothing is entered. * `options` — a fixed list of choices: the value is picked from a select. * `required` — whether a value must be provided. Files and directory names may contain {{ token }} placeholders, resolved while copying: ``` src/{{name}}.ts -> src/myapp.ts ``` The **same input pipeline** runs everywhere: * **CLI** — `dbx create` prompts for each input on an interactive terminal (the standard `name`/`scope` first, then the template's own inputs). Pass `--var key=value` (repeatable) to skip a prompt. * **Programmatic API** — `scaffoldTemplate(template, { cwd, tokens, variables })`. * **VS Code** — **Create from template...** prompts for each input (a quick pick when `options` is set). The builtin templates use the same pipeline (they declare `name`, `scope`, `packageManager` and `includeConfig` inputs). ## Actions After the files are written, a template can run **actions** — extra steps such as installing dependencies. Declare them in `template.json`: ```json [template.json] { "actions": [ { "id": "install", "prompt": "Install dependencies?", "builtin": "install" }, { "id": "setup", "prompt": "Run the setup script?", "module": "action.mjs" }, { "id": "post", "command": "node scripts/post-scaffold.mjs" } ] } ``` * `id` — the action id (also the `--action ` key). * `prompt` — the prompt text (defaults to `Run ?`). * `default` — whether it runs by default (**default false** — opt-in). * `builtin` — a built-in action. `install` runs ` install` in the output directory. * `module` — a JS module (relative to the template directory) whose default export is `async (ctx) => void`. The module is **not** copied to the output. The context is `{ cwd, templateDir, tokens, variables, packageManager, log }`. * `command` — a shell command run in the output directory. Actions run through the same pipeline everywhere: the CLI prompts (or takes `--action `, repeatable), the extension prompts, and the programmatic API passes `actions: string[]` to `scaffoldTemplate`. The builtin templates declare an opt-in **Install dependencies?** action (`builtin: 'install'`, off by default). ## Local templates A local template is a directory with a `template.json`. Turn any folder into one with `template:init` (and register it in one step with `--add`): ```sh dbx template:init ./templates/myapp-service \ --kind application --name "Myapp service" --var name --tag service --add ``` ```json [template.json] { "name": "Myapp service", "description": "A service package", "kind": "application", "tags": ["service"], "variables": [{ "name": "name", "default": "service" }], "ignore": ["fixtures"] } ``` Register sources so they are picked up automatically: ```sh dbx template:add ./templates # local dir (auto-inits if needed) dbx template:add @org/create # npm @scope/create dbx template:add git:https://github.com/myapp/tpl.git dbx template:remove local:./templates # drop a source ``` `template:add` records them in `.dbx/toolchain/templates.json`; `template:remove` takes an id or a `type:locate` key. Sources can also be declared in the config: ```ts [dbx.config.ts] export default defineConfig({ toolchain: { templates: { sources: [ { type: 'local', locate: './templates', kind: 'application' }, { type: 'npm', locate: '@org/create', online: true }, ], }, }, }); ``` ## Global templates A template registered with `template:init --add` or `template:add` is **also** stored in the global registry at `~/.dbx/toolchain/.registry/templates`, so it is available in every project (and in the VS Code extension). Pass `--no-global` to keep it project-only: ```sh dbx template:init ./templates/myapp --kind application --name "Myapp" --add # local + global dbx template:add ./templates --no-global # project only ``` Global templates are merged with the project's own; a project template wins on an id clash. The global search paths default to `~/.dbx/toolchain/.registry/templates`, and each path may be a directory or an `http(s)` **remote registry** (a JSON `{ "sources": [...] }` or an array of sources): ```sh dbx template:registry # list the resolved paths dbx template:registry --add ~/shared/templates --add https://myapp.dev/templates.json dbx template:registry --set ~/shared/templates dbx template:registry --remove ~/shared/templates dbx template:registry --clear # reset to the default ``` The paths live in the CLI config `~/.dbx/toolchain/cli/config.json` (`registrySearchPaths`, a string or array) and are kept in sync with the VS Code setting `deltabox.registrySearchPaths`: the extension records the VS Code user dir in that config and mirrors setting changes into it, and the CLI writes the setting back when you change the paths. `vscodeDir` in the CLI config points at the VS Code user directory (the one containing `settings.json`). The project-scoped registries are stored in `.dbx/toolchain/registries.json` and default to `.dbx/toolchain/.registry/templates`. `dbx registry [--json]` lists the detected template/provider registries, and `dbx registry --add --scope global|project` (or `--remove`) manages them. A remote (`http(s)`) registry is a JSON `{ "sources": [...] }` / array of sources. The VS Code **Registries** view (below **Templates**) shows the Providers/Templates roots with **New registry...** / **Remove registry...** actions; remote registries open in the browser. `dbx template:remove --global ` removes a stored global template. ## Online templates Online sources are resolved with `--online` (or `dbx template:add`): * **npm** — a published create package whose `package.json` has a `createConfig.templates` (or `dbx.templates`) manifest. Scoped (`@org/create`) and unscoped (`create-myapp`, `myapp-create`) packages are supported; individual templates are listed and created through `vp create`. The registry defaults to the project package manager's registry (`.yarnrc.yml` `npmRegistryServer`, `.npmrc` `registry`, ...). Override it per source with `--registry`: ```sh dbx template:add @org/create dbx template:add create-myapp dbx template:add create-myapp --registry https://registry.example.com ``` * **git** — a repository (optionally with a `ref` and/or `subdir`) listed as a template and created through `vp create`: ```sh dbx template:add git:https://github.com/myapp/templates --ref v1.2.0 --subdir apps/web ``` * **remote** — an `http(s)` JSON source registry (`{ sources }`, `{ templates }` or an array of sources). Its sources are merged into the registry; each is then loaded by its own type: ```sh dbx template:add remote:https://example.com/dbx-templates.json ``` * **Vite+** — set `create.defaultTemplate` in the `dbx.config.*`'s `vite` section (the full Vite+ config) to make a scope the default for `vp create`. Sources and registries can be restricted with host/path globs (checked for local paths and remote URLs, which also guards SSRF): ```ts [dbx.config.ts] toolchain: { registry: { templates: { allow: ['*.example.com', 'https://registry.example.com/**', '**/templates/**'], deny: ['*.internal.example.com'], }, }, } ``` ## VS Code The extension drives the same CLI: **From template...** runs `template:list --json` then `create`; **Add template...** runs `template:init --add` on a folder you pick and asks whether to add it to the **global** registry (yes by default); **Remove template...** runs `template:list --registry` then `template:remove`. The `deltabox.registrySearchPaths` setting controls the global search paths (see [Global templates](#global-templates)). --- --- url: https://toolchain.dbx.studio/guide/template-structures.md --- # Template and registry structures These trees show the files each builtin template produces and how the Vite+ provider templates, custom templates, providers and registries are laid out. > The package-manager catalog file depends on the chosen manager: `.yarnrc.yml` > for Yarn, `pnpm-workspace.yaml` for pnpm, and `.npmrc`/`package.json` fields > for npm or Bun. The trees below show Yarn. ## Offline project templates ### `project` ```tree - name: myapp description: project children: - name: vite.config.ts description: Vite+ plugin + Oxc defaults - name: package.json - name: src children: - index.ts - name: tests children: - index.test.ts - name: tsconfig.base.json - name: tsconfig.default.json - name: tsconfig.build.json - name: tsconfig.json - name: .gitignore - name: README.md - name: .yarnrc.yml description: catalog ``` ### `application` ```tree - name: myapp description: application children: - name: vite.config.ts description: Vite+ plugin + Oxc defaults - name: package.json - name: index.html highlight: true - name: src children: - name: main.ts highlight: true - name: index.ts - name: tests children: - index.test.ts - name: tsconfig.base.json - name: tsconfig.default.json - name: tsconfig.build.json - name: tsconfig.json - name: .gitignore - name: README.md - name: .yarnrc.yml description: catalog ``` ### `folder` ```tree - name: scratch description: folder children: - name: README.md ``` ### `monorepo` ```tree - name: myapp description: monorepo root children: - name: vite.config.ts description: Vite+ plugin + Oxc defaults - name: package.json description: workspaces + run scripts - name: tsconfig.base.json - name: tsconfig.workspaces.json description: root paths + references - name: tsconfig.json - name: .gitignore - name: README.md - name: .yarnrc.yml description: catalog ``` ### `monorepo-example` ```tree - name: myapp description: monorepo + example workspace children: - name: vite.config.ts - name: package.json - name: tsconfig.base.json - name: tsconfig.workspaces.json - name: tsconfig.json - name: .gitignore - name: README.md - name: .yarnrc.yml - name: packages children: - name: core highlight: true children: - vite.config.ts - package.json - name: src children: - index.ts - name: tests children: - index.test.ts - tsconfig.default.json - tsconfig.build.json - tsconfig.json ``` ### `workspace` `dbx create --template workspace --name core` writes the workspace package into the nearest workspace directory (here `packages/core`). ```tree - name: packages children: - name: core description: workspace package children: - vite.config.ts - package.json - name: src children: - index.ts - name: tests children: - index.test.ts - tsconfig.default.json - tsconfig.build.json - tsconfig.json ``` ## Quality-of-life builtins These templates layer a working app over the `project`/`application` scaffold. Highlighted files are the template-specific ones. ### `vitepress` ```tree - name: myapp description: VitePress docs children: - name: vite.config.ts - name: package.json - name: tsconfig.base.json - name: tsconfig.default.json - name: tsconfig.build.json - name: tsconfig.json - name: .gitignore - name: README.md - name: .yarnrc.yml - name: docs children: - name: index.md highlight: true - name: guide children: - name: getting-started.md highlight: true - name: .vitepress children: - name: config.ts highlight: true - name: tests children: - name: config.test.ts highlight: true ``` ### `express` ```tree - name: myapp description: Express 5 API children: - name: vite.config.ts - name: package.json - name: tsconfig.base.json - name: tsconfig.default.json - name: tsconfig.build.json - name: tsconfig.json - name: .gitignore - name: README.md - name: .yarnrc.yml - name: src children: - name: app.ts highlight: true - name: index.ts highlight: true - name: tests children: - name: app.test.ts highlight: true ``` ### `bun` ```tree - name: myapp description: Bun HTTP server children: - name: vite.config.ts - name: package.json - name: tsconfig.base.json - name: tsconfig.default.json description: node + bun types - name: tsconfig.build.json - name: tsconfig.json - name: .gitignore - name: README.md - name: .yarnrc.yml - name: src children: - name: app.ts highlight: true - name: index.ts highlight: true - name: tests children: - name: app.test.ts highlight: true ``` ### `fastify` ```tree - name: myapp description: Fastify 5 API children: - name: vite.config.ts - name: package.json - name: tsconfig.base.json - name: tsconfig.default.json - name: tsconfig.build.json - name: tsconfig.json - name: .gitignore - name: README.md - name: .yarnrc.yml - name: src children: - name: app.ts highlight: true - name: index.ts highlight: true - name: tests children: - name: app.test.ts highlight: true ``` ### `orpc` ```tree - name: myapp description: oRPC + Zod API children: - name: vite.config.ts - name: package.json - name: tsconfig.base.json - name: tsconfig.default.json - name: tsconfig.build.json - name: tsconfig.json - name: .gitignore - name: README.md - name: .yarnrc.yml - name: src children: - name: planets.ts highlight: true - name: router.ts highlight: true - name: index.ts highlight: true - name: tests children: - name: planets.test.ts highlight: true ``` ### `file-server` ```tree - name: myapp description: dependency-free file server children: - name: vite.config.ts - name: package.json - name: tsconfig.base.json - name: tsconfig.default.json - name: tsconfig.build.json - name: tsconfig.json - name: .gitignore - name: README.md - name: .yarnrc.yml - name: public children: - name: index.html highlight: true - name: src children: - name: server.ts highlight: true - name: index.ts highlight: true - name: tests children: - name: server.test.ts highlight: true ``` ### `file-server-s3` ```tree - name: myapp description: AWS S3 file server children: - name: vite.config.ts - name: package.json - name: .env.example highlight: true description: S3_BUCKET / S3_REGION / credentials - name: tsconfig.base.json - name: tsconfig.default.json - name: tsconfig.build.json - name: tsconfig.json - name: .gitignore - name: README.md - name: .yarnrc.yml - name: src children: - name: server.ts highlight: true - name: index.ts highlight: true - name: tests children: - name: server.test.ts highlight: true ``` ### `file-server-bun-s3` ```tree - name: myapp description: Bun S3 file server children: - name: vite.config.ts - name: package.json - name: .env.example highlight: true - name: tsconfig.base.json - name: tsconfig.default.json description: node + bun types - name: tsconfig.build.json - name: tsconfig.json - name: .gitignore - name: README.md - name: .yarnrc.yml - name: src children: - name: app.ts highlight: true - name: index.ts highlight: true - name: tests children: - name: app.test.ts highlight: true ``` ### `file-server-minio` ```tree - name: myapp description: MinIO / S3-compatible file server children: - name: vite.config.ts - name: package.json - name: .env.example highlight: true description: local MinIO defaults - name: tsconfig.base.json - name: tsconfig.default.json - name: tsconfig.build.json - name: tsconfig.json - name: .gitignore - name: README.md - name: .yarnrc.yml - name: src children: - name: server.ts highlight: true - name: index.ts highlight: true - name: tests children: - name: server.test.ts highlight: true ``` ### `file-server-rclone` ```tree - name: myapp description: rclone-backed file server children: - name: vite.config.ts - name: package.json - name: tsconfig.base.json - name: tsconfig.default.json - name: tsconfig.build.json - name: tsconfig.json - name: .gitignore - name: README.md - name: .yarnrc.yml - name: src children: - name: server.ts highlight: true - name: index.ts highlight: true - name: tests children: - name: server.test.ts highlight: true ``` ### `ollama-chat` ```tree - name: myapp description: Ollama chat UI children: - name: vite.config.ts - name: package.json - name: index.html highlight: true - name: tsconfig.base.json - name: tsconfig.default.json - name: tsconfig.build.json - name: tsconfig.json - name: .gitignore - name: README.md - name: .yarnrc.yml - name: src children: - name: main.ts highlight: true - name: ollama.ts highlight: true - name: style.css highlight: true - name: tests children: - name: ollama.test.ts highlight: true ``` ## Vite+ provider templates These are delegated to `vp create`; the exact files can change between Vite+ versions. The trees below show the current built-in layouts. ### `vite-plus` (interactive) `vite-plus` runs `vp create` with no fixed template id, so the tree is whichever Vite+ template you pick interactively. Use one of the fixed entries below for a stable shape. ### `vite-plus-monorepo` (`vite:monorepo`) ```tree - name: myapp description: Vite+ monorepo children: - name: package.json - name: pnpm-workspace.yaml - name: README.md - name: tsconfig.json - name: vite.config.ts - name: .gitignore - name: .yarnrc.yml - name: packages description: created by the workspace template ``` ### `vite-plus-application` (`vite:application`) ```tree - name: myapp description: Vite+ application children: - name: .gitignore - name: index.html - name: package.json - name: public - name: src children: - name: main.ts - name: style.css - name: tsconfig.json - name: vite.config.ts ``` ### `vite-plus-library` (`vite:library`) ```tree - name: myapp description: Vite+ library children: - name: .gitignore - name: README.md - name: package.json - name: src children: - name: index.ts - name: tsconfig.json - name: vite.config.ts ``` ### `vite-plus-generator` (`vite:generator`) Requires a Vite+ monorepo. The generator is placed in `generators/` or `tools/` when such a parent exists and is registered in the root `create.templates`. ```tree - name: generators children: - name: my-generator description: Vite+ Bingo generator children: - name: package.json - name: README.md - name: tsconfig.json - name: bin children: - name: index.ts description: runTemplateCLI entry - name: src children: - name: template.ts description: createTemplate + Zod options + produce() ``` ## Custom templates A local template is any directory with a `template.json`. Files and directory names may use {{ token }} placeholders; actions can be builtin, a JS module or a shell command. ```tree - name: templates children: - name: myapp-service description: custom template children: - name: template.json highlight: true description: inputs, actions, ignore - name: action.mjs description: optional module action (not copied) - name: README.md - name: src children: - name: "{{name}}.ts" highlight: true description: resolved while copying ``` Register it project-locally or globally: ```tree - name: myapp children: - name: .dbx children: - name: toolchain children: - name: registries.json description: project template/provider paths - name: templates children: - name: myapp-service description: source registered above ``` ## Custom providers A provider registry is a JSON file (or a directory of `*.json` files, or an `http(s)` URL). Project paths are searched before global paths. ```tree - name: myapp description: project children: - name: .dbx children: - name: toolchain children: - name: registries.json - name: .registry children: - name: providers children: - name: providers.json highlight: true description: provider descriptors - name: tools children: - name: echo-provider children: - name: index.mjs description: binary the provider forwards to ``` Typical `providers.json` content: ```json [.dbx/toolchain/.registry/providers/providers.json] [ { "id": "echo", "name": "Echo", "binary": "node", "commands": [ { "name": "echo:version", "subcommand": "--version", "description": "Print the Node version" } ] } ] ``` ## Registries ### Project registry ```tree - name: myapp children: - name: .dbx children: - name: toolchain children: - name: registries.json description: templates + providers arrays - name: .registry children: - name: templates description: implicit local registry - name: providers description: implicit local registry ``` ### Global registry ```tree - name: "~" description: home children: - name: .dbx children: - name: toolchain children: - name: cli children: - name: config.json description: registrySearchPaths + providerRegistrySearchPaths - name: .registry children: - name: templates - name: providers ``` ### Remote registry A remote registry is a JSON document with a `sources` array (or a bare array). Each source is resolved by its own type (`local`, `npm`, `git`, `remote`). ```tree - name: https://example.com children: - name: dbx-templates.json highlight: true description: "{ sources: [...] } or [...]" ``` ### npm organization registry (Vite+) Vite+ also accepts an `@org/create` package whose `package.json` declares `createConfig.templates`: ```tree - name: "@org/create" children: - name: package.json highlight: true description: createConfig.templates - name: README.md - name: templates children: - name: web children: - package.json - src - name: library children: - package.json - src ``` --- --- url: https://toolchain.dbx.studio/guide/vite.md --- # Vite+ There are two ways to use dbx with Vite: * **Plugin mode (recommended):** put the toolchain config inline in the `dbx()` Vite plugin inside `vite.config.*`. No `dbx.config.*` is required, and dbx never manages `vite.config.*` because the plugin lives there. * **Config mode:** keep the whole Vite+ config in `dbx.config.*` under `toolchain.vite`, and let `dbx sync` write a thin `vite.config.ts` shim. Both can be combined: a `dbx.config.*` provides shared config and the plugin options are merged on top. ## Vite+ as the local CLI Install `vite-plus` as a dev dependency and let it provide Vite, Vitest, Oxfmt, Oxlint, Rolldown and tsdown. Do not add those packages separately. On Yarn, add `resolutions` so every dependency resolves the copies Vite+ bundles: ```json [package.json] { "resolutions": { "vite": "npm:@voidzero-dev/vite-plus-core@", "vitest": "" } } ``` Run `vp toolchain vite-plus-core` and `vp toolchain vitest` to get the exact versions. Without the Vitest pin, a dependency or workspace package can pull a different Vitest and split its internals (mocks, `expect`, runner state). Use `vp` in the package scripts (`vp dev`, `vp build`, `vp test`, `vp check`, `vp pack`) so contributors only need the project-local CLI; a global `vp` delegates to the same installed version. ## Plugin mode ```ts [vite.config.ts] import { defineConfig } from 'vite-plus'; // or 'vite' for plain Vite import { dbx } from '@deltabox/toolchain/vite'; export default defineConfig({ plugins: [ dbx({ toolchain: { project: { name: 'my-app', scope: '@org' }, fmt: { oxc: true }, lint: { oxc: true }, ci: { sync: true }, changelog: { preset: 'conventional' }, }, }), ], // your usual Vite config }); ``` The plugin carries the config inline and the dbx CLI (sync, projects, watch and the VS Code extension) reads it back from `vite.config.*`. The plugin also derives the Vite options from the dbx sections: | dbx section | Vite option | | ----------- | -------------------------------------- | | `logger` | `logLevel` / `customLogger` | | `watch` | `server.watch` (the `exclude` globs) | | `fmt` | Vite+ `fmt` (only on a Vite+ project) | | `lint` | Vite+ `lint` (only on a Vite+ project) | The `vite` section is deliberately omitted from the plugin options: the Vite config is the user config in plugin mode. Vite+ keys are only added when the project declares `vite-plus`; a pure Vite project gets only standard Vite options. Vite+ CLI passthroughs (`dbx vite:*`) are refused unless Vite+ is installed/detected. `dbx sync` runs before the dev server/build (or `dbx sync --check` in CI) and re-syncs when `vite.config.*`, `dbx.config.*` or a tsconfig input changes. Builtin scaffolds (`dbx create`, `dbx project:init`, `dbx project:init:workspace`) use plugin mode: they generate a `vite.config.*` with `dbx({ toolchain })`, Vitest (`test`) and Vite+ tasks (`run.tasks`) instead of a `dbx.config.*`. The scaffolded packages depend on `vite-plus` and use `vp` for build/test, so no separate `vitest` or `tsdown` dependency is written. ## Config mode The `vite` section holds the **entire Vite+ configuration**. Every key is passed through verbatim to Vite+, so `dbx.config.*` stays the only hand-authored root config; `dbx sync` writes a thin root `vite.config.ts` that resolves it at load time. ```ts [dbx.config.ts] export default defineConfig({ toolchain: { vite: { fmt: { semi: true, singleQuote: true }, lint: { ignorePatterns: ['dist/**'] }, test: { include: ['src/**/*.test.ts'], environment: 'node' }, run: { tasks: { build: { command: 'vp pack' } } }, }, }, }); ``` The section is typed as Vite+'s own config (`ToolchainViteConfig` = Vite's `UserConfig` as augmented by Vite+), so the whole Vite+ surface autocompletes in `dbx.config.ts`. ## The generated shim `dbx sync` writes a fixed `vite.config.ts`: ```ts [vite.config.ts] // Generated by @deltabox/toolchain. import { defineConfig, type ViteUserConfig } from 'vite-plus'; import { resolveVite } from '@deltabox/toolchain/vite'; export default defineConfig(resolveVite({ cwd: import.meta.dirname })); ``` The shim imports `defineConfig` from whichever Vite package the project installs — `vite` or `vite-plus` (detected from `package.json`, walking up so a hoisted workspace dependency is found). For a plain `vite` project it imports `defineConfig, type UserConfig` from `vite` and calls `resolveVite`, so the same shim type-checks against both. `resolveVite(options?)` resolves the **same-directory** `dbx.config.*` (so a nested workspace `vite.config.ts` uses its own config), or the `toolchain` you pass, then returns `toolchain.vite`. You can also pass inline overrides with `resolveVite({ vite: { ... } })`, which are deep-merged over the loaded section. The file never drifts, because the real config stays in `dbx.config.*`. The root shim must live at the **root**: `vp run`, `vp check` and `vp staged` do not accept `--config`, so the shim has to be the file Vite+ loads. ## Options | Option | Type | Default | Description | | -------- | ------------------- | ------- | ----------------------------------------------- | | `config` | `boolean \| string` | `true` | Write the managed shim; a string sets its path. | Everything else under `vite` is Vite+ config (plugins, `test`, `lint`, `fmt`, `run.tasks`, ...). `vite.fmt` / `vite.lint` override `toolchain.fmt.oxc` / `toolchain.lint.oxc` (deep merge). `fmt: true` / `lint: true` use the shared `DEFAULT_FMT_RULES` / `DEFAULT_LINT_RULES`; an options object is merged over them. Their ignore lists are exported as `DEFAULT_FMT_IGNORE_PATTERNS` / `DEFAULT_LINT_IGNORE_PATTERNS` (both layered over `DEFAULT_IGNORE_PATTERNS`) from `@deltabox/toolchain` and `@deltabox/toolchain/shared`, so you can extend them instead of repeating the defaults. Import sorting is part of those defaults: `sortImports` gets a `workspace` custom group resolved from every dbx project (see `resolveFmtCustomGroups`), so workspace packages do not need manual groups. Set `vite: { config: false }` to leave a hand-written `vite.config.ts` alone (the section is still read for provider colouring and the `dbx` provider passthrough). `config: 'config/vite.custom.ts'` writes the shim there instead (relative to the project, or an absolute path inside it). ## Nested workspaces `vite` is **never inherited**. A workspace with no `vite` section keeps its hand-written `vite.config.*` untouched; `dbx sync` only writes a shim when the project declares `vite` itself. Declare the settings the workspace needs in its own config: ```ts [packages/web/dbx.config.ts] export default defineConfig({ toolchain: { vite: { shim: 'static', resolve: { tsconfigPaths: true }, run: { tasks: { build: { command: 'vp pack' } } }, }, }, }); ``` `vite.fmt` / `vite.lint` are the exception: when the workspace opts into `fmt` / `lint`, they are hoisted into the top-level `fmt.oxc` / `lint.oxc` before inheritance, so shared formatting still flows down. Vite+ recommends one root `fmt` / `lint` block with `overrides` for per-package rules; per-workspace formatter/linter blocks are not applied by `vp check`, so prefer the root `fmt.oxc.overrides` / `lint.oxc.overrides` (see the [Monorepo guide](/guide/monorepo#shared-formatting-and-linting)). ## Keep the shim out of Oxfmt Add the shim to `vite.fmt.ignorePatterns`, otherwise `vp fmt` rewrites the generated file and `dbx sync --check` reports drift: ```ts vite: { fmt: { ignorePatterns: ['/vite.config.ts']; } } ``` In a monorepo, put `**/vite.config.ts` on the **root** top-level `fmt.oxc` config so every workspace shim is covered (an `ignorePatterns` array in a workspace replaces the root's list). `dbx migrate --from vite` adds the ignore for you (see [Migrations](/guide/migrations/#vite-config)). When `fmt` / `lint` are defined, `dbx sync` also writes `.oxfmtrc.json` / `.oxlintrc.json` for the Oxc VS Code extension. They are root-only unless a workspace config defines its own `fmt` / `lint`. ## Commands Vite+ commands are reachable directly or through the `vite` namespace, and are registered as a provider (see [Providers](/guide/providers)): ```sh dbx fmt # the active formatter (vp fmt when Oxc) dbx run -r build # forwards to `vp run -r build` dbx vite dev # explicit namespace (always works) dbx vite:build # named alias for `vp build` ``` A bare `dbx ` is forwarded to Vite+ when the name (or a Vite+ alias) matches — built-in commands win, so `dbx migrate` stays the toolchain's migration. `dbx fmt` / `dbx lint` route to the configured/discovered Biome/Prettier/Dprint/ESLint tool, and keep the `vp` passthrough when the active tool is Oxc (see [Formatting & linting](/guide/formatting#running-the-active-tool)). ## Programmatic API ```ts import { resolveVite, renderViteConfig, viteConfigObject, viteProvider, viteSyncTask, } from '@deltabox/toolchain/vite'; ``` | Export | Description | | ------------------------------ | --------------------------------------------------------------------------------- | | `resolveVite(options?)` | Resolve `toolchain.vite` (or a passed `toolchain`), with inline `vite` overrides. | | `detectViteSpecifier(cwd)` | Which package (`vite` / `vite-plus`) the project has, for the shim import. | | `renderViteConfig(specifier?)` | The managed `vite.config.ts` shim source (defaults to `vite-plus`). | | `viteConfigObject(config?)` | The `vite` section without the toolchain opt-out `config`. | | `viteSyncTask()` | The sync task (writes the shim). | | `viteProvider()` | The Vite+ provider descriptor. | See [Configuration](/guide/config/vite) for the `dbx.config` integration and the [Providers](/guide/providers) guide for the passthrough commands. --- --- url: https://toolchain.dbx.studio/guide/vite-plugin.md --- # Vite plugin `@deltabox/toolchain` ships the `dbx()` Vite/Vite+ plugin. It carries the whole toolchain config inline, so a Vite project does not need a `dbx.config.*`, and it runs `dbx sync` before dev/build (or `dbx sync --check` in CI). > The plugin is published from the **`@deltabox/toolchain/vite`** subpath. The > standalone `vite-plugin-dbx` package is not published yet, so import > `@deltabox/toolchain/vite` (not `vite-plugin-dbx`) until it ships. ## Install ```sh yarn add -D @deltabox/toolchain ``` A Vite+ project also needs `vite-plus` (which provides `vp`, Vite, Vitest, Oxfmt and Oxlint); see [Vite+](/guide/vite). ## Use ```ts // vite.config.ts import { defineConfig } from 'vite-plus'; // or 'vite' import { dbx, DBX_TASKS } from '@deltabox/toolchain/vite'; export default defineConfig({ plugins: [ dbx({ toolchain: { project: { name: 'my-app', scope: '@org' }, fmt: true, lint: true, // ...any other dbx sections }, }), ], run: { tasks: { ...DBX_TASKS } }, }); ``` ## What it does * Loads the inline `toolchain` config (merged over a nearby `dbx.config.*` when one exists). * Runs `dbx sync` before the dev server / build, or `dbx sync --check` when `CI` is set. * Re-syncs when a dbx input file changes in watch mode. * Derives Vite options from the dbx sections: `logger` → `logLevel` / `customLogger`, `watch` → `server.watch`, and `fmt` / `lint` → the Vite+ formatter/linter (only when `vite-plus` is installed). * Exposes `DBX_TASKS` (`dbx:sync`, `dbx:check`) for `run.tasks` / `vp run`. In a **workspace**, leave `fmt` and `lint` out of the plugin config: the root `vite.config.*` owns them and Vite+ applies the root options to the workspace. `fmt: true` / `lint: true` there would select the shared defaults instead. See [Vite+](/guide/vite) for the full Vite+ integration, the Vite+ provider and the `toolchain.vite` options, and the [configuration reference](/config/reference) for every section. --- --- url: https://toolchain.dbx.studio/guide/vscode.md --- # VS Code extension This VS Code extension provides a sidebar for managing projects. ## Install Download from the [Visual Studio Code Marketplace](https://marketplace.visualstudio.com/items?itemName=deltabox.toolchain-vscode). or through the CLI: ```sh code --install-extension deltabox.toolchain-vscode ``` ## Commands | Command | What it does | | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Sync all / active / selected | Run `dbx sync --recursive`, which walks every managed project in dependency order (nested workspaces included). Configless projects are skipped unless `deltabox.toolchain.manageConfigless` is enabled. | | Check sync | `sync --check` across the workspace. | | Sync tsconfig | Run `dbx sync --only tsconfig` (refresh aliases/references after builds). | | Format project | Run `dbx fmt` with the formatter detected/configured for the project (Oxfmt/Vite+, Prettier, Biome, dprint or standalone Oxc). | | Lint project | Run `dbx lint` with the linter detected/configured for the project (Oxlint/Vite+, ESLint or Biome). | | Manage tsconfig... | Auto-wire the root workspaces tsconfig paths/references (`dbx tsconfig`). | | Scaffold project | Single project, monorepo root (with/without example), workspace, or **From template...**. | | Generate configs / Generate config | Run `project:config` for missing configs (or for one project), or refresh only the project graph; picks TS/JS. | | Migrate tooling... | Migrate Biome/Prettier/Dprint/ESLint/Oxc/vite config to the toolchain (`dbx migrate`). | | Run workflow | Trigger generated workflows with their vendor CLI (`gh`/`glab`/`az`). | | Run Vite+ command... | QuickPick over the Vite+ provider commands, run in a terminal. | | Create Vite+ project... | `vp create` in a terminal. | | Install MCP server + skill... | `dbx mcp:install` with a provider picker (Claude, Codex, VS Code, OpenCode, Pi or a custom directory). | | Install official skill... | `dbx skills --official` with a provider picker; adds the official dbx docs skill only when missing. | | List MCP installations | `dbx mcp:list` — show where the MCP server + skill are installed. | | Generate changelog | Run `dbx changelog` in the selected project. | | Clean build artifacts | Remove `dist/` and `*.tsbuildinfo` (`dbx cleanup`). | | Add provider... / Refresh providers | Register a custom provider (project or global registry) and reload the provider list. | | Run command... | Run a provider command (`dbx `) in a terminal (provider tree context menu). | | Add template... / Remove template... | `template:init --add` / `template:list --registry` + `template:remove`. | | Add template... / Remove template source... | Registry actions: add a template source or drop one while keeping the files; **Refresh templates** reloads the list. | | Create from template... | `dbx create --template ` (terminal for online templates; `--online` is added automatically for online sources). | | New registry... / Remove registry... / Refresh registries | Manage the provider/template registry search paths and reload the **Registries** view. | | Choose dbx source... / Select dbx version... | Pick the project's `dbx` or the bundled CLI, and pin the toolchain version. | | Refresh projects / Refresh files | Rediscover the project graph / reload the **Managed Files** view. | | Show all actions | Open the searchable action palette (see [Actions](#actions)). | | Reset tooling | Remove generated files / manifest / config. | | Toggle auto-sync | Enable/disable sync-on-change. | Interactive commands (the dev server, `vp create`, online scaffolding) run in an integrated terminal at the project root; everything else runs in the output channel. **Format project** and **Lint project** are generic toolchain commands, not Vite+ commands: they run `dbx fmt` / `dbx lint`, which route to the detected/configured formatter and linter. A project using Prettier, ESLint, Biome, dprint or standalone Oxc gets the same actions as a Vite+ project (the `vp` passthrough is only used when Oxc is backed by `vite-plus`). Tree context menus also expose scoped commands that are hidden from the Command Palette: **Sync this project**, **Go to project**, **Run the project's Vite+ command**, **Remove provider**, **Copy provider id**, **Create from template**, **Show template info**, **Copy template id**, and the registry item actions (**Open registry**, **Add new registry**, **Remove registry**). ## Project menu Every project card (and every project in the **Projects** tree) exposes the same actions, scoped to that project: * **Sync** / **Check sync** — regenerate / verify the project's managed files. * **Generate config** — write a `dbx.config.*` (TS/JS), or refresh only the project graph. * **Run workflow...** — trigger one of the project's generated workflows. The picker lists every enabled workflow with its provider and path, and dispatches it through the matching vendor CLI (`gh`, `glab` or `az`). * **Run Vite+ command...** — run a `vp` command in that project. * **Reset tooling...** — remove the generated files + manifest, or everything including the config. * **Go to project** — reveal the project in the Explorer. ## File Explorer decorations and project reveal Every file recorded in a project's `.dbx/toolchain/manifest.json` gets a `dbx` badge and the contributed blue label color in the File Explorer. The decoration refreshes after a sync (and from **Refresh files**), and can be turned off with `deltabox.toolchain.decorateManagedFiles`. VS Code has no contribution point that overrides a single file's icon inside the active file icon theme, so the badge plus label color is the supported marker; changing the icon itself would require switching the whole workbench icon theme. Switching the active editor selects the deepest project that owns the file in the **Projects** view and expands its workspace group. Files outside every project are ignored, the reveal never takes focus, and the listener is disposed with the extension. ## Providers, templates and Vite+ in the editor The **Providers** and **Templates** views read `dbx providers --json` and `dbx template:list --json`, so adding one surfaces it in the UI automatically. ### Plugin mode A project configured through the `dbx()` Vite plugin (rather than a `dbx.config.*`) is detected automatically: the Projects view shows it as `plugin`, sync stays enabled, and auto-sync watches `vite.config.*`. The extension never manages `vite.config.*` in plugin mode — the CLI's `vite` sync task skips it, and config generation skips projects that already have the plugin. Vite+ commands are only enabled when Vite+ is detected for the project. When it is not, the provider and its commands are greyed out (`available: false` in `dbx providers --json`) and the extension refuses to run them, while plain Vite projects keep working normally. ### Add provider... Writes a custom provider to the default project registry (`.dbx/toolchain/.registry/providers/providers.json`) or the global `~/.dbx/toolchain/.registry/providers/` when you choose the global scope, which `toolchainProviders()` merges with the built-ins, so a registered provider's commands also become `dbx` commands (`dbx `), runnable from the view. Provider search paths can also be added with the **Registries** view; the `deltabox.providerRegistrySearchPaths` setting mirrors them globally. ### Add template... Runs `template:init --add` and asks whether to add the template to the **global** registry (yes by default), so it is available in every project. See [Global templates](/guide/templates#global-templates). The `deltabox.registrySearchPaths` setting controls the global search paths and is kept in sync with the CLI config. ### Remove template source... Runs `template:list --registry` + `template:remove`. The **Registries** view (below **Templates**) shows the detected provider and template registries as **Providers** / **Templates** roots. Each item has **Open registry** (the folder in the explorer, or the website for remote URLs), **Add new registry** and **Remove registry** (it only drops the path, keeping the files). The title bar's **New registry...** / **Remove registry...** actions add or remove search paths for either kind, asking whether they are global or project-scoped. Remote registries are `http(s)` JSON registries: template registries accept `{ sources }` or an array of sources; provider registries accept `{ providers }` or an array of provider descriptors. ### Create from template... Prompts for the template's inputs and actions (see [Templates](/guide/templates)) before running `dbx create`. Scaffolding also asks for a package manager (`yarn` default). The Home view links to this documentation with **Need help? Go to documentation**. ## Actions The **Actions** view (below **Projects**) lists every dbx action grouped by area (Changelog, CI, Cleanup, MCP, Migrate, Pack, Project, Providers, Registries, Sync, Templates, Tools). Groups are collapsed by default and sorted ascending; expanding one shows its actions sorted by name. Selecting an action runs its VS Code command directly. The Home view's **More actions...** button opens the same list as a searchable, paged QuickPick. Navigation entries (`Go back`, `Next page (n/m)`) are rendered before the real choices, and every prompt-based dbx flow (scaffolding, template pickers, ...) uses the same paging factory. Actions only delegate to their own VS Code command; the palette itself never shells out. ## Auto-sync The Home view shows the current state as a clickable **Auto-sync enabled** / **Auto-sync paused** button (the same secondary style as the other quick actions). Opening it lists the global and workspace scopes independently, so a global value and a workspace value can disagree: * **Enable/Disable (global)** writes `deltabox.toolchain.enabled` at the global VS Code scope and mirrors the value into the CLI global store (`~/.dbx/toolchain/cli/config.json`, via `dbx enable/disable --global`). * **Enable/Disable (workspace)** writes `.vscode/settings.json` through the workspace configuration target (via `dbx enable/disable --workspace`). A project's `toolchain.enabled` config takes precedence over both settings. The extension resolves it through the project's CLI (`dbx enabled --json`), so a disabled config keeps auto-sync off even when the VS Code setting is on. Auto-sync watches input files only. The extension asks the CLI (`dbx watch --list --json`) for the concrete, project-graph-resolved files: every `dbx.config.*` plus each enabled project's `tsconfig.baseFile`, `tsconfig.defaultFile` and the root `tsconfig.rootFile`. Custom file names are honoured, nested configs can disable or override their own tsconfig section, and the list is refreshed whenever a `dbx.config.*` changes (and after each sync). Each resolved pattern is scoped to its own workspace root (and a concrete nested file is watched from its own directory), so a same-named file in another workspace folder or an ancestor can never trigger this root's sync, and VS Code does not install a recursive watcher over the whole root (which can hold `node_modules` handles during a package-manager link step on Windows). Only the root whose input changed is synced. Setting `deltabox.toolchain.watch` explicitly replaces the resolved inputs; user globs are matched across every workspace folder, absolute/ancestor globs are ignored, and an empty list disables watching. Generated outputs are never watched. The scheduler debounces bursts, allows one sync at a time, queues at most one follow-up, and suppresses events briefly after a run. When a sync finds no workspace tsconfig files while `tsconfig.refs`/`tsconfig.composite` are on (or a `tsconfig.workspaces.json` is present), the extension surfaces the CLI's warning as a notification (once per session) with a **Show output** action. When removing a section stops managing a file that dbx created, the sync notification lists the removed relative paths and offers **Restore** (write the previous content back) or **Close**. A file that existed before dbx first managed it is **adopted**: it is unmanaged but never deleted. The **Managed Files** view also shows a **Workflow conflicts** group for hand-written workflows dbx left untouched (the manifest's `workflowConflicts`). Each item names the config key to opt out with, and opens the existing file. ## Settings | Setting | Default | Description | | ---------------------------------------------------- | --------------- | ---------------------------------------------------------------------------------------------------------- | | `deltabox.toolchain.enabled` | `true` | Auto sync on watched changes. A project's `toolchain.enabled` config takes precedence. | | `deltabox.toolchain.debounce` | `300` | Debounce (ms) before a sync. | | `deltabox.toolchain.command` | `sync` | The command to run on change. | | `deltabox.toolchain.manageConfigless` | `false` | Manage projects without their own `dbx.config.*` (passes `--configless` to sync/watch). | | `deltabox.toolchain.containerizeTemplates` | `false` | Generate Docker artifacts when scaffolding a new project (also prompted per create). | | `deltabox.toolchain.formatManagedFiles` | `true` | Format the managed files written by `dbx sync` (adds `--no-format` when disabled). | | `deltabox.toolchain.formatManagedFilesFix` | `true` | Rewrite managed files when formatting instead of check mode (adds `--no-format-fix` when disabled). | | `deltabox.toolchain.formatManagedFilesCommand` | `""` | Override the managed-file formatter command (`{files}` expands to the files). Empty = auto-detect. | | `deltabox.toolchain.formatManagedFilesExclude` | `[]` | Managed files to leave unformatted (globs; passed to `dbx sync --format-exclude`). | | `deltabox.toolchain.enableFormatImportGroupDefaults` | `true` | Add the resolved workspace `sortImports` custom group when syncing; set `false` to manage groups yourself. | | `deltabox.toolchain.decorateManagedFiles` | `true` | Show a `dbx` badge and blue label color on files recorded in the project manifests. | | `deltabox.toolchain.watch` | `[]` (resolved) | Inputs that trigger a sync (empty = resolved from the config). | | `deltabox.toolchain.version` | `""` (auto) | Pin the `@deltabox/toolchain` version this workspace runs. | | `deltabox.registrySearchPaths` | `[]` | Template registry search paths (dirs or `http(s)` URLs). | | `deltabox.providerRegistrySearchPaths` | `[]` | Provider registry search paths (JSON files/dirs/URLs). | `deltabox.toolchain.enableFormatImportGroupDefaults` (default `true`) adds the resolved `workspace` group to Oxfmt's `sortImports.customGroups` when the extension syncs or generates configs. Set it to `false` in user or workspace settings to keep full control of the import groups. The extension passes the effective value to the CLI; direct CLI runs and Vite+ configs also honour the workspace-scoped `.vscode/settings.json` value. When a workspace has its own `@deltabox/toolchain` whose version differs from the extension's bundled CLI, the extension asks which to run and shows both detected versions. **Select dbx version...** pins a version in the project's `.vscode/settings.json` (like TypeScript's version picker); it runs that version via `npx` unless the project already installs it. Project lookup follows the repository boundary: from the open folder (and every workspace root in a multi-root workspace) the extension walks up to the nearest `.git`, so a toolchain hoisted to the monorepo root is found even when a nested workspace package is opened as the folder. The project's own `dbx` stays the default; the bundled CLI is only the fallback. ## Command palette Search for `deltabox:` to find: * **Sync active project** / **Sync selected projects** / **Sync all projects** * **Check sync** * **Sync tsconfig** * **Manage tsconfig...** * **Scaffold project...** * **Generate configs...** / **Generate config...** * **Migrate tooling...** * **Run workflow...** * **Run Vite+ command...** * **Create Vite+ project...** * **Install MCP server + skill...** * **Install official skill...** * **List MCP installations** * **Generate changelog** * **Clean build artifacts** * **Add provider...** / **Refresh providers** * **Add template...** / **Remove template...** * **Add template...** / **Remove template source...** / **Refresh templates** * **New registry...** / **Remove registry...** / **Refresh registries** * **Choose dbx source...** / **Select dbx version...** * **Refresh projects** / **Refresh files** * **Show all actions** * **Reset tooling...** * **Toggle auto-sync** The project and tree context menus add scoped commands that are intentionally hidden from the palette (sync this project, go to project, run the project's Vite+ command, remove/copy a provider, template info/copy id, and the registry item actions). --- --- url: https://toolchain.dbx.studio/guide/providers.md --- # Providers A **provider** is an external toolchain exposed through `dbx`: its CLI, the programmatic API and the VS Code extension. Providers contribute namespaced commands and a descriptor the editor reads over `dbx providers --json`. ## List providers ```sh dbx providers # table dbx providers --json # descriptor (id, binary, commands, actions) ``` ## Vite+ (`vite-plus`) The bundled provider wraps the `vp` binary — the unified Vite / Vitest / Oxlint / Oxfmt / Rolldown / tsdown toolchain. ### Resolution `dbx vite:*` resolves `vp` in this order: 1. the project-local shim (`node_modules/.bin/vp`), 2. a global `vp` on `PATH`, 3. `npx --yes vite-plus`. ### Generic passthrough ```sh dbx vite dev dbx vite build dbx vite add zod dbx vite check ``` Everything after `vite` is forwarded verbatim to `vp`, so all Vite+ commands and flags are reachable. A bare `dbx ` whose name is a Vite+ command (or a Vite+ alias) is forwarded too, so `dbx fmt` / `dbx run -r build` need no `vite` namespace — built-in commands win (`dbx migrate` stays the toolchain's). ### Colour Provider output keeps `vp`'s own colours, but follows the logger's colour state. The global `--no-color` flag turns provider colour off, and the `providers` section can opt out on its own even on a colour terminal: ```ts [dbx.config.ts] export default defineConfig({ toolchain: { providers: { color: false }, }, }); ``` When colour is off, `dbx` runs `vp` with `NO_COLOR=1` and `FORCE_COLOR=0` so the wrapped process emits plain output. Leave the section unset to let `vp` detect colour from its own terminal. ### Named commands Every catalogued subcommand is also available as a first-class command for discovery + the editor: ``` vite:create vite:migrate vite:dev vite:check vite:lint vite:fmt vite:test vite:build vite:pack vite:run vite:add vite:remove vite:update ... vite:toolchain vite:upgrade vite:implode ``` ### Programmatic ```ts import { resolveVp, runVp, hasVp, vpVersion, describeVp, resolveVpCommand, viteCommandName, VP_COMMANDS, } from '@deltabox/toolchain/vite'; if (hasVp(process.cwd())) { await runVp(['check'], { cwd: process.cwd() }); } ``` | Export | Description | | -------------------------------------- | --------------------------------------------------------------------------- | | `resolveVp(cwd?)` | Resolve the `vp` invocation (`{ exe, args, source }`). | | `hasVp(cwd?)` | Whether a local/global `vp` is available (no `npx` fallback). | | `runVp(args, options?)` | Run `vp`, streaming output or `mode: 'capture'`; never exits the host. | | `vpVersion(cwd?)` / `describeVp(cwd?)` | The `vp --version` output / a one-line resolution description. | | `which(bin)` | Find an executable on `PATH` (resolves `PATHEXT` on Windows). | | `resolveVpCommand(name)` | Resolve a subcommand **or alias** to its canonical name (`i` -> `install`). | | `viteCommandName(name)` | The `dbx` command name for a `vp` subcommand (`dev` -> `vite:dev`). | | `VP_COMMANDS` | The `vp` command catalog that drives the CLI + the provider descriptor. | ```ts // A bare `dbx ` falls through to `vite` when it names a Vite+ command. resolveVpCommand('fmt'); // 'fmt' viteCommandName('fmt'); // 'vite:fmt' ``` ### Use dbx from Vite+ Vite+ consumers can drive dbx from `vite.config.ts`, so a Vite+-only project still gets dbx's generated/managed files: ```ts [vite.config.ts] import { defineConfig } from 'vite-plus'; import { dbx, DBX_TASKS } from '@deltabox/toolchain/vite'; export default defineConfig({ plugins: [dbx()], run: { tasks: { ...DBX_TASKS } }, // your usual Vite / Vite+ config }); ``` * The `dbx()` plugin runs `dbx sync` before the dev server / build, or `dbx sync --check` in CI (which fails the build when generated files are out of date), and re-syncs when a `dbx.config.*` / `tsconfig.*.json` input changes. * The plugin resolves the `dbx` binary from the project first: the local `node_modules/.bin/dbx`, then the project's own `@deltabox/toolchain` bin. A global `dbx` on `PATH` is used **only when the project doesn't pin the toolchain at all** — otherwise it's skipped (with a warning) in favour of `npx @deltabox/toolchain@`. That way a stale global install can never run and silently revert the project's generated files. * `run: { tasks: { ...DBX_TASKS } }` also exposes `vp run dbx:sync` / `vp run dbx:check`. Vite+ reads `run.tasks` from the **static** config (a plugin's `config` hook is ignored), so the tasks are spread in the config rather than added by the plugin. Drop the `run` block if you don't want them. * Because Vite Task runs a task's `command` through a shell, `DBX_TASKS` bakes in the binary resolved by `resolveDbx` (the project's own, or the pinned `npx` fallback) rather than relying on `dbx` being on `PATH` — a missing environment then warns instead of silently running the wrong binary. Use `dbxTaskCommand(sub)` to build a task command for another subcommand. ## Other language toolchains Providers are not JavaScript-only. A provider is just a descriptor around a CLI binary, so the same mechanism can expose the tools a polyglot repository already uses: | Language | Binary | Example commands | | --------- | -------------------------- | ------------------------------------- | | Python | `uv` (or `ruff`, `pytest`) | `dbx python:run`, `dbx python:sync` | | C# / .NET | `dotnet` | `dbx dotnet:build`, `dbx dotnet:test` | | Java | `mvn` / `gradle` | `dbx maven:test`, `dbx gradle:build` | | Rust | `cargo` | `dbx rust:build`, `dbx rust:clippy` | | Go | `go` | `dbx go:test`, `dbx go:vet` | Each provider maps command names to a `binary` + `subcommand`; remaining operands are forwarded verbatim. Register one provider per binary, or use a runner such as `uv` or `cargo` to cover several tasks. Once registered, the commands appear in `dbx providers`, the CLI help and the VS Code Providers view, so a polyglot repo has one command surface even when the languages do not. ```json [.dbx/toolchain/.registry/providers/rust.json] [ { "id": "rust", "name": "Rust (cargo)", "binary": "cargo", "commands": [ { "name": "rust:build", "subcommand": "build", "description": "Build the Rust workspace." }, { "name": "rust:test", "subcommand": "test", "description": "Run Rust tests." }, { "name": "rust:clippy", "subcommand": "clippy", "description": "Lint with Clippy." }, { "name": "rust:fmt", "subcommand": "fmt", "description": "Format Rust sources." } ] } ] ``` ## Custom providers Providers are loaded from **search paths** (JSON files, directories of `*.json`, or `http(s)` registry URLs). A JSON file can be an array of provider descriptors or `{ "providers": [...] }`. Project paths (first wins on an id clash): * `.dbx/toolchain/.registry/providers` — the implicit default directory; * `.dbx/toolchain/registries.json` — its `providers` array; * `.dbx/toolchain/providers.json` — the legacy file, still read. Global paths: * `~/.dbx/toolchain/.registry/providers` — the default directory; * `~/.dbx/toolchain/cli/config.json` — `providerRegistrySearchPaths`, or `registrySearchPaths.providers`; * the VS Code `deltabox.providerRegistrySearchPaths` setting (kept in sync). `toolchainProviders()` merges every local registry with the built-ins (a project provider wins on an id clash), so a custom provider's commands become `dbx` commands — `dbx ` forwards to ` ...` — and it shows up in `dbx providers` and the editor. Remote registries are fetched by `dbx providers --json`/`loadToolchainProviders()`. Restrict them with `toolchain.registry.providers` (`allow`/`deny` host + path globs); the same policy applies to local registry paths: ```json [.dbx/toolchain/.registry/providers/providers.json] [ { "id": "echo", "name": "Echo", "binary": "node", "commands": [ { "name": "echo:version", "subcommand": "--version", "description": "Print the Node version" } ] } ] ``` ```sh dbx registry --json # list template + provider paths dbx registry --kind providers --scope project --add ./providers dbx registry --kind providers --scope global --add https://example.com/providers.json ``` The VS Code **Providers** view manages the registry items (**Add provider...** / **Remove provider**), and the **Registries** view shows the provider search paths. See [VS Code Extension](/guide/vscode). For a rendered directory tree of a typical custom provider, template and registry, see [Template and registry structures](/guide/template-structures#custom-providers). ## Providers in the editor The VS Code extension reads `providers --json` and builds its **Providers** view and menus from it, so adding a provider surfaces it automatically. See [VS Code Extension](/guide/vscode). --- --- url: https://toolchain.dbx.studio/guide/formatting.md --- # Formatting & linting `toolchain.fmt` and `toolchain.lint` select a formatter/linter, hold its options, and optionally add project-scoped VS Code defaults: ```ts [dbx.config.ts] export default defineConfig({ toolchain: { fmt: { vscode: true, // add missing VS Code formatter settings (default false) oxc: { printWidth: 100, singleQuote: true }, biome: { formatter: { indentWidth: 4 } }, }, lint: { vscode: true, oxc: { rules: { eqeqeq: 'warn' } }, eslint: { rules: {} }, }, }, }); ``` The supported tools are: * `fmt`: `oxc` (Oxfmt), `biome`, `prettier`, `dprint`. * `lint`: `oxc` (Oxlint), `biome`, `eslint`. Each tool accepts `true` (use the defaults) or `false` (disable that tool), in addition to its options object. The Oxfmt/Oxlint option types are generated from the tools' official JSON schemas (vendored in the package), so editor completion and the generated config reference match the tool. The shared ignore lists are exported from `@deltabox/toolchain` and `@deltabox/toolchain/shared`: `DEFAULT_IGNORE_PATTERNS` (build/cache dirs), and `DEFAULT_FMT_IGNORE_PATTERNS` / `DEFAULT_LINT_IGNORE_PATTERNS` (the Oxc defaults, layered over `DEFAULT_IGNORE_PATTERNS`). Import them to extend the defaults rather than re-listing them. Oxfmt import sorting is enabled in the defaults as well. `sortImports` includes a `workspace` group built from every `dbx.config.*` project's scope/name; `resolveFmtCustomGroups()` returns that group so you can reuse it in a custom `sortImports` config. Set `sortImports: false` to opt out. ## Shorthand opt-in `fmt: true` / `lint: true` (or an options object with only `vscode`) picks a tool automatically. `dbx sync` resolves it in this order: 1. the project's `.vscode/settings.json`; 2. the nearest `package.json` or tooling config file, walking up to the repo root (a workspace-specific tool beats a root-installed one); 3. the VS Code user settings language blocks; 4. the Oxc defaults. Each level prefers a tool's own config file (`.oxfmtrc.json`, `biome.json`, `.prettierrc`, `dprint.json`, `.eslintrc.*`, ...) before its `package.json` dependency, and honours the formatter/linter precedence. If nothing is found, sync warns (`fmt.no-tool` / `lint.no-tool`) and still applies the Oxc defaults. Existing user-owned config files are not overwritten blindly: the detected tool's options are read into the matching `toolchain.fmt.*` / `toolchain.lint.*` entry. Oxc options are merged over the toolchain defaults using the same mapping as [`dbx migrate`](/guide/migrations/). ## Running the active tool `dbx fmt` / `dbx lint` run the tool the config (or discovery) selects, even when `toolchain.fmt` / `toolchain.lint` is omitted: * an explicit `toolchain.fmt.*` / `toolchain.lint.*` tool wins, in precedence order; * otherwise the same discovery `dbx sync` uses picks a tool from the project `.vscode/settings.json`, the nearest config file/`package.json`, or the VS Code user settings; * with nothing configured or installed, they fall back to `vp fmt` / `vp lint` (Oxfmt / Oxlint). Mode flags are translated per tool (`--check`/`--write` for formatters, `--fix` for linters) and other operands are forwarded. Oxc keeps the full Vite+ passthrough, so `dbx vite fmt ...` still accepts every `vp` flag. ## Formatting managed files Managed-file formatting is **opt-in**. Enable `sync.format` to format the files `dbx sync` writes with the project's active formatter, in fix mode. This keeps generated files (workflows, tsconfigs, editor settings, configs, ...) consistent with the rest of the repository instead of leaving them in the generator's raw output. ```ts [dbx.config.ts] toolchain: { sync: { format: { enabled: true, fix: true, // default; false runs the formatter in check mode command: 'prettier --write {files}', // optional override exclude: ['**/generated/**'], // per-file opt-out }, }, } ``` `sync.format: true` uses the defaults (enabled + fix). It is disabled when the section/key is absent; `sync.format: false` disables it explicitly. The default command follows the detected/configured formatter: | Tool | Fix mode | Check mode (`fix: false`) | | ---------------- | ------------------------------ | -------------------------- | | Vite+ Oxfmt | `vp fmt ` | `vp fmt --check ` | | standalone Oxfmt | `oxfmt ` | `oxfmt --check ` | | Prettier | `prettier --write ` | `prettier --check ` | | Biome | `biome format --write ` | `biome format ` | | dprint | `dprint fmt ` | `dprint check ` | A custom `command` is split like a shell command line (quotes are honoured). The `{files}` token expands to the managed files; when it is absent, the files are appended. If no formatter can be detected, the step is skipped. The same switch is available on the command line and in VS Code: ```sh dbx sync --no-format # disable for this run dbx sync --no-format-fix # run the formatter in check mode dbx sync --format-command "prettier --write {files}" dbx sync --format-exclude "**/generated/**" ``` VS Code exposes them as `deltabox.toolchain.formatManagedFiles`, `formatManagedFilesFix`, `formatManagedFilesCommand` and `formatManagedFilesExclude`. `dbx sync --check` temporarily writes + formats the files to compare the same content a real sync would produce, then restores the originals; a successful check therefore reflects the formatted output too. ## Precedence When more than one formatter/linter is configured, editor defaults use: * **formatters**: `oxc` > `biome` > `prettier` > `dprint`. * **linters**: `oxc` > `biome` > `eslint`. `dbx sync` warns (`fmt.conflict` / `lint.conflict`) when this happens; silence it with [`logger.suppress`](/guide/config/logging). `toolchain.vite.fmt` / `toolchain.vite.lint` are the Oxc config written by Vite+, and **override** `fmt.oxc` / `lint.oxc` with a deep merge (scalars, arrays and booleans in `vite.*` win). With both: ```ts toolchain: { fmt: { oxc: { semi: false, singleQuote: true } }, vite: { fmt: { singleQuote: false } }, } // effective Oxfmt options: { semi: false, singleQuote: false } ``` ## Generated config files * `fmt.oxc` / `lint.oxc` (+ `vite.fmt` / `vite.lint`) write managed `.oxfmtrc.json` / `.oxlintrc.json`. * `fmt.biome` / `lint.biome` merge into the managed `biome.json`. * The deprecated top-level `biome` section still works; prefer `fmt.biome` / `lint.biome`. Oxc files are root-only unless a nested `dbx.config.*` defines `fmt.oxc` / `lint.oxc` / `vite.fmt` / `vite.lint` itself. Biome keeps its existing per-project behaviour. When more than one formatter or linter is configured, sync warns (`fmt.conflict` / `lint.conflict`) because the generated config files and editor defaults may conflict. ## VS Code editor defaults Set `fmt.vscode` and/or `lint.vscode` (both default `false`) to add missing project-scoped settings to `.vscode/settings.json`. The generated defaults are deliberately small: * `editor.defaultFormatter` * language blocks (`[javascript]`, `[typescript]`, ...) * `editor.codeActionsOnSave` (lint only) Use an options object to override or exclude individual keys: ```ts toolchain: { fmt: { oxc: {}, vscode: { overrides: { 'editor.defaultFormatter': 'oxc.oxc-vscode', '[typescript]': { 'editor.defaultFormatter': 'esbenp.prettier-vscode' }, }, exclude: ['[javascript]'], }, }, lint: { oxc: {}, vscode: true }, } ``` These editor defaults are **not tracked** and existing keys are never overridden. (The separate Conventional Commits/Biome VS Code sync may track `.vscode/settings.json` when those sections are enabled.) Remove or change the generated keys freely. Setting `vscode: false` (or omitting it) adds nothing. A nested project scaffolded below a root that already has `.oxfmtrc.json` / `.oxlintrc.json` omits its own Oxc files and `fmt.oxc` / `lint.oxc` opt-ins, so `dbx fmt` / `dbx lint` keep using the root configuration. ## Migrating ```sh dbx migrate --from oxc --write # .oxfmtrc/.oxlintrc -> fmt.oxc/lint.oxc dbx migrate --from biome --from prettier --write dbx migrate --from all --write ``` Unless `--target` is given, the migrated formatter/linter options go to `toolchain.vite.fmt`/`toolchain.vite.lint` when the existing Vite config already defines `fmt`/`lint`; otherwise they go to the top-level `toolchain.fmt.oxc`/`toolchain.lint.oxc`. See [Migrations](/guide/migrations/). ## Biome > **Deprecated:** prefer `toolchain.fmt.biome` / `toolchain.lint.biome` (see > above). The top-level `biome` section still works and still writes > `biome.json`. The `biome` section generates a `biome.json` for consumers that still want a Biome config. The toolchain itself is built on **Oxc** (Oxfmt + Oxlint) through Vite+, but a repo that runs Biome directly can let the toolchain manage its `biome.json` from the same `dbx.config.*`. ```ts [dbx.config.ts] export default defineConfig({ toolchain: { biome: true, // or { overrides: { ... } } }, }); ``` `dbx sync` writes `biome.json`, resolving the {{ name }} / {{ scope }} replacement tokens and merging your overrides over the defaults. If any other formatter/linter is also configured, sync still writes both the Biome and Oxc config files, but warns (`fmt.conflict` / `lint.conflict`) that the two tools may conflict. Silencing it is possible with `logger: { suppress: ['fmt.conflict'] }`; prefer one toolchain per repo. ### Options | Option | Type | Default | Description | | ----------- | ------------------------- | -------------------- | -------------------------------------------- | | `enabled` | `boolean` | enabled when defined | Master switch. | | `vscode` | `boolean` | `true` | Write the Biome VS Code settings/extensions. | | `overrides` | `Record` | — | Deep-merged over the generated `biome.json`. | #### `overrides` Overrides are merged into the generated config **recursively**, and **arrays are unioned** (not replaced) — so `files.includes` can be extended: ```ts biome: { overrides: { files: { includes: ['!**/generated/**'] }, formatter: { indentWidth: 2 }, }, } ``` Default array entries can be pruned with a `$remove:` entry (its value is JSON, or a raw string when it is not valid JSON) or replaced wholesale with `$reset`: ```ts import { BIOME_RESET, removeBiomeEntry } from '@deltabox/toolchain/biome'; biome: { overrides: { files: { includes: [ removeBiomeEntry('!**/.generated'), // drop a default '!**/generated/**', ], }, assist: { actions: { source: { organizeImports: { options: { groups: [BIOME_RESET, ['@/lib/**']] }, }, }, }, }, }, } ``` `removeBiomeEntry(entry)` builds the directive, and nested arrays (eg. import groups) are matched deeply. The same directives work in `fmt.biome` / `lint.biome`; sources are applied in order, so later ones see earlier results. #### `vscode` When on (the default), the sync also writes the recommended Biome VS Code settings and the Biome extension recommendation (see [VS Code Extension](/guide/vscode)). Set `biome: { vscode: false }` to skip them. ### Programmatic API ```ts import { BIOME_RESET, biomeConfig, biomeSyncTask, biomeVscodeSettings, mergeBiomeConfig, removeBiomeEntry, renderBiomeConfig, renderBiomeJson, resolveBiomeArray, } from '@deltabox/toolchain/biome'; ``` | Export | Description | | ----------------------------------------- | -------------------------------------------------------- | | `biomeSyncTask()` | The sync task (writes `biome.json`). | | `biomeConfig` / `biomeVscodeSettings` | The generic Biome config / recommended VS Code settings. | | `renderBiomeConfig(tokens, overrides?)` | Resolve tokens + merge overrides into an object. | | `renderBiomeJson(tokens, overrides?)` | Serialize the rendered config. | | `mergeBiomeConfig(base, patch)` | The recursive/array-union merge used above. | | `resolveBiomeArray(base, patch)` | Resolve `$remove:`/`$reset` directives for one array. | | `removeBiomeEntry(entry)` / `BIOME_RESET` | Build the array-pruning / array-reset directives. | > Migrating **from** Biome to Oxc is a different concern — see > [Migrations](/guide/migrations/). --- --- url: https://toolchain.dbx.studio/guide/scripts.md --- # Package scripts `dbx` writes files, not your `package.json` — but a few scripts are worth standardizing, because the toolchain's formatting/linting and task running both go through **Vite+**. Any bare `dbx ` that matches a Vite+ command is forwarded straight to it (`dbx fmt`, `dbx run -r build`, `dbx dev`), so a project only needs the one `dbx` command. This page shows the recommended root scripts and how to move an existing Biome + Turbo project onto them. ## Recommended scripts The repo root `package.json`: ```json [package.json] { "scripts": { "fmt": "dbx fmt", "lint": "dbx lint --fix", "check": "dbx check", "build": "dbx run -r build", "typecheck": "dbx run -r typecheck", "test": "dbx run -r test", "dbx:sync": "dbx sync", "dbx:watch": "dbx watch", "commitlint": "commitlint", "postinstall": "vp hooks enable" } } ``` | Script | What it does | | ------------------------------ | --------------------------------------------------------------- | | `fmt` / `lint` / `check` | Oxfmt / Oxlint across the repo (`check` = format check + lint). | | `build` / `typecheck` / `test` | Runs the task in every workspace, in dependency order. | | `dbx:sync` / `dbx:watch` | Regenerate the managed files / re-sync on change. | | `commitlint` / `postinstall` | Conventional Commits + the Vite+ hook dispatcher. | Notes: * A bare command that names a Vite+ command is forwarded to Vite+ (`vp`) — eg. `dbx fmt`, `dbx dev`, `dbx run -r build`, `dbx add zod` (Vite+ aliases too). Built-in commands win, so `dbx migrate` is the toolchain's migration — use `dbx vite migrate` for Vite+'s. The explicit `dbx vite ` passthrough always works. * Vite+ resolves from the **repo root**, so `fmt`/`lint` live there — keep them out of the individual workspaces. * `dbx run -r ` runs a task in every workspace package in dependency order. A task is either a `package.json` script or a `vite.config.ts` `run.tasks` entry. For long-running processes use `dbx run -r --parallel dev`. * `dbx` is the toolchain binary, so `yarn dbx ` (eg. `yarn dbx sync`) works even without a script; the `dbx:*` aliases are just for discoverability. When `ci.changelog` is enabled, `dbx sync` writes a `commit-msg` hook that runs commitlint, so commits are linted locally as well as in CI. On a Vite+ project it writes the project-owned `.vite-hooks/commit-msg`; activate the dispatcher on install with `vp hooks enable` (or `vp config`, which also wires agent integration). Projects without Vite+ keep the husky fallback (`.husky/commit-msg` with `postinstall: husky`). Hook scripts have no extension, so on Windows add `.vite-hooks/* text eol=lf` (or the husky equivalent) to `.gitattributes` — a trailing CR silently breaks the hook. To check staged files before a commit, add a project-owned `.vite-hooks/pre-commit` that runs `vp staged`, and configure the checks in the root `vite.config.ts`: ```ts [vite.config.ts] staged: { '*': 'vp check --fix', }, ``` `vp staged` bundles lint-staged and requires Node.js ≥ 22.22.1 (or ≥ 24.11.0). `vp hooks enable` only manages the dispatcher; it never overwrites project-owned hooks such as `commit-msg` and `pre-commit`. ## Vite+ commands with the `dbx()` plugin When the project uses the `dbx()` Vite plugin (`vite.config.ts`), call Vite+ directly for the toolchain commands: ```json [package.json] { "scripts": { "dev": "vp dev", "build": "vp build", "check": "vp check", "test": "vp test", "dbx:sync": "dbx sync" } } ``` `vp fmt`, `vp lint`, `vp run -r build` and the rest of the Vite+ commands work from the repo root; `dbx` still owns `sync`, `watch`, `changelog` and the other non-Vite+ commands. `dbx fmt` / `dbx lint` remain the portable form — they route to the detected formatter/linter when a project is not on Vite+. See Vite+ [Built-in commands vs scripts](https://viteplus.dev/guide/run#built-in-commands-vs-scripts) for which commands are built in and which run `package.json` scripts. ## Migrate an existing project 1. Add the toolchain + Vite+, and drop what they replace: ```diff - "@biomejs/biome": "catalog:", - "turbo": "^2.11.2", + "@deltabox/toolchain": "^1.2.3", + "vite-plus": "^1.2.0", ``` 2. Fold the Biome config into a root `vite.config.ts`: ```sh dbx migrate --from biome --target vite --write ``` Or, if the project uses `dbx.config.ts`, author the Vite+ config there under `toolchain.vite`. `dbx sync` then writes the root `vite.config.ts` shim (see [Vite+](/guide/config/vite)). `dbx migrate --from vite --write` folds an existing hand-written `vite.config.ts` in. 3. Replace the scripts (see the tables below), then delete `biome.json` and `turbo.json`. 4. Add a `dbx.config.ts` and sync the managed files: ```sh dbx sync ``` 5. Verify — this is what CI runs: ```sh dbx sync --check yarn build ``` ### Biome → Oxc | Before | After | | ------------------------ | ---------------- | | `biome format --write .` | `dbx fmt` | | `biome check --fix .` | `dbx lint --fix` | | `biome.json` | `vite.config.ts` | Remove `@biomejs/biome`, delete `biome.json`, and drop any per-workspace `fmt`/`lint` scripts. ### Turbo → Vite Task | Before | After | | ----------------- | ------------------------------------------ | | `turbo build` | `dbx run -r build` | | `turbo typecheck` | `dbx run -r typecheck` | | `turbo test` | `dbx run -r test` | | `turbo dev` | `dbx run -r --parallel dev` | | `turbo.json` | (optional) `run.tasks` in `vite.config.ts` | Remove `turbo` and `turbo.json`. Ordering comes from each package's `package.json` dependencies, so no `turbo.json` graph is needed. ## Per-workspace tasks Each package declares `build`, `typecheck` and `test` in its own `vite.config.*` (or `dbx.config.*`) with explicit cache input/output, so `dbx run` reports cache hits (a `package.json` script cannot carry cache config). Use the Vite+ commands rather than the individual tools: ```ts [packages//vite.config.ts] import { defineConfig } from 'vite-plus'; export default defineConfig({ run: { tasks: { build: { command: 'vp pack', cache: { input: [{ auto: true }, '!dist/**'], output: ['dist/**'] }, }, test: { command: 'vp test run', cache: { input: [{ auto: true }], output: [] }, }, }, }, }); ``` See the [Monorepo guide](/guide/monorepo) for the full task setup, [Migrations](/guide/migrations/) for the `dbx migrate` reference, and [Providers (Vite+)](/guide/providers) for the `dbx vite` passthrough. --- --- url: https://toolchain.dbx.studio/guide/cli.md --- # CLI The `dbx` binary is composed from framework-agnostic command descriptors. Commands that run against a project load its toolchain config — the `dbx()` Vite plugin config when present, otherwise the nearest `dbx.config.*` — so config-derived defaults apply unless you override them on the command line. ## Global flags | Flag | Description | | ------------------- | -------------------------------------------------------------- | | `--log-level ` | Minimum log level: `debug`, `info`, `warn`, `error`, `silent`. | | `--color` | Force coloured output (the default). | | `--no-color` | Disable coloured output (including help/error formatting). | | `--no-update-check` | Do not check for a newer `dbx` version. | | `--config ` | Use a specific config file instead of discovering one. | | `--no-config` | Ignore config files and use CLI flags/env defaults only. | | `-H, --help` | Display help for the program or subcommand. | | `-V, --version` | Output the version number. | These override the [`logger` config](/guide/config/logging) and may appear before or after the subcommand. `--config` resolves relative to the current directory (absolute paths are used as-is); `--no-config` skips discovery entirely (including inherited parent configs). `dbx` checks the npm registry in the background (about once a day) and prints a short notice with a link to the release when a newer version is published. The check is skipped in CI and when `NO_UPDATE_NOTIFIER` or `DBX_NO_UPDATE_CHECK` is set, and can be turned off with `--no-update-check`. ## Interactive CLI The CLI is scriptable first: every prompt has a flag equivalent. In a TTY, however, some commands prompt when the flags are omitted: ```sh dbx create # template + name + scope + template inputs/actions dbx migrate --recursive # choose the projects to migrate ``` `dbx migrate` detects migrations automatically without `--from`; the prompt is only the project picker for `--recursive`. `--json`, a piped stdin, or the explicit flags disable prompts. See [Scaffolding](#scaffolding) and [Migrations](#migrations) for the flag forms. ## Output Colour is on by default and follows `--no-color` / the [`logger` config](/guide/config/logging). `--no-color` also disables the program's configured help/error colours (the `dbx` program passes `disableColors` from the parsed global `color` flag). ## Core | Command | Description | | ----------- | ---------------------------------------------------------------------------------------------------------------------- | | `projects` | Discover projects and write `.dbx/toolchain/projects.json`. | | `sync` | Regenerate every managed file (`--check`, `--recursive`, `--watch`, `--force`, `--only`, `--json`). | | `watch` | Sync once, then watch key inputs and re-sync. | | `reset` | Remove generated files, the manifest and/or the config (`--all`, `--recursive`); reverts `tsconfig.overrides` first. | | `providers` | List registered providers + their commands (`--json`). | | `enable` | Enable the toolchain (`--workspace` by default, or `--global`; `--json`). | | `disable` | Disable the toolchain (`--workspace` by default, or `--global`; `--json`). | | `enabled` | Print the resolved enabled state and scope (`--json`). A config `toolchain.enabled` wins over `.vscode/settings.json`. | ### Task-only sync `dbx sync --only ` runs just the named sync tasks (comma-separated) and does **not** prune files owned by the tasks it skipped. This is useful at the end of a build, when only the tsconfig aliases/references need refreshing: ```sh dbx sync --only tsconfig ``` Unknown task names fail with the list of available tasks. ## Scaffolding | Command | Description | | ------------------------ | ---------------------------------------------------------------------------------------------------------------- | | `project:init` | A single-package TypeScript project (`--package-manager`). | | `project:init:monorepo` | A monorepo root (add `--example` for one example workspace). | | `project:init:workspace` | A workspace package into an existing monorepo root. | | `project:config` | Generate `dbx.config.*` for projects missing one (TS/JS, `--skip-config` for graph only; folds `vite.config.*`). | | `create` | Scaffold from a template (`--template`/`--kind`, `--name`, `--scope`, `--out`). | Templates that declare inputs/actions are prompted for them (`--var key=value`, `--action `), see [Templates](/guide/templates). On an interactive terminal, a bare `dbx create` (no `--template`/`--kind`/`--name`) prompts for the template, name and scope with clack; Ctrl-C cancels. See [Templates](/guide/templates). ## Templates | Command | Description | | ------------------- | ------------------------------------------------------------------------------------ | | `template:list` | List templates (`--kind`, `--registry`, `--online`, `--json`). | | `template:init` | Write a `template.json` to a directory (`--kind`, `--name`, `--add`, `--no-global`). | | `template:add` | Record a source (auto-inits local; `--no-global` keeps it project-only). | | `template:remove` | Remove a source by id or `type:locate`. | | `template:registry` | List/add/remove the global template search paths (`--vscode-dir`, `--clear`). | | `registry` | List/add/remove/set template **or provider** registries (`--kind`, `--scope`). | | `template:info` | Show one template. | See [Templates](/guide/templates). ## Migrations ```sh dbx migrate --from biome --write # .oxfmtrc.json + .oxlintrc.json dbx migrate --from biome --from prettier --write # several sources dbx migrate --from biome --target vite --write dbx migrate --from oxc --write # .oxfmtrc/.oxlintrc -> dbx.config dbx migrate --from all # every detected source dbx migrate --from vite --recursive --write # migrate every detected project dbx migrate --recursive # interactive project picker dbx migrate --check # CI: exit 1 when stale dbx migrate:list ``` See [Migrations](/guide/migrations/). ## Tsconfig / cleanup / changelog / workflows | Command | Description | | --------------------------- | ---------------------------------------------------------------------------------- | | `tsconfig` | Regenerate workspace `tsconfig.json` files (`--restore [kind]` reverts overrides). | | `cleanup` / `cleanup:turbo` | Remove build artifacts / the turbo cache. | | `changelog` | Derive the semver bump and update CHANGELOG + versions. | | `workflow` | Trigger generated workflows with their vendor CLI (`gh`, `glab` or `az`). | ### Workflows `dbx workflow [id...]` runs every enabled workflow (or the named ids/custom ids/file names) with the CLI for its provider: ```sh dbx workflow # every enabled workflow dbx workflow ci release # by id dbx workflow deploy.yml # by file name dbx workflow --list --json # ids, paths and providers dbx workflow ci --ref main # pass a branch/ref dbx workflow ci --gh /path/to/gh --glab glab --az az ``` GitHub uses `gh workflow run `, GitLab `glab ci run` (the project's configured CI file), and Azure `az pipelines run --name ` (the file stem by default). When the matching CLI is not installed the command reports it and continues with the other workflows. See [CI](/guide/ci/) for the vendor workflow config. ## Providers Every provider subcommand is a passthrough. Vite+ commands are reachable both directly and through the `vite` namespace: ```sh dbx fmt # the active formatter (vp fmt when Oxc) dbx run -r build # forwards to `vp run -r build` dbx vite dev # explicit namespace (always works) dbx vite:build # named alias for `vp build` ``` A bare `dbx ` is forwarded to Vite+ when the name (or a Vite+ alias) matches — built-in commands win, so `dbx migrate` stays the toolchain's migration. The `vite` command forwards its operands verbatim, so **every** Vite+ CLI command and flag is reachable. ## Programmatic The CLI is assembled from framework-agnostic command descriptors, so a consumer can build its own program (or reuse the routing helpers): ```ts import { createCli, runCli, builtinCommands, withCliContext, withDefaultVite, extractConfigSelection, extractLogOptions, } from '@deltabox/toolchain/cli'; ``` | Export | Description | | -------------------------------------- | ---------------------------------------------------------------------- | | `createCli(commands?, options?)` | Build the `dbx` engine program (global flags + built-in commands). | | `runCli(argv?, options?)` | Parse and run the CLI (extracts logger flags, then defaults Vite+). | | `builtinCommands()` | The commands built into the root CLI (config commands need an engine). | | `withCliContext(commands)` | Wrap commands with dbx config loading, logging and framing. | | `withDefaultVite(argv, commandNames?)` | Insert `vite` before a bare Vite+ command (built-ins win). | | `extractLogOptions(argv)` | Pull `--log-level` / `--color` / `--no-color` out of argv. | | `extractConfigSelection(argv)` | Pull `--config ` / `--no-config` out of argv. | `createCli(commands)` accepts a typed command array (for example from `defineCliCommand`) and keeps the command/option types on `program.commands`; `createCli()` uses `builtinCommands()`. Invalid argv prints only the error message by default. Pass `{ helpOnError: true }` to `createCli({ helpOnError: true })`, `createCli(commands, { helpOnError: true })` or `runCli(argv, { helpOnError: true })` to also print the full help after an unknown option/command or a bad value. `dbx` groups options and commands by default: `vite:list` is listed under a `Vite+ commands:` heading. The built-in commands mirror the docs sidebar: core workspace commands stay under `Commands:`, followed by `Project & templates`, `Tooling`, `Automation & API`, `Agents` and `Vite+`. Commands are sorted ascending by name within each section by default; pass `{ sort: 'desc' }` to reverse that or `{ sort: false }` to keep registration order (in groups too). Pass `{ groups: false }` for flat lists, or `{ groups: { auto: false } }` to only honor explicit command groups. The same options work through `createCli` and `runCli`. `extractLogOptions` makes the logger flags work before *or* after the subcommand and stops at `--`, so a wrapped binary's own flags are never eaten. `withDefaultVite` powers the bare-command passthrough described above: ```ts extractLogOptions(['node', 'dbx', 'sync', '--no-color']); // { argv: ['node', 'dbx', 'sync'], options: { color: false } } withDefaultVite(['node', 'dbx', 'fmt', '--check']); // ['node', 'dbx', 'vite', 'fmt', '--check'] ``` ## Config generator The generic Zod/env config engine is not a `dbx` command: a consumer builds an engine with `createConfigEngine` and registers the `config:*` commands on its **own** CLI. See [Config Generator](/guide/config-generator/). --- --- url: https://toolchain.dbx.studio/guide/docker.md --- # Docker `@deltabox/toolchain-docker` generates a deployable, multi-stage `Dockerfile`, a `.dockerignore` and a `docker-compose.yaml`. Containerization is **opt-in** and happens only when you scaffold: the files are a starting point, not `dbx sync`-managed artifacts, so you can edit them freely afterwards. ```sh # Add Docker artifacts to a new project dbx create --template express --name api --containerize # Or scaffold with the project command dbx project:init --name api --containerize ``` In VS Code, **Create from template...** asks *Containerize with Docker?*. The setting `deltabox.toolchain.containerizeTemplates` supplies the default and is used by the curated **Scaffold** flow. Programmatically, pass `containerize: true` to `scaffoldTemplate()`. Every scaffold gets `Dockerfile`, `.dockerignore` and `docker-compose.yaml` for local development (`docker compose up --build`). ## Programmatic API `dockerFiles()` renders the artifacts (without writing), and `writeDockerFiles()` writes them to a project: ```ts import { dockerFiles, writeDockerFiles } from '@deltabox/toolchain/docker'; const files = dockerFiles({ cwd: process.cwd(), image: 'myapp/api', tag: 'latest', port: 3000, }); const written = writeDockerFiles({ cwd: process.cwd(), compose: true, force: true, // overwrite existing artifacts }); ``` | Option | Default | What it does | | ----------------- | --------------------------- | ---------------------------------------------- | | `image` | project name | OCI image name. | | `tag` | `latest` | Image tag. | | `port` | `3000` / `8080` | Port the runtime image exposes. | | `runtime` | `auto` | `node`, `static`, `bun`, or detect. | | `entry` | `dist/index.js` | Built server entry for `node`/`bun` runtimes. | | `output` | `dist` | Build output directory (`static` copies this). | | `nodeVersion` | `engines.node` or `22` | Node.js version for non-Vite+ images. | | `baseImage` | Vite+/Bun/Node image | Override the build-stage image. | | `runtimeImage` | Debian/Bun/nginx/Node image | Override the runtime image. | | `user` | `nobody` / `node` / `bun` | Runtime user. | | `compose` | `false` | Also render `docker-compose.yaml`. | | `healthcheck` | `true` | Add an HTTP `HEALTHCHECK`. | | `healthcheckPath` | `/` | Path the healthcheck requests. | | `dockerfile` | `Dockerfile` | Dockerfile file name. | | `dockerignore` | `true` | Render `.dockerignore`. | `writeDockerFiles()` does not overwrite existing files unless `force: true` (scaffolding passes it for a fresh project). There is no `docker` config section and no sync task: the generated files are yours to maintain. ## Images * **Vite+ projects** build with `ghcr.io/voidzero-dev/vite-plus:latest`, install with `vp install`, build with `vp build`, and copy the resolved Node.js binary into the runtime stage. * **Bun projects** use `oven/bun:1` to build and `oven/bun:1-slim` to run. * **Other Node projects** use `node:-bookworm-slim`. * **Static sites** copy the build output into `nginxinc/nginx-unprivileged:alpine`, so the container runs as a non-root user on port `8080`. Server images run as a non-root user and get a `HEALTHCHECK` that requests `http://127.0.0.1:`. ## COPY sources and installs The dependency-install stage copies only sources that exist when the Dockerfile is generated: `package.json` plus the project's lockfile/workspace files (`yarn.lock`/`.yarnrc.yml`, `pnpm-lock.yaml`/`pnpm-workspace.yaml`, `package-lock.json`, `bun.lock`/`bun.lockb`). A Vite+ project also copies an existing `.node-version` before `vp install`, so Vite+ selects the same Node.js version in the image. No lockfile is assumed, and a missing lockfile is never `COPY`ed, so a fresh scaffold builds. The generated `.dockerignore` matches dependencies and build output at any depth (`**/node_modules`, `**/dist`, the configured output directory, ...), so nested workspace copies are excluded from the build context too. Yarn Plug'n'Play projects do not get `node_modules`. Their runtime image copies the generated `.pnp.cjs` (or `.pnp.js`), an optional `.pnp.loader.mjs`, and `.yarn`, then starts Node with `--require ./.pnp.cjs` (and `--experimental-loader` when the loader exists). The declared package manager is the single source of truth: `packageManager` in `package.json` (or the `packageManager` option) drives both the copied lockfiles and the `RUN` command. A Bun-runtime project with no declared manager installs with Bun; otherwise the declared manager wins, so `yarn.lock` is never paired with `bun install`. When a Bun-runtime project declares yarn/pnpm/npm, dependencies install in a `node:` `deps` stage and the Bun image only builds (the official Bun image has no npm/corepack). Without a lockfile the install runs without a frozen flag (`yarn install`, `pnpm install`, `npm install`, `bun install`, `vp install`). ## Detection With `runtime: 'auto'` the generator reads `package.json`: * a `vitepress build` script is a **static** site (`docs/.vitepress/dist`); * a `bun build`/`bun ...` start script is a **Bun** server; * a `start` script is a **Node** server; * a `vp build` script without `start` is a **static** app; * otherwise it falls back to a **Node** server. --- --- url: https://toolchain.dbx.studio/guide/mcp.md --- # MCP (Model Context Protocol) `@deltabox/toolchain` ships an MCP server that exposes the dbx APIs to AI harnesses and editors. It is a dependency-free stdio server, so it works with any MCP client and does not pull the MCP SDK into your project. ```sh dbx mcp:serve ``` The server exposes one tool per public dbx capability: | Tool | Runs | | -------------------- | ------------------------------------------------------------ | | `dbx_sync` | `dbx sync` (with `check`, `recursive`, `configless`, `only`) | | `dbx_projects` | `dbx projects` | | `dbx_providers` | `dbx providers` | | `dbx_templates` | `dbx template:list` | | `dbx_template_info` | `dbx template:info` | | `dbx_changelog` | `dbx changelog` | | `dbx_migrate` | `dbx migrate` (preview unless `write`) | | `dbx_project_config` | `dbx project:config` | | `dbx_tsconfig` | `dbx tsconfig` | | `dbx_workflow` | `dbx workflow` | | `dbx_run` | an allowlisted `dbx` command | Every tool runs the project's own resolved `dbx` binary, so the MCP surface always matches the CLI version the project pins. Plugin-mode projects work without a `dbx.config.*` (the server reads the `dbx()` Vite plugin options). ## Install ```sh dbx mcp:install --provider claude dbx mcp:install --provider vscode --scope global dbx mcp:install --provider custom --dir ./tools/mcp ``` `dbx mcp:list` prints the builtin providers and the exact files each one writes: | Provider | Project config | Skill / instructions | | ---------- | -------------------- | ----------------------------------------------- | | `claude` | `.mcp.json` | `.claude/skills/deltabox/SKILL.md` | | `codex` | `.codex/config.toml` | `.codex/skills/deltabox/SKILL.md` | | `vscode` | `.vscode/mcp.json` | `.github/instructions/deltabox.instructions.md` | | `opencode` | `opencode.json` | `.opencode/skills/deltabox/SKILL.md` | | `pi` | `.pi/mcp.json` | `.pi/skills/deltabox/SKILL.md` | | `custom` | `/mcp.json` | `/deltabox/SKILL.md` | `--scope global` writes to the provider's user profile instead (`~/.claude.json`, `~/.codex/config.toml`, `~/.config/opencode/opencode.json`, ...). `--no-skills` writes only the MCP config, and `--json` prints the exact paths that were written. The VS Code extension exposes the same flow from **Install MCP server + skill...** (and the Home view's Quick Actions). ## Skills `dbx skills` installs the **official dbx toolchain skill** without the MCP server. The skill is documentation-only: it tells the agent to read [`https://toolchain.dbx.studio/llms.txt`](https://toolchain.dbx.studio/llms.txt) and follow the relevant docs page before answering or editing files. It also tells the agent to inspect the project first: * `dbx.config.*` / `vite.config.*` (with the `dbx()` plugin) and `.vscode/settings.json` (`deltabox.toolchain.enabled`) to see whether the toolchain is enabled. * `.dbx/toolchain/projects.json` for the project graph and config locations, and `.dbx/toolchain/manifest.json` for managed files. * The enabled `toolchain` sections, so conventions such as commitlint/changelog commit messages are respected. ```sh dbx skills # list the install status per agent dbx skills --official # install for every builtin agent dbx skills --official --provider claude # one agent dbx skills --official --provider vscode --scope global dbx skills --official --provider custom --dir ./tools/agent dbx skills --official --force # overwrite an existing skill ``` Installs are idempotent: an existing skill file is left untouched unless `--force` is passed, so local edits are preserved. `--json` prints the status or write results. ### Automatic installation Opt in through `toolchain.mcp.skills`; `dbx sync` (and `dbx watch`) then adds the skill wherever it is missing: ```ts export default defineConfig({ toolchain: { mcp: { skills: { agents: ['claude', 'vscode'], scope: 'project', }, }, }, }); ``` | Option | Meaning | | --------- | --------------------------------------------------------------- | | `agents` | Agent id or ids (default: every builtin provider). | | `scope` | `project` (default) or `global`. | | `dir` | Custom directory (with `agents: ['custom']`). | | `force` | Overwrite existing files (default: `false`). | | `enabled` | Set `false` to keep the section configured but stop installing. | The skill paths mirror the MCP provider table above, using the `deltabox-toolchain` stem (for example `.claude/skills/deltabox-toolchain/SKILL.md`). The VS Code extension adds an **Install official skill...** prompt action alongside the MCP installer. ### Programmatic API ```ts import { checkSkill, installOfficialSkill, installSkill, resolveMcpSkillsConfig, } from '@deltabox/toolchain/mcp'; checkSkill({ agent: 'claude', cwd }); // { path, exists } installOfficialSkill({ agent: 'claude', cwd }); // writes only when missing installSkill({ agent: 'vscode', scope: 'global', force: true }); resolveMcpSkillsConfig(config); // the configured agents/scope, or undefined ``` --- --- url: https://toolchain.dbx.studio/guide/logger.md --- # Logger Every toolchain message goes through one logger, so output stays consistent and respects a single configuration. The `logger` section controls its level, colours and prefix. ```ts [dbx.config.ts] export default defineConfig({ toolchain: { logger: { level: 'debug', color: false, name: 'dbx' }, }, }); ``` ## Options | Option | Type | Default | Description | | ---------- | -------------------------------------------------- | ------- | ------------------------------------------------------ | | `level` | `debug` | `info` | `warn` | `error` | `silent` | `info` | Minimum level to print. | | `color` | `boolean` | `true` | Force colours on/off. | | `name` | `string` | `dbx` | Prefix for non-indented lines. | | `suppress` | `string \| string[]` | none | Silence warnings/errors by id, substring or `/regex/`. | | `logger` | `ToolchainLogger` | none | Custom logger implementation. | Colour is **on by default** (the toolchain forces it rather than relying on TTY autodetection); `--no-color` or `logger: { color: false }` turn it off. Human output is rendered with [`@clack/prompts`](https://bombshell.dev/clack) — level symbols (`•` info, `◆` success, `▲` warn, `■` error) and a guide. ## Custom logger `logger.logger` accepts a `ToolchainLogger` (`raw`, `rawError`, `write`, `debug`, `info`, `success`, `warn`, `error`). The toolchain still applies `level` and `suppress` before delegating, so a custom sink receives only visible messages. ```ts [dbx.config.ts] toolchain: { logger: { logger: { raw: m => process.stdout.write(`${m}\n`), rawError: m => process.stderr.write(`${m}\n`), write: () => {}, debug: () => {}, info: m => sink.info(m), success: m => sink.info(m), warn: m => sink.warn(m), error: m => sink.error(m), }, }, } ``` ## CLI overrides | Flag | Description | | ------------------- | ---------------------------------------------------------- | | `--log-level ` | Minimum level: `debug`, `info`, `warn`, `error`, `silent`. | | `--color` | Force coloured output (the default). | | `--no-color` | Disable coloured output. | They win over the config and may appear before or after the subcommand. `--no-color` also disables the program's configured help/error colours. ## Machine output `--json` (and provider passthroughs) write raw, unprefixed, undecorated output through the same logger (`logger.raw`), so it is safe to pipe into `jq` or another tool. ## Providers Provider passthrough commands (Vite+) follow the logger's colour setting, and the [`providers`](/guide/providers#colour) section can force provider colours on or off independently. `color: false` runs the wrapped binary with `NO_COLOR=1` and `FORCE_COLOR=0`. ## Programmatic API ```ts import { configureLogger, createLogger, getLogger, isLogLevel, logger, normalizeLogLevel, setLogConfig, setLogOverrides, } from '@deltabox/toolchain/shared'; ``` | Export | Description | | ---------------------------------- | ------------------------------------------------------ | | `logger` | The active logger (delegates to the current instance). | | `createLogger(options?)` | Build a logger with explicit options. | | `setLogConfig(section)` | Apply the `logger` config section. | | `setLogOverrides(options)` | Apply CLI overrides (win over the config). | | `configureLogger(options?)` | Alias for `setLogOverrides`. | | `isLogLevel` / `normalizeLogLevel` | Validate/coerce a level. | Use `logger.info` for human messages and `logger.raw` for machine output; avoid `console.log` so output stays consistent and respects the config and CLI flags. --- --- url: https://toolchain.dbx.studio/guide/watch.md --- # Watch The `watch` section configures `dbx watch`, which syncs once and then re-runs on input changes. ```ts [dbx.config.ts] export default defineConfig({ toolchain: { watch: { enabled: true, debounce: 150 }, }, }); ``` ## Options | Option | Type | Default | Description | | ----------- | -------------------- | -------------------- | ------------------------------------------- | | `enabled` | `boolean` | enabled when defined | Watch by default. | | `debounce` | `number` | `150` | Debounce window in ms before a re-sync. | | `exclude` | `string \| string[]` | common ignored paths | Glob(s) excluded from watching. | | `gitignore` | `boolean` | `true` | Respect `.gitignore` files (root + nested). | `exclude` adds to the common ignored paths (`node_modules`, `.dbx`, `dist`, `build`, ...), and `gitignore` also honours the repo's `.gitignore` files (root and nested, each scoped to its own directory) so ignored directories are never watched. Set `gitignore: false` to watch them anyway. The common list is exported as `DEFAULT_IGNORE_PATTERNS` from `@deltabox/toolchain` and `@deltabox/toolchain/shared` if you need to build on it. ```ts watch: { exclude: ['**/fixtures/**'], gitignore: true } ``` ## How it works ```sh dbx watch ``` `dbx watch` runs one sync, then watches the config file plus every task's `watch` globs and re-runs on change. A config change reloads the config (and rebuilds the watched inputs) before re-syncing. Writes made by the sync itself must not re-trigger a run, so a short quiet window follows each sync. Only **input** files are watched (eg. `dbx.config.*`, `tsconfig.default.json`, `tsconfig.workspaces.json`), never the generated outputs — so a sync can never loop on its own writes. Custom tsconfig names (`tsconfig.rootFile`, `tsconfig.defaultFile`) are watched instead of the defaults. `dbx watch --list` prints the resolved inputs without watching (`--json` adds the tsconfig file names; the VS Code extension reads it): ```sh dbx watch --list --json # { "globs": ["**/dbx.config.*", "tsconfig.workspaces.json", "**/tsconfig.default.json"], # "tsconfig": { "baseFile": "tsconfig.base.json", ... } } ``` `dbx watch --force` runs even when there is no `dbx.config.*`, and `watch: false` / `watch: { enabled: false }` disables it (so a plain `dbx watch` warns and exits). ## VS Code The VS Code extension has its own debounced scheduler that mirrors this behaviour (see [VS Code Extension](/guide/vscode#auto-sync)); the `watch` section configures the **CLI** `dbx watch` command. --- --- url: https://toolchain.dbx.studio/guide/changelog.md --- # Changelog ## CI The `ci` section drives everything Conventional Commits (by default): the CI that lints commit messages, the local commit hook, the `commitlint.config.mjs`, the GitHub workflows, and the changelog pipeline that bumps versions and writes `CHANGELOG.md`. Its `ci.changelog` config holds the changelog-specific options. ```ts [dbx.config.ts] export default defineConfig({ toolchain: { ci: { ci: true, release: true, changelog: { branches: { main: 'main', dev: 'dev' }, commitlint: { types: ['feat', 'fix', 'docs', 'chore'], scopes: ['api', 'web', 'deps'], }, versioning: { target: 'individual', workspaces: ['packages/*', 'apps/*'] }, }, }, }, }); ``` `dbx sync` writes the opted-in GitHub workflows (`.github/workflows`), the commitlint config, and the `commit-msg` hook. On a Vite+ project the hook is `.vite-hooks/commit-msg`, installed by `vp hooks enable` / `vp config`; projects without Vite+ keep the husky fallback (`.husky/commit-msg`). Activate the dispatcher with a `postinstall` script: ```json [package.json] { "scripts": { "commitlint": "commitlint", "postinstall": "vp hooks enable" } } ``` For Vite+ projects, add a `.vite-hooks/pre-commit` running `vp staged` and put the staged checks in the root `vite.config.ts` (`staged: { '*': 'vp check --fix' }`). See [Package scripts](/guide/scripts) for the full recommended script set. ## Group order and titles `groups` customizes the Conventional-Commits sections. It works on both `toolchain.changelog.groups` (manual runs) and `ci.changelog.groups` (CI + manual when inherited). An array sets the order and optionally the titles: ```ts ci: { changelog: { groups: [ { type: 'feat', title: 'New Features' }, { type: 'fix', title: 'Bug Fixes' }, 'perf', ], }, } ``` A record is a shorthand for the same thing, ordered by its keys. Use `false` to hide a group: ```ts groups: { feat: 'New Features', fix: 'Bug Fixes', chore: false, } ``` The default order is **Breaking Changes**, `feat`, `fix`, then the remaining types (`perf`, `refactor`, `docs`, ...). Types you do not mention are appended in the default order. `order` overrides the array/record position, and every title/order/hidden value accepts a callback. The whole `groups` value can also be a callback, so it can be computed from the types/items in the current run: ```ts groups: context => [ { type: 'feat', title: group => `New Features (${group.groupItems.length})`, order: 0, }, { type: 'fix', hidden: group => group.groupItems.length === 0 }, ...context.types.filter(type => !['feat', 'fix'].includes(type)), ]; ``` Callbacks are TS/JS-config-only. `dbx changelog --format-only` also uses the configured order/titles when regrouping existing entries. `groups` only groups **commit sections** inside one version. To treat several changelog versions as one release body, use [`release.group`](/guide/changelog/release#grouped-release-bodies) instead. ## Release bodies `changelog.release` controls the body `dbx changelog --release-body ` prints for a release. It can group every version since the previous published release into one body, choose a different boundary, or include prereleases. See [Release bodies](/guide/changelog/release) for the options, CLI flags and individual-versioning behavior. ## Breaking-change detection Breaking commits are detected by Conventional Commits rules by default: a `!` before the subject colon (`feat!:`, `feat(scope)!:`) or a `BREAKING CHANGE:` / `BREAKING-CHANGE:` footer line. Configure `breaking` on either `toolchain.changelog` or `ci.changelog` to override it: ```ts breaking: 'conventional', // default // breaking: 'any', // legacy loose match anywhere in the subject/body // breaking: false, // disable breaking detection // breaking: { pattern: '^feat!:' }, // breaking: { match: 'BREAKING CHANGE' }, // breaking: ({ subject, body }) => subject.includes('!'), ``` The same setting is used for version bumps, changelog grouping and `--format-only` regrouping. ## Manual `toolchain.changelog` The top-level `changelog` section configures manual runs for `dbx changelog`, the VS Code actions and the programmatic API. It accepts the pipeline options (commitlint, versioning, groups, VS Code settings), but not the CI-only workflow options or `branches`: ```ts [manual pipeline] toolchain: { changelog: { commitlint: { types: ['feat'], scopes: ['api'] }, versioning: true, vscode: true, }, } ``` Move the generated workflows to the top-level `ci` section, and put the pipeline options under `ci.changelog` when CI should use them too. Branches and workflow overrides only exist on `ci.changelog`: ```ts [after] toolchain: { ci: { ci: true, release: true, changelog: { branches: { main: 'main' }, commitlint: { types: ['feat'], scopes: ['api'] }, versioning: true, vscode: true, }, }, } ``` `ci.changelog` inherits `toolchain.changelog` when it is enabled without pipeline options (`ci.changelog: true`, a raw workflow string, or workflow-only overrides). Options set explicitly on `ci.changelog` win. ## GitHub metadata When `gh` is installed and authenticated, a run resolves commit authors, PR credit and issue titles/links from GitHub. Lookups are batched so a large range stays close to a handful of requests: * one REST `compare/{base}...{head}` request per scanned range for commit authors; * GraphQL `associatedPullRequests` lookups in batches of 100 commits (a PR author wins over the commit author, matching the changelog credit rules); * aliased GraphQL issue lookups, 100 issues per request. Without `gh` (or with `DBX_NO_GH=1`) the pipeline falls back to git metadata and plain `#123` references. Commits that no remote-tracking ref reaches are skipped (GitHub cannot resolve an unpushed SHA), and terminal client errors (eg. a 404 for a missing ref) are not retried. Other failures are retried `DBX_GH_MAX_RETRIES` times (default 5) with a `DBX_GH_RETRY_DELAY` ms delay (default 3000), then `gh` is disabled for the rest of the run. Set `DBX_GH_BIN` to point at a different `gh` executable. ## Where to start * [CI](/guide/ci/) — the opt-in GitHub workflows (CI checks, changelog, release, issues, sync) and their common settings. * [Branches](/guide/changelog/branches) — `main`/`dev` branch globs. * [commitlint](/guide/changelog/commitlint) — config location, types/scopes and the no-commitlint fallback. * [Versioning](/guide/changelog/versioning) — which `package.json` versions a run bumps. * [Release bodies](/guide/changelog/release) — `--release-body`, grouping, boundary rules and CLI overrides. * [CLI](/guide/changelog/cli) — running the changelog locally. * [Writing commit messages](/guide/changelog/writing-commit-messages) — avoiding shell-mangled messages. * [Troubleshooting](/guide/changelog/troubleshooting) — the upstream commitlint parser-preset error. * [Releases](/guide/ci/releases) — the release PR workflow and GitHub Release. --- --- url: https://toolchain.dbx.studio/guide/changelog/branches.md --- # Branches `ci.changelog.branches.main` and `ci.changelog.branches.dev` pick which branches the generated workflows target. Each accepts a glob or an array of globs: | Branch | Drives | Default | | ------ | ------------------------------------------------------------------------------ | -------------------- | | `main` | The **CI** workflow (push), the **release** workflow, and the release PR base. | `['main']` | | `dev` | The **changelog/version** workflow (push). | none — reuses `main` | `dev` has **no default**: when it is omitted the changelog workflow runs on `main` (so a single-branch repo needs no `dev`). Set it for a `dev` → `main` flow: ```ts ci: { changelog: { branches: { main: 'main', dev: 'dev' } } } // or multiple branches per purpose: ci: { changelog: { branches: { main: ['main', 'release/**'], dev: ['dev', 'next'] } } } ``` The `sync` workflow runs on both. Any per-workflow `pushBranches` override (eg. `ci.release.pushBranches`) still wins. --- --- url: https://toolchain.dbx.studio/guide/changelog/cli.md --- # CLI ```sh dbx changelog # bump + write (uses ci.changelog.versioning) dbx changelog --dry-run # preview the root entry dbx changelog --range v1.2.0..HEAD # scan a specific range dbx changelog --version 2.0.0 # force a version (retags the changelogs) dbx changelog --format-only # regroup existing changelogs, no bump dbx changelog --release-body 2.0.0 # print the release PR body for a version dbx changelog --release-body 2.0.0 --release-group # group since the last release dbx changelog --release-body 2.0.0 --release-since v1.9.0 # explicit boundary dbx changelog --release-body 2.0.0 --no-release-group # disable configured grouping ``` The command reads `ci.changelog` and falls back to the manual `toolchain.changelog` pipeline options (commitlint, versioning, vscode). This lets a project keep manual/API changelog runs without enabling the CI workflow; `ci.changelog` inherits the same options when it does not override them. The generated `changelog` workflow runs `dbx changelog --range ...` on every push to the `dev` branches (or `main` when `dev` is unset), so versioning is applied from CI as well as locally. `dbx workflow [id...]` triggers the generated workflows with their vendor CLI (`gh`, `glab` or `az`); with no ids it triggers every workflow you declared under `toolchain.ci`. See [Workflows](/guide/cli#workflows). ## Formatting `--format-only` regroups the existing entries without bumping versions. It keeps list items, unwraps hard-wrapped lines, keeps multi-line `BREAKING CHANGE:` footers together and preserves fenced code blocks. Numeric-only short hashes (eg. `#4033009`) are resolved against git, so they stay commit links while real issue numbers stay issue links. Existing subjects and descriptions are never re-rendered from git: hand corrections (including backtick fixes) survive, and a description is only filled in when the entry has none. See [Writing commit messages](/guide/changelog/writing-commit-messages). --- --- url: https://toolchain.dbx.studio/guide/changelog/commitlint.md --- # commitlint By default the generated `commitlint.config.mjs` lives at the project root. Set `ci.changelog.commitlint.dir` to write it elsewhere: ```ts ci: { changelog: { commitlint: { dir: '.config'; } } } // -> .config/commitlint.config.mjs ``` When a custom dir is set, the generated commit hook and the CI commitlint step both pass `--config /commitlint.config.mjs`, so commitlint finds it. Note that editor tooling that discovers the config by convention (eg. the Conventional Commits VS Code extension, which loads from the repo root) expects the config at the root — keep the default unless you have a reason to move it. `commitlint.types` and `commitlint.scopes` are the allowed Conventional-Commits types/scopes: ```ts ci: { changelog: { commitlint: { types: ['feat', 'fix', 'docs', 'chore'], scopes: ['api', 'web', 'deps'], }, }, } ``` ## Disabling commitlint Set `ci.changelog.commitlint: false` (or `{ enabled: false }`) to generate changelogs **without** the Conventional-Commits rules. The changelog workflow is still generated, but dbx writes no `commitlint.config.mjs`, no commit hook and no commitlint step in the CI workflow. The changelog then falls back to a coarse grouping: commits are hoisted into `Major changes`, `Minor changes` and `Patch changes` buckets (breaking commits and `feat:` go to major/minor; everything else is a patch), while the package changes section (eg. new packages) is kept. This is intentionally less detailed than the rule/scope grouping, but it works with any commit-message style. > The extension's `No "exports" main defined in ... conventional-changelog-conventionalcommits ...` > error is an upstream commitlint bug (ESM-only parser preset), not a config > discovery problem. See [Troubleshooting](/guide/changelog/troubleshooting). --- --- url: https://toolchain.dbx.studio/guide/changelog/intro-outro.md --- # Intro and outro text `toolchain.changelog.intro` and `toolchain.changelog.outro` add custom text to the newest changelog entry. They are opt-in: when the section is absent or an entry is disabled, nothing is added. `ci.changelog` inherits the same options. Each setting accepts one entry or an array (`Arrayable`). An entry contains: | Field | Description | | --------- | -------------------------------------------------------------------------------------------------------------- | | `content` | The text to insert. Mutually exclusive with `file`. | | `file` | A file whose contents are inserted (relative to the repo root or absolute). Mutually exclusive with `content`. | | `target` | A workspace path relative to the repo root, `.` for the root, or a glob like `apps/*`. | | `include` | Only apply to workspaces whose repo-relative directory matches these globs (tsconfig-style include). | | `exclude` | Skip workspaces whose repo-relative directory matches these globs. | | `enabled` | Set `false` to skip the entry (default `true`). | Intro text is placed before the version body; outro text is appended after it. Entries are applied in config order, and multiple matching entries are joined with a blank line. Workspaces outside `ci.changelog.versioning.workspaces` (or the default workspace fallback) are skipped. ```ts export default defineConfig({ toolchain: { changelog: { intro: [ { target: '.', content: '> **Pre-release:** APIs may change.' }, { include: 'apps/*', file: 'docs/CHANGELOG.intro.md' }, ], outro: { target: 'packages/ui', content: '_Thanks to everyone who contributed!_', }, }, }, }); ``` The same target selector is reused by the scoped versioning options (`prerelease`, `bump`, `allowOverBump`, `commit`, `provider`); see [Versioning](/guide/changelog/versioning#targeted-options). ### CLI flags You can add an intro/outro without editing the config: ```sh dbx changelog --intro "> **Beta:** APIs may change." --outro-file CHANGELOG.outro.md dbx changelog --intro-file CHANGELOG.intro.md --outro "Thanks to all contributors!" ``` Flags are appended to the configured entries (config is still loaded from the dbx() Vite plugin or dbx.config.\*). The intro is rendered below the version heading. --- --- url: https://toolchain.dbx.studio/guide/changelog/release.md --- # Release bodies `changelog.release` controls the body produced by `dbx changelog --release-body `. That body is the aggregated changelog for a release: the entries from the previous published version up to the requested one, not just the newest entry. ```sh dbx changelog --release-body 3.0.0 ``` The command prints the body to stdout and writes nothing. The generated release workflow uses the same command for the release PR and the GitHub Release; see [Releases](/guide/ci/releases) for the workflow itself. The setting is available on both changelog sections: * `ci.changelog.release` — CI and manual runs that inherit the CI config. * `toolchain.changelog.release` — manual `dbx changelog`, the VS Code actions and the programmatic API. ```ts [dbx.config.ts] toolchain: { ci: { changelog: { release: { group: true }, }, }, } ``` ## How the body is built * Only versions present in the root `CHANGELOG.md` can bound the body. Unrelated tags (calendar versions, package tags for another workspace) are ignored. * Version headings are never printed. The output contains only the bodies. * When an entry has `` / `` markers, only the content inside them is used. * Equal `
` summary groups from several versions are merged, and repeated `### Package changes` footers are collapsed to the newest one (the cumulative diff). * An empty result falls back to `Release `. * The command is read-only, so running it twice produces the same body. With `versioning.target: 'individual'`, the root `CHANGELOG.md` remains the aggregate release body. Package changelogs stay scoped to their own package and are not merged into the GitHub Release body. ## Grouped release bodies By default the body stops at the previous released version. When a project publishes prereleases (for example `3.0.0-beta.1` ... `3.0.0-beta.16` before `3.0.0`), the stable GitHub Release would only mention the changes since the last beta. Set `release.group` to treat every version since the previous **published** release as one version: ```ts [dbx.config.ts] toolchain: { ci: { changelog: { versioning: { target: 'individual', prerelease: 'beta' }, release: { group: true }, }, }, } ``` * A **stable** release skips prerelease versions when it picks the boundary, so all betas since the last stable release are merged into one body. Version headings and duplicate section groups are never repeated; the newest `### Package changes` footer wins because it already covers the whole range. * A **prerelease** release still stops at the previous prerelease, so each beta lists only its own changes instead of repeating the whole cycle. * A **first release** (no published release yet) groups every changelog entry when grouping is enabled; without grouping it keeps the newest-entry fallback. * Missing tags are tolerated: if no released version can be found, grouping selects the entries above the newest match, or the whole changelog when none matches. The boundary comes from published GitHub Releases when `gh` is available and the repository has at least one (drafts are excluded); otherwise it falls back to the local tags merged into `HEAD`. ## Options | Setting | Effect | | ---------------------------- | ----------------------------------------------------------------------------------------- | | `release.group` | Enable grouped release bodies. **Default `false`.** | | `release.includePrereleases` | Let a prerelease bound a stable release's body (only the changes since that beta). | | `release.since` | Explicit lower boundary version/tag (eg. `v1.2.0`); a missing version falls back to auto. | ```ts [dbx.config.ts] toolchain: { ci: { changelog: { release: { group: true, // Let a beta stop the body instead of grouping every beta. includePrereleases: true, // Or skip discovery and start after this version. since: 'v3.0.0-beta.1', }, }, }, } ``` `since` accepts a version or tag (`1.2.0`, `v1.2.0`, `@scope/pkg@1.2.0`). When it does not name a version in the changelog, automatic discovery is used. ## CLI flags The options can be overridden for one run: ```sh dbx changelog --release-body 3.0.0 --release-group dbx changelog --release-body 3.0.0 --release-since v3.0.0-beta.1 dbx changelog --release-body 3.0.0 --release-include-prereleases dbx changelog --release-body 3.0.0 --no-release-group ``` `--release-group` wins over the config for that run, and `--no-release-group` turns a configured grouping off (useful for debugging). ## Release workflow The generated release workflow (`release.yml`) runs `dbx changelog --release-body "$version"` for both the release PR body and the GitHub Release. It therefore picks up `changelog.release` from the config automatically; no workflow change is needed after enabling grouping. See [Releases](/guide/ci/releases) for the workflow options and the release PR flow. --- --- url: https://toolchain.dbx.studio/guide/changelog/troubleshooting.md --- # Troubleshooting ## `No "exports" main defined in ... conventional-changelog-conventionalcommits` Seen from the Conventional Commits VS Code extension (`vivaxy.vscode-conventional-commits`), usually alongside empty type/scope suggestions and a `The cwd is ...` line: ``` commitlint: Error: No "exports" main defined in node_modules/conventional-changelog-conventionalcommits/package.json ``` This is a **known upstream commitlint bug** (commitlint#4864): the generated config `extends: ['@commitlint/config-conventional']`, which sets `parserPreset: 'conventional-changelog-conventionalcommits'`, and v10 of that package is **ESM-only** (`exports` has no `require`/`default`), so the extension's bundled (older) commitlint cannot `require.resolve` it. The config is read fine — the *preset* fails to resolve, so the extension falls back to empty rules. The commit hook and CI are unaffected when commitlint is recent enough to resolve pure-ESM presets (commitlint ≥ 21.2.3). If your local commitlint is older, pin the preset to the last CJS-compatible release: ```json [package.json] { "resolutions": { "conventional-changelog-conventionalcommits": "9.3.1" } } ``` (Use `overrides` instead of `resolutions` for npm.) Updating the extension to a version bundling the fixed commitlint also resolves it. --- --- url: https://toolchain.dbx.studio/guide/changelog/versioning.md --- # Versioning `ci.changelog.versioning` controls whether — and where — a changelog run writes `version` fields into `package.json`. It accepts a boolean or an object, and defaults to `true`. ```ts ci: { changelog: { versioning: true } } // uniform, defaults ci: { changelog: { versioning: false } } // never write versions ci: { changelog: { versioning: { target: 'root-only' } } } ci: { changelog: { versioning: { target: 'individual', workspaces: ['packages/*'] } } } ``` ## `target` | Target | What it bumps | | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `uniform` | The root (when it has a `package.json`) **and every workspace** to one shared version. **Default.** | | `root-only` | Only the root `package.json`. Workspaces are left untouched and get no changelog entry. | | `individual` | The root tracks the overall bump; **each workspace is bumped on its own** from the commits touching its files, so versions can drift apart (like an "independent" monorepo). | With `versioning: false` no `version` field is written at all — the changelog entries are still generated (headed as `uniform` would), so you can keep versioning in another tool (for example changesets). ## `workspaces` An array of glob patterns selecting the workspaces to version, relative to the repo root. It resolves in this order: 1. the `workspaces` patterns you pass, when you pass them; 2. otherwise the root `package.json` `workspaces` field, when present; 3. otherwise the root `package.json` alone (a single-package repo); 4. otherwise a warning is logged and nothing is versioned. ```ts ci: { changelog: { versioning: { target: 'individual', workspaces: ['packages/*', '!packages/private-*'], }, }, } ``` Glob negation (`!pattern`) is honoured: the excluded workspaces are removed from the set, so private packages are never versioned or given a changelog. `individual` uses a `git log` path filter per workspace, so a workspace is only bumped when the scanned commit range touched a file inside it — or a file in one of the workspaces it depends on (see [Workspace changelogs](#workspace-changelogs)). The root's version always follows the overall bump derived from every scanned commit. Re-runs are idempotent: commits already listed in a workspace's own `CHANGELOG.md` are filtered out before the bump is derived. A workspace with no new commits is skipped entirely (no bump, no duplicate entry), and an old `feat` cannot re-bump a workspace as a minor on a later run. ## `prerelease` Set a tag such as `beta` or `rc` to keep a release on a prerelease channel: ```ts ci: { changelog: { versioning: { target: 'individual', prerelease: 'beta' } } } ``` * A stable version bumps its core and starts the channel: `1.0.0` + a minor bump → `1.1.0-beta.0`. * An existing prerelease keeps its core and increments the counter instead of bumping again: `1.1.0-beta.0` → `1.1.0-beta.1`. * Switching tags keeps the core and starts the new channel at `.0`: `1.1.0-alpha.2` → `1.1.0-beta.0`. * The suffix is checked before it is applied, so it is never appended twice. The tag is a single identifier (`^[0-9A-Za-z-]+$`); the numeric counter is added automatically. The same rule applies to `uniform`, `root-only` and `individual` targets, including each workspace's own version in `individual` mode. A stable release can group every prerelease since the last stable release into one GitHub Release body with `changelog.release.group: true`. See [Grouped release bodies](/guide/changelog/release#grouped-release-bodies). ## Version hooks Use [`toolchain.hooks.beforeVersion`](/guide/config/hooks#beforeversion) for work that must happen before the writes (for example a release guard), and [`toolchain.hooks.afterVersion`](/guide/config/hooks#afterversion) for work that must follow a version bump, such as syncing a scaffold catalog: ```ts [dbx.config.ts] hooks: { beforeVersion: ({ previousVersion, version }) => { assertReleaseAllowed(previousVersion, version); }, afterVersion: ({ cwd }) => syncScaffoldCatalog(cwd), }, ``` Both hooks receive the repository root and the new version (`beforeVersion` also receives `previousVersion`); async hooks are awaited. The generated changelog workflow stages `.yarnrc.yml` with the bump, so a catalog update lands in the same commit. ## How a run decides its versions Each run: 1. reads the commits in the range (`--range`/`--processing-method`, default `HEAD`); 2. derives the semver bump (`feat` → minor, `fix`/other → patch, `!` or a `BREAKING CHANGE` footer → major); 3. plans the versions per `target` + `workspaces` (see above); 4. writes the plan's `package.json` versions and prepends the new entry to the root `CHANGELOG.md` and each versioned workspace's `CHANGELOG.md`. Use `dbx changelog --dry-run` to preview the proposed root entry without touching any file; the log line reports the active `target` (or `disabled`). ## Workspace changelogs Each versioned workspace gets **its own `CHANGELOG.md`** (created if missing), headed by the version the plan assigned it. A workspace's entry only lists its **related commits**: those touching the workspace directory **or any workspace it transitively depends on**, resolved from the project dependency graph (`.dbx/toolchain/projects.json`, written by `dbx projects`). So a change in a shared package shows up in the changelog of every package that consumes it, not just in its own. Without a graph (eg. `dbx projects` was never run), a workspace falls back to filtering on its own directory only. A workspace with no related commits is skipped (no empty entry, no file created). ## Package changes footer By default the root entry ends with a `### Package changes` footer comparing the working tree against the previous released version. It reads dependency fields from every `package.json` and the package-manager catalogs: * Yarn: `.yarnrc.yml` (`catalog:` and named `catalogs:`); * pnpm: `pnpm-workspace.yaml` (`catalog:` and named `catalogs:`); * Bun: `package.json` `workspaces.catalog` / `catalogs`. Catalog entries are diffed in the same map as declared dependencies, so a catalog-only range change is reported under the root package at both ends of the release. Entries are grouped by the declaring package (one top-level bullet per package, with each changed dependency nested under it). Pass `--no-package-changes-section` to omit the footer. `--format-only` recomputes each released entry's footer from its release refs. The newest entry is usually unreleased, so its footer compares the working tree with the previous release — the same diff `dbx changelog` wrote. A tagged newest entry keeps its ref-to-ref diff and never picks up uncommitted dependency changes. ## Custom bump rules `versioning.bump` maps `major`, `minor` and `patch` to a matcher. Matchers can be booleans, substrings, `/regex/flags` strings, arrays, matcher objects (`{ type, types, scope, scopes, pattern, match, breaking }`) or callbacks (TS/JS configs only). ```ts ci: { changelog: { versioning: { bump: { major: [{ breaking: true }, { type: 'feat', scope: 'api' }], minor: { type: 'feat' }, patch: { type: 'fix' }, }, }, }, } ``` A matcher object requires only the fields you want; the rest are ignored: | Field | Matches | | ---------- | ------------------------------------------------------------------------------------------------ | | `type` | One Conventional-Commits type (for example `feat`). | | `types` | Any type in the list. | | `scope` | One Conventional-Commits scope. | | `scopes` | Any scope in the list. | | `pattern` | A regular expression tested against the subject + body. | | `match` | A substring of the subject + body. | | `breaking` | `true` for breaking commits, `false` for non-breaking commits. Omit it to ignore breaking state. | ### Rules replace Conventional Commits This is the most important rule: **adding any `bump` level replaces the Conventional-Commits fallback for that target.** Unlisted levels never match, so they cannot add their own bump. A run always produces at least a `patch` bump because semver has no smaller published version. ```ts bump: { minor: { type: 'feat' }, } ``` With only a `minor` rule, a `feat!:` commit is a **minor** bump (there is no `major` rule), and a `fix:` commit is a **patch** bump (the minimum). If you want the usual Conventional-Commits behavior plus one override, spell every level out: ```ts bump: { major: { breaking: true }, minor: { type: 'feat' }, patch: true, } ``` `versioning.bump` only decides the next version number. Changelog section grouping (`feat`, `fix`, ...) is controlled separately by `groups` and still uses Conventional Commits. ### Disabling a level Set a level to `false` (or leave it out) to disable it. This is useful when a team only wants major bumps from an explicit marker, or never wants minor bumps: ```ts bump: { // Breaking changes no longer bump major. major: false, minor: { type: 'feat' }, patch: true, } ``` What each switch does: | Setting | Result | | ----------------- | -------------------------------------------------------------------------------------------------- | | `major: false` | Breaking commits cannot bump major. They use the highest other match, or patch. | | `minor: false` | Feats cannot bump minor. They use the highest other match, or patch. | | `patch: false` | Custom patch matchers stop matching, but a run still produces at least a patch bump. | | all three `false` | Nothing matches; the run still produces a patch bump. | | remove `bump` | Conventional Commits decides again (`feat` minor, `fix`/other patch, `!`/`BREAKING CHANGE` major). | `breaking: false` is not the same as omitting `breaking`: it matches only **non-breaking** commits. `{ breaking: true }` matches only breaking commits. ### More examples Bump major for an explicit marker instead of Conventional Commits: ```ts bump: { major: 'BREAKING CHANGE:', minor: { type: 'feat' }, patch: true, } ``` That matches the literal footer text. Use `{ breaking: true }` instead if you want the configured Conventional-Commits detection (`!` or a `BREAKING CHANGE:` footer) to decide. Bump major for a specific scope and keep everything else on Conventional Commits: ```ts bump: { major: [{ breaking: true }, { type: 'feat', scope: 'api' }], minor: { type: 'feat' }, patch: true, } ``` Only let `feat` and `fix` drive the higher levels. Other types still produce a patch (the minimum), but never a minor/major bump through this rule set: ```ts bump: { minor: { type: 'feat' }, patch: { type: 'fix' }, } ``` Use the commit body, or any custom rule, through a callback. Callbacks receive `{ env, logger, packageJson?, commit, level }` and return a boolean or the level name. Returning a level name only matches while that same level is being evaluated, which keeps the highest-match rule predictable: ```ts bump: { major: ({ commit }) => commit.subject.startsWith('feat!'), minor: ({ commit, packageJson }) => commit.subject.startsWith('feat') && packageJson?.name === '@org/ui', patch: ({ commit }) => commit.subject.startsWith('fix'), } ``` Apply one escalation per additional matching commit: ```ts bump: { minor: { type: 'feat' }, patch: true, }, // Two matching commits become minor -> major; one stays minor. allowOverBump: true, ``` Targeted rules apply per workspace. A target with no matching scoped rule falls back to Conventional Commits (unless it has another scoped rule for that target): see [Targeted options](#targeted-options). ## Commit credits and formatting `versioning.commit` controls the commit bullet credits. All options default to `true` except `authorAvatar`. ```ts ci: { changelog: { versioning: { commit: { author: true, authorAvatar: true, commitSha: true, issues: true, format: ({ commit, author, issues, repo }) => `${commit.subject} — ${author.name}${issues.length ? ` (${issues.length} issues)` : ''}`, }, }, }, } ``` ## Providers `versioning.provider` selects who writes versions and changelog entries. It accepts one of: | Provider | What it does | | -------------------- | -------------------------------------------------------------------------------------------- | | `default` or omitted | The built-in pipeline: derive the bump, write `package.json` versions and changelog entries. | | `changesets` | Runs `changeset version` and leaves versions/changelogs to changesets. | | `(ctx) => string` | A callback that returns a custom version body (TS/JS configs only). | | `{ id, run(ctx) }` | The same as a callback, with a stable id for readability. | Unknown string ids throw instead of silently falling back to the built-in pipeline. ### Use changesets The changesets provider is for a repository that already uses [changesets](https://github.com/changesets/changesets) for versions and changelogs. It runs the repo-wide `changeset version` and does **not** run the built-in version bump, changelog writer, or version hooks. 1. Install and initialize changesets: ```sh yarn add -D @changesets/cli npx @changesets/cli init ``` This creates `.changeset/config.json`. Commit the `.changeset` directory. 2. Add a changeset with every user-facing change: ```sh npx @changesets/cli ``` 3. Select the provider. Keep `versioning` as an object; `versioning: false` disables the provider with the rest of the versioning section: ```ts ci: { changelog: { versioning: { provider: 'changesets', }, }, } ``` 4. Run `dbx sync` after changing the provider. The generated changelog workflow then also stages the `.changeset/*.md` files that `changeset version` consumes, so the version commit is complete. What changesets owns: * Package versions and `CHANGELOG.md` files. The built-in `target`, `workspaces`, `prerelease`, `bump`, `allowOverBump` and `commit` options are ignored (the changelog-specific `groups`, `intro`, `outro` and `details` options are also not applied). * Publishing/tagging. The provider only runs `changeset version`; run `changeset publish` (or changesets' GitHub Action) for the release itself. The generated release workflow is built around the root `package.json` version, so independent-package releases usually need changesets' own release automation. Behavior: * The command is `npx --yes @changesets/cli version` in the repository root. Set `DBX_CHANGESET_BIN` to run a local binary (or a `.js`/`.mjs` entrypoint) instead. * A missing `.changeset/config.json` fails with a setup hint before any writes. * `--dry-run` explains that changesets owns the output and returns without writing a proposed changelog. * `--version` takes precedence and retags the changelog headings, so do not combine it with the changesets provider. * Version hooks (`beforeVersion`/`afterVersion`) do not run for changesets. * Use changesets' prerelease mode (`changeset pre enter beta`, `changeset pre exit`) for prereleases; `versioning.prerelease` is ignored because changesets owns the version strings. If any versioned target selects `changesets` (for example through a targeted provider entry), changesets runs once for the whole repository. ### Custom providers A callback receives `{ cwd, changelog, records }`, where `cwd` is the repository root and `records` are the commits in the scanned range. Return a string to replace the version body for that target; return `undefined` to keep the built-in body. ```ts ci: { changelog: { versioning: { provider: ctx => { if (ctx.records.length === 0) return 'No user-facing changes.'; return `This release contains ${ctx.records.length} changes.`; }, }, }, } ``` The object form is the same, with an id: ```ts provider: { id: 'release-summary', run: ctx => `${ctx.records.length} commits`, } ``` The provider output is the body inside the version heading; the heading, release markers, package-changes footer and version bump are still written by the built-in pipeline. ### Targeted providers `provider` accepts the same scoped form as the other versioning options. This lets the root and each workspace use a different provider: ```ts ci: { changelog: { versioning: { target: 'individual', provider: [ { target: '.', options: { id: 'root', run: () => 'Root summary' } }, { target: 'packages/ui', options: 'changesets' }, { include: 'apps/*', options: ctx => `${ctx.records.length} app commits` }, ], }, }, } ``` With this config, selecting changesets for `packages/ui` still runs changesets once for the repository; the root and app providers are not used in that run. Without a changesets target, each target uses its own provider. ## Targeted options `prerelease`, `bump.{major,minor,patch}`, `allowOverBump`, `commit` and `provider` accept either the plain value or a scoped form: ```ts ci: { changelog: { versioning: { prerelease: [ { target: 'packages/ui', options: 'beta' }, { include: 'apps/*', options: 'rc' }, ], bump: { minor: [{ target: 'packages/core', options: /^feat/ }] }, allowOverBump: [{ target: 'packages/ui', options: true }], commit: [{ exclude: 'packages/legacy', options: { authorAvatar: true } }], provider: [ { target: '.', options: { id: 'custom', run: ctx => ctx.records.length + ' commits' }, }, ], }, }, } ``` Each scoped entry shares the same selector as `toolchain.changelog.intro` / `outro`: `target` (a workspace path, `.` for the root, or a glob like `apps/*`), `include` and `exclude`. The narrowest matching target wins; when nothing matches, the plain value is used. Workspaces outside `versioning.workspaces` are never considered. A targeted bump rule that does not match a target is **ignored** (not treated as a match-all rule). If no scoped level applies to that target, it falls back to Conventional Commits. If at least one level applies, the target uses the custom rules and unlisted levels do not auto-bump (see [Rules replace Conventional Commits](#rules-replace-conventional-commits)). If a level applies but its matcher does not match any commit, the result is patch (the minimum). `Arrayable` entries (one value or an array) are supported for every targeted option and for the intro/outro settings. ## Collapsible details `versioning.commit.details` wraps changelog sections in markdown `
`/`` blocks. It is enabled by default; `details: false` opts out. * `descriptions` (default on) nests a commit's description body under its bullet as a collapsible whose summary is `**See more...**`. * `breaking` (default on) wraps the breaking section; the summary names the section, so the duplicate heading is not repeated inside. * The version stays a normal `##` heading. `--release-body-wrap` wraps the body with the `**Release notes**` summary and `details.body` is opt-out there; in non-wrapping mode `details.body` is opt-in. * `intro`/`outro`/`footer` are opt-in wrappers; `types` (default on) wraps the CC type sections, leaving the generated `Package changes`/`New contributors` footers alone. Summaries accept inline Markdown, which is converted to HTML (``, ``, ``, links, images and ``) because Markdown is not parsed inside ``. Heading elements are not used there; summaries are bold or plain inline content. ```ts ci: { changelog: { versioning: { commit: { details: { descriptions: { title: 'More', expanded: true }, releaseNotes: { title: 'Release notes' }, intro: true, outro: true, footer: true, breaking: false, types: ['feat', 'fix'], custom: { start: '', end: '' }, }, }, }, }, } ``` * `descriptions` uses `See more...` by default and only applies when the commit has a body; the collapsible is nested under the commit bullet. * `releaseNotes`/`body` use `Release notes` by default; `breaking`/`types` use the section title (bold for breaking). * `intro`, `outro` and `footer` keep inline summaries. * `types` (default on) wraps CC type sections (all types when `true`), using the section title by default. * `minCommits` on a toggle skips the collapsible until that section has at least N commit entries. A top-level `minCommits` sets the default for every section; a nested value wins. The body defaults to **10** commits. * `custom` accepts a regex/string or `{ start, end }` markers; the match (or start match) becomes the summary. Every flag also accepts `{ title?: string; expanded?: boolean }`. ### Details lifecycle `details.lifecycle` controls when wrapping happens: * `after` (default): details are applied to the fully formatted entry. Custom `RegExp`/string searches therefore match the formatted text (bold headings, credits, etc.). * `before`: details are applied while the entry is rendered. `details.body` wraps the whole version body in a collapsible titled `Release notes`. It is opt-in normally and opt-out with `--release-body-wrap`, and requires at least 10 commits (`minCommits`) when enabled unless overridden. Release body wrapping uses `details.releaseNotes` with the same title by default. --- --- url: https://toolchain.dbx.studio/guide/changelog/writing-commit-messages.md --- # Writing commit messages The changelog is rendered from commit **subjects and bodies**, so what you commit is what readers see. Watch out for characters that a **shell** re-interprets — especially when a message is drafted by an **AI/LLM** and committed through `git commit -m "..."`. ## Shell escaping * **PowerShell** treats a backtick as its escape character, so `` `r `` / `` `n `` / `` `t `` / `` `b `` become CR / LF / TAB / backspace. A preceding `\` is left behind, so `` `resolveVite `` can land in the changelog as a stray `\`, a CR and `esolveVite`. * **bash** runs an unquoted `` `...` `` as command substitution, and `$(...)` / `${...}` expand before `git` ever sees them. The result is invisible control characters, stray `\` and dropped letters. `sanitizeText` maps the common control characters back to the letter they replaced (`BEL`→`a`, `BS`→`b`, `FF`→`f`, `VT`→`v`, `TAB`→`t`, `LF`→`n`, `CR`→`r`, `ESC`→`e`, `NUL`→`0`) and drops the stray `\`, so words like `any`, `false` and `bin` are restored. It also repairs the common backtick-to-backslash artifacts (a paired `\yarn cache dir\` or a lone trailing `baseTsdownConfig\`) back to inline code, while leaving Windows paths and regexes alone. A character the shell consumed without leaving a trace still cannot be recovered. ## Authoring safely * Prefer a **file over `-m`**: `git commit -F message.txt`, or a quoted heredoc (`git commit -F - <<'EOF' ... EOF`) — nothing is re-interpreted. Avoid assembling multi-line messages inline in PowerShell. * When an AI/LLM drafts the message, strip **typographic characters** before committing: curly quotes (`’ “ ”`), em/en dashes (`— –`), non-breaking spaces, zero-width characters and emoji all survive into the changelog and can break `commitlint` or the markdown. * **Preview the entry**: `dbx changelog --dry-run` prints the proposed entry — check it for stray `\`, `\r`, `\b`, `\t` or mojibake before releasing. * Prefer to highlight references and nouns like `npm`, `index.ts`, `some/path`, `https://hello.world`, `Vite`, `SomeType`, `funcName()`, `import { ... } from 'yes'`, `#fff`, `a-package-name`, and so on in the commit messages, for better readability for end-users. --- --- url: https://toolchain.dbx.studio/guide/ci.md --- # CI `dbx sync` writes the opted-in workflows for **GitHub Actions**, **GitLab CI** and **Azure Pipelines**. Every workflow is **opt-in**: declare it under `toolchain.ci` to write it; omit it (or set it to `false`) and the toolchain leaves that file unmanaged. Every workflow id (`ci`, `changelog`, `release`, `issues`, `sync`) accepts one of four forms: * `true` / `false` — write the generated GitHub default, or skip it; * a **`WorkflowOptions` object** — override parts of the GitHub default (branches, triggers, extra top-level keys, extra steps/jobs, token overrides); * a **complete vendor workflow** — `{ provider, workflow }` for `github`, `gitlab` or `azure`, written as-is; * a **raw YAML string** — written **verbatim** as the workflow file, for a workflow the object model can't express. ```ts [dbx.config.ts] export default defineConfig({ toolchain: { ci: { ci: true, // the generated GitHub CI checks issues: false, // don't write issues.yml release: { pushBranches: ['main'] }, // override the GitHub default changelog: { branches: { main: 'main', dev: 'dev' } }, // A complete GitLab pipeline, written to `.gitlab-ci.yml`: sync: { provider: 'gitlab', workflow: { stages: ['check'], check: { stage: 'check', script: ['yarn dbx sync --check'] }, }, }, }, }, }); ``` A raw string is **not** merged with the default, is **not** token-replaced, and gets **no generated header** — it is the file's exact content. The `ci.changelog.branches` defaults don't apply to it either (it defines its own triggers). An empty string disables the workflow. The `ci` key doubles as the CI-checks workflow (`ci.yml`) and the section name, so `toolchain.ci.ci` is the checks workflow. Set `toolchain.ci.enabled` to `false` to disable the whole section (and every nested workflow) at once. ## Vendor workflows A complete vendor workflow always has `provider` and `workflow`; `filename`, `dir` and `enabled` are optional: | `provider` | Default file | Run with | | ---------- | --------------------- | ------------------ | | `github` | `.github/workflows/` | `gh workflow run` | | `gitlab` | `.gitlab-ci.yml` | `glab ci run` | | `azure` | `azure-pipelines.yml` | `az pipelines run` | ```ts [dbx.config.ts] toolchain: { ci: { // .gitlab-ci.yml (the default GitLab path) ci: { provider: 'gitlab', workflow: { stages: ['test'], test: { stage: 'test', script: ['yarn test'] } }, }, // azure-pipelines.yml (the default Azure path) release: { provider: 'azure', workflow: { trigger: ['main'], pool: { vmImage: 'ubuntu-latest' }, steps: [] }, }, // A complete GitHub workflow, written to the default `.github/workflows/deploy.yml` custom: { deploy: { provider: 'github', workflow: { name: 'Deploy', on: { push: { branches: ['main'] } }, jobs: { deploy: { 'runs-on': 'ubuntu-latest', steps: [] } }, }, }, }, }, } ``` `filename` and `dir` override the generated path for any provider. The workflow object is written as-is (only the toolchain's {{ token }} replacements are applied), so it must be a complete pipeline. `dbx workflow` dispatches each workflow with its vendor CLI — see [CLI](/guide/cli#tsconfig-cleanup-changelog-workflows). ## Typed GitHub workflows If you prefer a typed builder over hand-writing YAML, use [`@github-actions-workflow-ts/lib`](https://github.com/emmanuelnk/github-actions-workflow-ts) (and its `@github-actions-workflow-ts/actions` catalog). The builder produces a plain workflow object in `.workflow`, which the `github` vendor form accepts: ```ts [dbx.config.ts] import { ActionsCheckoutV4, ActionsSetupNodeV4 } from '@github-actions-workflow-ts/actions'; import { NormalJob, Step, Workflow } from '@github-actions-workflow-ts/lib'; import { defineConfig, type GitHubWorkflow } from '@deltabox/toolchain'; const test = new NormalJob('test', { 'runs-on': 'ubuntu-latest' }); test.addStep(new ActionsCheckoutV4({ name: 'Checkout' })); test.addStep(new ActionsSetupNodeV4({ name: 'Setup Node', with: { 'node-version': '22' } })); test.addStep(new Step({ name: 'Test', run: 'yarn test' })); const ci = new Workflow('ci.yml', { name: 'CI', on: { push: { branches: ['main'] } }, }); ci.addJob(test); export default defineConfig({ toolchain: { ci: { ci: { provider: 'github', workflow: ci.workflow as unknown as GitHubWorkflow, }, }, }, }); ``` The toolchain does not depend on the builder, so the `workflow` field is typed from its own vendored GitHub schema. The two schemas can drift slightly (for example the builder's `Partial` makes `on` optional, and its `permissions` allows `id-token: read`), so cast the object when TypeScript rejects it. At runtime the workflow is validated by GitHub, exactly like a hand-written object. ## Workflows | Workflow | GitHub file | Page | | ---------- | ---------------- | ----------------------------------------- | | CI checks | `ci.yml` | [CI checks](/guide/ci/ci) | | Changelog | `changelog.yml` | [Changelog workflow](/guide/ci/changelog) | | Release | `release.yml` | [Releases](/guide/ci/releases) | | Issues | `issues.yml` | [Issues](/guide/ci/issues) | | Toolchain | `sync.yml` | [Sync](/guide/ci/sync) | | Dependabot | `dependabot.yml` | [Dependabot](/guide/ci/dependabot) | `ci.dependabot.security` additionally writes `.github/workflows/dependabot-security.yml` to enable GitHub's native security updates and apply a severity threshold. Extra workflows can be defined under `toolchain.ci.custom.` (for example `ci.custom.deploy` writes `.github/workflows/deploy.yml`, or the vendor default when it sets `provider`). Each accepts the same workflow forms, plus `filename` and `dir` overrides. See [Workflow settings](/guide/ci/settings) for the shared object options and the [Changelog](/guide/changelog/) guide for the versioning/commitlint pipeline. --- --- url: https://toolchain.dbx.studio/guide/ci/changelog.md --- # Changelog workflow The `ci.changelog` workflow (`changelog.yml`) generates the changelog and applies the version bump. It runs on every push to `ci.changelog.branches.dev` (or `main` when `dev` is not set), then commits the updated `CHANGELOG.md` files and `package.json` versions back to the branch. ```ts [dbx.config.ts] toolchain: { ci: { changelog: { branches: { main: 'main', dev: 'dev' }, pushBranches: ['dev'], // optional per-workflow override }, }, } ``` `ci.changelog` is also the changelog **pipeline** config. Its options are documented in the [Changelog](/guide/changelog/) guide: * [Branches](/guide/changelog/branches) * [commitlint](/guide/changelog/commitlint) * [Versioning](/guide/changelog/versioning) * [CLI](/guide/changelog/cli) The workflow is opt-in (`ci.changelog: true` or an object). `ci.changelog: false` leaves it unmanaged; `ci.changelog.commitlint: false` still generates the workflow but skips commitlint, its config and the local hook. `ci.changelog` inherits the manual `toolchain.changelog` pipeline options when it does not set them itself (for example `ci.changelog: true` or an object that only sets workflow options like `pushBranches`). Explicit `ci.changelog` options win; `branches` only exists on `ci.changelog`. The workflow itself can target another vendor with `{ provider, workflow }` (GitLab/Azure); the versioning/commitlint pipeline still lives in `toolchain.changelog` (or the `ci.changelog` object options), not in the vendor workflow. See [Workflow settings](/guide/ci/settings#vendor-workflows). --- --- url: https://toolchain.dbx.studio/guide/ci/ci.md --- # CI checks The `ci.ci` workflow (`ci.yml`) is the repository's main check. It runs on pushes to `ci.changelog.branches.main` and on pull requests to the generated branch globs, and its default job: 1. checks out the repo, then sets up the toolchain: a Vite/Vite+ project uses [`voidzero-dev/setup-vp`](https://viteplus.dev/guide/ci) (which installs Vite+, Node.js and the package manager, then runs `vp install`), while any other project sets up Node and Corepack and installs dependencies; 2. runs commitlint over the pushed range — **removed when commitlint is disabled** with `ci.changelog.commitlint: false`; 3. runs `dbx sync --check` so generated files cannot drift; 4. runs the package manager's `build`. ```ts [dbx.config.ts] toolchain: { ci: { ci: { pullRequestBranches: ['main', 'dev', 'release/**', 'dependabot/**'], steps: { after: [ { name: 'Format + lint', run: 'yarn check:fix' }, { name: 'Test', run: 'yarn test' }, ], }, }, }, } ``` Use [Workflow settings](/guide/ci/settings) for the shared options, including how a project is detected as Vite+ and how to force or disable that setup. The workflow is opt-in: `ci: { ci: true }` writes it; omitting `ci.ci` (or setting it to `false`) leaves the file unmanaged. Set `provider` (`gitlab`/`azure`) with a complete `workflow` object to write that vendor's pipeline instead. --- --- url: https://toolchain.dbx.studio/guide/ci/dependabot.md --- # Dependabot `ci.dependabot` writes `.github/dependabot.yml` so GitHub keeps the project's dependencies and pinned actions up to date, and can additionally enable native Dependabot security updates with grouped or individual PRs. Like every workflow it is **opt-in**: omit it (or set it to `false`) and the file is left unmanaged. ```ts [dbx.config.ts] toolchain: { ci: { dependabot: true, }, } ``` By default the config watches the **GitHub Actions** and **npm** ecosystems at the repository root with a **weekly** schedule. The `github-actions` entry also keeps pinned actions such as [`voidzero-dev/setup-vp`](https://viteplus.dev/guide/ci#automatic-version-updates), `actions/checkout` and `actions/setup-node` current, so a Vite+ CI setup does not drift. ```yaml [.github/dependabot.yml] version: 2 updates: - package-ecosystem: github-actions directory: / schedule: interval: weekly - package-ecosystem: npm directory: / schedule: interval: weekly ``` ## Security updates GitHub's native Dependabot security updates open PRs for vulnerable dependencies. They are a **repository setting**, not a `dependabot.yml` option, so `ci.dependabot.security` does two things: 1. Adds a `security-updates` group (`applies-to: security-updates`) to the generated `dependabot.yml` when the PR strategy is `grouped`. 2. Generates `.github/workflows/dependabot-security.yml`, which runs on the Dependabot schedule and enables (or disables) Dependabot security updates through the REST API. When a severity threshold is configured, it also dismisses alerts below that threshold so Dependabot does not open PRs for them. ```ts [dbx.config.ts] toolchain: { ci: { dependabot: { security: { vulnerabilities: { severity: 'high' }, pr: { strategy: 'grouped' }, }, }, }, } ``` `security: true` is shorthand for: ```ts security: { vulnerabilities: { severity: 'all' }, pr: { strategy: 'grouped' }, workflow: true, } ``` With the grouped strategy the generated config contains: ```yaml [.github/dependabot.yml] groups: security-updates: applies-to: security-updates patterns: - '*' ``` Choosing `pr: { strategy: 'individual' }` omits that group, so Dependabot opens one security PR per update. User-defined groups with `applies-to: security-updates` are kept as-is. The workflow needs a **repository administrator** token to change the repository setting. Create a `DBX_GITHUB_TOKEN` secret with `administration: write` (fine-grained) or the `repo` scope (classic). The workflow falls back to `GITHUB_TOKEN` for the alert-dismissal step (which works with the workflow's `security-events: write` permission), but `GITHUB_TOKEN` cannot enable the repository setting. If the token is missing, the step logs a warning and leaves the setting untouched. `severity` is applied by the generated workflow because `dependabot.yml` has no severity filter. It dismisses lower-severity alerts with the `not_used` reason; if you later lower the threshold, re-open those alerts manually. For native pre-alert filtering, use GitHub's auto-triage rules and set `security: { workflow: false }` so the toolchain does not manage the repository setting. Set `security: { vulnerabilities: false }` to disable Dependabot security updates; the generated workflow calls the disable endpoint. Set `security: { workflow: false }` to leave both the repository setting and alert dismissal to you. > `allow` also filters security updates. If you use it to narrow version > updates, include `'*'` (or every package you want protected) so vulnerability > PRs are not restricted. `update-types` rules still only affect version > updates, so the usual major-version `ignore` does not suppress security fixes. ## Options ```ts [dbx.config.ts] toolchain: { ci: { dependabot: { schedule: 'daily', directories: ['/', '/packages/api'], ecosystems: ['github-actions', 'npm'], labels: ['dependencies'], openPullRequestsLimit: 5, groups: { minor: { 'update-types': ['minor', 'patch'] }, }, security: { vulnerabilities: { severity: 'high' }, pr: { strategy: 'grouped' }, }, // Allow only the packages you actually want updated... allow: { npm: [ { 'dependency-name': 'vite' }, { 'dependency-name': 'vite-plus' }, ], 'github-actions': [{ 'dependency-name': '*' }], }, // ...and never cross a major version automatically. ignore: { npm: [ { 'dependency-name': '*', 'update-types': ['version-update:semver-major'], }, ], }, dir: '.github', // default filename: 'dependabot.yml', // default }, }, } ``` | Option | Default | What it does | | ----------------------------------- | --------------------------- | ---------------------------------------------------------- | | `schedule` | `weekly` | `daily`, `weekly` or `monthly`. | | `directories` | `['/']` | Directories to scan. | | `ecosystems` | `['github-actions', 'npm']` | Package ecosystems. | | `labels` | none | Labels added to the update PRs. | | `openPullRequestsLimit` | Dependabot default (5) | Maximum open update PRs per entry. | | `groups` | none | Update groups (patterns / update types). | | `security` | off | Enable security updates (boolean or object). | | `security.vulnerabilities` | `true` | Open PRs for vulnerable dependencies. | | `security.vulnerabilities.severity` | `all` | Keep alerts at/above a severity, or the listed severities. | | `security.pr.strategy` | `grouped` | `grouped` (one PR per ecosystem) or `individual`. | | `security.workflow` | `true` | Generate the workflow that applies the setting. | | `allow` | none | Allow rules (an array, or keyed by ecosystem). | | `ignore` | none | Ignore rules (an array, or keyed by ecosystem). | | `dir` / `filename` | `.github/dependabot.yml` | Generated path overrides. | | `enabled` | `true` when present | Set `false` to opt out explicitly. | A hand-written `.github/dependabot.yml` without the generated header is left untouched and reported as a conflict, exactly like a hand-written workflow. --- --- url: https://toolchain.dbx.studio/guide/ci/issues.md --- # Issues The `ci.issues` workflow (`issues.yml`) normalizes new issue titles from the issue's labels: a bug-labelled issue gets a `[bug]` prefix, an enhancement/feature/feat-labelled issue gets `[feat]`; issues without either label are left untouched. ```ts [dbx.config.ts] toolchain: { ci: { issues: true, }, } ``` The workflow is opt-in and only runs on `issues: opened`. It needs the `issues: write` permission, which the generated default declares. Use [Workflow settings](/guide/ci/settings) to change its triggers or add jobs, or set `provider` with a complete GitLab/Azure `workflow` to target another vendor. --- --- url: https://toolchain.dbx.studio/guide/ci/releases.md --- # Releases The generated `ci.release` workflow (`release.yml`) opens a release PR whose body is the **aggregated changelog**: every entry from the last released version up to the latest one, not just the newest entry. So a release that skips versions (eg. `v1.7.0` → `v1.7.8`) still documents `1.7.1`–`1.7.8` in one place. The body is produced by `dbx changelog --release-body `, which only considers versions that actually appear in `CHANGELOG.md` (so unrelated CI/calendar tags are ignored). For a first release, when there is no prior version, it falls back to the newest changelog entry instead of the whole file. See [Release bodies](/guide/changelog/release) for the extraction and grouping options. ```ts [dbx.config.ts] toolchain: { ci: { release: { pushBranches: ['main'] }, }, } ``` The workflow is opt-in. Use [Workflow settings](/guide/ci/settings) to override the job's extra steps/jobs or supply a fully hand-authored workflow. It can also be a complete GitLab/Azure pipeline via `{ provider, workflow }`. ## Grouped release bodies Set `changelog.release.group: true` to collapse every version since the previous published release into one body, so a stable release documents the whole prerelease cycle instead of only the last beta. See [Release bodies](/guide/changelog/release#grouped-release-bodies) for grouping, `includePrereleases`, `since`, CLI overrides, the boundary rules and individual-versioning behavior. ## GitHub prereleases `ci.release.prerelease` controls whether a release job marks a version with a prerelease suffix (for example `3.0.0-beta.2`) as a GitHub prerelease: | Value | Behavior | | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | `'auto'` | **Default.** Mark the release when the version contains a `-`; everything from the first `-` is the prerelease identifier (eg. `1.4.2-beta.4`). | | `true` | Always mark the release as a prerelease. | | `false` | Never mark the release; every version is a normal release. | Prerelease versions are not marked as the latest release. The default `ci.release` job only opens the release PR; it does not create the GitHub Release itself. When you replace that job with one that creates the release, pass `--prerelease` conditionally. The `{{ releasePrerelease }}` token carries the setting: ```yaml run: | version="$(node -p "require('./package.json').version")" args=(--title "v$version" --notes-file RELEASE_NOTES.md) prerelease="{{releasePrerelease}}" if [ "$prerelease" = "true" ] || { [ "$prerelease" = "auto" ] && [[ "$version" == *-* ]]; }; then args+=(--prerelease) fi gh release create "v$version" "${args[@]}" "dist/artifact" ``` The default is automatic detection, so this is usually all you need: ```ts ci: { release: { prerelease: 'auto', }, } ``` Disable it for every release job: ```ts ci: { release: { prerelease: false, }, } ``` Or force every release, including stable versions, to be marked: ```ts ci: { release: { prerelease: true, }, } ``` The managed release job in this repository uses `{{ releasePrerelease }}` for its `gh release create` step, so a beta such as `3.0.0-beta.17` is published as a GitHub prerelease. --- --- url: https://toolchain.dbx.studio/guide/ci/settings.md --- # Workflow settings A workflow can be a boolean, a raw YAML string, a complete vendor workflow (`{ provider, workflow }`), or a `WorkflowOptions` object. The object is merged over the generated GitHub default, so you only describe what changes. These options apply to every GitHub workflow (`ci`, `changelog`, `release`, `issues`, `sync`). ```ts [dbx.config.ts] toolchain: { ci: { ci: { enabled: true, pushBranches: ['main', 'next'], pullRequestBranches: ['main', 'release/**'], triggers: { schedule: [{ cron: '0 6 * * *' }] }, tokens: { nodeVersion: '24' }, extra: { permissions: { contents: 'read' } }, steps: { after: [{ name: 'Lint', run: 'yarn lint' }], }, jobs: { smoke: { 'runs-on': 'ubuntu-latest', steps: [{ run: 'echo ok' }], }, }, }, }, } ``` | Option | What it does | | --------------------- | ------------------------------------------------------------------------------- | | `enabled` | Enable/disable this workflow (default: enabled when present). | | `provider` | Vendor for a complete `workflow` object (default `github`). | | `pushBranches` | Replace `on.push.branches`. | | `pullRequestBranches` | Replace `on.pull_request.branches`. | | `triggers` | Merge extra `on.*` triggers. | | `extra` | Merge extra top-level keys (`permissions`, `concurrency`, `env`, ...). | | `steps` | Inject steps before/after a job's generated steps (one group or per-job). | | `jobs` | Merge extra complete jobs. | | `tokens` | Override workflow tokens (`nodeVersion`, `packageManager`, `yarnVersion`, ...). | | `filename` | Override the generated file name (default `ci.yml`, `release.yml`, ...). | | `dir` | Override the output directory (default `.github/workflows`). | ## Steps `steps` accepts one group or an array of groups. A group targets a job id (default: the first/primary job) and can add steps before or after the generated ones: ```ts steps: [ { job: 'ci', before: [{ name: 'Install extras', run: 'yarn add -D foo' }] }, { job: 'ci', after: [{ name: 'Smoke', run: 'yarn smoke' }] }, ]; ``` ## Tokens The default workflow templates use {{ token }} replacements. `tokens` merges over the project-wide values, so one workflow can use a different Node version or package manager without changing `project`. Overriding `packageManager` switches to that manager's default version unless you also set `packageManagerVersion` (or the legacy `yarnVersion` alias). `tokens.releasePrerelease` is seeded from `ci.release.prerelease` (default `auto`) for release jobs. Custom release steps can use {{ releasePrerelease }} to decide whether to pass `gh release create --prerelease`; see [Releases](/guide/ci/releases#github-prereleases). ## Vite+ projects For a Vite/Vite+ project the generated workflows install `vp` with the [`voidzero-dev/setup-vp`](https://viteplus.dev/guide/ci) integration instead of the Node/Corepack/package-manager install steps. The GitHub Action also sets up the project's Node.js version and the package manager, and runs `vp install`. A project is detected as Vite/Vite+ when any of these is true: * its `package.json` declares `vite-plus` (checked up to the repository root, so a hoisted workspace dependency counts); * it has a `vite.config.*` at the project root; * the toolchain's `vite` section is enabled (the dbx-managed Vite+ mode). Override the detection per workflow with `tokens.vitePlus` (`true` forces the setup-vp path, `false` keeps the Node/Corepack path). `tokens.setupVpVersion` pins a different exact `setup-vp` release or commit SHA; the action has no moving tag, so always pin an exact version. ```ts [dbx.config.ts] toolchain: { ci: { ci: { tokens: { setupVpVersion: 'v1.30.0' } }, sync: { tokens: { vitePlus: false } }, }, } ``` The other vendors use their own `setup-vp` integration when `setup: true` is set on a complete pipeline: * **GitLab** adds the reusable remote template to `include` (`setup-ref` pinned to the same version) and adds `extends: .setup-vp` to every job. The template does not install Node.js, so the pipeline still gets a `node:` image. * **Azure** adds the `setupVp` repository resource (`ref` pinned to the version) and the `azure/setup-vp.yml@setupVp` template step with `setupRef`/`nodeVersion`/`cache`/`runInstall`. A job that already defines a checkout or the template step is left alone. ```yaml [.gitlab-ci.yml] include: - remote: https://raw.githubusercontent.com/voidzero-dev/setup-vp/v1.22.0/gitlab/setup-vp.yml inputs: setup-ref: v1.22.0 image: node:22 test: extends: .setup-vp stage: test script: [yarn test] ``` Set `tokens.vitePlus: false` on a vendor workflow to keep its Node/Corepack setup instead. ## Raw YAML A string is used as the workflow file's exact content. It is not merged, not token-replaced and gets no generated header; an empty string disables it. ## Vendor workflows Set `provider` (`github`, `gitlab` or `azure`) with a complete `workflow` object to write another CI vendor's pipeline instead of the generated GitHub default. The object is written as-is (with the toolchain's {{ token }} replacements applied), so it must be a complete pipeline: ```ts [dbx.config.ts] toolchain: { ci: { ci: { provider: 'gitlab', workflow: { stages: ['test'], test: { stage: 'test', script: ['yarn test'] }, }, }, release: { provider: 'azure', workflow: { trigger: ['main'], pool: { vmImage: 'ubuntu-latest' }, steps: [{ script: 'yarn build' }], }, }, }, } ``` The default paths are `.gitlab-ci.yml` and `azure-pipelines.yml` (GitHub keeps `.github/workflows/.yml`); `filename` and `dir` override them. A complete vendor workflow defines its own triggers, so the `ci.changelog.branches` defaults do not rewrite them. `dbx workflow` runs each workflow with its vendor CLI (`glab ci run`, `az pipelines run --name `, or `gh workflow run`). Set `setup: true` to inject the provider-specific setup before the pipeline's own steps: GitHub gets the checkout/Node/Corepack/install steps, GitLab gets a `node:` image plus a `before_script`, and Azure gets `UseNode@1` plus an install script. It defaults to `false`, so the workflow is written as-is. If a hand-written `.gitlab-ci.yml` / `azure-pipelines.yml` already exists, sync leaves it untouched and records a workflow conflict, exactly like a GitHub workflow. Set `ci.: { enabled: false }` to opt out explicitly. ## Custom workflows Add any number of extra workflows with `toolchain.ci.custom`, keyed by workflow id. A custom workflow is enabled by **presence** (there is no boolean form): a string is written verbatim, a complete vendor workflow (`{ provider, workflow }`) is written as-is, or an object is merged over an empty GitHub workflow — build it with `triggers`, `extra` and `jobs` (plus `filename` / `dir`): ```ts [dbx.config.ts] toolchain: { ci: { custom: { deploy: { triggers: { workflow_dispatch: {}, push: { branches: ['main'] } }, filename: 'deploy.yml', // default: deploy.yml dir: '.github/workflows', // default jobs: { deploy: { 'runs-on': 'ubuntu-latest', steps: [ { uses: 'actions/checkout@v4' }, { run: 'yarn deploy' }, ], }, }, }, }, }, } ``` This writes `.github/workflows/deploy.yml` and manages it like any built-in workflow (the generated header is prepended, and `dbx sync --check` tracks it). Set `setup: true` to inject the shared checkout/Node/Corepack/install steps into each job; steps the job already defines are not duplicated. ## Existing workflows If a generated workflow path already contains a hand-written workflow that dbx has never managed (no manifest entry and no generated header), `dbx sync` leaves it untouched, warns, and records the conflict in `.dbx/toolchain/manifest.json`. Set `ci.: { enabled: false }` (or, for a custom workflow, `ci.custom.: { enabled: false }`) to make the opt-out explicit. The file is also never deleted when the workflow is later disabled, because dbx did not create it. Use `dbx workflow --list` (or `--list --json`) to see the enabled workflows and their exact paths; `dbx workflow ` honours `filename` and `dir` overrides. --- --- url: https://toolchain.dbx.studio/guide/ci/sync.md --- # Sync The `ci.sync` workflow (`sync.yml`) verifies that every generated file is up to date: it runs `dbx sync --check` on pushes (to both the `main` and `dev` branch globs) and on pull requests. A drift in a workflow, tsconfig, `vite.config.ts` or any other managed file fails the job. ```ts [dbx.config.ts] toolchain: { ci: { sync: true, }, } ``` The workflow is opt-in. The `ci` check workflow also runs `dbx sync --check`, so `sync.yml` is useful when you want the check to run on pull requests without the full build. See [Workflow settings](/guide/ci/settings) for trigger overrides, or set `provider` with a complete GitLab/Azure `workflow` to target another vendor. --- --- url: https://toolchain.dbx.studio/guide/migrations.md --- # Migrations `dbx migrate` converts a project's tooling config from another tool to **Oxc** (Oxfmt + Oxlint), or folds an existing Oxc/Vite config into `dbx.config.*`. Migrations are pluggable — adding a source tool is a matter of implementing one interface. ```sh dbx migrate:list # what's available + detected dbx migrate --from biome # dry-run dbx migrate --from biome --write # writes the oxc config dbx migrate --from biome --target vite --write dbx migrate --from biome --from prettier --write # several sources dbx migrate --from oxc --write # fold .oxfmtrc/.oxlintrc into dbx.config dbx migrate --from all # every detected source dbx migrate --check # CI: exit 1 when the oxc config is stale dbx migrate --from eslint --online --write # flat config via @oxlint/migrate ``` `dbx migrate` is a dry-run unless you pass `--write` (or `--check`). `--from` is repeatable; `--from all` (or omitting it) selects every detected source. ## Upgrading from v2 See the [v2 → v3 migration guide](/guide/migrations/v2-v3). ## Upgrading from v1 See the [v1 → v2 migration guide](/guide/migrations/v1-v2). ## Sources | Source | Notes | | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `biome` | Formatter options, `files.includes` negations → `ignorePatterns`, **`organizeImports.groups` → Oxfmt `sortImports`**, and a curated Biome → Oxlint rule map. | | `prettier` | Prettier-compatible options transfer directly; Tailwind/PackageJson plugins detected; `.prettierignore` → `ignorePatterns`. | | `eslint` | JSON configs map rule names + severities (`@typescript-eslint/*` → `typescript/*`); JS/flat configs use `@oxlint/migrate` with `--online --write`. | | `dprint` | `dprint.json` layout + TypeScript options → Oxfmt. | | `oxc` | Folds `.oxfmtrc.json` / `.oxlintrc.json` into `dbx.config.*`'s `toolchain.fmt.oxc` / `toolchain.lint.oxc`; `dbx sync` manages them again. | | `vite` | Folds a hand-written `vite.config.*` into `dbx.config.*`'s `toolchain.vite` (see below). | ## Targets * `--target files` (default) — writes `.oxfmtrc.json` and `.oxlintrc.json`. * `--target vite` — folds the result into an existing `vite.config.ts` (inserting/replacing `fmt` and `lint`), which is what Vite+ reads. * The `oxc` source targets `dbx.config.*` (`toolchain.fmt.oxc` / `toolchain.lint.oxc`, or `toolchain.vite.fmt/lint` when `--target vite`). Unless `--target` is given, formatter/linter migrations route by what the existing Vite config already owns: * If `vite.config.*` (or an existing `toolchain.vite`) defines `fmt`/`lint`, the migrated options are merged into `toolchain.vite.fmt`/`toolchain.vite.lint`, and no top-level `toolchain.fmt`/`toolchain.lint` is created. * Otherwise they are folded into the top-level `toolchain.fmt.oxc` / `toolchain.lint.oxc`, and `vite.fmt`/`vite.lint` are left undefined. ## Recursive migration By default `dbx migrate` only touches the root (`--cwd`, or the current directory). `--recursive` walks the discovered projects under the root and migrates each one that has a **detected source**: ```sh dbx migrate --from biome --from prettier --recursive --write ``` On an interactive terminal it first asks which projects to migrate with a multi-select — every candidate is listed by its relative path (with its package name as a hint), plus an **All projects** option. Non-interactive runs (piped output, CI, or `--json`) migrate every candidate without prompting. A project is a candidate when a migration matching `--from` (or any migration, for `all`/no `--from`) is detected in its directory — so a workspace with its own `biome.json` or `vite.config.*` is included, and one without is skipped. ## `vite.config` The `vite` source moves a hand-written `vite.config.*` into `dbx.config.*`'s `toolchain.vite`, so the whole Vite+ config lives in the one hand-authored config and `dbx sync` writes a thin `vite.config.ts` shim that resolves it at load time: ```sh dbx migrate --from vite # dry-run: shows what would fold in dbx migrate --from vite --write # folds the object into toolchain.vite dbx sync # writes the managed vite.config.ts shim ``` When the folded config already owns `fmt`, it adds `/vite.config.ts` to `toolchain.vite.fmt.ignorePatterns`, so Oxfmt leaves the generated shim alone (otherwise `vp fmt` would rewrite it and `dbx sync --check` would report drift). When it does not, `vite.fmt` stays undefined; the default fmt ignores already cover `**/vite.config.ts`. It extracts the object literal passed to `defineConfig(...)` (or the default-exported object) with a string-aware, balanced-paren scanner and text-splices it into the nearest `dbx.config.*`: it inserts `vite: { ... }`, or **deep-merges** into an existing `toolchain.vite` (nested objects are combined; arrays and scalars from the vite config win), so its settings are kept. A previous `config: false` opt-out is flipped to `config: true`, since the hand-written file is being removed. When the config references imports, plugins or any non-literal expression it is reported as **unmapped** and nothing is written, rather than emitting broken output. A JSON `dbx.config.json` is also left alone (the object is folded by hand). When the project has a `vite.config.*` but **no** `dbx.config.*` (a workspace that never had one), the migration creates a fresh `dbx.config.ts` holding the folded `toolchain.vite`, wrapped in `defineConfig` from `@deltabox/toolchain` (like the scaffold). A workspace resolves that import through the root's installed dependency — in a self-hosted repo, via a root `portal:.` self-link. The now-redundant `vite.config.*` is removed and recreated by `dbx sync` as a shim that imports `defineConfig` from the project's own Vite package (`vite` or `vite-plus`, detected from `package.json`). Pass `--ignore-vite-config-file` to keep the original file. ### Nested configs In a monorepo, pass `--recursive` to fold **each workspace's** own `vite.config.*` into that workspace's `dbx.config.*` (creating one when it is missing) instead of the root's: ```sh dbx migrate --from vite --recursive --write ``` Without `--recursive`, only the root's `vite.config.*` is migrated and nested ones are left alone. Detection is per project root (a directory with a `package.json` or `dbx.config.*`, up to five levels deep), so a `vite.config.*` in a deeper subdirectory of a project is not discovered. A workspace with no `dbx.config.*` gets a fresh one holding just its `toolchain.vite`; it inherits the rest of the config from the nearest ancestor at load time. ## Post-migration sync A `--write` run finishes by regenerating the project's toolchain-managed files (the same files `dbx sync` writes) for every project it changed — so a migrated project is immediately consistent, eg. the managed `vite.config.ts` shim appears right after folding a hand-written config. Two flags narrow that step: | Flag | Effect | | ------------------------ | ------------------------------------------------------------------------- | | `--ignore-managed-files` | Skip the post-migration sync entirely; managed files are left untouched. | | `--ignore-changelog` | Run the sync but drop the `changelog` task (workflows, commitlint, hook). | The sync only runs after `--write`; a dry-run reports what it would do instead. ## Package scripts `dbx migrate` migrates the tooling **files**; the matching `package.json` scripts are a small follow-up. The common swaps: | Before | After | | ------------------------ | --------------------------- | | `biome format --write .` | `dbx fmt` | | `biome check --fix .` | `dbx lint --fix` | | `turbo build` | `dbx run -r build` | | `turbo typecheck` | `dbx run -r typecheck` | | `turbo test` | `dbx run -r test` | | `turbo dev` | `dbx run -r --parallel dev` | Then drop `@biomejs/biome` + `turbo` (and `biome.json` + `turbo.json`) and add `@deltabox/toolchain` + `vite-plus`. The full walkthrough — recommended scripts, the dependency diff and per-workspace tasks — is on the [Package scripts](/guide/scripts) page. ## CI check `--check` runs the migrations without writing and exits non-zero when a target file is missing or differs from what the migration would produce, so a pipeline can require that a repo is fully on Oxc: ```sh dbx migrate --check || echo "still on Biome/etc — run migrate --write" ``` The check resolves the **effective** `dbx.config.*` (including an inherited ancestor config), so a workspace that inherits `fmt`/`lint` from the root is not asked to keep an intermediate `.oxfmtrc.json` / `.oxlintrc.json`. A disabled section (`fmt: false`) does not count as owning the config. `--online` allows network access: the ESLint migration shells out to `@oxlint/migrate` to evaluate JS/flat configs (it writes `.oxlintrc.json`, so it runs only together with `--write`). ## Honest output Anything that cannot be mapped faithfully is reported instead of dropped: ``` unmapped (7): - organizeImports !lucide*: negated group members are approximated - linter.rules.suspicious.noUnknownAtRules: no Oxlint equivalent ``` ## Programmatic ```ts import { listMigrations, detectMigrations, runMigration } from '@deltabox/toolchain/migrate'; const detected = detectMigrations(process.cwd()); const result = await runMigration('biome', { cwd: process.cwd(), target: 'vite', write: true }); console.log(result.unmapped); ``` ## Notes `oxfmt --migrate biome`-style tools cover formatter options only; the pieces the upstream tools skip (Biome `organizeImports`, Biome linter rules, Dprint) are handled here. --- --- url: https://toolchain.dbx.studio/guide/migrations/v1-v2.md --- # Migrating from v1 to v2 **v2** focuses on a smaller, schema-driven config-generator API. Most runtime features keep working, but the programmatic config-generator surface is a breaking change. ## Breaking changes ### `ConfigScopes` and `ConfigScopeDef` are gone Pass a `ConfigSchema` directly. It accepts a Zod schema, an untyped `Schema`, an array of schemas, or a record keyed by scope. ```ts // v1 const engine = createConfigEngine({ scopes: { server: { zodSchema: serverConfig }, cli: { zodSchema: cliConfig }, }, }); // v2 const engine = createConfigEngine({ schema: { server: serverConfig, cli: cliConfig }, }); ``` `ConfigSchemaType` is the untyped `Schema` plus the toolchain's `ConfigMeta`. ### Render functions are internal Use the `generateConfig*` functions or the engine methods. They return generated contents and only write when you pass an output directory/path. ```ts // v1 renderConfigTypes(scopes, { outputDir }); renderScopeMarkdown(scopes, { outDir }); // v2 generateConfigTypes(schema, { outputDir }); generateConfigMarkdown(schema, { outputDir }); ``` Set `outputDir: false` (or omit it) to generate without writing. ### Schema maps were removed `CONFIG_SECTION_SCHEMAS`, `CONFIG_TYPE_SCHEMAS` and `CONFIG_SECTION_DESCRIPTIONS` were removed. Use `configSchema` (the section schemas) or `dbxConfigSchema`, and read descriptions from each schema's `.describe()` / `.meta()`. ### Metadata is the source of truth Generators read `ConfigMeta` from Zod `.meta()` or from untyped schema nodes. `env`/`path` are deprecated in favour of `envName`/`envPath`; `cliFlag` and `cliFlagShort` customize CLI flags. Types can use `typeName` / `id` to control the generated interface name. ### Collection names * `collectEnvVars` → `collectVars` * `collectRequiredEnvVars` → `collectRequired` * `EnvVarDef` → `ConfigDef` * `EnvValueType` → `ConfigValueType` * engine `requiredEnvVars` → `requiredVars` * `writeMarkdown({ outDir })` → `writeMarkdown({ outputDir })` ## Behaviour changes * `toolchain.fmt` / `toolchain.lint` shorthand (`true` or `{ vscode: ... }`) now infers a tool from installed packages, then VS Code user settings, then falls back to Oxc defaults. Existing user config files are folded through the migration mappings instead of being overwritten. * Formatter/linter conflict warnings use `fmt.conflict` / `lint.conflict`. Missing tools warn with `fmt.no-tool` / `lint.no-tool`. * `fmt.vscode` / `lint.vscode` only add `editor.defaultFormatter`, language blocks and `editor.codeActionsOnSave`; use `{ overrides, exclude }` to adjust them. * A custom logger can be supplied through `toolchain.logger.logger`. * Changelog versioning supports custom bump rules/callbacks, over-bump opt-in, provider selection and commit credit/format options. ## tsconfig changes ### Resolve paths/references programmatically or from the CLI **v2** adds a extends-aware resolver. Use it instead of hand-rolling alias parsing: ```ts import { resolveTsconfig } from '@deltabox/toolchain/tsconfig'; const { alias, paths, references } = resolveTsconfig({ root: process.cwd(), tsconfig: 'tsconfig.json', // optional; defaults to /tsconfig.json }); ``` ```sh dbx tsconfig --json # { alias, paths, references } dbx tsconfig --alias # Vite/Vitest resolve.alias entries dbx tsconfig --paths # resolved compilerOptions.paths dbx tsconfig --references # resolved project references dbx tsconfig --tsconfig tsconfig.build.json dbx tsconfig --root packages/app --no-extends ``` The resolver follows `extends` per field: a child can define `paths` while inheriting `references` (or the reverse). When a config has no `baseUrl`, its relative paths resolve from the config file that declares them. ### Stop editing generated `tsconfig.json` files `dbx` owns the generated `tsconfig.json`; move customizations to `tsconfig.default.json` or `toolchain.tsconfig.overrides` and re-run sync: ```ts export default defineConfig({ toolchain: { tsconfig: { overrides: { base: { compilerOptions: { target: 'ES2022' } }, default: { compilerOptions: { strict: true } }, build: { compilerOptions: { declaration: true } }, root: { compilerOptions: { types: ['node'] } }, }, }, }, }); ``` ```sh dbx sync --recursive dbx sync --recursive --check ``` Overrides are deep-merged into the user-owned files (`baseFile`, `rootFile`, `defaultFile`, `buildFile`; custom names are honoured). The first time a file is patched, its original content is snapshotted in `.dbx/toolchain/manifest.json` under `snapshots` (a tree of **relative** paths mirroring the repo), and the applied override under `tsconfigOverrides`. Deleting an override key reverts it: the original value comes back when the snapshot defines the key, otherwise the key is removed (a value edited after the override set it is kept). A missing target is skipped with a `tsconfig.missing-file` warning instead of being created. ```sh dbx tsconfig --restore # remove every applied override now dbx tsconfig --restore build # only base | root | default | build ``` `dbx reset` restores the overrides before it removes the manifest. The patched files are never part of the manifest's managed `files`, so neither a sync nor a reset deletes them. See [tsconfig → `overrides`](/guide/tsconfig#overrides). `tsconfig.baseFile` (default `tsconfig.base.json`) names the root base tsconfig that `overrides.base` targets. Use `tsconfig.extends` to choose what scaffolded `tsconfig.base/default/build.json` files extend (for example `build: './tsconfig.json'` to reuse path aliases in builds, at the cost of pulling workspace source into the build). ### Sync task API Custom sync tasks can use these additions: * `SyncTask.watch` / `SyncTask.keep` accept a function of the config (`config => string[]`), so globs can follow configured file names. * A `ManagedFile` returned with `track: false` is written and drift-checked like any other, but stays user-owned: it is not recorded in the manifest, never pruned by a later sync and never removed by `dbx reset`. * `resolveWatchGlobs(tasks, config, projectType?)` (core) resolves the active tasks' inputs; `dbx watch --list [--json]` prints them, and the VS Code extension watches them (custom tsconfig names included) unless `deltabox.toolchain.watch` is set explicitly. Its default is now `[]`. * `SyncContext.manifest` holds task metadata persisted in the manifest between syncs (`snapshots`, `tsconfigOverrides`); `SyncContext.check` is true for `dbx sync --check`. ### Do not hand-add workspace aliases Keep `paths`/`references` in `tsconfig.workspaces.json`; the generator expands them into each workspace. For Vite/Vitest, prefer Vite's native `resolve.tsconfigPaths: true`, or pass `resolveTsconfig().alias` to `resolve.alias`. If you created a `vitest.aliases.ts` during the transition, delete it and use one of those two options. ## Vite and task changes * Runtime shims are still the default (`vite.shim: 'runtime'`). Static shims (`vite.shim: 'static'`) serialize the config and import only `defineConfig`, useful when loading the shim without a built package. * `vite.shimImport` changes the `resolveVite` import specifier for runtime shims. Relative values are resolved from the repo root and rewritten per generated config. * `typecheck:ci` was removed; `typecheck` already uses the source tsconfig. Use `yarn typecheck` in CI and delete any `typecheck:ci` scripts or Vite+ tasks. * The emulate test suite can be cleaned with `yarn test:clean`. ## Recommended upgrade steps 1. Replace `scopes` with `schema` in `createConfigEngine`. 2. Replace `render*` imports with `generateConfig*`. 3. Remove imports of the deleted schema maps; use `configSchema` or individual schema exports. 4. Rename `env`/`path` metadata to `envName`/`envPath` when convenient (the old names still work). 5. Remove hand-written `tsconfig.json` aliases and move them to `tsconfig.workspaces.json`; run `dbx sync --recursive`. 6. Replace any custom tsconfig path parser with `resolveTsconfig()` (or `dbx tsconfig --json`). 7. Delete `vitest.aliases.ts` if present; enable `resolve.tsconfigPaths: true` or use `resolveTsconfig().alias`. 8. Replace `typecheck:ci` with `typecheck` in scripts/CI. 9. Optionally move options you want managed in `tsconfig.base.json` / `tsconfig.workspaces.json` / the workspace default and build tsconfigs into `toolchain.tsconfig.overrides`, and keep committing `.dbx/toolchain/manifest.json` (it now holds their snapshots). 10. Run `yarn dbx sync`, `yarn config:types`, `yarn typecheck`, `yarn test` and `yarn dbx sync --recursive --check` after upgrading. --- --- url: https://toolchain.dbx.studio/guide/migrations/v2-v3.md --- # Migrating from v2 to v3 **v3** is a correctness and cleanup release. Release notes [here](https://github.com/deltabox-studio/toolchain/releases/tag/v3.0.0). Full changelog [here](https://github.com/deltabox-studio/toolchain/blob/main/CHANGELOG.md#300-november-2026). ## Table of contents * [Migrating from v2 to v3](#migrating-from-v2-to-v3) * [The most important breaking changes](#the-most-important-breaking-changes) * [Some of the smaller changes](#some-of-the-smaller-changes) * [Breaking changes](#breaking-changes) * [Deprecations](#deprecations) * [New features](#new-features) * [Behaviour changes](#behaviour-changes) * [Recommended upgrade steps ](#recommended-upgrade-steps) ## The most important breaking changes * The `tsdown` workspace rename to `pack`. * The redesigned config-generator programmatic API. * The config CLI program runtime replacing the commander-based CLI assembly. * The `dbx()` Vite plugin becoming the preferred config path (available from the `@deltabox/toolchain/vite` subpath as usual). * Vite+ (`vite-plus`) replacing the separate `vite`, `vitest` and `tsdown` dev dependencies (it bundles those tools behind `vp`). * `@deltabox/toolchain` packages releasing independently instead of in lockstep. * Vite+ projects configuring `pack`, `test` and `run.tasks` in `vite.config.*` instead of `tsdown.config.*`, `vitest.config.*` and `turbo.json`. * `fmt`/`lint` moving into `vite.config.*` in Vite+ mode. ## Some of the smaller changes * Improved changelog and release notes formatting. * Managed `tsconfig.json` now declaring `include`/`exclude`/`compilerOptions.types` from extended tsconfig. * UTF-8 BOM support (great for shells). * Dockerfiles that build from a fresh scaffold. * Scaffold-only Docker generation. * `--online` for online templates. * Stricter nested/configless inheritance and VS Code discovery. * The `dbx.config.*` format itself is unchanged, so most projects only need to update the dependency and re-run `dbx sync`. * Idempotent CI releases. ## Breaking changes ### The `tsdown` workspace is now `pack` The workspace package `@deltabox/toolchain-tsdown` is renamed to `@deltabox/toolchain-pack`, and the umbrella subpath `@deltabox/toolchain/tsdown` becomes `@deltabox/toolchain/pack`. The workspace directory moves from `packages/tsdown` to `packages/pack` and the commitlint scope changes from `tsdown` to `pack`. The underlying bundler is still tsdown, so `baseTsdownConfig` and `createPostBanner` keep their shape. Replace the import specifier: ```diff [tsdown.config.ts] -import { baseTsdownConfig } from '@deltabox/toolchain/tsdown'; +import { baseTsdownConfig } from '@deltabox/toolchain/pack'; ``` and the workspace dependency for maintainers/contributors: ```diff [package.json] -"@deltabox/toolchain-tsdown": "workspace:*", +"@deltabox/toolchain-pack": "workspace:*", ``` `createTsdownConfig` now takes one options object instead of an `(overrides, banner)` pair: ```diff [tsdown.config.ts] -const config = createTsdownConfig({ format: ['cjs'] }, { name: 'Myapp' }); +const config = createTsdownConfig({ + overrides: { format: ['cjs'] }, + banner: { name: 'Myapp' }, +}); ``` ### Vite+ projects: `pack`, `test` and `run.tasks` live in `vite.config.*` **This only applies when the project uses Vite+** (`vite-plus` and Vite+'s `vite.config.*`). If the project is not on Vite+, keep the standalone `tsdown.config.*`, `vitest.config.*` and `turbo.json` files as they are. In a Vite+ project, the bundler, test runner and task runner read their configuration from `vite.config.*`. Move each standalone config into the matching Vite+ block, then delete the old file: ```diff [tsdown.config.ts → vite.config.ts] # tsdown.config.ts -import { defineConfig } from 'tsdown'; - -export default defineConfig({ - entry: ['src/index.ts'], - dts: true, - format: ['esm', 'cjs'], -}); # vite.config.ts +import { defineConfig } from 'vite-plus'; + +export default defineConfig({ + pack: { + entry: ['src/index.ts'], + dts: true, + format: ['esm', 'cjs'], + }, +}); ``` ```diff [vitest.config.ts → vite.config.ts] # vitest.config.ts -import { defineConfig } from 'vitest/config'; - -export default defineConfig({ - test: { - include: ['src/**/*.test.ts'], - environment: 'node', - }, -}); # vite.config.ts +import { defineConfig } from 'vite-plus'; + +export default defineConfig({ + test: { + include: ['src/**/*.test.ts'], + environment: 'node', + }, +}); ``` ```diff [turbo.json → vite.config.ts] # turbo.json -{ - "tasks": { - "build": { - "dependsOn": ["^build"], - "outputs": ["dist/**"] - } - } -} # vite.config.ts +import { defineConfig } from 'vite-plus'; + +export default defineConfig({ + run: { + tasks: { + build: { + command: 'vp build', + cache: { output: ['dist/**'] }, + }, + }, + }, +}); ``` Vite Task derives cross-package order from `package.json` dependencies, so turbo's `^build` is not needed. A task name cannot also be a `package.json` script: move the script into the task (or keep the script and skip the task definition) so the name is declared once. In a `dbx()` plugin project, add `pack` / `test` / `run.tasks` to the existing `defineConfig` next to the `plugins` field; do not replace the plugin config. In config mode, put the same keys under `toolchain.vite` in `dbx.config.*` and let `dbx sync` write the Vite shim. ### The `dbx()` Vite plugin is the default config path New scaffolds are configured through the `dbx()` Vite plugin. Import it from the `@deltabox/toolchain/vite` subpath: `vite-plugin-dbx` is not published yet, so the standalone package name is not available to install. ```diff # invalid -import { dbx, DBX_TASKS } from '@deltabox/toolchain-vite'; # correct +import { dbx, DBX_TASKS } from '@deltabox/toolchain/vite'; ``` The v2 `@deltabox/toolchain-vite` workspace is now `vite-plugin-dbx`, and the umbrella subpath `@deltabox/toolchain/vite` re-exports it. A managed `vite.config.*` shim is only written when the project declares its own `vite` section. In plugin mode the whole toolchain config lives in `vite.config.*`; there is no `dbx.config.*` to author: ```diff [vite.config.ts] +import { defineConfig } from 'vite-plus'; + +import { dbx } from '@deltabox/toolchain/vite'; + +export default defineConfig({ + plugins: [ + dbx({ + toolchain: { + project: { name: 'app' }, + fmt: true, + lint: true, + }, + }), + ], +}); ``` `dbx.config.*` remains fully supported as the non-Vite fallback, so an existing `dbx.config.*` project does not need to move. If you generate projects programmatically, expect the generated `vite.config.*` to carry the plugin instead of a separate `dbx.config.*`. ### Vite+ is the single dev dependency **v3** no longer installs `vite`, `vitest` or `tsdown` for you. `vite-plus` is the single dev dependency and provides `vp` (Vite, Vitest, Oxfmt, Oxlint, Rolldown and tsdown); it is not bundled into `@deltabox/toolchain` at runtime. Replace the individual dev dependencies with `vite-plus` and use `vp` / `vp run` for those commands (declare it in the monorepo root, not in every single workspace): ```diff [package.json] { "devDependencies": { - "tsdown": "catalog:", - "vite": "catalog:", - "vitest": "catalog:" + "vite-plus": "catalog:" }, "scripts": { - "build": "tsdown", - "test": "vitest run", - "lint": "oxlint .", - "format": "oxfmt ." + "build": "vp build", + "test": "vp test", + "lint": "vp lint", + "fmt": "vp fmt" } } ``` Workspace packages are released **individually** now: each public `packages/*` workspace has its own version and `CHANGELOG.md`, and the release workflow publishes any package whose version is not on npm yet. A consumer that depends on a published subpackage should track that package's version instead of the umbrella's. ### Git hooks use the Vite+ dispatcher When `ci.changelog` is enabled, `dbx sync` writes the `commit-msg` hook to `.vite-hooks/commit-msg` on a Vite+ project (it used to be `.husky/commit-msg`); projects without Vite+ keep the husky fallback. To migrate: ```sh yarn remove husky rm -rf .husky git config --unset core.hooksPath # only if it still points at .husky/_ ``` Replace `"postinstall": "husky"` with `"postinstall": "vp hooks enable"`, then run `vp hooks enable` to install the `.vite-hooks/_` dispatcher. Add `.vite-hooks/* text eol=lf` to `.gitattributes` on Windows. Staged checks move to Vite+ too: add `.vite-hooks/pre-commit` running `vp staged` and a `staged` block in the root `vite.config.ts` (`staged: { '*': 'vp check --fix' }`). ### Config generator programmatic API The engine keeps the v2 `createConfigEngine({ schema })` shape, but v3 reshapes the surrounding API: * The ambient env declarations are now `dbx-env.d.ts` (previously `env.d.ts`). Update the `include`/`files` entries in your tsconfigs if you referenced the old file name. * Runtime loading uses `parseConfig`, `parseEnvConfig` and `parseCliConfig`, plus `collect` and `loadConfig` / `loadConfigAsync` for file-backed configs. The source-specific `loadEnvConfig*`, `loadCliConfig*` and `loadFileConfig*` family (with `Sync`/`Async` variants) selects the file+env, file+CLI or file-only source set explicitly. The old `parseEnvTree` + `envString`/`envInt`/`envBool` accessors and `applyOverrides` remain available, but are legacy; prefer the parsers so env, CLI and overrides are validated through the schema. * The engine groups its generators: `engine.env` (and `engine.env.types`), `engine.types`, `engine.markdown` (`.cli`, `.env`, `.file`), `engine.cli` (`.generate`, `.options`, `.program`), `engine.jsonSchema` and `engine.configJson`. `configCommands({ engine })` now also exposes `config:all`, and the standalone `generateConfig*` functions return content unless you pass an output path. * The high-level CLI program is now part of the public API: `engine.cli.program.create()` returns a runnable `ConfigProgram` (with `createCommand()` for one command), and `createConfigProgram(commands, options?)` builds one from framework-agnostic `CliCommand[]`. `commander` is no longer used or exported. The standalone `generateConfigProgram(schema, options)` returns the generated command descriptors without building a program. * JSON Schema generation can preserve Zod's `$ref`/`$defs` graph (`preserveDefs: true`), and the markdown/CLI generators expose more frontmatter, scope and reference options. Static schema defaults are also new. The `engine.*` generator methods are grouped now: ```diff [scripts/generate-config-reference.ts] -engine.writeConfigTypes({ outputDir: 'types' }); +engine.types.write({ outputDir: 'types' }); -engine.writeEnvTypes({ outputDir: 'types' }); +engine.env.types.write({ outputDir: 'types' }); -engine.writeMarkdown({ outputDir: 'docs/reference/configuration' }); +engine.markdown.write({ outputDir: 'docs/reference/configuration' }); -await engine.writeJsonSchema({ output: 'config.schema.json' }); +await engine.jsonSchema.write({ output: 'config.schema.json' }); -engine.buildConfigJson(); +engine.configJson.build(); ``` The runtime side moves from the `parseEnvTree` + `env*` accessors to the schema parsers: ```diff [src/config.ts] -import { envInt, envString, parseEnvTree } from '@deltabox/toolchain/config'; +import { loadConfigAsync } from '@deltabox/toolchain/config'; -const tree = parseEnvTree(process.env, 'MYAPP_'); -const serverConfig = { - host: envString(tree, 'host', '0.0.0.0'), - port: envInt(tree, 'port', 3000), -}; +const config = await loadConfigAsync({ + cwd: process.cwd(), + parser: serverConfigSchema, + source: 'env', + envPrefix: 'MYAPP_', +}); ``` And the ambient env declarations change file name: ```diff [tsconfig.json] { "include": [ "src", - "types/env.d.ts" + "types/dbx-env.d.ts" ] } ``` If you only consume the generated files, re-run the generators; if you imported the engine, update the calls to the grouped API and the runtime parsers. ### CLI command descriptors and program runtime v3 replaces the commander-based CLI assembly with the config program runtime. Custom CLIs now build the same program the `dbx` binary uses: ```ts import { configCommands } from '@deltabox/toolchain/config'; const program = engine.cli.program.create(() => configCommands({ engine }), { name: 'myapp', version: '1.0.0', globalOptions: [{ flags: '--json', description: 'Print JSON.' }], disableColors: ({ color }) => color === false, }); await program.invokeAsync(process.argv.slice(2)); ``` * Rename `ToolchainCommand` / `ToolchainOption(s)` annotations to `CliCommand` / `CliOption(s)`. Wrap inline descriptors in `defineCliCommand()` from `@deltabox/toolchain/shared`; this preserves the literal `options` tuple so `run` values are inferred. The `CliOptionValues` type exposes the same shape directly. * `engine.cli.program.create()` builds schema-derived commands with typed `run({ config, values, context })`; `createCommand(scope, spec)` builds one config-backed command and `createCommand('name', spec)` builds a runtime-only one. The callback may be async. `engine.cli.generate()` / `.options()` remain the low-level option generators. * If you used the v3 beta program names, `engine.cli.program.generate()` is now `create()` and the old `engine.cli.program.command()` builder is now `createCommand()`. The chain's `.command()` method for subcommands is unchanged. * A built program exposes `invoke()` / `invokeAsync()`, `argv()`, `withContext()`, `globalOption()` / `globalOptions()`, `hook()` / `hooks()`, `bin`, `formatHelp()`, `formatError()` and `configure()`. `invoke()` throws when a handler, hook or `disableColors` resolver is async; use `invokeAsync()`. * `configCommands()` remains library-only; `dbx` does not register a `config:*` group because each command needs a consumer-bound `ConfigEngine`. * A command's `bin` field executes a relative/absolute binary instead of the in-process handler; `argv` overrides the invocation arguments for `program.invoke()`. ### Oxc configs live in `vite.config.*` in Vite+ mode In a Vite+ project, `dbx sync` no longer writes standalone `.oxfmtrc.json` / `.oxlintrc.json` files. The formatter and linter options live in the Vite config (`toolchain.vite.fmt` / `toolchain.vite.lint`, or the root `fmt`/`lint` sections), which Vite+ reads directly. If an existing Vite+ project has standalone `.oxfmtrc.json` / `.oxlintrc.json` files, fold them into the Vite config with `dbx migrate --from oxc --write`; `dbx sync` will no longer write or prune them: ```diff [.oxfmtrc.json] -{ - "printWidth": 100, - "singleQuote": true -} ``` ```diff [.oxlintrc.json] -{ - "rules": { - "no-console": "warn" - } -} ``` ```diff [vite.config.ts] export default defineConfig({ plugins: [ dbx({ toolchain: { + fmt: { oxc: { printWidth: 100, singleQuote: true } }, + lint: { oxc: { rules: { 'no-console': 'warn' } } }, }, }), ], }); ``` ### Project templates are one module per template The monolithic template module is gone. The supported programmatic surface from `@deltabox/toolchain/project` (also re-exported by the umbrella) is: ```ts import { createProjectTemplateFiles, isProjectTemplateId, PROJECT_TEMPLATE_IDS, type ProjectTemplateId, } from '@deltabox/toolchain/project'; ``` Look a template up through `PROJECT_TEMPLATE_IDS` / `createProjectTemplateFiles` instead of importing a shared `qol` helper. ### Docker plans expose their copy sources `resolveDockerPlan()` now returns `installSources` — the exact files the Dockerfile copies before installing dependencies. Code that constructs a `DockerPlan` by hand must provide it; prefer `resolveDockerPlan()` + `dockerFiles()` instead: ```diff -const plan: DockerPlan = buildPlan(); +const plan = resolveDockerPlan({ + cwd: process.cwd(), + packageManager: 'yarn', +}); ``` ```diff const plan: DockerPlan = { runtime: 'node', - // ... + installSources: ['package.json', 'yarn.lock', '.yarnrc.yml'], + // ... }; ``` ## Deprecations These APIs still work in v3, but are deprecated or kept only as compatibility aliases. The explicit schema/type deprecations are `toolchain.biome`, `meta.env`, `meta.path` and `generateEnvTypes`; the rest are legacy aliases kept for existing projects. Prefer the replacement; they may be removed in a future major. ### Configuration * **`toolchain.biome`** — deprecated in favour of `toolchain.fmt.biome` and `toolchain.lint.biome`. `biome.overrides` still writes `biome.json`, and `biome.vscode` still controls the Biome VS Code settings; `dbx sync` warns with `deprecated.section.biome`. See [Formatting](/guide/formatting). * **`vite.shimImport: 'vite-plugin-dbx'`** — the legacy plugin specifier is still accepted, but generated shims use `@deltabox/toolchain/vite`. See [Vite plugin](/guide/vite-plugin). * **`tokens.yarnVersion`** — legacy alias for `tokens.packageManagerVersion`. `packageManagerVersion` wins when both are set; prefer it, especially with a non-Yarn package manager. See [Workflow settings](/guide/ci/settings). * **`vite-plugin-dbx`** — the private legacy package/specifier. New configs and generated shims use `@deltabox/toolchain/vite`; existing plugin configs that still import the old specifier keep working through plugin detection. ### Changelog CLI * `--release-notes ` — deprecated alias for `--release-body `. * `--release` — deprecated alias for `--release-body-wrap`. Both aliases are still parsed for existing scripts, but are not listed in `dbx changelog --help`. See [Changelog CLI](/guide/changelog/cli). ### Config generator * **`meta.env`** — deprecated; use `meta.envName`. * **`meta.path`** — deprecated; use `meta.envPath`. * **`generateEnvTypes`** — deprecated; use `generateConfigEnv`. * **`parseEnvTree` + `envString` / `envInt` / `envBool`** — legacy runtime accessors. They remain exported, but prefer the schema parsers (`parseConfig`, `parseEnvConfig`, `parseCliConfig`, `loadConfigAsync`). See [Config generator programmatic API](#config-generator-programmatic-api). * **`loadConfigAsync({ schema })`** — the object-based form remains for compatibility; prefer `loadConfigAsync({ parser })` so env, CLI and overrides are validated through the schema. ### Changelog and templates API * **`main`** (from `@deltabox/toolchain/changelog`) — compatibility alias for `runChangelog`. * **`ProjectContext.repoUrl`** — legacy alias for `repo`. * **`ProjectContext.yarnVersion`** — legacy alias for `packageManagerVersion`. ### Compatibility paths * **`.dbx/toolchain/providers.json`** and **`~/.dbx/toolchain/.registry/providers.json`** — legacy provider registry files, still read. Add new project providers under `.dbx/toolchain/.registry/providers/` and global providers under `~/.dbx/toolchain/.registry/providers/`. See [Providers](/guide/providers#custom-providers). ## New features The v3 line also adds a large set of capabilities on top of v2, grouped by area: ### Config engine and CLI * Schema-derived CLI programs through `engine.cli.program.create()`, with typed options, subcommands, inherited global options, help formatting and typed `run({ config, values, context })` handlers. * Typed `CliCommand` descriptors (`defineCliCommand`) that infer option values from their flags, plus scoped CLI generation from config schemas. * Source-specific config loaders (file, env and CLI argv) with base-value merging, so env/CLI values override file values without schema defaults replacing them. Multi-source selections and `envExpose` metadata are supported. * Static schema defaults and generated `toolchain.hooks` from function schemas. * `enabled` / `regenerate` controls on sections, the `loader` config section and `project.manageConfigless`. * `dbx enable` / `dbx disable` and the `dbx enabled` command. * A reusable CLI docs generator (`engine.markdown.cli`) for command references. * Grouped and sorted help: `group` labels on options and commands, a `groups` program option (`true` or `{ auto, delimiter }`) that automatically groups commands by their delimited name path (`vite:list` -> `Vite commands:`), and `sort: 'asc' | 'desc' | false` for deterministic ordering (ascending by default, including inside groups). `dbx --help` groups its own commands like the docs sidebar. See [program options](/guide/config-generator/api#program-members-and-options). * `helpOnError` on the program (and on `createCli` / `runCli`) opts back into printing the full help after invalid argv; the default now prints only the error message. * `dbx test:repo`, plus readable spinners and surfaced Vite+ passthrough errors. ### Vite+, formatting and task running * Vite+ (`vite-plus`) as the single dev dependency and `vp` / `vp run` as the task runner; the shared pack config and workspace aliases no longer need a separate `tsdown` dependency. * `dbx fmt` / `dbx lint` route to the active formatter/linter, with better auto-detection of the configured tool. * Oxfmt and Oxlint option types generated from the tools' vendored JSON schemas, and typed tool options plus changelog callbacks. * Nested scaffolds leave `fmt` / `lint` to the root config instead of emitting their own blocks. * Scaffolds opt into the catalog they write, so `dbx sync` keeps the catalog managed. ### Templates, scaffolding and Docker * New quality-of-life builtin templates and project/template generators. * Opt-in containerization for scaffolds (`--containerize`), including scaffold-only Docker generation. * The new `@deltabox/toolchain-docker` package, wired into the umbrella; Docker plans now expose the exact `installSources` copied before installing. * `--online` for online templates, with clearer opt-in behaviour. ### MCP * An MCP server, installers for Claude, Codex, VS Code, OpenCode, Pi and custom directories, and the `dbx mcp:*` commands. * The official dbx docs skill: `dbx skills --official` installs it per agent (`--provider`) and location (`--scope` / `--dir`), checks first and never overwrites unless `--force`. The `checkSkill` / `installSkill` / `installOfficialSkill` APIs expose the same flow. The skill tells agents to read [`llms.txt`](https://toolchain.dbx.studio/llms.txt) and inspect the project config, graph and managed-file manifest before acting. See [Skills](/guide/mcp#skills). * Opt-in automatic skill installation through `toolchain.mcp.skills`; `dbx sync` adds missing skills for the configured agents. ### Changelog and CI * Opt-in Dependabot security updates and dependency-update workflows. * `beforeVersion` / `afterVersion` lifecycle hooks. * Changelog `intro` / `outro`, `minCommits`, nested `See more...` descriptions, release mode and collapsible bodies. * Grouped release bodies (`changelog.release.group`) that roll every prerelease since the previous published release into one stable release entry. * GitHub Releases mark prerelease versions (`3.0.0-beta.2`) as prereleases by default (`ci.release.prerelease: 'auto'` detects the semver suffix); `false` opts out, and custom release jobs can read the `{{releasePrerelease}}` token. * Scoped versioning options and configurable breaking-change detection. * Batched GitHub metadata lookups (commit authors, PR credit, issue titles). * Complete GitHub, GitLab and Azure workflow configs with autocomplete and dispatch through the vendor CLI. ### VS Code extension * A scoped auto-sync mode, the action palette and the Actions view. * Managed-file decorations and a reveal-active-project action. * Plugin-mode projects, MCP install and improved sync UX; sync notifications, `sync all`, a migration target picker and `manageConfigless` support. * The official dbx skill installer (`dbx skills --official`) is available from the action palette, the Command Palette and the Home Quick Actions, with the same agent/location picker as the MCP installer. * A Docker prompt while scaffolding, plus generic format/lint actions and formatting settings. * The workflow provider in the run picker. ## Behaviour changes ### Config inheritance is strictly opt-in A nested `dbx.config.*` only inherits the sections it explicitly enables (`fmt`, `lint`, `biome`, `changelog`, `catalogs`, `logger`); `project` metadata is inherited except its identity fields. Projects without their own `dbx.config.*` (or `dbx()` vite plugin in `vite.config.*`) are unmanaged by default; pass `--configless` or set `project.manageConfigless: true` to inherit the nearest ancestor config. See [Nested configs](/guide/config/nested-configs). ```diff [packages/web/dbx.config.ts] export default defineConfig({ toolchain: { project: { name: 'web' }, + // v3: a nested config only inherits sections it opts into. + fmt: true, + lint: true, }, }); ``` ```diff [dbx.config.ts] export default defineConfig({ toolchain: { project: { + manageConfigless: true, }, }, }); ``` ### Online templates need `--online` `dbx create --template ` and the `template:*` commands only resolve online (npm/git/Vite+) sources when `--online` is passed. Local and builtin templates work without it, and a local-only run never touches the network. Scripts and CI that relied on implicit online resolution must add the flag: ```diff -dbx create --template @org/template --name app +dbx create --template @org/template --name app --online ``` ### Toolchain enable/disable A top-level `toolchain.enabled` switch is available. The boolean shorthand is workspace-scoped: ```ts export default defineConfig({ plugins: [dbx({ toolchain: { enabled: false } })], }); ``` Config files and the inline `dbx()` plugin only accept the workspace scope; the object form (`{ disabled, scope: 'global' | 'workspace' }`) is reserved for the CLI/programmatic API and the VS Code extension. `dbx enable`/`dbx disable` choose the workspace scope by default; pass `--global` to update `~/.dbx/toolchain/cli/config.json`. The project config takes precedence over both the CLI workspace setting and `.vscode/settings.json`. ### Dependabot security updates `toolchain.ci.dependabot` now accepts an opt-in `security` setting. It adds the security-update group to `.github/dependabot.yml` and generates `.github/workflows/dependabot-security.yml` to enable GitHub's native security updates and optionally dismiss alerts below a severity threshold. ```diff [dbx.config.ts] export default defineConfig({ toolchain: { ci: { dependabot: { + security: { + vulnerabilities: { severity: 'high' }, + pr: { strategy: 'grouped' }, + }, }, }, }, }); ``` `security: true` keeps every severity and groups PRs per ecosystem. The workflow needs a `DBX_GITHUB_TOKEN` secret with repository admin access to change the repository setting; `GITHUB_TOKEN` is used for alert dismissal. Set `security: { workflow: false }` to manage the setting yourself, or `security: { vulnerabilities: false }` to disable security updates. No migration is required: without `security`, the generated `dependabot.yml` and behaviour are unchanged. ### Managed-file regeneration Every managed section now accepts `regenerate?: boolean` (default `true`). Set it to `false` to skip that section in `dbx sync`: its files are neither written nor drift-checked, and sync does not prune them. User-owned files (`tsconfig.workspaces.json`, `tsconfig.build.json`) are only seeded when missing; an existing file is never overwritten by the missing-file fallback. ```diff [dbx.config.ts] export default defineConfig({ toolchain: { - tsconfig: true, + tsconfig: { regenerate: false }, }, }); ``` ### Changelog versioning * `versioning.target: 'individual'` is idempotent. Commits already listed in a workspace's `CHANGELOG.md` are filtered out before deriving its bump, and a workspace with no new commits is skipped entirely. Re-running no longer bumps untouched workspaces or re-counts an old `feat` as a new minor. * Workspace glob negation (`['packages/*', '!packages/private-*']`) is honoured. * A UTF-8 BOM in any `package.json` (common with PowerShell/Notepad) no longer makes `dbx changelog` fail; the same BOM handling applies to local CLI discovery, providers, Prettier detection and the VS Code extension. * The `### Package changes` footer now reads Yarn (`.yarnrc.yml`), pnpm (`pnpm-workspace.yaml`) and Bun (`package.json` `workspaces.catalog`) catalogs, including named catalogs. * Running changelog from a nested workspace uses the repository root for the fallback commit/issue links instead of the workspace's own `package.json`. If you version workspaces individually, opt excluded packages out of the glob: ```diff [dbx.config.ts] versioning: { target: 'individual', - workspaces: ['packages/*'], + workspaces: ['packages/*', '!packages/private-*'], }, ``` ### Docker * Only files that exist when the Dockerfile is generated are copied: `package.json` plus the project's lockfile/workspace files. `.node-version*` is never assumed, and a missing lockfile is not copied. * The declared package manager drives both the copy list and the install command. A Bun-runtime project with no declared manager installs with Bun; otherwise the declared manager wins (so `yarn.lock` is not paired with `bun install`). When a Bun-runtime project declares yarn/pnpm/npm, dependencies install in a `node:` `deps` stage and the Bun image only builds. * When there is no lockfile, the install runs without a frozen flag. ### Scaffolding and migrations * `dbx project:init --out ` (and `project:init:monorepo`) no longer inherits the current project's name when `--name` is omitted; it uses the target directory's basename. The in-place case still inherits `project.name`. * `dbx migrate --check` resolves the effective (inherited) config, so a workspace inheriting `fmt`/`lint` from the root is not asked to keep an intermediate `.oxfmtrc.json` / `.oxlintrc.json`. A disabled section (`fmt: false`) does not count as owning the config. ### CLI and VS Code * `--no-color` now also disables the configured help/error colours. A custom program can implement the same switch with the `disableColors` program option. * Invalid argv (unknown command/option, missing value) prints only the error message by default. Pass `helpOnError: true` to a `ConfigProgram`, or to `createCli` / `runCli` via `RootCliOptions`, to append the full help text again. * Help command lists are grouped and sorted alphabetically by default. Use the `groups` and `sort` program options to opt out (`groups: false`, `sort: false`) or change the order (`sort: 'desc'`). * `dbx sync --json` always emits a JSON envelope, including when the config failed to load (`{ results: [], upToDate: false, error }`). * `dbx projects --max-depth` rejects non-numeric values instead of silently turning the limit into `NaN`; `--max-depth 0` still scans only the root. * The VS Code extension walks up to the repository boundary for the project's `dbx`, checks every workspace root in a multi-root workspace, and keeps the project's CLI as the default (the bundled CLI is only the fallback). ### TypeScript declarations * The shared tsdown base config externalizes declaration imports **as written** (`deps.dts.neverBundle: true`), so emitted `.d.ts` files reference bare package specifiers instead of build-machine absolute `node_modules` paths. Packages whose public types reference another package must declare it in `dependencies` (or `peerDependencies`). * The base config also ships a Rolldown leak reporter. It scans emitted JS, declaration and textual asset chunks and fails the build by default when an absolute `node_modules` path appears. Configure it with the `nodeModulesLeakReporter` option (or `false` to disable it): `{ level: 'warn' | 'info' | 'silent', when: 'generateBundle' | 'writeBundle' | 'closeBundle' }`. `writeBundle` is the default; use `closeBundle` when a later plugin rewrites output in `writeBundle`. Non-fatal levels respect tsdown/rolldown's log level. The plugin is also exported as `createNodeModulesLeakReporter` for use in your own builds. ```diff [tsdown.config.ts] const config = createTsdownConfig({ overrides: { format: ['cjs'] }, + nodeModulesLeakReporter: { level: 'warn', when: 'writeBundle' }, }); ``` ## Recommended upgrade steps 1. Update `@deltabox/toolchain` to v3 and replace the individual `vite`, `vitest` and `tsdown` dev dependencies with `vite-plus`. 2. Import the Vite plugin from `@deltabox/toolchain/vite` (not `vite-plugin-dbx`, which is not published yet). 3. If the project uses Vite+, move `tsdown.config.*`, `vitest.config.*` and `turbo.json` into `vite.config.*` as `pack`, `test` and `run.tasks`. 4. Run `dbx sync --recursive` and commit the regenerated managed files. 5. Rename generated `env.d.ts` references to `dbx-env.d.ts`, and switch custom runtime loaders to `parseConfig` / `parseEnvConfig` / `parseCliConfig` (or `loadConfigAsync` for files). 6. Run `dbx sync --recursive --check`, `yarn typecheck`, `yarn lint` and your test suite. 7. Regenerate Docker artifacts created by v2 (or edit the `COPY` lines to list only files that exist) and rebuild the image once with Docker available. 8. Replace imports of the old monolithic template helper with `PROJECT_TEMPLATE_IDS` / `createProjectTemplateFiles`. 9. If you build a `DockerPlan` by hand, add its `installSources` (or switch to `resolveDockerPlan()`). 10. Re-run `dbx migrate --check` in CI; inherited workspace configs may now pass where v2 reported a false drift. 11. Add `--online` to any `dbx create --template` / `template:*` script that resolves npm/git/Vite+ sources. 12. If you use `ci.dependabot`, opt into `security` and add the `DBX_GITHUB_TOKEN` secret (repository admin) before the generated security workflow runs. 13. If you assemble a custom CLI, rebuild it with `engine.cli.program.create()` (or the lower-level `createConfigProgram()` for engine-agnostic command lists), wrap descriptors in `defineCliCommand()`, and move any `commander` wiring to the program runtime. --- --- url: https://toolchain.dbx.studio/guide/api.md --- # Programmatic API Every surface the CLI and the extension use is also importable. The umbrella package re-exports the config model + sync runner and every workspace package, so a consumer can import the whole surface from the root or a single package through a subpath. ## Where to start * [Umbrella (`@deltabox/toolchain`)](/guide/api/umbrella) — the root exports and the namespaced packages. * [Subpath exports](/guide/api/subpath-exports) — the per-package entry points. * [Package reference](/guide/api/package-reference) — every package's public exports. * [Logging](/guide/api/logging) — the shared logger. * [Examples](/guide/api/examples) — short, copy-pasteable recipes. * [Registering commands](/guide/api/registering-commands) — wire `CliCommand[]` onto the engine program runtime. ```ts import { defineConfig, loadToolchainConfig, runSync, defaultSyncTasks } from '@deltabox/toolchain'; const { config, tokens, projectType } = await loadToolchainConfig(process.cwd()); await runSync({ tasks: defaultSyncTasks(), cwd: process.cwd(), config, tokens, projectType }); ``` --- --- url: https://toolchain.dbx.studio/guide/api/examples.md --- # Examples ## Vite+ provider Resolve and run the project's Vite+ CLI, or map a Vite+ command name: ```ts import { resolveVp, runVp, resolveVpCommand, VP_COMMANDS } from '@deltabox/toolchain/vite'; await runVp(['check'], { cwd: process.cwd() }); resolveVpCommand('i'); // 'install' ``` ## Migrations Detect the migrations that apply to a project and run them: ```ts import { detectMigrations, runMigration } from '@deltabox/toolchain/migrate'; for (const migration of detectMigrations(process.cwd())) { await migration.run({ cwd: process.cwd(), write: true }); } ``` ## Templates Load the available templates and scaffold one: ```ts import { loadTemplates, scaffoldTemplate } from '@deltabox/toolchain/template'; const [template] = await loadTemplates({ cwd: process.cwd() }); if (template) { await scaffoldTemplate(template, { cwd: './out', tokens: { name: 'myapp' }, }); } ``` ## Providers Read provider descriptors the way the editor does: ```ts import { toolchainProviders } from '@deltabox/toolchain/providers'; console.log(toolchainProviders().map(provider => provider.id)); ``` ## Sync only the tsconfig task Useful after a build changes package exports: ```ts import { defaultSyncTasks, loadToolchainConfig, runSync } from '@deltabox/toolchain'; const loaded = await loadToolchainConfig(process.cwd()); await runSync({ tasks: defaultSyncTasks(), only: ['tsconfig'], cwd: process.cwd(), config: loaded.config, tokens: loaded.tokens, projectType: loaded.projectType, }); ``` ## Config engine Bind a schema once, then use it to generate or parse configuration: ```ts import { createConfigEngine, parseEnvConfig } from '@deltabox/toolchain/config'; const engine = createConfigEngine({ schema, envPrefix: 'MYAPP_' }); const runtimeConfig = parseEnvConfig(engine.schema, process.env, { envPrefix: 'MYAPP_', }); ``` ## Runnable CLI program Build a CLI from the generated config commands: ```ts import { configCommands } from '@deltabox/toolchain/config'; const program = engine.cli.program.create(() => configCommands({ engine }), { name: 'my-cli', globalOptions: [{ flags: '--no-color', description: 'Disable colours.' }] as const, disableColors: ({ color }) => color === false, }); await program.invokeAsync(process.argv.slice(2)); ``` --- --- url: https://toolchain.dbx.studio/guide/api/logging.md --- # Logging Every toolchain message goes through one level-aware logger, rendered with [`@clack/prompts`](https://bombshell.dev/clack) (level symbols + guide). Use it instead of `console.log` so output stays consistent and respects the config and the CLI flags. | Export / member | Description | | ------------------------------------------------- | -------------------------------------------------------------------------------------------- | | `logger` | The active singleton: `raw`, `debug`, `info`, `success`, `warn`, `error`, `level`, `colors`. | | `createLogger(options)` | Create an independent logger (`level`, `color`, `name`). | | `setLogConfig(section)` | Apply the `logger` section from the loaded config. | | `setLogOverrides(options)` | Apply CLI overrides (win over the config). `configureLogger` is an alias. | | `getLogOverrides()` / `getLogger()` | Read the current overrides / the active instance. | | `LOG_LEVELS` / `isLogLevel` / `normalizeLogLevel` | The valid levels, most verbose first (`debug`, `info`, `warn`, `error`, `silent`). | ```ts import { createLogger, logger, setLogConfig, setLogOverrides } from '@deltabox/toolchain/shared'; setLogConfig({ level: 'debug', color: false, name: 'dbx' }); // from dbx.config.* setLogOverrides({ level: 'warn' }); // from --log-level logger.info('human message'); logger.success('done'); logger.error('failed'); logger.raw(JSON.stringify(payload)); // machine output: no prefix, no colour ``` Use `raw` for machine output (`--json`): it is never prefixed or decorated. `logger.warn`/`error` write to stderr; `debug`/`info`/`success`/`raw` to stdout. Messages that start with whitespace (indented continuations) are never prefixed. This mirrors the [`logger` config section](/guide/config/logging) and the `--log-level ` / `--no-color` [CLI flags](/guide/cli#global-flags), which call `setLogConfig` / `setLogOverrides` under the hood. --- --- url: https://toolchain.dbx.studio/guide/api/package-reference.md --- # Package reference ## `@deltabox/toolchain/shared` The base layer: the config model, logging, process/string/object utilities and the template engine. | Export | Description | | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------- | | `defineConfig(config)` | Identity helper for a typed `dbx.config.*` (object, promise, or sync/async callback). | | `sectionEnabled(section)` / `sectionConfig(section)` | Opt-in-by-presence helpers for a config section. | | `resolveTokens(config)` | Flatten a config into {{ token }} replacements. | | `CONFIG_FILE_NAMES` | The config file names the loader probes, in priority order. | | `repoSlugFromUrl(url)` | Derive an `owner/name` slug from a repository URL. | | `findOwnCliEntry(cwd?)` / `localToolchainVersion(cwd?)` / `TOOLCHAIN_PACKAGE` | Locate a project's own toolchain bin + pinned version (prefer them over a global `dbx`). | | `createLogger(options)` / `logger` | The shared logger (see [Logging](/guide/api/logging)). | | `WARNING_MAP` / `ERROR_MAP` / `warningMessage(id, values?)` | Central messages keyed by stable logger/suppression ids. | | `spawnCross(cmd, args, options)` / `run(cmd, args, options)` | Cross-platform, shell-free spawning; `timeoutMs` kills the child tree. | | `killProcessTree(child)` | Kill a child process and its descendants (Windows `taskkill /t`). | | `readJsonFile` / `readJsonAt` / `toJson` / `writeJsonFile` | Small JSON file helpers. | | `mergeJsonAt(cwd, relative, patch)` | Deep-merge a patch over an existing JSON file. | | `deepMerge` / `applyOverrides` / `isPlainObject` / `sort` / `mapValues` | Object utilities (including layered typed overrides). | | `defineCliCommand(command)` | Build a `CliCommand` while preserving the literal `options` tuple for typed values. | | `CliOptionValues` | The commander-style typed values produced by an option tuple. | | `applyReplacements` / `applyReplacementsDeep` / `createReplacer` | The {{ token }} template engine (also `tokenPattern`, `extractTokens`). | | `DEFAULT_IGNORE_PATTERNS` / `DEFAULT_FMT_IGNORE_PATTERNS` / `DEFAULT_LINT_IGNORE_PATTERNS` | The shared build/cache ignores and the Oxfmt/Oxlint extensions. | | `resolveIgnorePatterns(cwd?, options?)` / `collectGitignorePatterns(cwd?)` | Defaults + `exclude` + `.gitignore` resolution, and the matching helpers (`isIgnoredPath`). | | `toYaml(value)` | A tiny YAML emitter for the GitHub Actions subset. | The config **types** and **schemas** also live here: `ToolchainConfig`, `DbxConfig`, `SyncTask`, `SyncContext`, `ManagedFile`, `CliCommand`, `CliOption`, `CliOptionValues`, `CliCommandContext`, `ToolchainProvider`, `ToolchainViteConfig` (Vite+'s config type), `Replacements`, and the generated `config-types` / `config-schema` exports. ```ts import { defineConfig, sectionEnabled, applyReplacements } from '@deltabox/toolchain/shared'; const text = applyReplacements('Hello {{name:world}}', { name: 'myapp' }); ``` ## `@deltabox/toolchain/core` Loads `dbx.config.*`, builds the project graph and runs the sync tasks. | Export | Description | | ------------------------------------------------------------- | ----------------------------------------------------------------------------------- | | `loadToolchainConfig(cwd?)` | Find + load the config, resolve tokens and the project type. | | `findConfigFile(cwd?)` | The config file path, if any. | | `runSync(options)` | Run the given `SyncTask[]` (or `only` a named subset) and return the summary. | | `runWatch(options)` | Sync once, then watch inputs and re-sync (honours `only`). | | `selectSyncTasks(tasks, only)` | Select tasks by name; throws on unknown names. | | `buildProjectGraph(root, options?)` | Discover workspace packages and their dependencies. | | `orderProjects(nodes)` / `detectPackageManager(root)` | Dependency ordering and package-manager detection. | | `writeProjectGraph` / `readProjectGraph` | Persist/read `.dbx/toolchain/projects.json`. | | `selectProjects(options)` | Select projects by kind/name/glob. | | `resetToolchain(options)` / `resetProjects(options)` | Remove generated files, the manifest and/or the config (`restore` hook runs first). | | `vscodeSyncTask(options?)` | The VS Code settings/extensions sync task. | | `resolveProjectType(cwd, config?)` / `detectProjectType(cwd)` | The project kind (`monorepo-root` / `monorepo-workspace` / `project`). | | `readManifest(cwd)` / `writeManifest(cwd, files)` | The `.dbx/toolchain/manifest.json` helpers. | | `resolveFmtCustomGroups(input?)` | Build the `sortImports` workspace group from every dbx project (graph-based). | ```ts import { defaultSyncTasks, runSync, selectSyncTasks } from '@deltabox/toolchain'; await runSync({ tasks: defaultSyncTasks(), only: ['tsconfig'], cwd, config, tokens, }); // Or select explicitly: const tasks = selectSyncTasks(defaultSyncTasks(), ['tsconfig']); ``` `only` implies `prune: false`, so a task subset never deletes files owned by the tasks it skipped. Unknown task names throw. ## `@deltabox/toolchain/config` The generic Zod/env engine (see the [Config Generator](/guide/config-generator/) guide for the full workflow). | Export | Description | | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | | `createConfigEngine(options)` | Bind a schema, env prefix, base group and root into an engine. | | `parseConfig` / `parseEnvConfig` / `parseCliConfig` | Runtime parsers: env + CLI + overrides, validated. | | `loadConfig` / `loadConfigSync` / `loadConfigAsync` | Discover/import a config file and parse it. | | `loadEnvConfig*` / `loadCliConfig*` / `loadFileConfig*` | Source-specific loader variants (Sync/Async). | | `collect(schema, options?)` | Resolve env + CLI into a typed config (no overrides). | | `configCommands({ engine, defaults? })` | The `config:*` commands for a consumer's own CLI. | | `createConfigProgram(commands, options?)` | Low-level program factory; prefer `engine.cli.program.create()`. | | `generateConfigProgram(schema, options)` | Generate `CliCommand[]` from a config schema. | | `ConfigProgramError` | Invalid-argv error (`code`, `input`, optional `suggestion`). | | `formatGenerated(source, options?)` | Format generated output with Oxfmt (see below). | | `GENERATED_FORMAT_OPTIONS` | The baseline Oxfmt options used by the generators. | | `parseEnvTree(env, prefix?)` / `envString` / `envInt` / `envBool` / `envList` / `envMap` | Legacy dependency-free tree accessors. | | `compileZodSchema(schema)` | Compile a Zod schema for fast repeated parsing. | | `envPathOf(env, prefix?)` / `metaOf(schema)` | Env-name to dotted-path derivation and `.meta()` reading. | | `findProjectRoot(start?)` / `monorepoRoot(from?)` | Walk up to the nearest `package.json`. | | `generateConfigTypes` / `generateConfigEnv` | Type/env generators (optional disk writes). | | `generateConfigMarkdown` / `generateCliOptions` | Markdown/CLI generators (optional disk writes). | | `generateCliDocs(commands, options?)` | A CLI reference from `CliCommand` descriptors. | | `generateConfigJsonSchema` / `generateJsonSchemaFile` | JSON Schema generation. | | `normalizeJsonSchemaMetadata(node)` | Normalize Zod JSON Schema metadata for editor schemas. | | `generateEnv` / `generateEnvDts` / `generateConfigEnv` | `.env` / env type generation. | | `generateCliOptions` / `flagOf` / `cliFlagOf` / `createCliArgsParser` | CLI option generation + parsing. | ## `@deltabox/toolchain/vite` The Vite+ provider: resolving/running `vp`, the `dbx()` plugin and the `vite` sync task (see the [Providers](/guide/providers) guide). | Export | Description | | ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------- | | `resolveVp(cwd?)` / `hasVp(cwd?)` / `runVp(args, options?)` | Resolve and run the `vp` binary (local shim, global, then `npx`). | | `vpVersion(cwd?)` / `describeVp(cwd?)` / `which(bin)` | Version, resolution description and PATH lookup. | | `VP_COMMANDS` / `viteCommandName(name)` / `resolveVpCommand(name)` | The `vp` command catalog + name/alias resolution. | | `viteProvider()` / `viteCommands()` | The provider descriptor and the `dbx vite:*` commands. | | `dbx(options?)` / `DBX_TASKS` / `dbxTaskCommand(sub)` | The Vite/Vite+ plugin and the resolved `run.tasks` to spread in. | | `resolveDbx(cwd?)` / `runDbx(args, cwd?)` | Resolve/run the `dbx` binary (the project's own first; a pinned project never runs a global `dbx`). | | `resolveVite(options?)` | Resolve `toolchain.vite` (or a passed `toolchain`), with inline `vite` overrides. | | `detectViteSpecifier(cwd)` | Which package (`vite` / `vite-plus`) the project has, for the shim import. | | `renderViteConfig(specifier?)` / `viteConfigObject(config?)` | The managed `vite.config.ts` shim (per specifier) + the section minus `config`. | | `viteSyncTask()` | The `vite` sync task that writes the shim. | | `resolveFmtCustomGroups(input?)` | Re-exported from core: the `sortImports` workspace group resolver. | ## `@deltabox/toolchain/cli` | Export | Description | | -------------------------------------- | -------------------------------------------------------------------------- | | `builtinCommands()` | The commands built into the root CLI (config commands need an engine). | | `createCli(commands?, options?)` | Build the `dbx` program; pre-typed arrays keep their command/option types. | | `runCli(argv?, options?)` | Parse and run the CLI (extracts logger flags, defaults bare Vite+). | | `withDefaultVite(argv, commandNames?)` | Insert `vite` before a bare Vite+ command. | | `extractLogOptions(argv)` | Pull `--log-level` / `--color` / `--no-color` out of argv. | See the [CLI](/guide/cli) guide for the routing behaviour. ## `@deltabox/toolchain/migrate` | Export | Description | | ----------------------------------------------------------------------------------- | ------------------------------------------------ | | `migrations()` / `listMigrations(cwd)` / `detectMigrations(cwd)` | The registered migrations and detection. | | `findMigration(idOrFrom)` / `runMigration(...)` / `runDetectedMigrations(ctx)` | Run one or every detected migration. | | `biomeToOx` / `eslintToOx` / `prettierToOx` / `dprintToOx` / `viteToToolchain` | The built-in `ToolchainMigration` objects. | | `mapBiomeToOxfmt` / `mapBiomeToOxlint` / `mapPrettierToOxfmt` / `mapDprintToOxfmt` | Source-to-Oxc mapping helpers. | | `extractViteObject(source)` / `scanLiteralObject(text)` / `foldViteIntoConfig(...)` | The `vite` source's extraction + splice helpers. | | `diffFiles(files)` / `hasPending(diffs)` | Diff planned files against disk (for `--check`). | | `mergeViteConfig(source, ...)` / `writeViteTarget(...)` | The Vite+ (`--target vite`) output helpers. | ## `@deltabox/toolchain/template` | Export | Description | | ------------------------------------------------------------------------------- | ---------------------------------------------------------- | | `loadTemplates(options)` / `collectSources(options)` | Resolve builtin/local/online sources into templates. | | `scaffoldTemplate(template, options)` | Copy a template into a target directory, resolving tokens. | | `addTemplateSource(cwd, source)` / `removeTemplateSource(cwd, key)` | Manage `.dbx/toolchain/templates.json`. | | `readTemplateRegistry` / `writeTemplateRegistry` | Read/write the template source registry. | | `BUILTIN_TEMPLATES` / `loadLocalTemplates(root, idPrefix?)` | The offline templates. | | `readTemplateDir` / `readTemplateManifest` / `writeTemplateManifest` | A local `template.json` directory. | | `parseSourceSpec(spec, cwd?)` / `gitTemplate(source)` / `loadNpmTemplates(pkg)` | Online source parsing/loading. | ## `@deltabox/toolchain/providers` | Export | Description | | --------------------------- | ----------------------------------------------------- | | `toolchainProviders()` | Every registered provider with its actions resolved. | | `providerActions(provider)` | The default actions for a provider (one per command). | | `viteProvider()` | The Vite+ provider descriptor. | ```ts import { toolchainProviders } from '@deltabox/toolchain/providers'; console.log(toolchainProviders().map(p => p.id)); ``` ## `@deltabox/toolchain/pack` | Export | Description | | -------------------------------------------------------------- | -------------------------------------------- | | `baseTsdownConfig` | The shared tsdown base config. | | `createTsdownConfig(overrides?)` / `createPostBanner(options)` | Build a tsdown config / a post-build banner. | | `cleanup(options?)` / `cleanupCommands()` | Remove build artifacts / the turbo cache. | ## `@deltabox/toolchain/tsconfig` | Export | Description | | ---------------------------------------------------------------------------- | ----------------------------------------------------- | | `tsconfigSyncTask()` | The tsconfig sync task. | | `tsconfigBaseTemplate` / `tsconfigDefaultTemplate` / `tsconfigBuildTemplate` | The base/default/build templates. | | `renderTsconfigBase` / `renderTsconfigDefault` / `renderTsconfigBuild` | Render the templates with replacements. | | `buildMonorepoTsconfig(options)` / `renderMonorepoTsconfig(options)` | The monorepo root tsconfig with references + aliases. | | `renderTsconfigTemplates(replacements?)` | Render every template at once. | | `resolveTsconfig(options?)` / `readTsconfig(file)` | Resolve paths/references/aliases (extends-aware). | | `generateTsconfigs(options)` / `runTsconfigCli(argv?)` | The tsconfig generator and its CLI. | | `tsconfigFileNames(config)` / `restoreTsconfigOverrides(options)` | Configured file names / remove applied overrides. | | `applyOverride` / `mergeOverride` / `revertOverride` | Override deep-merge + snapshot-aware revert helpers. | | `getSnapshot` / `setSnapshot` / `deleteSnapshot` | The manifest snapshot tree (repo-relative paths). | ## `@deltabox/toolchain/changelog` | Export | Description | | ----------------------------------------------------------------------- | ---------------------------------------------------- | | `runChangelog(argv?)` / `main` | Derive the bump and update the changelog + versions. | | `runWorkflows(options)` / `resolveWorkflowId(name)` | Trigger generated workflows with the vendor CLI. | | `workflowTargets(config)` / `workflowRunCommand(target, options)` | List enabled workflows / build a vendor CLI command. | | `renderWorkflow(id, options)` / `renderWorkflows(...)` | Render workflow YAML. | | `renderCommitlintConfig(options?)` / `changelogSyncTask()` | Commitlint config + the changelog sync task. | | `readCommits(range)` / `deriveBump(records)` / `buildSummary(records)` | Git commit reading, bump derivation and summaries. | | `renderChangelogEntry(...)` / `parseExistingChangelog(content)` | Changelog entry rendering/parsing. | | `buildReleaseNotes(...)` / `releaseNotesFromGit(version, cwd, options)` | Aggregate release bodies (optionally grouped). | | `formatBody(body)` / `formatLine(line, repo)` | Description + changelog-line normalization. | `formatLine(line, repo)` normalizes a changelog line in place: numeric-only short hashes (eg. `#4033009`) stay commit links, genuine issue numbers stay issue links, and a bare `BREAKING CHANGE:` marker is bolded unless it is already bold. ## `@deltabox/toolchain/biome` | Export | Description | | ----------------------------------------------------------------------- | ---------------------------------------------------------- | | `biomeConfig` / `biomeVscodeSettings` | The generic Biome config and recommended VS Code settings. | | `renderBiomeConfig(replacements?, overrides?)` / `renderBiomeJson(...)` | Resolve tokens + merge overrides, then serialize. | | `mergeBiomeConfig(base, patch)` / `renderVscodeSettings(indent?)` | Recursive merge and settings rendering. | | `biomeSyncTask()` | The biome sync task (writes `biome.json`). | ## `@deltabox/toolchain/project` | Export | Description | | -------------------------------------------------------------------------------------------- | -------------------------------------------------- | | `createRootProjectFiles(ctx)` / `createMonorepoRootFiles(ctx)` / `createWorkspaceFiles(ctx)` | Scaffold files for each project kind. | | `generateProjectConfigs(options)` | Generate `dbx.config.ts` for projects missing one. | | `renderToolchainConfig(ctx)` / `renderWorkspaceTsconfig(composite?)` | Render the tooling config / a workspace tsconfig. | | `renderGitignore()` | Render a generic `.gitignore`. | | `catalogsSyncTask()` / `renderYarnrc(catalog)` / `renderPnpmWorkspace(catalog, packages?)` | The catalogs sync task + catalog file renderers. | | `writeGeneratedFiles(files, cwd?)` | Write a `GeneratedFile[]`. | | `projectCommands()` | The `project:*` commands. | --- --- url: https://toolchain.dbx.studio/guide/api/registering-commands.md --- # Registering commands Packages export framework-agnostic `CliCommand[]` descriptors; build them into a program with `engine.cli.program.create()` (preferred), or with the lower-level `createConfigProgram` when the command list is not tied to an engine (this is how the bundled `dbx` binary and a consumer's own CLI are assembled): ```ts import { configCommands } from '@deltabox/toolchain/config'; const program = engine.cli.program.create(() => configCommands({ engine }), { name: 'myapp', version: '1.0.0', globalOptions: [{ flags: '--json', description: 'Print JSON.' }], disableColors: ({ color }) => color === false, }); await program.invokeAsync(); ``` For config-driven commands, `engine.cli.program.create(...)` builds the program runtime with schema-derived options and typed `run` values. It accepts the full program options, including `globalOptions`, `disableColors`, `helpOnError`, `groups`, `sort`, `format`, `argv` and the output hooks. See [Running a built program](/guide/config-generator/api#running-a-built-program) and the [program members](/guide/config-generator/api#program-members-and-options). Custom descriptors do not need to be added to `builtinCommands()` to appear in the generated reference. Pass the same command list to `generateCliDocs`: ```ts import { builtinCommands } from '@deltabox/toolchain/cli'; import { generateCliDocs } from '@deltabox/toolchain/config'; const markdown = generateCliDocs([...builtinCommands(), ...myCommands], { prefix: 'my-cli', }); ``` `generateCliDocs` omits `hidden` commands, keeps the first of any duplicate name, and renders args/options (with defaults) the same way as the `dbx` reference. ## Typed command args `CliCommand` infers its `run(args, context)` object from the literal `options` list. Use `defineCliCommand` so the literal tuple is preserved: ```ts import { defineCliCommand } from '@deltabox/toolchain/shared'; const command = defineCliCommand({ name: 'serve', description: 'Serve.', options: [ { flags: '--json', description: 'JSON output.' }, { flags: '--cwd ', description: 'Project root.' }, { flags: '--tag ', description: 'Tags.' }, { flags: '--no-color', description: 'Disable colour.' }, ], // args.json?: boolean, args.cwd?: string, // args.tag?: string[], args.color?: boolean run: args => serve(args), }); ``` The same inference is available as a type through `CliOptionValues`. Unknown positional args and dynamic flags remain addressable through the index signature. Descriptors also carry optional `argv` and `bin` fields. `argv` feeds the standalone config program runtime (`program.invoke()`/`invokeAsync()`, defaulting to `process.argv.slice(2)`); `bin` makes that runtime execute a relative or absolute binary instead of the in-process `run`. See [the config program runtime](/guide/config-generator/api#running-a-built-program) for `create()`, hooks and help/error formatting. --- --- url: https://toolchain.dbx.studio/guide/api/subpath-exports.md --- # Subpath exports | Import | What it provides | | ------------------------------- | ----------------------------------------------------------------------------------------------- | | `@deltabox/toolchain/cli` | Build the `dbx` engine program + bare-command routing. | | `@deltabox/toolchain/core` | Load `dbx.config.*`, run/watch sync, the project graph, manifest, reset. | | `@deltabox/toolchain/config` | The Zod/env config engine, generators, `config:*` commands and CLI program runtime. | | `@deltabox/toolchain/vite` | Resolve/run `vp`, the Vite+ provider, the `dbx()` plugin and `vite` sync. | | `@deltabox/toolchain/migrate` | Pluggable migrations to Oxfmt/Oxlint (Biome, ESLint, Prettier, Dprint). | | `@deltabox/toolchain/template` | The builtin/local/online template registry, loading and scaffolding. | | `@deltabox/toolchain/providers` | The provider registry (`toolchainProviders`) the editor reads. | | `@deltabox/toolchain/pack` | The tsdown base config, `createTsdownConfig`, post banner and cleanup. | | `@deltabox/toolchain/tsconfig` | The tsconfig sync task, templates and the tsconfig generator. | | `@deltabox/toolchain/changelog` | The changelog runner, workflows, commitlint and the changelog sync task. | | `@deltabox/toolchain/biome` | The generic Biome config, rendering helpers and the biome sync task. | | `@deltabox/toolchain/project` | Project/monorepo/workspace file generation and `dbx.config.ts` scaffolding. | | `@deltabox/toolchain/shared` | The config model, logger, provider model, template engine, ignore defaults, `run`/`spawnCross`. | --- --- url: https://toolchain.dbx.studio/guide/api/umbrella.md --- # Umbrella (`@deltabox/toolchain`) The root re-exports `@deltabox/toolchain-core` and `@deltabox/toolchain-shared` **directly**, and exposes the remaining packages as **namespaces** plus the sync runner: ```ts import { // identity helper (typed config) defineConfig, // config + sync loadToolchainConfig, runSync, runWatch, defaultSyncTasks, // opt-in-by-presence helpers sectionEnabled, sectionConfig, resolveTokens, // logging logger, createLogger, // ignore-list defaults DEFAULT_IGNORE_PATTERNS, DEFAULT_FMT_IGNORE_PATTERNS, DEFAULT_LINT_IGNORE_PATTERNS, } from '@deltabox/toolchain'; // The other packages are namespaced: import { biome, changelog, config, core, pack, project, shared, tsconfig, } from '@deltabox/toolchain'; ``` ```ts const { config, tokens, projectType } = await loadToolchainConfig(process.cwd()); await runSync({ tasks: defaultSyncTasks(), cwd: process.cwd(), config, tokens, projectType }); ``` --- --- url: https://toolchain.dbx.studio/contribute.md --- # Overview Feel free to contribute to the development or docs. > PRs from strangers are disabled for safety and work-load reasons. > > Only maintainers are able to create PRs for now. > > I only add trusted people as maintainers. > You can become a maintainer by forking the repo and for a while create your own worthy PRs with bug fixes/features in the forked repo. Only then, you will be eligible to get reviewed for a maintainer role. ## Guides * [Development](/contribute/development) covers the fork/clone setup, the local commands and the linter/formatter bootstrap fix. * [Documentation](/contribute/documentation) covers writing, previewing and building the docs. --- --- url: https://toolchain.dbx.studio/contribute/development.md --- # Development ## Setup You need to fork **or** clone this repo: ```sh gh repo fork deltabox-studio/toolchain # fork gh repo clone deltabox-studio/toolchain # clone ``` The `dev` branch is the main branch, so no need to switch branches. ## Commands This repo is a Yarn 4 workspace. Vite+ (`vp`) drives format, lint, test and the task runner from the root `vite.config.ts`, which dogfoods the `dbx()` plugin. There is no root `dbx.config.ts`, `vitest.config.ts` or `tsdown.config.ts`. Node `^22.22.1` or `^24.11.0` is required: that is the floor for the bundled Vitest 5 and for `vp staged`. The toolchain config lives in the plugin's `toolchain` option; Vitest and the published package build live in the standard `test` and `pack` fields. Each workspace uses a hand-written plugin-mode `vite.config.ts`; Vite and Vitest resolve workspace imports through `resolve.tsconfigPaths`. ```sh yarn install # fresh checkout yarn dev # run the CLI from src/ via tsx yarn typecheck # packages + root yarn check # Oxfmt + Oxlint check (no writes) yarn check:fix # same, auto-fixing every workspace + the root yarn fmt # `vp fmt` yarn lint # `vp lint --fix` yarn build # packages + root via `vp run` (root pack config) yarn test # builds, then package + root tests yarn test:clean # remove leftover emulation temp workspaces ``` > `vp` resolves only at the repo root, so run these from the root. A full > `yarn build` is only needed for the published `dist`/VSIX: typechecks, > `vp run`/`fmt`/`lint`/`test`, `yarn dev` and Vitest run from source. The > emulate suite spawns the built `dist/cli/index.js` and therefore needs a > build. To run a command against one package, use `vp -C ` > (`vp -C packages/config test`) rather than `cd`-ing into it. ## Git hooks The project-owned hooks live in `.vite-hooks`: * `commit-msg` runs commitlint. * `pre-commit` runs `vp staged`, which applies the root `staged` config (`'*': 'vp check --fix'`) to the staged files. `yarn install` runs the `postinstall` bootstrap, which calls `vp hooks enable` to install the generated dispatcher and point `core.hooksPath` at it. Disable hooks for one clone with `vp hooks disable`, or for one process with `VP_GIT_HOOKS=0`. The dispatcher and its shims live in the ignored `.vite-hooks/_` directory; the hook scripts themselves are committed. The VS Code extension's unit tests run with the root Vitest suite. Its integration suite launches a real extension host (`yarn workspace toolchain-vscode test:integration`); CI runs it under Xvfb in the `vscode-integration` job after `ci`. On Windows it cannot run while VS Code stable is open. ## Random linter/formatter errors The root `vite.config.ts` imports the plugin from `@deltabox/toolchain/vite`, which resolves through the repo's self-link: ``` node_modules/@deltabox/toolchain -> . (repo root) package.json exports "./vite" -> ./dist/vite.js ``` Deleting every `dist/` removes `dist/vite.js`, so loading `vite.config.ts` fails before Oxc/Vite+ can start. Clearing `.vite-temp` will not help. **Fix:** rebuild the root `dist` without going through `vp` (which itself needs the config): ```sh yarn bootstrap ``` This is the checkout bootstrap already used by `postinstall`. It builds the root `dist` directly from `scripts/root-pack.ts` using Vite+'s bundled `tsdown`, bypassing the config-loading cycle. **Notes:** * You only need the root `dist/vite.js` for config loading. The root build inlines workspace sources, so `packages/*/dist` can stay deleted. * If you clean all `dist` dirs again, run `yarn bootstrap` (or `yarn install`, which re-runs the `postinstall`) before using the Oxc VS Code extension or `vp`. ## Docs The docs live in `apps/docs` (VitePress). See [Documentation](/contribute/documentation) for the local preview, build and writing workflow. --- --- url: https://toolchain.dbx.studio/contribute/documentation.md --- # Documentation Full documentation, guides and examples live at [toolchain.dbx.studio](https://toolchain.dbx.studio/guide). The source pages live in `apps/docs` and are built with VitePress. ## Preview locally ```sh yarn workspace @deltabox/toolchain-docs dev ``` ## Build ```sh yarn docs build ``` The build also regenerates the LLM bundles (`llms.txt` and `llms-full.txt`) and copies them to the repo root. ## Writing pages * Add Markdown pages under `apps/docs/guide`, `apps/docs/config` or `apps/docs/contribute`. * The guide sidebar is generated from the docs tree, so a new page appears in its section automatically. New top-level sections, the navbar and the manual Introduction groups are configured in `apps/docs/.vitepress/config.ts`. * The pages under `apps/docs/config` are generated. Run `yarn config:generate` after changing the config schema; do not edit those pages by hand. * Run `yarn fmt` and `yarn docs build` before opening a PR. See the [VitePress documentation](https://vitepress.dev/) for Markdown syntax and theme options. ## Development See [Development](/contribute/development) for the repo setup, commands and the linter/formatter bootstrap fix. --- --- url: https://toolchain.dbx.studio/llms.md --- # LLMs This documentation is published in machine-readable forms so LLMs and coding agents can read it efficiently, following the [llms.txt](https://llmstxt.org) standard: * [`/llms.txt`](/llms.txt) — a concise, link-first overview: a short description, how the toolchain works, and a table of contents linking to the Markdown version of every page. Small enough to fit in a context window. * [`/llms-full.txt`](/llms-full.txt) — the **entire** documentation concatenated into a single Markdown file, for when an agent wants everything in one fetch. Every page is also available as raw Markdown by appending `.md` to its URL (eg. `/guide/tsconfig.md`). ## When the site is unavailable If `https://toolchain.dbx.studio` is down, the same documentation lives in the repository at [github.com/deltabox-studio/toolchain/tree/main/apps/docs](https://github.com/deltabox-studio/toolchain/tree/main/apps/docs). --- --- url: https://toolchain.dbx.studio/CHANGELOG.md --- # Changelog ## 3.0.0-beta.15 (November 2026) * Update domain `toolchain.deltabox.studio` to `toolchain.dbx.studio` ([#966f975](https://github.com/deltabox-studio/toolchain/commit/966f975) by [T0chi](https://github.com/T0chi)) ## 3.0.0-beta.14 (November 2026) #### Changelog * Escape html-like tags so the docs build succeeds ([#b63280c](https://github.com/deltabox-studio/toolchain/commit/b63280c) by [T0chi](https://github.com/T0chi)) * VitePress compiles Markdown as Vue SFCs, so a raw '\' placeholder from a commit body was parsed as an unclosed element and failed apps/docs. Escape tag-like sequences in generated commit subjects and bodies (and while reformatting bullets), while leaving inline code spans, autolinks and comparisons untouched. Also escape the existing beta.19 entry in both changelogs. ## 3.0.0-beta.13 (November 2026) #### Config * Sort help commands and add a sort option ([#518d057](https://github.com/deltabox-studio/toolchain/commit/518d057) by [T0chi](https://github.com/T0chi)) * Commands now render in ascending name order within every help section, including command groups. A new sort option accepts 'asc' (default), 'desc' or false (declaration order), is exposed as program.sort and threads through createCli/runCli via RootCliOptions. Group headings keep their first-appearance order so the dogfood sidebar grouping is preserved. Docs and llms bundle updated. * Group commands by delimited name paths ([#8598303](https://github.com/deltabox-studio/toolchain/commit/8598303) by [T0chi](https://github.com/T0chi)) * Add a groups program option (default true) that renders help commands in grouped sections. With auto enabled (default) commands sharing a name path such as vite:list are grouped under a capitalised heading using the configured delimiter(s), defaulting to ':'. Explicit CliCommand/ConfigProgramCommand group labels override the derived group, groups:false renders a flat list, and groups:{auto:false} only honours explicit groups. dbx createCli/runCli expose the same option. * Group help options by heading ([#4815336](https://github.com/deltabox-studio/toolchain/commit/4815336) by [T0chi](https://github.com/T0chi)) * CliOption gains an optional group label. The default help renderer keeps ungrouped options under Options: and prints each group under its own capitalised heading (case-insensitive, first-appearance order). Grouping works for command options and program globals; the help/format docs and llms bundle are updated. #### Cli * Group the dogfood commands and options like the docs sidebar ([#4d986db](https://github.com/deltabox-studio/toolchain/commit/4d986db) by [T0chi](https://github.com/T0chi)) * Apply the new group feature to the built-in dbx CLI. Core workspace commands stay under Commands:, followed by Project & templates, Tooling, Automation & API, Agents and Vite+ headings in docs-sidebar order. Options gain per-command groups (sync, changelog, migrate, project/template scaffolding, tsconfig, MCP/skills, ...), with groups:false and auto:false still behaving as documented. The generated CLI reference and llms bundle are refreshed. * Make help-on-error opt-in ([#2a01d42](https://github.com/deltabox-studio/toolchain/commit/2a01d42) by [T0chi](https://github.com/T0chi)) * Invalid argv no longer appends the full program help automatically, so failures stay short and scriptable. Config programs gain a helpOnError option (exposed as the readonly program.helpOnError), and dbx's createCli/runCli accept { helpOnError: true } to restore the old behavior. Defaults to false and matches the config engine cli program option. #### Mcp * Teach the official skill to inspect the project ([#1982ac2](https://github.com/deltabox-studio/toolchain/commit/1982ac2) by [T0chi](https://github.com/T0chi)) * The installed skill now tells agents to check whether dbx is enabled via dbx.config.*, a vite.config.* dbx() plugin or .vscode/settings.json (deltabox.toolchain.enabled), read .dbx/toolchain/projects.json for the project graph/config locations and manifest.json for managed files, and inspect the enabled toolchain sections. It calls out commitlint/changelog conventions for commits and documents sync --check. * Add the official dbx skill installer ([#359e166](https://github.com/deltabox-studio/toolchain/commit/359e166) by [T0chi](https://github.com/T0chi)) * Introduce the official docs skill, which tells agents to read https://toolchain.dbx.studio/llms.txt before answering or editing. The mcp package gains checkSkill/installSkill/installOfficialSkill (idempotent, forceable), a 'dbx skills --official' command with provider/scope/dir options, and a skills sync task driven by the new toolchain.mcp.skills section (opt-in by presence). The VS Code extension exposes an 'Install official skill' prompt action and Home quick action. Config types, schema, generated reference and docs are updated. #### Config * Suffix grouped help headings with options or commands ([#342825a](https://github.com/deltabox-studio/toolchain/commit/342825a) by [T0chi](https://github.com/T0chi)) * Named option groups now render as '\ options:' and command groups as '\ commands:', while the default sections stay 'Options:' and 'Commands:'. The program 'groups' option now also flattens option groups when false, so the same toggle controls every help group. - Cover grouped help, sorting and the official skill in v2-v3 ([#d01d5f9](https://github.com/deltabox-studio/toolchain/commit/d01d5f9) by [T0chi](https://github.com/T0chi)) * Document the groups/sort program options, opt-in helpOnError, the dbx skills command and API, toolchain.mcp.skills automatic installation, and the VS Code skill installer action in the migration guide. - Update documentation ([#ba637c3](https://github.com/deltabox-studio/toolchain/commit/ba637c3) by [T0chi](https://github.com/T0chi)) #### Cli * Document the dogfood command groups ([#dcd6d1b](https://github.com/deltabox-studio/toolchain/commit/dcd6d1b) by [T0chi](https://github.com/T0chi)) * List the built-in help groups and their docs-sidebar order. #### Config * Clarify that groups covers options and commands ([#c80cc9c](https://github.com/deltabox-studio/toolchain/commit/c80cc9c) by [T0chi](https://github.com/T0chi)) * The groups program option flattens both option and command groups when false and auto only affects derived command groups. Update the option JSDoc, RootCliOptions docs and guides to say so explicitly. - Replace remaining unicode ellipses ([#0bc4a05](https://github.com/deltabox-studio/toolchain/commit/0bc4a05) by [T0chi](https://github.com/T0chi)) * Normalize the docs committed after the last formatter pass so check stays clean. ## 3.0.0-beta.12 (November 2026) #### Release * Mark prerelease versions as GitHub prereleases ([#dd1c62f](https://github.com/deltabox-studio/toolchain/commit/dd1c62f) by [T0chi](https://github.com/T0chi)) #### Changelog * Document bump rules and harden versioning providers ([#5ae5e02](https://github.com/deltabox-studio/toolchain/commit/5ae5e02) by [T0chi](https://github.com/T0chi)) * Group release bodies since the last published release ([#93b8762](https://github.com/deltabox-studio/toolchain/commit/93b8762) by [T0chi](https://github.com/T0chi)) #### Changelog * Repair and audit markdown code fences ([#8a4ab01](https://github.com/deltabox-studio/toolchain/commit/8a4ab01) by [T0chi](https://github.com/T0chi)) - Update permalinks ([#5abe04e](https://github.com/deltabox-studio/toolchain/commit/5abe04e) by [T0chi](https://github.com/T0chi)) - Add a deprecations section to the v2-v3 guide ([#3121d44](https://github.com/deltabox-studio/toolchain/commit/3121d44) by [T0chi](https://github.com/T0chi)) #### Release * Clarify auto prerelease detection ([#bc5c01f](https://github.com/deltabox-studio/toolchain/commit/bc5c01f) by [T0chi](https://github.com/T0chi)) #### Changelog * Add a release bodies guide under the changelog section ([#e00a44b](https://github.com/deltabox-studio/toolchain/commit/e00a44b) by [T0chi](https://github.com/T0chi)) ## 3.0.0-beta.11 (November 2026) * Use the published Vite subpath in generated configs ([#d5f2fab](https://github.com/deltabox-studio/toolchain/commit/d5f2fab) by [T0chi](https://github.com/T0chi)) - Rename format scripts and tasks to fmt ([#fcd3ae0](https://github.com/deltabox-studio/toolchain/commit/fcd3ae0) by [T0chi](https://github.com/T0chi)) * Refresh readmes and extension copy ([#ad7e37d](https://github.com/deltabox-studio/toolchain/commit/ad7e37d) by [T0chi](https://github.com/T0chi)) * Highlight who the toolchain is for ([#bdd324a](https://github.com/deltabox-studio/toolchain/commit/bdd324a) by [T0chi](https://github.com/T0chi)) * Expand who the toolchain is for ([#128d875](https://github.com/deltabox-studio/toolchain/commit/128d875) by [T0chi](https://github.com/T0chi)) * Explain providers for other language toolchains ([#1671f9e](https://github.com/deltabox-studio/toolchain/commit/1671f9e) by [T0chi](https://github.com/T0chi)) * Note the toolchain dogfoods itself ([#e864aef](https://github.com/deltabox-studio/toolchain/commit/e864aef) by [T0chi](https://github.com/T0chi)) * Cover core features in why use this ([#195bba8](https://github.com/deltabox-studio/toolchain/commit/195bba8) by [T0chi](https://github.com/T0chi)) * Split programmatic API examples into sections ([#8f8ebd9](https://github.com/deltabox-studio/toolchain/commit/8f8ebd9) by [T0chi](https://github.com/T0chi)) * Add contextual sidebar sections ([#aca7fdf](https://github.com/deltabox-studio/toolchain/commit/aca7fdf) by [T0chi](https://github.com/T0chi)) * Remove Contribute from the top navbar ([#5dce447](https://github.com/deltabox-studio/toolchain/commit/5dce447) by [T0chi](https://github.com/T0chi)) * Move navbar search beside the logo ([#aa7c7de](https://github.com/deltabox-studio/toolchain/commit/aa7c7de) by [T0chi](https://github.com/T0chi)) * Add v3 new features to the migration guide ([#0a5ee8b](https://github.com/deltabox-studio/toolchain/commit/0a5ee8b) by [T0chi](https://github.com/T0chi)) * Fix invalid folder-tree YAML in template structures ([#c7e8efa](https://github.com/deltabox-studio/toolchain/commit/c7e8efa) by [T0chi](https://github.com/T0chi)) - Commit pending docs and type updates ([#5701b52](https://github.com/deltabox-studio/toolchain/commit/5701b52) by [T0chi](https://github.com/T0chi)) - Cleanup references ([#a0027cd](https://github.com/deltabox-studio/toolchain/commit/a0027cd) by [T0chi](https://github.com/T0chi)) ## 3.0.0-beta.10 (November 2026) * Align hooks and monorepo guidance with Vite+ ([#0aadd01](https://github.com/deltabox-studio/toolchain/commit/0aadd01) by [T0chi](https://github.com/T0chi)) ## 3.0.0-beta.9 (November 2026) * Clarify vite-plus is a dev dependency ([#b7d5ce6](https://github.com/deltabox-studio/toolchain/commit/b7d5ce6) by [T0chi](https://github.com/T0chi)) ## 3.0.0-beta.8 (November 2026) #### Changelog * Build release bodies from markers and rename flags ([#825985d](https://github.com/deltabox-studio/toolchain/commit/825985d) by [T0chi](https://github.com/T0chi)) - Prefer engine.cli.program.create and update v3 guides ([#325d2fd](https://github.com/deltabox-studio/toolchain/commit/325d2fd) by [T0chi](https://github.com/T0chi)) - Cover template structures and config CLI programs ([#8d5e2c5](https://github.com/deltabox-studio/toolchain/commit/8d5e2c5) by [T0chi](https://github.com/T0chi)) * Document folder-tree template structures, the config-engine program/command APIs, schema-driven CLI metadata, and the new source-specific loaders. Refresh generated CLI/config pages and the llms bundles. - Document static config types in the overview ([#fd00295](https://github.com/deltabox-studio/toolchain/commit/fd00295) by [T0chi](https://github.com/T0chi)) - Expand the v2 to v3 migration guide ([#854baaf](https://github.com/deltabox-studio/toolchain/commit/854baaf) by [T0chi](https://github.com/T0chi)) - Revamp the config generator guides ([#f54c5f1](https://github.com/deltabox-studio/toolchain/commit/f54c5f1) by [T0chi](https://github.com/T0chi)) - Add client and server config guide ([#5dcbedc](https://github.com/deltabox-studio/toolchain/commit/5dcbedc) by [T0chi](https://github.com/T0chi)) #### Config * Regenerate schema and reference artifacts ([#2f0b6af](https://github.com/deltabox-studio/toolchain/commit/2f0b6af) by [T0chi](https://github.com/T0chi)) - Format generated config artifacts and docs ([#2ff28be](https://github.com/deltabox-studio/toolchain/commit/2ff28be) by [T0chi](https://github.com/T0chi)) - Replace unicode ellipses with three dots ([#2d7c130](https://github.com/deltabox-studio/toolchain/commit/2d7c130) by [T0chi](https://github.com/T0chi)) ## 3.0.0-beta.7 (November 2026) * Add Contribute to the docs navigation ([#c7a32e4](https://github.com/deltabox-studio/toolchain/commit/c7a32e4) by [T0chi](https://github.com/T0chi)) * Add the contribute guide ([#17c62df](https://github.com/deltabox-studio/toolchain/commit/17c62df) by [T0chi](https://github.com/T0chi)) * Update migration guide links ([#b58b9fb](https://github.com/deltabox-studio/toolchain/commit/b58b9fb) by [T0chi](https://github.com/T0chi)) ## 3.0.0-beta.6 (November 2026) * Reorganize the documentation navigation ([#342de5a](https://github.com/deltabox-studio/toolchain/commit/342de5a) by [T0chi](https://github.com/T0chi)) * Document the Vite plugin and Vite+ commands ([#95c1e66](https://github.com/deltabox-studio/toolchain/commit/95c1e66) by [T0chi](https://github.com/T0chi)) * Expand the v3 migration guide ([#9a6d0d0](https://github.com/deltabox-studio/toolchain/commit/9a6d0d0) by [T0chi](https://github.com/T0chi)) #### Vscode * Sync the extension reference ([#9824034](https://github.com/deltabox-studio/toolchain/commit/9824034) by [T0chi](https://github.com/T0chi)) #### Config * Revamp the configuration overview ([#fe4137e](https://github.com/deltabox-studio/toolchain/commit/fe4137e) by [T0chi](https://github.com/T0chi)) ## 3.0.0-beta.5 (November 2026) #### Ci * Bump setup-vp to v1.22.0 ([#9c32cae](https://github.com/deltabox-studio/toolchain/commit/9c32cae) by [T0chi](https://github.com/T0chi)) ## 3.0.0-beta.4 (November 2026) #### Deps * Bump the minor-and-patch group across 1 directory with 59 updates ([#45](https://github.com/deltabox-studio/toolchain/issues/45)) ([#1c2276c](https://github.com/deltabox-studio/toolchain/commit/1c2276c) by [dependabot\[bot\]](https://github.com/dependabot[bot])) * chore(deps): bump the minor-and-patch group across 1 directory with 59 updates * Bumps the minor-and-patch group with 59 updates in the / directory: * | Package | From | To | | --- | --- | --- | | [@commitlint/cli](https://github.com/conventional-changelog/commitlint/tree/HEAD/@commitlint/cli) | `21.2.3` | `21.2.4` | | [@commitlint/config-conventional](https://github.com/conventional-changelog/commitlint/tree/HEAD/@commitlint/config-conventional) | `21.2.3` | `21.2.4` | | [@types/vscode](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/HEAD/types/vscode) | `1.140.0` | `1.146.0` | | [vitepress-plugin-group-icons](https://github.com/yuyinws/vitepress-plugin-group-icons) | `1.8.1` | `1.8.2` | | [vitepress-plugin-llms](https://github.com/okineadev/vitepress-plugin-llms) | `1.14.0` | `1.15.0` | | [@babel/helper-string-parser](https://github.com/babel/babel/tree/HEAD/packages/babel-helper-string-parser) | `7.29.7` | `7.29.14` | | [@babel/parser](https://github.com/babel/babel/tree/HEAD/packages/babel-parser) | `7.29.9` | `7.29.14` | | [@babel/runtime](https://github.com/babel/babel/tree/HEAD/packages/babel-runtime) | `7.29.10` | `7.29.14` | | [@babel/types](https://github.com/babel/babel/tree/HEAD/packages/babel-types) | `7.29.8` | `7.29.14` | | [@clack/prompts](https://github.com/bombshell-dev/clack/tree/HEAD/packages/prompts) | `1.8.1` | `1.9.0` | | [@commitlint/ensure](https://github.com/conventional-changelog/commitlint/tree/HEAD/@commitlint/ensure) | `21.2.3` | `21.2.4` | | [@commitlint/lint](https://github.com/conventional-changelog/commitlint/tree/HEAD/@commitlint/lint) | `21.2.3` | `21.2.4` | | [@commitlint/load](https://github.com/conventional-changelog/commitlint/tree/HEAD/@commitlint/load) | `21.2.3` | `21.2.4` | | [@commitlint/rules](https://github.com/conventional-changelog/commitlint/tree/HEAD/@commitlint/rules) | `21.2.3` | `21.2.4` | | [@conventional-changelog/template](https://github.com/conventional-changelog/conventional-changelog/tree/HEAD/packages/template) | `1.4.0` | `1.4.1` | | [@eslint-community/regexpp](https://github.com/eslint-community/regexpp) | `4.12.2` | `4.12.3` | | [@eslint/config-array](https://github.com/eslint/rewrite/tree/HEAD/packages/config-array) | `0.23.5` | `0.23.6` | | [@fastify/deepmerge](https://github.com/fastify/deepmerge) | `3.2.2` | `3.2.4` | | [@fastify/fast-json-stringify-compiler](https://github.com/fastify/fast-json-stringify-compiler) | `5.1.1` | `5.2.0` | | [@fastify/forwarded](https://github.com/fastify/forwarded) | `3.1.1` | `3.1.2` | | [@fastify/proxy-addr](https://github.com/fastify/proxy-addr) | `5.1.2` | `5.1.3` | | [@iconify-json/logos](https://github.com/iconify/icon-sets) | `1.2.17` | `1.2.20` | | [@iconify-json/vscode-icons](https://github.com/iconify/icon-sets) | `1.2.93` | `1.2.99` | | [@jridgewell/resolve-uri](https://github.com/jridgewell/resolve-uri) | `3.1.2` | `3.1.3` | | [@rolldown/pluginutils](https://github.com/rolldown/plugins/tree/HEAD/packages/pluginutils) | `1.0.1` | `1.1.1` | | [@shikijs/vscode-textmate](https://github.com/shikijs/vscode-textmate) | `10.0.2` | `10.1.0` | | [@types/lodash](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/HEAD/types/lodash) | `4.17.26` | `4.17.27` | | [brace-expansion](https://github.com/juliangruber/brace-expansion) | `1.1.21` | `1.1.22` | | [conventional-commits-parser](https://github.com/conventional-changelog/conventional-changelog/tree/HEAD/packages/conventional-commits-parser) | `7.1.3` | `7.1.4` | | [cookie](https://github.com/jshttp/cookie) | `2.0.1` | `2.0.2` | | [dotenv](https://github.com/motdotla/dotenv) | `18.0.7` | `18.0.10` | | [enhanced-resolve](https://github.com/webpack/enhanced-resolve) | `5.26.0` | `5.27.0` | | [es-toolkit](https://github.com/toss/es-toolkit) | `1.52.0` | `1.53.2` | | [fast-json-stringify](https://github.com/fastify/fast-json-stringify) | `7.1.0` | `7.3.6` | | [fast-uri](https://github.com/fastify/fast-uri) | `3.1.8` | `3.1.9` | | [fastify](https://github.com/fastify/fastify) | `5.12.5` | `5.12.8` | | [find-my-way](https://github.com/delvedor/find-my-way) | `9.10.0` | `9.10.1` | | [graceful-fs](https://github.com/isaacs/node-graceful-fs) | `4.2.11` | `4.2.12` | | [is-core-module](https://github.com/inspect-js/is-core-module) | `2.17.0` | `2.18.0` | | [jiti](https://github.com/unjs/jiti) | `2.6.1` | `2.7.0` | | [light-my-request](https://github.com/fastify/light-my-request) | `6.8.0` | `6.8.1` | | [mdast-util-to-hast](https://github.com/syntax-tree/mdast-util-to-hast) | `13.2.1` | `13.2.2` | | [mdast-util-to-markdown](https://github.com/syntax-tree/mdast-util-to-markdown) | `2.2.0` | `2.2.3` | | [postcss](https://github.com/postcss/postcss) | `8.5.29` | `8.5.33` | | [ret](https://github.com/fent/ret.js) | `0.5.0` | `0.5.1` | | [semver](https://github.com/npm/node-semver) | `6.3.1` | `6.3.2` | | [sisteransi](https://github.com/terkelg/sisteransi) | `1.0.5` | `2.0.0` | | [tabbable](https://github.com/focus-trap/tabbable) | `6.5.0` | `6.5.2` | | [tapable](https://github.com/webpack/tapable) | `2.3.3` | `2.3.4` | | [tar](https://github.com/isaacs/node-tar) | `7.5.22` | `7.5.23` | | [thread-stream](https://github.com/mcollina/thread-stream) | `4.2.0` | `4.2.1` | | [undici](https://github.com/nodejs/undici) | `8.11.2` | `8.12.4` | | [unist-util-visit-parents](https://github.com/syntax-tree/unist-util-visit-parents) | `6.0.2` | `6.1.0` | | [unist-util-visit](https://github.com/syntax-tree/unist-util-visit) | `5.1.0` | `5.2.0` | | [vfile-message](https://github.com/vfile/vfile-message) | `4.0.3` | `4.0.4` | | [vue-tsc](https://github.com/vuejs/language-tools/tree/HEAD/packages/tsc) | `3.3.13` | `3.3.14` | | [vue](https://github.com/vuejs/core) | `3.5.44` | `3.5.45` | | [ws](https://github.com/websockets/ws) | `8.22.0` | `8.23.0` | | [zod](https://github.com/colinhacks/zod) | `4.6.5` | `4.6.7` | * Updates `@commitlint/cli` from 21.2.3 to 21.2.4 * [Release notes](https://github.com/conventional-changelog/commitlint/releases) * [Changelog](https://github.com/conventional-changelog/commitlint/blob/master/@commitlint/cli/CHANGELOG.md) * [Commits](https://github.com/conventional-changelog/commitlint/commits/v21.2.4/@commitlint/cli) * Updates `@commitlint/config-conventional` from 21.2.3 to 21.2.4 * [Release notes](https://github.com/conventional-changelog/commitlint/releases) * [Changelog](https://github.com/conventional-changelog/commitlint/blob/master/@commitlint/config-conventional/CHANGELOG.md) * [Commits](https://github.com/conventional-changelog/commitlint/commits/v21.2.4/@commitlint/config-conventional) * Updates `@types/vscode` from 1.140.0 to 1.146.0 * [Release notes](https://github.com/DefinitelyTyped/DefinitelyTyped/releases) * [Commits](https://github.com/DefinitelyTyped/DefinitelyTyped/commits/HEAD/types/vscode) * Updates `vitepress-plugin-group-icons` from 1.8.1 to 1.8.2 * [Release notes](https://github.com/yuyinws/vitepress-plugin-group-icons/releases) * [Commits](https://github.com/yuyinws/vitepress-plugin-group-icons/compare/v1.8.1...v1.8.2) * Updates `vitepress-plugin-llms` from 1.14.0 to 1.15.0 * [Release notes](https://github.com/okineadev/vitepress-plugin-llms/releases) * [Commits](https://github.com/okineadev/vitepress-plugin-llms/compare/v1.14.0...v1.15.0) * Updates `@babel/helper-string-parser` from 7.29.7 to 7.29.14 * [Release notes](https://github.com/babel/babel/releases) * [Changelog](https://github.com/babel/babel/blob/main/CHANGELOG.md) * [Commits](https://github.com/babel/babel/commits/v7.29.14/packages/babel-helper-string-parser) * Updates `@babel/parser` from 7.29.9 to 7.29.14 * [Release notes](https://github.com/babel/babel/releases) * [Changelog](https://github.com/babel/babel/blob/main/CHANGELOG.md) * [Commits](https://github.com/babel/babel/commits/v7.29.14/packages/babel-parser) * Updates `@babel/runtime` from 7.29.10 to 7.29.14 * [Release notes](https://github.com/babel/babel/releases) * [Changelog](https://github.com/babel/babel/blob/main/CHANGELOG.md) * [Commits](https://github.com/babel/babel/commits/v7.29.14/packages/babel-runtime) * Updates `@babel/types` from 7.29.8 to 7.29.14 * [Release notes](https://github.com/babel/babel/releases) * [Changelog](https://github.com/babel/babel/blob/main/CHANGELOG.md) * [Commits](https://github.com/babel/babel/commits/v7.29.14/packages/babel-types) * Updates `@clack/prompts` from 1.8.1 to 1.9.0 * [Release notes](https://github.com/bombshell-dev/clack/releases) * [Changelog](https://github.com/bombshell-dev/clack/blob/main/packages/prompts/CHANGELOG.md) * [Commits](https://github.com/bombshell-dev/clack/commits/@clack/prompts@1.9.0/packages/prompts) * Updates `@commitlint/ensure` from 21.2.3 to 21.2.4 * [Release notes](https://github.com/conventional-changelog/commitlint/releases) * [Changelog](https://github.com/conventional-changelog/commitlint/blob/master/@commitlint/ensure/CHANGELOG.md) * [Commits](https://github.com/conventional-changelog/commitlint/commits/v21.2.4/@commitlint/ensure) * Updates `@commitlint/lint` from 21.2.3 to 21.2.4 * [Release notes](https://github.com/conventional-changelog/commitlint/releases) * [Changelog](https://github.com/conventional-changelog/commitlint/blob/master/@commitlint/lint/CHANGELOG.md) * [Commits](https://github.com/conventional-changelog/commitlint/commits/v21.2.4/@commitlint/lint) * Updates `@commitlint/load` from 21.2.3 to 21.2.4 * [Release notes](https://github.com/conventional-changelog/commitlint/releases) * [Changelog](https://github.com/conventional-changelog/commitlint/blob/master/@commitlint/load/CHANGELOG.md) * [Commits](https://github.com/conventional-changelog/commitlint/commits/v21.2.4/@commitlint/load) * Updates `@commitlint/rules` from 21.2.3 to 21.2.4 * [Release notes](https://github.com/conventional-changelog/commitlint/releases) * [Changelog](https://github.com/conventional-changelog/commitlint/blob/master/@commitlint/rules/CHANGELOG.md) * [Commits](https://github.com/conventional-changelog/commitlint/commits/v21.2.4/@commitlint/rules) * Updates `@conventional-changelog/template` from 1.4.0 to 1.4.1 * [Release notes](https://github.com/conventional-changelog/conventional-changelog/releases) * [Changelog](https://github.com/conventional-changelog/conventional-changelog/blob/master/packages/template/CHANGELOG.md) * [Commits](https://github.com/conventional-changelog/conventional-changelog/commits/template-v1.4.1/packages/template) * Updates `@eslint-community/regexpp` from 4.12.2 to 4.12.3 * [Release notes](https://github.com/eslint-community/regexpp/releases) * [Commits](https://github.com/eslint-community/regexpp/compare/v4.12.2...v4.12.3) * Updates `@eslint/config-array` from 0.23.5 to 0.23.6 * [Release notes](https://github.com/eslint/rewrite/releases) * [Changelog](https://github.com/eslint/rewrite/blob/main/packages/config-array/CHANGELOG.md) * [Commits](https://github.com/eslint/rewrite/commits/config-array-v0.23.6/packages/config-array) * Updates `@fastify/deepmerge` from 3.2.2 to 3.2.4 * [Release notes](https://github.com/fastify/deepmerge/releases) * [Commits](https://github.com/fastify/deepmerge/compare/v3.2.2...v3.2.4) * Updates `@fastify/fast-json-stringify-compiler` from 5.1.1 to 5.2.0 * [Release notes](https://github.com/fastify/fast-json-stringify-compiler/releases) * [Commits](https://github.com/fastify/fast-json-stringify-compiler/compare/v5.1.1...v5.2.0) * Updates `@fastify/forwarded` from 3.1.1 to 3.1.2 * [Release notes](https://github.com/fastify/forwarded/releases) * [Commits](https://github.com/fastify/forwarded/compare/v3.1.1...v3.1.2) * Updates `@fastify/proxy-addr` from 5.1.2 to 5.1.3 * [Release notes](https://github.com/fastify/proxy-addr/releases) * [Commits](https://github.com/fastify/proxy-addr/compare/v5.1.2...v5.1.3) * Updates `@iconify-json/logos` from 1.2.17 to 1.2.20 * [Commits](https://github.com/iconify/icon-sets/commits) * Updates `@iconify-json/vscode-icons` from 1.2.93 to 1.2.99 * [Commits](https://github.com/iconify/icon-sets/commits) * Updates `@jridgewell/resolve-uri` from 3.1.2 to 3.1.3 * [Release notes](https://github.com/jridgewell/resolve-uri/releases) * [Commits](https://github.com/jridgewell/resolve-uri/compare/v3.1.2...v3.1.3) * Updates `@rolldown/pluginutils` from 1.0.1 to 1.1.1 * [Release notes](https://github.com/rolldown/plugins/releases) * [Changelog](https://github.com/rolldown/plugins/blob/main/packages/pluginutils/CHANGELOG.md) * [Commits](https://github.com/rolldown/plugins/commits/pluginutils@1.1.1/packages/pluginutils) * Updates `@shikijs/vscode-textmate` from 10.0.2 to 10.1.0 * [Commits](https://github.com/shikijs/vscode-textmate/compare/v10.0.2...v10.1.0) * Updates `@types/lodash` from 4.17.26 to 4.17.27 * [Release notes](https://github.com/DefinitelyTyped/DefinitelyTyped/releases) * [Commits](https://github.com/DefinitelyTyped/DefinitelyTyped/commits/HEAD/types/lodash) * Updates `brace-expansion` from 1.1.21 to 1.1.22 * [Release notes](https://github.com/juliangruber/brace-expansion/releases) * [Commits](https://github.com/juliangruber/brace-expansion/compare/v1.1.21...v1.1.22) * Updates `conventional-commits-parser` from 7.1.3 to 7.1.4 * [Release notes](https://github.com/conventional-changelog/conventional-changelog/releases) * [Changelog](https://github.com/conventional-changelog/conventional-changelog/blob/master/packages/conventional-commits-parser/CHANGELOG.md) * [Commits](https://github.com/conventional-changelog/conventional-changelog/commits/conventional-commits-parser-v7.1.4/packages/conventional-commits-parser) * Updates `cookie` from 2.0.1 to 2.0.2 * [Release notes](https://github.com/jshttp/cookie/releases) * [Commits](https://github.com/jshttp/cookie/compare/v2.0.1...v2.0.2) * Updates `dotenv` from 18.0.7 to 18.0.10 * [Changelog](https://github.com/motdotla/dotenv/blob/master/CHANGELOG.md) * [Commits](https://github.com/motdotla/dotenv/compare/v18.0.7...v18.0.10) * Updates `enhanced-resolve` from 5.26.0 to 5.27.0 * [Release notes](https://github.com/webpack/enhanced-resolve/releases) * [Changelog](https://github.com/webpack/enhanced-resolve/blob/main/CHANGELOG.md) * [Commits](https://github.com/webpack/enhanced-resolve/compare/v5.26.0...v5.27.0) * Updates `es-toolkit` from 1.52.0 to 1.53.2 * [Release notes](https://github.com/toss/es-toolkit/releases) * [Changelog](https://github.com/toss/es-toolkit/blob/main/CHANGELOG.md) * [Commits](https://github.com/toss/es-toolkit/compare/v1.52.0...v1.53.2) * Updates `fast-json-stringify` from 7.1.0 to 7.3.6 * [Release notes](https://github.com/fastify/fast-json-stringify/releases) * [Commits](https://github.com/fastify/fast-json-stringify/compare/v7.1.0...v7.3.6) * Updates `fast-uri` from 3.1.8 to 3.1.9 * [Release notes](https://github.com/fastify/fast-uri/releases) * [Commits](https://github.com/fastify/fast-uri/compare/v3.1.8...v3.1.9) * Updates `fastify` from 5.12.5 to 5.12.8 * [Release notes](https://github.com/fastify/fastify/releases) * [Commits](https://github.com/fastify/fastify/compare/v5.12.5...v5.12.8) * Updates `find-my-way` from 9.10.0 to 9.10.1 * [Release notes](https://github.com/delvedor/find-my-way/releases) * [Commits](https://github.com/delvedor/find-my-way/compare/v9.10.0...v9.10.1) * Updates `graceful-fs` from 4.2.11 to 4.2.12 * [Commits](https://github.com/isaacs/node-graceful-fs/compare/v4.2.11...v4.2.12) * Updates `is-core-module` from 2.17.0 to 2.18.0 * [Changelog](https://github.com/inspect-js/is-core-module/blob/main/CHANGELOG.md) * [Commits](https://github.com/inspect-js/is-core-module/compare/v2.17.0...v2.18.0) * Updates `jiti` from 2.6.1 to 2.7.0 * [Release notes](https://github.com/unjs/jiti/releases) * [Changelog](https://github.com/unjs/jiti/blob/main/CHANGELOG.md) * [Commits](https://github.com/unjs/jiti/compare/v2.6.1...v2.7.0) * Updates `light-my-request` from 6.8.0 to 6.8.1 * [Release notes](https://github.com/fastify/light-my-request/releases) * [Commits](https://github.com/fastify/light-my-request/compare/v6.8.0...v6.8.1) * Updates `mdast-util-to-hast` from 13.2.1 to 13.2.2 * [Release notes](https://github.com/syntax-tree/mdast-util-to-hast/releases) * [Commits](https://github.com/syntax-tree/mdast-util-to-hast/compare/13.2.1...13.2.2) * Updates `mdast-util-to-markdown` from 2.2.0 to 2.2.3 * [Release notes](https://github.com/syntax-tree/mdast-util-to-markdown/releases) * [Commits](https://github.com/syntax-tree/mdast-util-to-markdown/compare/2.2.0...2.2.3) * Updates `postcss` from 8.5.29 to 8.5.33 * [Release notes](https://github.com/postcss/postcss/releases) * [Changelog](https://github.com/postcss/postcss/blob/main/CHANGELOG.md) * [Commits](https://github.com/postcss/postcss/compare/8.5.29...8.5.33) * Updates `ret` from 0.5.0 to 0.5.1 * [Release notes](https://github.com/fent/ret.js/releases) * [Commits](https://github.com/fent/ret.js/compare/v0.5.0...v0.5.1) * Updates `semver` from 6.3.1 to 6.3.2 * [Release notes](https://github.com/npm/node-semver/releases) * [Changelog](https://github.com/npm/node-semver/blob/v6.3.2/CHANGELOG.md) * [Commits](https://github.com/npm/node-semver/compare/v6.3.1...v6.3.2) * Updates `sisteransi` from 1.0.5 to 2.0.0 * [Release notes](https://github.com/terkelg/sisteransi/releases) * [Commits](https://github.com/terkelg/sisteransi/compare/v1.0.5...v2.0.0) * Updates `tabbable` from 6.5.0 to 6.5.2 * [Release notes](https://github.com/focus-trap/tabbable/releases) * [Changelog](https://github.com/focus-trap/tabbable/blob/master/CHANGELOG.md) * [Commits](https://github.com/focus-trap/tabbable/commits) * Updates `tapable` from 2.3.3 to 2.3.4 * [Release notes](https://github.com/webpack/tapable/releases) * [Changelog](https://github.com/webpack/tapable/blob/main/CHANGELOG.md) * [Commits](https://github.com/webpack/tapable/compare/v2.3.3...v2.3.4) * Updates `tar` from 7.5.22 to 7.5.23 * [Release notes](https://github.com/isaacs/node-tar/releases) * [Changelog](https://github.com/isaacs/node-tar/blob/main/CHANGELOG.md) * [Commits](https://github.com/isaacs/node-tar/compare/v7.5.22...v7.5.23) * Updates `thread-stream` from 4.2.0 to 4.2.1 * [Release notes](https://github.com/mcollina/thread-stream/releases) * [Commits](https://github.com/mcollina/thread-stream/compare/v4.2.0...v4.2.1) * Updates `undici` from 8.11.2 to 8.12.4 * [Release notes](https://github.com/nodejs/undici/releases) * [Commits](https://github.com/nodejs/undici/compare/v8.11.2...v8.12.4) * Updates `unist-util-visit-parents` from 6.0.2 to 6.1.0 * [Release notes](https://github.com/syntax-tree/unist-util-visit-parents/releases) * [Commits](https://github.com/syntax-tree/unist-util-visit-parents/compare/6.0.2...6.1.0) * Updates `unist-util-visit` from 5.1.0 to 5.2.0 * [Release notes](https://github.com/syntax-tree/unist-util-visit/releases) * [Commits](https://github.com/syntax-tree/unist-util-visit/compare/5.1.0...5.2.0) * Updates `vfile-message` from 4.0.3 to 4.0.4 * [Release notes](https://github.com/vfile/vfile-message/releases) * [Commits](https://github.com/vfile/vfile-message/compare/4.0.3...4.0.4) * Updates `vue-tsc` from 3.3.13 to 3.3.14 * [Release notes](https://github.com/vuejs/language-tools/releases) * [Changelog](https://github.com/vuejs/language-tools/blob/master/CHANGELOG.md) * [Commits](https://github.com/vuejs/language-tools/commits/v3.3.14/packages/tsc) * Updates `vue` from 3.5.44 to 3.5.45 * [Release notes](https://github.com/vuejs/core/releases) * [Changelog](https://github.com/vuejs/core/blob/main/CHANGELOG.md) * [Commits](https://github.com/vuejs/core/compare/v3.5.44...v3.5.45) * Updates `ws` from 8.22.0 to 8.23.0 * [Release notes](https://github.com/websockets/ws/releases) * [Commits](https://github.com/websockets/ws/compare/8.22.0...8.23.0) * Updates `zod` from 4.6.5 to 4.6.7 * [Release notes](https://github.com/colinhacks/zod/releases) * [Commits](https://github.com/colinhacks/zod/compare/v4.6.5...v4.6.7) * \--- updated-dependencies: * dependency-name: "@babel/helper-string-parser" dependency-version: 7.29.14 dependency-type: indirect update-type: version-update:semver-patch dependency-group: minor-and-patch * dependency-name: "@babel/parser" dependency-version: 7.29.14 dependency-type: indirect update-type: version-update:semver-patch dependency-group: minor-and-patch * dependency-name: "@babel/runtime" dependency-version: 7.29.14 dependency-type: indirect update-type: version-update:semver-patch dependency-group: minor-and-patch * dependency-name: "@babel/types" dependency-version: 7.29.14 dependency-type: indirect update-type: version-update:semver-patch dependency-group: minor-and-patch * dependency-name: "@clack/prompts" dependency-version: 1.9.0 dependency-type: indirect update-type: version-update:semver-minor dependency-group: minor-and-patch * dependency-name: "@commitlint/cli" dependency-version: 21.2.4 dependency-type: direct:development update-type: version-update:semver-patch dependency-group: minor-and-patch * dependency-name: "@commitlint/config-conventional" dependency-version: 21.2.4 dependency-type: direct:development update-type: version-update:semver-patch dependency-group: minor-and-patch * dependency-name: "@commitlint/ensure" dependency-version: 21.2.4 dependency-type: indirect update-type: version-update:semver-patch dependency-group: minor-and-patch * dependency-name: "@commitlint/lint" dependency-version: 21.2.4 dependency-type: indirect update-type: version-update:semver-patch dependency-group: minor-and-patch * dependency-name: "@commitlint/load" dependency-version: 21.2.4 dependency-type: indirect update-type: version-update:semver-patch dependency-group: minor-and-patch * dependency-name: "@commitlint/rules" dependency-version: 21.2.4 dependency-type: indirect update-type: version-update:semver-patch dependency-group: minor-and-patch * dependency-name: "@conventional-changelog/template" dependency-version: 1.4.1 dependency-type: indirect update-type: version-update:semver-patch dependency-group: minor-and-patch * dependency-name: "@eslint-community/regexpp" dependency-version: 4.12.3 dependency-type: indirect update-type: version-update:semver-patch dependency-group: minor-and-patch * dependency-name: "@eslint/config-array" dependency-version: 0.23.6 dependency-type: indirect update-type: version-update:semver-patch dependency-group: minor-and-patch * dependency-name: "@fastify/deepmerge" dependency-version: 3.2.4 dependency-type: indirect update-type: version-update:semver-patch dependency-group: minor-and-patch * dependency-name: "@fastify/fast-json-stringify-compiler" dependency-version: 5.2.0 dependency-type: indirect update-type: version-update:semver-minor dependency-group: minor-and-patch * dependency-name: "@fastify/forwarded" dependency-version: 3.1.2 dependency-type: indirect update-type: version-update:semver-patch dependency-group: minor-and-patch * dependency-name: "@fastify/proxy-addr" dependency-version: 5.1.3 dependency-type: indirect update-type: version-update:semver-patch dependency-group: minor-and-patch * dependency-name: "@iconify-json/logos" dependency-version: 1.2.20 dependency-type: indirect update-type: version-update:semver-patch dependency-group: minor-and-patch * dependency-name: "@iconify-json/vscode-icons" dependency-version: 1.2.99 dependency-type: indirect update-type: version-update:semver-patch dependency-group: minor-and-patch * dependency-name: "@jridgewell/resolve-uri" dependency-version: 3.1.3 dependency-type: indirect update-type: version-update:semver-patch dependency-group: minor-and-patch * dependency-name: "@rolldown/pluginutils" dependency-version: 1.1.1 dependency-type: indirect update-type: version-update:semver-minor dependency-group: minor-and-patch * dependency-name: "@shikijs/vscode-textmate" dependency-version: 10.1.0 dependency-type: indirect update-type: version-update:semver-minor dependency-group: minor-and-patch * dependency-name: "@types/lodash" dependency-version: 4.17.27 dependency-type: indirect update-type: version-update:semver-patch dependency-group: minor-and-patch * dependency-name: "@types/vscode" dependency-version: 1.146.0 dependency-type: direct:development update-type: version-update:semver-minor dependency-group: minor-and-patch * dependency-name: brace-expansion dependency-version: 1.1.22 dependency-type: indirect update-type: version-update:semver-patch dependency-group: minor-and-patch * dependency-name: conventional-commits-parser dependency-version: 7.1.4 dependency-type: indirect update-type: version-update:semver-patch dependency-group: minor-and-patch * dependency-name: cookie dependency-version: 2.0.2 dependency-type: indirect update-type: version-update:semver-patch dependency-group: minor-and-patch * dependency-name: dotenv dependency-version: 18.0.10 dependency-type: indirect update-type: version-update:semver-patch dependency-group: minor-and-patch * dependency-name: enhanced-resolve dependency-version: 5.27.0 dependency-type: indirect update-type: version-update:semver-minor dependency-group: minor-and-patch * dependency-name: es-toolkit dependency-version: 1.53.2 dependency-type: indirect update-type: version-update:semver-minor dependency-group: minor-and-patch * dependency-name: fast-json-stringify dependency-version: 7.3.6 dependency-type: indirect update-type: version-update:semver-minor dependency-group: minor-and-patch * dependency-name: fast-uri dependency-version: 3.1.9 dependency-type: indirect update-type: version-update:semver-patch dependency-group: minor-and-patch * dependency-name: fastify dependency-version: 5.12.8 dependency-type: indirect update-type: version-update:semver-patch dependency-group: minor-and-patch * dependency-name: find-my-way dependency-version: 9.10.1 dependency-type: indirect update-type: version-update:semver-patch dependency-group: minor-and-patch * dependency-name: graceful-fs dependency-version: 4.2.12 dependency-type: indirect update-type: version-update:semver-patch dependency-group: minor-and-patch * dependency-name: is-core-module dependency-version: 2.18.0 dependency-type: indirect update-type: version-update:semver-minor dependency-group: minor-and-patch * dependency-name: jiti dependency-version: 2.7.0 dependency-type: indirect update-type: version-update:semver-minor dependency-group: minor-and-patch * dependency-name: light-my-request dependency-version: 6.8.1 dependency-type: indirect update-type: version-update:semver-patch dependency-group: minor-and-patch * dependency-name: mdast-util-to-hast dependency-version: 13.2.2 dependency-type: indirect update-type: version-update:semver-patch dependency-group: minor-and-patch * dependency-name: mdast-util-to-markdown dependency-version: 2.2.3 dependency-type: indirect update-type: version-update:semver-patch dependency-group: minor-and-patch * dependency-name: postcss dependency-version: 8.5.33 dependency-type: indirect update-type: version-update:semver-patch dependency-group: minor-and-patch * dependency-name: ret dependency-version: 0.5.1 dependency-type: indirect update-type: version-update:semver-patch dependency-group: minor-and-patch * dependency-name: semver dependency-version: 6.3.2 dependency-type: indirect update-type: version-update:semver-patch dependency-group: minor-and-patch * dependency-name: sisteransi dependency-version: 2.0.0 dependency-type: indirect update-type: version-update:semver-major dependency-group: minor-and-patch * dependency-name: tabbable dependency-version: 6.5.2 dependency-type: indirect update-type: version-update:semver-patch dependency-group: minor-and-patch * dependency-name: tapable dependency-version: 2.3.4 dependency-type: indirect update-type: version-update:semver-patch dependency-group: minor-and-patch * dependency-name: tar dependency-version: 7.5.23 dependency-type: indirect update-type: version-update:semver-patch dependency-group: minor-and-patch * dependency-name: thread-stream dependency-version: 4.2.1 dependency-type: indirect update-type: version-update:semver-patch dependency-group: minor-and-patch * dependency-name: undici dependency-version: 8.12.4 dependency-type: indirect update-type: version-update:semver-minor dependency-group: minor-and-patch * dependency-name: unist-util-visit dependency-version: 5.2.0 dependency-type: indirect update-type: version-update:semver-minor dependency-group: minor-and-patch * dependency-name: unist-util-visit-parents dependency-version: 6.1.0 dependency-type: indirect update-type: version-update:semver-minor dependency-group: minor-and-patch * dependency-name: vfile-message dependency-version: 4.0.4 dependency-type: indirect update-type: version-update:semver-patch dependency-group: minor-and-patch * dependency-name: vitepress-plugin-group-icons dependency-version: 1.8.2 dependency-type: direct:development update-type: version-update:semver-patch dependency-group: minor-and-patch * dependency-name: vitepress-plugin-llms dependency-version: 1.15.0 dependency-type: direct:development update-type: version-update:semver-minor dependency-group: minor-and-patch * dependency-name: vue dependency-version: 3.5.45 dependency-type: indirect update-type: version-update:semver-patch dependency-group: minor-and-patch * dependency-name: vue-tsc dependency-version: 3.3.14 dependency-type: indirect update-type: version-update:semver-patch dependency-group: minor-and-patch * dependency-name: ws dependency-version: 8.23.0 dependency-type: indirect update-type: version-update:semver-minor dependency-group: minor-and-patch * dependency-name: zod dependency-version: 4.6.7 dependency-type: indirect update-type: version-update:semver-patch dependency-group: minor-and-patch ... * **Signed-off-by:** dependabot\[bot] * chore(deps): regenerate the lockfile for the minor and patch updates * chore(deps): keep @types/vscode aligned with engines.vscode *** * **Signed-off-by:** dependabot\[bot] * **Co-authored-by:** dependabot\[bot] <49699333+dependabot\[bot]@users.noreply.github.com> * **Co-authored-by:** T0chi <34287213+T0chi@users.noreply.github.com> ## 3.0.0-beta.3 (November 2026) #### Deps * Bump the security-updates group across 1 directory with 3 updates ([#44](https://github.com/deltabox-studio/toolchain/issues/44)) ([#ce9a835](https://github.com/deltabox-studio/toolchain/commit/ce9a835) by [dependabot](https://github.com/dependabot)) * chore(deps): bump the security-updates group across 1 directory with 3 updates * Bumps the security-updates group with 3 updates in the / directory: [vite](https://github.com/vitejs/vite/tree/HEAD/packages/vite), [fast-uri](https://github.com/fastify/fast-uri) and [undici](https://github.com/nodejs/undici). * Updates `vite` from 5.4.21 to 6.4.5 * [Release notes](https://github.com/vitejs/vite/releases) * [Changelog](https://github.com/vitejs/vite/blob/v6.4.5/packages/vite/CHANGELOG.md) * [Commits](https://github.com/vitejs/vite/commits/v6.4.5/packages/vite) * Updates `fast-uri` from 3.1.8 to 3.1.9 * [Release notes](https://github.com/fastify/fast-uri/releases) * [Commits](https://github.com/fastify/fast-uri/compare/v3.1.8...v3.1.9) * Updates `undici` from 8.11.2 to 8.12.4 * [Release notes](https://github.com/nodejs/undici/releases) * [Commits](https://github.com/nodejs/undici/compare/v8.11.2...v8.12.4) * \--- updated-dependencies: * dependency-name: fast-uri dependency-version: 3.1.9 dependency-type: indirect dependency-group: security-updates * dependency-name: undici dependency-version: 8.12.4 dependency-type: indirect dependency-group: security-updates * dependency-name: vite dependency-version: 6.4.5 dependency-type: direct:development dependency-group: security-updates ... * **Signed-off-by:** dependabot\[bot] * chore(deps): regenerate the lockfile for the security updates *** * **Signed-off-by:** dependabot\[bot] * **Co-authored-by:** dependabot\[bot] <49699333+dependabot\[bot]@users.noreply.github.com> * **Co-authored-by:** T0chi <34287213+T0chi@users.noreply.github.com> ### New contributors * [dependabot](https://github.com/dependabot) * Bump the security-updates group across 1 directory with 3 updates ([#44](https://github.com/deltabox-studio/toolchain/issues/44)) ([#ce9a835](https://github.com/deltabox-studio/toolchain/commit/ce9a835)) ## 3.0.0-beta.2 (November 2026) #### Project * Leave fmt and lint to the root in nested scaffolds ([#c646ea5](https://github.com/deltabox-studio/toolchain/commit/c646ea5) by [T0chi](https://github.com/T0chi)) - Align the READMEs and guides with v3 ([#c6487b8](https://github.com/deltabox-studio/toolchain/commit/c6487b8) by [T0chi](https://github.com/T0chi)) ## 3.0.0-beta.1 (November 2026) #### Changelog * Add the beforeVersion lifecycle hook ([#3f62f0c](https://github.com/deltabox-studio/toolchain/commit/3f62f0c) by [T0chi](https://github.com/T0chi)) * Add the afterVersion lifecycle hook ([#c927eee](https://github.com/deltabox-studio/toolchain/commit/c927eee) by [T0chi](https://github.com/T0chi)) ## 3.0.0-beta.0 (November 2026) * Resolve the bug-hunt findings ([#f07f951](https://github.com/deltabox-studio/toolchain/commit/f07f951) by [T0chi](https://github.com/T0chi)) #### Changelog * Relabel details summaries and default the release body ([#7ccfc86](https://github.com/deltabox-studio/toolchain/commit/7ccfc86) by [T0chi](https://github.com/T0chi)) * Add collapsible `details` rendering ([#f7d1c6a](https://github.com/deltabox-studio/toolchain/commit/f7d1c6a) by [T0chi](https://github.com/T0chi)) * Make releases idempotent and prerelease-aware ([#610138b](https://github.com/deltabox-studio/toolchain/commit/610138b) by [T0chi](https://github.com/T0chi)) #### Cli * Add spinners and Dependabot allow rules ([#fa9ba22](https://github.com/deltabox-studio/toolchain/commit/fa9ba22) by [T0chi](https://github.com/T0chi)) #### Tsconfig * Support remote extends with opt-in flattening ([#44b5c8a](https://github.com/deltabox-studio/toolchain/commit/44b5c8a) by [T0chi](https://github.com/T0chi)) * Add `strict` aliases and export-aware auto modes ([#fee5091](https://github.com/deltabox-studio/toolchain/commit/fee5091) by [T0chi](https://github.com/T0chi)) * Serialize regex aliases for JSON transports ([#d7d8caf](https://github.com/deltabox-studio/toolchain/commit/d7d8caf) by [T0chi](https://github.com/T0chi)) #### Docker * Correct PnP runtimes, nested ignores and Vite+ node versions ([#68eee6f](https://github.com/deltabox-studio/toolchain/commit/68eee6f) by [T0chi](https://github.com/T0chi)) * Allow user-owned files and always add compose ([#51b9ccc](https://github.com/deltabox-studio/toolchain/commit/51b9ccc) by [T0chi](https://github.com/T0chi)) #### Config * Rename the generated ambient env types to `dbx-env.d.ts` ([#078b316](https://github.com/deltabox-studio/toolchain/commit/078b316) by [T0chi](https://github.com/T0chi)) * Add runtime config APIs and grouped `ConfigEngine` types ([#b69980e](https://github.com/deltabox-studio/toolchain/commit/b69980e) by [T0chi](https://github.com/T0chi)) * Add `collect`, parser and config loader APIs ([#4a3b745](https://github.com/deltabox-studio/toolchain/commit/4a3b745) by [T0chi](https://github.com/T0chi)) #### Pack * Rename the `tsdown` workspace to `pack` ([#02719e5](https://github.com/deltabox-studio/toolchain/commit/02719e5) by [T0chi](https://github.com/T0chi)) #### Core * Make managed-file formatting opt-in ([#2a7c709](https://github.com/deltabox-studio/toolchain/commit/2a7c709) by [T0chi](https://github.com/T0chi)) * Format managed files after `dbx sync` ([#fb3d9be](https://github.com/deltabox-studio/toolchain/commit/fb3d9be) by [T0chi](https://github.com/T0chi)) #### Vscode * Decorate managed files and reveal the active project ([#a6debec](https://github.com/deltabox-studio/toolchain/commit/a6debec) by [T0chi](https://github.com/T0chi)) * Add scoped auto-sync, the action palette and the Actions view ([#c330378](https://github.com/deltabox-studio/toolchain/commit/c330378) by [T0chi](https://github.com/T0chi)) * Add generic format/lint actions and formatting settings ([#c256de5](https://github.com/deltabox-studio/toolchain/commit/c256de5) by [T0chi](https://github.com/T0chi)) #### Shared * Add static schema defaults ([#3b810d3](https://github.com/deltabox-studio/toolchain/commit/3b810d3) by [T0chi](https://github.com/T0chi)) #### Config * Reuse changelog group and option schemas ([#cbd9b54](https://github.com/deltabox-studio/toolchain/commit/cbd9b54) by [T0chi](https://github.com/T0chi)) #### Changelog * Add `minCommits` and nested `See more...` descriptions ([#9fa603b](https://github.com/deltabox-studio/toolchain/commit/9fa603b) by [T0chi](https://github.com/T0chi)) * Fix details formatting and add release mode ([#5fa519f](https://github.com/deltabox-studio/toolchain/commit/5fa519f) by [T0chi](https://github.com/T0chi)) * Apply details after formatting and add body collapsibles ([#83dd7da](https://github.com/deltabox-studio/toolchain/commit/83dd7da) by [T0chi](https://github.com/T0chi)) * Add scoped versioning options and changelog `intro`/`outro` ([#09cf5d9](https://github.com/deltabox-studio/toolchain/commit/09cf5d9) by [T0chi](https://github.com/T0chi)) #### Cli * Add changelog intro/outro flags and respect `enabled` ([#7d74c71](https://github.com/deltabox-studio/toolchain/commit/7d74c71) by [T0chi](https://github.com/T0chi)) * Add `dbx enable`/`disable` and `enabled` ([#67ea4c3](https://github.com/deltabox-studio/toolchain/commit/67ea4c3) by [T0chi](https://github.com/T0chi)) #### Mcp * Add the MCP server, installers and `dbx mcp:*` commands ([#0553843](https://github.com/deltabox-studio/toolchain/commit/0553843) by [T0chi](https://github.com/T0chi)) #### Config * Escape generated JSDoc comments, closes [#41](https://github.com/deltabox-studio/toolchain/issues/41) ([#220d228](https://github.com/deltabox-studio/toolchain/commit/220d228) by [T0chi](https://github.com/T0chi)) (fixes [#41](https://github.com/deltabox-studio/toolchain/issues/41)) #### Cli * Harden flag parsing and document library-only config commands ([#aaaa11a](https://github.com/deltabox-studio/toolchain/commit/aaaa11a) by [T0chi](https://github.com/T0chi)) #### Config * Share the runtime loader with core ([#e84e4e6](https://github.com/deltabox-studio/toolchain/commit/e84e4e6) by [T0chi](https://github.com/T0chi)) - Add the v2 to v3 guide and refresh behavior docs ([#c6efc52](https://github.com/deltabox-studio/toolchain/commit/c6efc52) by [T0chi](https://github.com/T0chi)) - Describe Docker as scaffolding-only ([#8e5c46e](https://github.com/deltabox-studio/toolchain/commit/8e5c46e) by [T0chi](https://github.com/T0chi)) - Document the opt-in Dependabot config ([#7028669](https://github.com/deltabox-studio/toolchain/commit/7028669) by [T0chi](https://github.com/T0chi)) - Document Docker support ([#e618041](https://github.com/deltabox-studio/toolchain/commit/e618041) by [T0chi](https://github.com/T0chi)) - Document the quality-of-life templates ([#a9b62b2](https://github.com/deltabox-studio/toolchain/commit/a9b62b2) by [T0chi](https://github.com/T0chi)) - Document the GitLab and Azure `setup-vp` setup ([#d385e7d](https://github.com/deltabox-studio/toolchain/commit/d385e7d) by [T0chi](https://github.com/T0chi)) - Document the Vite+ CI detection and tokens ([#64c394e](https://github.com/deltabox-studio/toolchain/commit/64c394e) by [T0chi](https://github.com/T0chi)) - Add managed-file examples and refresh generated docs ([#e9dba38](https://github.com/deltabox-studio/toolchain/commit/e9dba38) by [T0chi](https://github.com/T0chi)) - Describe the plugin-first Vite+ superset and regenerate docs ([#01008f6](https://github.com/deltabox-studio/toolchain/commit/01008f6) by [T0chi](https://github.com/T0chi)) - Document the config loader, strict opt-in inheritance and configless projects ([#2eff4c8](https://github.com/deltabox-studio/toolchain/commit/2eff4c8) by [T0chi](https://github.com/T0chi)) #### Ci * Document security updates in the v3 migration guide ([#1aa7091](https://github.com/deltabox-studio/toolchain/commit/1aa7091) by [T0chi](https://github.com/T0chi)) #### Changelog * Apply details formatting to historical entries ([#0bfbd98](https://github.com/deltabox-studio/toolchain/commit/0bfbd98) by [T0chi](https://github.com/T0chi)) * Document package changes on `--format-only` ([#a8b6cdb](https://github.com/deltabox-studio/toolchain/commit/a8b6cdb) by [T0chi](https://github.com/T0chi)) #### Config * Refresh generated reference and llms bundle ([#fd2f709](https://github.com/deltabox-studio/toolchain/commit/fd2f709) by [T0chi](https://github.com/T0chi)) * Refresh generated config artifacts and guides ([#067760e](https://github.com/deltabox-studio/toolchain/commit/067760e) by [T0chi](https://github.com/T0chi)) * Regenerate schema, types and reference ([#6f48302](https://github.com/deltabox-studio/toolchain/commit/6f48302) by [T0chi](https://github.com/T0chi)) * Link external schemas and add real defaults ([#04dc8d1](https://github.com/deltabox-studio/toolchain/commit/04dc8d1) by [T0chi](https://github.com/T0chi)) - Normalize imports and docs ([#c7f0d25](https://github.com/deltabox-studio/toolchain/commit/c7f0d25) by [T0chi](https://github.com/T0chi)) #### Config * Regenerate the schema, types and docs ([#2c4dc1e](https://github.com/deltabox-studio/toolchain/commit/2c4dc1e) by [T0chi](https://github.com/T0chi)) * Regenerate the CLI docs and llms output ([#cf8661f](https://github.com/deltabox-studio/toolchain/commit/cf8661f) by [T0chi](https://github.com/T0chi)) * Regenerate the schema, types and docs ([#82ca5c3](https://github.com/deltabox-studio/toolchain/commit/82ca5c3) by [T0chi](https://github.com/T0chi)) * Generate plain array unions and `details` types ([#486d264](https://github.com/deltabox-studio/toolchain/commit/486d264) by [T0chi](https://github.com/T0chi)) * Regenerate the schema, types and docs ([#12788f0](https://github.com/deltabox-studio/toolchain/commit/12788f0) by [T0chi](https://github.com/T0chi)) * Regenerate types and references ([#3c7917a](https://github.com/deltabox-studio/toolchain/commit/3c7917a) by [T0chi](https://github.com/T0chi)) * Regenerate types and references ([#de928fa](https://github.com/deltabox-studio/toolchain/commit/de928fa) by [T0chi](https://github.com/T0chi)) ## 2.6.1 (November 2026) #### Changelog * Scope package changes by package name ([#0ee9b9e](https://github.com/deltabox-studio/toolchain/commit/0ee9b9e) by [T0chi](https://github.com/T0chi)) * key dependency changes by the declaring package.json name so workspace-specific pins (eg. the docs site's Vite 5) are reported under that workspace * scope the catalog to the root package name; keep workspace catalog: refs unresolved so a catalog bump is reported once * add regression tests and regenerate every CHANGELOG.md with the scoped footer ## 2.6.0 (November 2026) * Route fmt/lint to the active tool and opt scaffolds into catalogs ([#76df575](https://github.com/deltabox-studio/toolchain/commit/76df575) by [T0chi](https://github.com/T0chi)) * dbx fmt/lint resolve the configured/discovered formatter or linter (oxc > biome > prettier > dprint; oxc > biome > eslint) and run it, falling back to the vp/Oxc passthrough * project:init/create scaffolds add the catalogs section for the catalog file they write, so dbx sync owns it instead of leaving the managed file orphaned * document the active-tool routing and add the dedicated package catalogs guide ## 2.5.0 (November 2026) #### Config * Add a reusable CLI docs generator ([#900566a](https://github.com/deltabox-studio/toolchain/commit/900566a) by [T0chi](https://github.com/T0chi)) * add generateCliDocs(commands, options?) for custom command descriptors * use it to render the dbx CLI reference * document generating docs for a consumer's own command list * cover hidden/duplicate commands, args/options and custom prefix/title * Add self-contained vendor types and `tsconfig` auto/`rewriteAlias` schemas ([#31c47a9](https://github.com/deltabox-studio/toolchain/commit/31c47a9) by [T0chi](https://github.com/T0chi)) #### Changelog * Inject provider setup into custom and vendor workflows ([#b6b240f](https://github.com/deltabox-studio/toolchain/commit/b6b240f) by [T0chi](https://github.com/T0chi)) * add an opt-in setup flag to custom workflow options and vendor settings * GitHub injects the missing checkout/Node/Corepack/install steps * GitLab adds a Node image + before_script; Azure adds UseNode@1 + install * avoid duplicating setup steps the workflow already defines * resolve vendor workflow tokens from the default token set #### Biome * Add array removal directives and resolve toolchain debt ([#da100c8](https://github.com/deltabox-studio/toolchain/commit/da100c8) by [T0chi](https://github.com/T0chi)) * add $remove: / $reset array directives with a resolver step for biome.json * fix peer warnings (declare vite, filter the stale VitePress plugin peer) * replace the RULE_MAP cast with an Object.hasOwn guard * add a direct extension env-propagation test * drop the 30s real-git changelog timeout #### Cli * Add `sync --only` task selection and `selectSyncTasks` ([#49d73dd](https://github.com/deltabox-studio/toolchain/commit/49d73dd) by [T0chi](https://github.com/T0chi)) #### Vscode * Split extension modules and add `syncTsconfig` action ([#f121c47](https://github.com/deltabox-studio/toolchain/commit/f121c47) by [T0chi](https://github.com/T0chi)) #### Tsconfig * Auto-wire aliases/references with `rewriteAlias` and gating ([#124f4b5](https://github.com/deltabox-studio/toolchain/commit/124f4b5) by [T0chi](https://github.com/T0chi)) #### Cli * Sync and watch configless projects with the inherited config ([#346060d](https://github.com/deltabox-studio/toolchain/commit/346060d) by [T0chi](https://github.com/T0chi)) * The command context did not expose the ancestor config path, so dbx sync/watch in a nested project without its own dbx.config.\* warned and did nothing. Pass parentPath through the context and allow both commands when it is set. The VS Code Sync all compensation now works for configless projects, while sync --recursive stays config-bearing-only and is documented as such. - Document watcher scoping and project identity inheritance ([#074bfcd](https://github.com/deltabox-studio/toolchain/commit/074bfcd) by [T0chi](https://github.com/T0chi)) * Update the VS Code auto-sync section and the project guide to match the implementation: watchers are root-scoped and sync only the changed root; project name/scope/description/type are never inherited. Regenerate llms-full.txt. #### Tsconfig * Note that refsAuto requires tsc --build ([#74a25b2](https://github.com/deltabox-studio/toolchain/commit/74a25b2) by [T0chi](https://github.com/T0chi)) * Project references are only followed by tsc --build; tsc -p --noEmit ignores them. Document the refsAuto requirement and why this repo keeps the references hand-written (refsAuto: false). #### Config * Document every generator and generateCliDocs ([#28f812e](https://github.com/deltabox-studio/toolchain/commit/28f812e) by [T0chi](https://github.com/T0chi)) * add engine + standalone examples for each generator * document CLI docs, post-processing and advanced options * cross-link generateCliDocs from the config-generator index and CLI commands #### Vscode * Expand the extension guide and README ([#942aa55](https://github.com/deltabox-studio/toolchain/commit/942aa55) by [T0chi](https://github.com/T0chi)) * Restore the updated provider/template sections, settings and auto-sync documentation in both the guide and the extension README. ## 2.4.0 (November 2026) #### Shared * Improve workflow config autocomplete ([#5babd18](https://github.com/deltabox-studio/toolchain/commit/5babd18) by [T0chi](https://github.com/T0chi)) * Add typed WorkflowTriggers, WorkflowExtra and WorkflowTokens shapes so known workflow keys are suggested, and regenerate the config types, schema and reference. * Expose formatter and linter ignore defaults ([#5f2c8b1](https://github.com/deltabox-studio/toolchain/commit/5f2c8b1) by [T0chi](https://github.com/T0chi)) * Export DEFAULT_FMT_IGNORE_PATTERNS and DEFAULT_LINT_IGNORE_PATTERNS alongside DEFAULT_IGNORE_PATTERNS, and document how to extend them. #### Project * Add config generation options and migration routing ([#c658b0d](https://github.com/deltabox-studio/toolchain/commit/c658b0d) by [T0chi](https://github.com/T0chi)) * Support --skip-config, --language and --config-extension, write the project graph before configs, generate TS/JS configs, and route migrated fmt/lint into toolchain.vite only when the existing Vite config owns them. #### Vscode * Add tooling actions and config generation ([#31da418](https://github.com/deltabox-studio/toolchain/commit/31da418) by [T0chi](https://github.com/T0chi)) * Add the format import-group setting, migrate/global Home actions, and config generation prompts (TS/JS, graph-only) that also work from the Command Palette. #### Core * Add import sorting defaults and workspace groups ([#1c5f5a3](https://github.com/deltabox-studio/toolchain/commit/1c5f5a3) by [T0chi](https://github.com/T0chi)) * Enable sortImports by default, resolve a workspace custom group from the project graph, and inject it into resolveVite, vite sync and tooling normalization. #### Shared * Repair PowerShell backtick artifacts in changelogs ([#61ced92](https://github.com/deltabox-studio/toolchain/commit/61ced92) by [T0chi](https://github.com/T0chi)) * Repair paired \code\ and lone trailing identifier backslashes back to inline code while leaving paths and regexes alone, and correct the affected 2.3.1-2.3.3 entries. ## 2.3.0 (November 2026) #### Changelog * Dispatch workflows with their vendor CLI ([#eea38ae](https://github.com/deltabox-studio/toolchain/commit/eea38ae) by [T0chi](https://github.com/T0chi)) #### Config * Type tool options and changelog callbacks ([#10bd933](https://github.com/deltabox-studio/toolchain/commit/10bd933) by [T0chi](https://github.com/T0chi)) #### Config * Escape CLI reference tables and fail on missing output ([#15978be](https://github.com/deltabox-studio/toolchain/commit/15978be) by [T0chi](https://github.com/T0chi)) #### Core * Keep managed paths inside the project root ([#2496bee](https://github.com/deltabox-studio/toolchain/commit/2496bee) by [T0chi](https://github.com/T0chi)) #### Changelog * Preserve hand-corrected text in `--format-only` ([#2041e5f](https://github.com/deltabox-studio/toolchain/commit/2041e5f) by [T0chi](https://github.com/T0chi)) #### Shared * Restore `PowerShell`-escaped letters ([#4d2be6a](https://github.com/deltabox-studio/toolchain/commit/4d2be6a) by [T0chi](https://github.com/T0chi)) - Document vendor workflows, typed builders and `--format-only` ([#eb66982](https://github.com/deltabox-studio/toolchain/commit/eb66982) by [T0chi](https://github.com/T0chi)) #### Changelog * Document `formatLine` ([#61e28ec](https://github.com/deltabox-studio/toolchain/commit/61e28ec) by [T0chi](https://github.com/T0chi)) #### Config * Regenerate config-types, schema and docs ([#0b0ca20](https://github.com/deltabox-studio/toolchain/commit/0b0ca20) by [T0chi](https://github.com/T0chi))