Generate

Every generator has two forms:

• Bound engine — engine.generateConfigTypes() injects the engine's envPrefix, baseGroup, root and envPathOf.
• Standalone — generateConfigTypes(schema, options) takes those options explicitly, for one-off scripts and tests.

write* methods write to disk and return the written paths. The generate* methods return the content and only write when you pass outputDir/output (a string); false disables writing.

At a glance

Output	Engine	Standalone
.env.example	engine.generateEnvFile() / engine.writeEnvFile()	generateEnvFile()
Env types	engine.generateConfigEnv() / engine.writeEnvTypes()	generateConfigEnv()
Config types	engine.generateConfigTypes() / engine.writeConfigTypes()	generateConfigTypes()
Markdown	engine.generateConfigMarkdown() / engine.writeMarkdown()	generateConfigMarkdown()
JSON Schema	engine.generateJsonSchema() / engine.writeJsonSchema()	generateConfigJsonSchema() / generateJsonSchemaFile()
Metadata JSON	engine.buildConfigJson()	buildConfigJson()
CLI options	engine.generateConfigCli() / generateCliOptions()	generateCliOptions()
CLI docs	—	generateCliDocs()
Formatting	—	formatGenerated()

Env file — .env.example

engine.writeEnvFile({ output: '.env.example' });

Standalone, with the common options:

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

const content = generateEnvFile(schema, {
    envPrefix: 'MYAPP_',
    header: 'Copy to .env and fill the blanks.',
    scopes: ['server', 'cli'],
    exclude: ['MYAPP_INTERNAL_TOKEN'],
    values: { MYAPP_PORT: '8080' },
    extra: { MYAPP_FEATURE_FLAG: 'true' },
});

Options: include/exclude (env names), values (default overrides), scopes, bare, extra (raw NAME=value lines), header, scopeSeparator. Secrets are emitted commented out.

Env types — env.ts + env.d.ts

engine.writeEnvTypes({ outputDir: 'types' }); // types/env.ts, types/env.d.ts

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

const files = generateConfigEnv(schema, {
    envPrefix: 'MYAPP_',
    outputDir: 'types',
    envInterfaceName: 'AppEnv',
    viteEnvInterfaceName: 'AppViteEnv',
    importPath: './env.js',
    augmentVite: true,
    envComment: 'Runtime configuration.',
});
// files: { 'env.ts': '...', 'env.d.ts': '...' }

Options: envFile/dtsFile (file names), header, envHeader, dtsHeader, augmentVite (a declare module 'vite' augmentation).

Config types

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

Standalone, with hand-written overrides and aliases:

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

const files = generateConfigTypes(schema, {
    baseGroup: 'base',
    outputDir: 'types',
    interfaceNames: { server: 'ServerConfig' },
    aliases: { server: 'export type ServerOptions = ServerConfig;' },
    imports: ["import type { FastifyServerOptions } from 'fastify';"],
    overrides: {
        ServerConfig: `export interface ServerConfig {
    host?: string;
    port?: number;
}`,
    },
    header: '// Generated — do not edit.',
    extension: 'ts',
    includeEnv: false,
});

Options: interfaceNames (per scope), aliases (per scope, appended), overrides (full declaration text, keyed by type name), imports (emitted once at the top), extension, header, and the include* annotation flags.

Markdown

engine.writeMarkdown({ outputDir: 'docs/reference/configuration' });

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

const files = generateConfigMarkdown(schema, {
    baseGroup: 'base',
    envPrefix: 'MYAPP_',
    outputDir: 'docs/reference/configuration',
    title: 'Configuration',
    frontmatter: ctx => `title: ${ctx.options.title ?? 'Configuration'}`,
    combined: true, // one index.md instead of one file per scope
    includeEnv: false,
});

frontmatter: false omits the frontmatter, a string replaces the body, and a callback builds it from the generator options. combined: true renders every scope into one file. cliScope, shortFlags and references control the CLI equivalents and footer links.

JSON Schema

const doc = await engine.generateJsonSchema();
await engine.writeJsonSchema({ output: 'config.schema.json' });

import { generateConfigJsonSchema, generateJsonSchemaFile } from '@deltabox/toolchain/config';

const doc = await generateConfigJsonSchema(schema, {
    baseGroup: 'base',
    id: 'https://acme.dev/schemas/config.json',
    title: 'Acme configuration',
    description: 'Every env-backed setting.',
});
const path = await generateJsonSchemaFile(schema, { output: 'config.schema.json' });

Both functions are async. generateConfigJsonSchema returns the document; generateJsonSchemaFile writes it and returns the path.

Config metadata JSON

const metadata = engine.buildConfigJson();
fs.writeFileSync('config.json', `${JSON.stringify(metadata, null, 4)}\n`);

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

const metadata = buildConfigJson(schema, {
    envPrefix: 'MYAPP_',
    comment: 'Generated from the config schemas.',
});

The document contains $comment, version, and env[] entries with the name, path, scope, description, default, required, secret and public flags. Secrets never include a default.

CLI options

const defs = engine.generateConfigCli({ scope: 'cli' });
// engine.generateCliOptions() is an alias.

import { createCliArgsParser, generateCliOptions } from '@deltabox/toolchain/config';

const defs = generateCliOptions(schema, {
    envPrefix: 'MYAPP_',
    scope: 'cli',
    output: 'cli-options.json',
});
const parser = createCliArgsParser(defs);
parser.parse(['--base-url', 'http://localhost:8080']);

Options: scope (default cli), output, shortFlags, envPathOf.

CLI docs

generateCliDocs(commands, options?) renders a markdown reference from ToolchainCommand descriptors. It is standalone because it does not read a config schema:

import { builtinCommands } from '@deltabox/toolchain/cli';
import { generateCliDocs } from '@deltabox/toolchain/config';

const markdown = generateCliDocs([...builtinCommands(), ...myCommands], {
    title: 'CLI reference',
    intro: 'Generated from the registered commands.',
    prefix: 'my-cli',
    outline: [2, 3],
});

Hidden commands are omitted, duplicate names keep the first descriptor, and args/options/defaults are rendered like the dbx reference. Pass the result through formatGenerated(..., { fileName: 'cli.md' }) to format it.

Formatting

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

const formatted = await formatGenerated(source, {
    fileName: 'config.ts', // infers the language
    options: { printWidth: 100 }, // merged over GENERATED_FORMAT_OPTIONS
});

formatGenerated is best-effort: it returns the input unchanged when no formatter is available.

Advanced

Post-process generated output

Generators return strings or records, so you can transform them before writing:

import fs from 'node:fs';

import { formatGenerated, generateConfigTypes } from '@deltabox/toolchain/config';

const files = generateConfigTypes(schema, { baseGroup: 'base' });
for (const [scope, source] of Object.entries(files)) {
    const withBanner = `// Generated from schemas/${scope}.ts — do not edit.\n${source}`;
    const formatted = await formatGenerated(withBanner, { fileName: `${scope}.ts` });
    fs.mkdirSync('types', { recursive: true });
    fs.writeFileSync(`types/${scope}.ts`, formatted);
}

Custom headers, imports and overrides

generateConfigTypes(schema, {
    header: '/* eslint-disable */',
    imports: ["import type { AppEnv } from './env.js';"],
    overrides: {
        ServerConfig: 'export interface ServerConfig extends BaseServer {}',
    },
});

overrides is keyed by the generated type name and replaces the whole declaration, so keep the imports/header options handy for types the schema cannot express.

Dry runs

Every generator accepts outputDir: false / output: false:

generateConfigTypes(schema, { outputDir: false });
await generateConfigJsonSchema(schema, { output: false });

The engine's write* methods always write; use the generate* methods when you only need the content.

Engine vs standalone

The engine form injects the bound options; the standalone form takes them explicitly. They produce the same output:

const engine = createConfigEngine({
    schema,
    envPrefix: 'MYAPP_',
    baseGroup: 'base',
});

engine.generateConfigMarkdown(); // uses the bound options

generateConfigMarkdown(schema, {
    envPrefix: 'MYAPP_',
    baseGroup: 'base',
});

See Generated outputs for the shape of each file and CLI commands for the config:* descriptors.