Loader
The toolchain.loader section controls how dbx.config.* files are imported. A TS/JS config is loaded through tsx, so it can use the project's TypeScript path aliases and import .ts sources with a .js specifier.
Options
| Option | Type | Default | Description |
|---|---|---|---|
tsconfig | boolean | string | true | The tsconfig used to resolve imports. true = nearest tsconfig.json. |
true(default) — use the nearesttsconfig.jsonabove the config file (the workspace's own)."path/to/tsconfig.json"— use a different tsconfig. The path is resolved from the project root.false— disable tsconfig resolution. Relative.js→.tsrewriting still works, but tsconfigpathsaliases do not.
import { defineConfig } from '@deltabox/toolchain';
export default defineConfig({
toolchain: {
loader: { tsconfig: 'tsconfig.loader.json' },
},
});loader is repository-scoped: it is not merged into a nested workspace's config. A nested config uses its parent's loader choice when it does not set one itself.
Path aliases and source extensions
With the default loader, imports resolve the way the project's TypeScript does:
import { shared } from '@org/shared/config.js'; // shared/config.ts
import { defineConfig } from '@deltabox/toolchain';
export default defineConfig({
toolchain: {
project: shared.project,
},
});The loader rewrites these specifiers when the target exists:
| Import | Resolves to |
|---|---|
./helper.js | helper.ts, helper.tsx, ... |
./helper.mjs | helper.mts |
./helper.cjs | helper.cts |
./helper.jsx | helper.tsx |
It also follows a tsconfig's relative extends chain for baseUrl / paths. A genuinely missing package or module is still an error: the loader does not silently turn it into an empty module.
Programmatic API
loadToolchainConfig accepts the same override directly:
import { loadToolchainConfig } from '@deltabox/toolchain';
const loaded = await loadToolchainConfig(process.cwd(), {
loaderTsconfig: 'tsconfig.loader.json', // or false
});The option takes precedence over the config's own loader.tsconfig and over the parent config's choice. When omitted, the loader uses the config's loader.tsconfig, then the parent config's, then the nearest tsconfig.json.
Notes
- The loader reads
loader.tsconfigfrom the config it is loading, so the first import must already be resolvable. Put a shared choice on the root config (it is used for nested configs) or point the nearesttsconfig.jsonat it. .jsonconfigs are parsed directly and do not use a tsconfig.
Reusing the loader in another project
@deltabox/toolchain/config exposes the same building blocks for consumers with their own config format:
import {
collect,
createConfigFile,
loadConfig,
loadConfigSync,
parseCliConfig,
parseConfig,
parseEnvConfig,
} from '@deltabox/toolchain/config';
// Discover + validate a config (JSON, CJS, ESM or TypeScript).
const loaded = await loadConfig({ packageJsonKeys: ['myapp'], schema });
// Or parse a specific source.
const fromEnv = parseEnvConfig(schema, process.env, { envPrefix: 'MYAPP_' });
const fromCli = parseCliConfig(schema, process.argv.slice(2));
const fromFile = parseConfig(schema, loaded?.config);
// Scaffold a starter config file.
createConfigFile({ name: 'myapp.config.ts', content: '{ enabled: true }' });The loader also accepts the same tsconfig, ancestor and filter options as the built-in one:
const loaded = await loadConfig({
parser: schema,
configFileOptions: {
filename: 'myapp.config',
commonLocation: [{ path: '.' }, { cwd: 'packages', path: '*/' }],
// Resolve TS imports through this tsconfig (`false` disables it).
tsconfig: 'tsconfig.loader.json',
// Search ancestors when nothing is found at cwd (stops at `.git`).
parent: true,
// Skip files that are not valid candidates for this loader.
accept: file => !file.endsWith('.shim.ts'),
},
});The object API accepts tsconfig, parent and accept directly instead of nesting them in configFileOptions. findConfigFile and findParentConfigFile run the same discovery without loading anything.
Discovery defaults to ., config and configs, matching the built-in loader. commonLocation.path globs support *, **, ?, simple [...] character classes and {a,b} alternatives. A function export is resolved when a parser/schema is passed; without one the raw export is returned, so a caller can supply its own environment (as the dbx plugin probe does).
collect(schema, options) lists every config leaf (env/CLI metadata) and accepts envPrefix, include/exclude, maxDepth, and validate with errorOptions for required/empty values. loadConfigSync handles JSON and CommonJS only; use loadConfigAsync (or a custom loader) for TypeScript.
Scaffolding formats
createConfigFile infers the format from the file name (or takes an explicit type): file (TypeScript/JavaScript defineConfig), json, yaml, env (KEY=value lines) and cli (--flag=value lines). Object content is serialized for the chosen format, and defaults/overrides merge under/over it:
createConfigFile({
name: 'myapp.config.yaml',
content: { project: { name: 'myapp' } },
defaults: { project: { license: 'MIT' } },
});
createConfigFile({ name: '.env.example', content: { APP_HOST: 'localhost' } });