Skip to content

About this page

On this page

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 ​

sh
# as a dev dependency in the project you want to manage
npm install @deltabox/toolchain --save-dev
sh
# as a dev dependency in the project you want to manage
yarn add -D @deltabox/toolchain
sh
# as a dev dependency in the project you want to manage
pnpm add -D @deltabox/toolchain
sh
# 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 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 ​

AreaSection in the config
GitHub workflows, commitlint, Conventional-Commits VS Code settingsci
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 / scaffoldingtemplates
Package catalogs (.yarnrc.yml / pnpm-workspace.yaml)catalogs
Watch behaviourwatch

Every section is opt-in by presence: define it to enable it, omit it to leave that area untouched.

Next ​