
Getting started
@deltabox/toolchain is a config-driven layer around Vite+. 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
# as a dev dependency in the project you want to manage
npm install @deltabox/toolchain --save-dev# as a dev dependency in the project you want to manage
yarn add -D @deltabox/toolchain# as a dev dependency in the project you want to manage
pnpm add -D @deltabox/toolchain# as a dev dependency in the project you want to manage
bun add -D @deltabox/toolchain# or for global usage
npm install -g @deltabox/toolchainThe published package exposes one binary, dbx:
dbx --helpInteractive CLI
Commands are flag-driven, but in an interactive terminal (a TTY) a few prompt for the values you omit:
dbx create # pick a template, project name, scope, inputs and actions
dbx migrate --recursive # pick which projects to migratedbx 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):
import { dbx } from '@deltabox/toolchain/vite';
export default {
plugins: [dbx({ toolchain: { fmt: true, lint: true } })],
};See Vite plugin for the install steps and what the plugin does.
Or, for a project that does not use Vite, scaffold a standalone config:
dbx project:config # detect + write dbx.config.tsOr start from a template:
dbx template:list
dbx create --template project --name my-app --out ./my-appSync
sync runs every enabled task and writes the managed files (adding a manifest at .dbx/toolchain/manifest.json):
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 changeThe generated state lives under .dbx/. Add it to .gitignore, keeping only the manifest (it holds no absolute paths):
.dbx/*
!.dbx/toolchain
.dbx/toolchain/*
!.dbx/toolchain/manifest.jsondbx 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 |
| Watch behaviour | watch |
Every section is opt-in by presence: define it to enable it, omit it to leave that area untouched.