TypeScript

@deltabox/toolchain is written in TypeScript and ships the config model, the generated .d.ts files and the ambient Zod metadata types. This page covers the type-safety story for consumers.

dbx.config.ts

defineConfig is an identity helper that gives the config file full autocomplete and type-checking, including the opt-in toolchain.ci workflows:

dbx.config.ts

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

export default defineConfig({
    toolchain: {
        project: { name: 'acme', scope: '@acme' },
        ci: {
            ci: true,
            changelog: {
                commitlint: { scopes: ['api', 'web'] },
                versioning: { target: 'individual' },
            },
        },
    },
});

It accepts an object, a promise, or a sync/async callback — the loader resolves it (see defineConfig).

Config types

The toolchain shape is exported as ToolchainConfig (and the individual sections as ToolchainCiConfig, ChangelogConfig, ...):

import type { ToolchainConfig, ToolchainCiConfig } from '@deltabox/toolchain';

const ci: ToolchainCiConfig = { ci: true, changelog: true };
const config: ToolchainConfig = { project: { name: 'acme' }, ci };

The same types are available from @deltabox/toolchain/shared, and each subpath re-exports the types it owns.

Ambient schema metadata

Zod's .meta() is typed by default, but the toolchain adds its own fields (env, path, required, deprecated, deprecationMessage, example, since, see, remarks, experimental, alpha, beta, secret, scope, public, defaultValue). Add the ambient declaration once in a project-wide .d.ts:

env.d.ts

/// <reference types="@deltabox/toolchain/globals" />

Now a schema used with the config generator is fully typed:

import { z } from 'zod';

export const serverConfig = z.object({
    port: z.number().default(3000).meta({
        env: 'MYAPP_PORT',
        description: 'HTTP port',
        example: '3000',
    }),
    password: z.string().meta({
        env: 'MYAPP_AUTH_PASSWORD',
        required: true,
        secret: true,
    }),
});

ConfigMeta is ConfigBaseMeta & ConfigEnvMeta:

• ConfigBaseMeta: description, required, deprecated, deprecationMessage, example, since, see, remarks, experimental, alpha, beta, secret, scope, public, defaultValue.
• ConfigEnvMeta: envName and envPath (both optional, so non-env configs can use metadata too).

.describe() is still the primary description and is rendered into the generated types, JSON Schema and markdown reference; .meta({ description }) is used as a fallback and adds env/docs metadata.

Programmatic API

The loader and sync runner are typed end-to-end:

import {
    defineConfig,
    defaultSyncTasks,
    loadToolchainConfig,
    runSync,
    type ToolchainConfig,
} from '@deltabox/toolchain';

const loaded = await loadToolchainConfig(process.cwd());
const config: ToolchainConfig = loaded.config;
await runSync({
    tasks: defaultSyncTasks(),
    cwd: process.cwd(),
    config,
    tokens: loaded.tokens,
    projectType: loaded.projectType,
});

// Run only a named task (eg. refresh the tsconfig aliases after a build).
await runSync({
    tasks: defaultSyncTasks(),
    only: ['tsconfig'],
    cwd: process.cwd(),
    config,
    tokens: loaded.tokens,
    projectType: loaded.projectType,
});

only implies prune: false, so a subset never deletes files owned by the tasks it skipped. See the Programmatic API guide for the package-by-package reference.

Vite+

The generated vite.config.ts shim is typed against the project's Vite package (vite or vite-plus) and resolveVite<T> is generic, so resolveVite<ViteUserConfig>({ cwd: import.meta.dirname }) keeps the full Vite+ surface (see Vite+).

JSON Schema / editor autocomplete

config.schema.json is generated from the same Zod model and published at the site root, so a dbx.config.json gets editor completion. For a TypeScript config, defineConfig already provides the same information.