--- 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)