deltabox toolchain

All-in-one development toolchain that let's you scaffold projects, generate and manage configs, tsconfigs, custom templates, syncing, changelogs, CI, Vite+, migrations, and more.

• Save and use templates (local/remote) so you never have to scaffold the same projects over and over again.
• Generate config types, env variables, cli flags, markdown and JSON schemas, so your codebase stays consistent, validated and well-documented.
• Extend or setup CI for your changelogs, releases, issues etc.
• Sync your entire project so workspaces, docs and CI are always up-to-date.
• Plug it into Vite / Vite+ and streamline your DX for your existing Vite setup.

See the list of features.

See CHANGELOG.md for latest updates.

Documentation, guides and examples at toolchain.deltabox.studio.

The video and screenshot below is the VS Code extension. Read more about it at toolchain.deltabox.studio/guide/vscode.

https://github.com/user-attachments/assets/a4f1ad75-fedd-40ee-b84d-3365f7025a3e

Table of contents

• deltabox toolchain
  • Table of contents
  • Features
  • Install
  • Quickstart
  • Config generator
  • Vite / Vite+ plugin
  • CLI
  • Programmatic API
  • VS Code extension
  • Development
  • Docs
  • License

Features

• Config-driven
• Config generator
• Vite / Vite+ plugin
• Changelogs & releases
• tsconfig generation
• Providers
• Templates
• Migrations
• Editor first
• Monorepo aware
• Auto sync

See more at toolchain.deltabox.studio.

Install

# as a dev dependency in the project you want to manage
yarn add -D @deltabox/toolchain

# or for global usage
npm install -g @deltabox/toolchain

The package exposes one binary, dbx:

yarn dbx --help

Quickstart

# 1. Write a dbx.config.ts for the current project
dbx project:config

# 2. Generate / refresh every managed file (adds .dbx/toolchain/manifest.json)
dbx sync

# 3. Verify in CI — fails when files are out of date
dbx sync --check

A minimal config:

import { defineConfig } from '@deltabox/toolchain';

export default defineConfig({
    toolchain: {
        project: { type: 'monorepo-root', name: 'acme', scope: '@acme' },
        changelog: { workflows: { ci: true, release: true } },
        tsconfig: { refs: true },
        biome: true,
        vite: { fmt: { semi: true, singleQuote: true } },
    },
});

The @deltabox/toolchain settings live under the toolchain key. Every section there is opt-in by presence: section: true enables it with defaults, section: false disables it, and section: { ... } configures it. See the configuration reference.

Config generator

The same Zod-first approach powers a standalone config engine. Describe your config once and generate .env.example, a JSON Schema, a markdown reference, TS types and CLI flags from it — no hand-maintained docs to drift:

import { z } from 'zod';

import { createConfigEngine } from '@deltabox/toolchain/config';

export const engine = createConfigEngine({
    scopes: {
        server: {
            zodSchema: z.object({
                port: z.number().default(3000).meta({ env: 'MYAPP_PORT' }),
            }),
        },
    },
    envPrefix: 'MYAPP_',
    baseGroup: 'base',
    root: process.cwd(),
});

await engine.writeJsonSchema({ output: 'config.schema.json' });
engine.writeEnvFile({ output: '.env.example' });
engine.writeMarkdown({ outDir: 'docs/reference/configuration' });

It also generates the TypeScript types — named interfaces with jsdoc from .describe(), where unions and nested objects stay named instead of being inlined:

engine.writeConfigTypes({ outputDir: 'types' });

// types/server.ts
export interface ServerConfig {
    /** HTTP port. */
    port?: number;
}

At runtime the same package loads it back — parseEnvTree folds the PREFIX_* variables into a tree and the typed accessors read it (schema validation is just a .parse() away):

import { envInt, envString, parseEnvTree } from '@deltabox/toolchain/config';

const tree = parseEnvTree(process.env, 'MYAPP_');
const port = envInt(tree, 'port', 3000);
const host = envString(tree, 'host', '0.0.0.0');

See the config generator guide for loading, overriding and validating the config.

The toolchain generates its own config types this way — see packages/shared/src/config-types.ts and the config generator guide.

configCommands({ engine }) also exposes the same generators as config:* commands on your own CLI. See the config generator guide.

Vite / Vite+ plugin

@deltabox/toolchain ships a Vite plugin, so a Vite (or Vite+) project can run dbx as part of its own pipeline — no separate dbx sync step:

// vite.config.ts
import { defineConfig } from 'vite'; // or '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.
• run: { tasks: { ...DBX_TASKS } } additionally exposes vp run dbx:sync / vp run dbx:check (Vite+ reads run.tasks from the static config, which a plugin cannot add). Drop the run block if you don't want those tasks.

See the providers guide.

CLI

Visit the CLI docs to learn more.

Note: Commands that run against a project load its dbx.config.ts first, so config-derived defaults apply unless overridden on the command line.

Programmatic API

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

VS Code extension

Download from the Visual Studio Code Marketplace.

or through the CLI:

code --install-extension deltabox.toolchain-vscode

See packages/vscode/README.md to learn more about how it works.

Development

This repo is a Yarn 4 workspace. Vite+ (vp) drives format, lint, test and the task runner from the root vite.config.ts. The generated shims are dogfooded with vite.shim: 'static', so vp loads them without a built package; Vite and Vitest resolve workspace imports through resolve.tsconfigPaths.

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 format         # `vp fmt`
yarn lint           # `vp lint --fix`
yarn build          # packages via `vp run` + root tsdown
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.

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.

Docs live in apps/docs (VitePress): yarn docs build.

Docs

Full documentation, guides and examples live at toolchain.deltabox.studio.

The source pages live in apps/docs.

License

MPL-2.0 © deltabox