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