tsconfig

The tsconfig section generates every workspace's tsconfig.json from a workspace default tsconfig (tsconfig.default.json), layering path aliases and project references from a single root workspaces tsconfig (tsconfig.workspaces.json). It runs only at a monorepo root (project.type: 'monorepo-root'); a single project keeps its hand-written tsconfig untouched.

dbx.config.ts

export default defineConfig({
    toolchain: {
        project: { type: 'monorepo-root', name: 'acme', scope: '@acme' },
        tsconfig: { aliases: true, refs: true, indent: 4 },
    },
});

dbx sync regenerates the managed tsconfig.json files and tracks them in .dbx/toolchain/manifest.json; dbx sync --check is the CI gate. See Configuration for the opt-in-by-presence shorthand (tsconfig: true enables the defaults).

Why so many tsconfig files?

TypeScript's language service (IntelliSense, diagnostics, autocomplete, "go to definition", project references, ...) always picks up the file literally named tsconfig.json. It offers no way to point the editor at a different file, and it only understands the options it can express in a single config.

That single-file constraint is painful in practice:

• Builds need different options than the editor. tsc for a build wants declaration/composite/emitDeclarationOnly, a wider include and no noEmit, while the editor wants fast, no-emit checking of src. Cramming both into one tsconfig.json makes one of the two slower or wrong.
• A monorepo has many projects with different options. Each workspace wants its own include/lib/types/jsx, but the editor only reads the nearest tsconfig.json.
• The language service can get slow. For TypeScript (especially ≤ 7) the editor loads and type-checks whatever the tsconfig.json includes; a config that pulls in every workspace (or the whole build graph) can noticeably slow IntelliSense. Keeping the editor config small and correct matters.
• Hand-managing the graph is tedious. Path aliases and project references have to stay in sync with the workspace list, and a stale reference silently degrades the editor.

The toolchain splits the concerns so each file has one job, and dbx sync keeps the generated tsconfig.json (the file the LSP actually reads) in sync with a shared workspaces tsconfig that declares the paths + references.

NOTE: the paths + references in tsconfig.workspaces.json automatically resolves relative paths in each workspace's generated tsconfig.

The files

The generator reads two hand-authored inputs (tsconfig.default.json, tsconfig.workspaces.json) and writes one managed output (tsconfig.json):

File	Owner	Role
tsconfig.base.json	you	Shared compiler options that every workspace config extends.
tsconfig.default.json	you	A workspace's own options — the input the generator reads. Optional.
tsconfig.build.json	you	Build/emit options (tsc -p tsconfig.build.json). Optional, never rewritten.
tsconfig.workspaces.json	you (root)	The root paths + references the generator expands. Optional.
tsconfig.json	generated	Extends tsconfig.default.json + the workspaces aliases/references.

Only tsconfig.json must keep its name — that is the file TypeScript's LSP reads. Everything else is optional and, if you prefer, renameable (see Renaming the files):

• No tsconfig.default.json: there is nothing to expand (the task logs a message and, when workspaces are expected, warns — see Warnings).
• No tsconfig.build.json: builds simply use another config; it is never required or rewritten.
• No tsconfig.workspaces.json: each workspace still gets a tsconfig.json that extends its own default, but there are no shared paths/references to wire.

The token in the templates (default src/env.d.ts) is resolved when a project is scaffolded, so a generated config's include points at the project's env types file.

Development vs build configs

tsconfig.json is the editor/development config: it extends tsconfig.default.json and layers the workspace paths aliases on top, so imports such as @acme/core resolve directly to packages/core/src. That is what gives go-to-definition, inline diagnostics and fast editor feedback against the real workspace source.

tsconfig.build.json intentionally extends tsconfig.default.json, nottsconfig.json, so it does not get those path aliases. A build (tsc -p tsconfig.build.json, tsdown, ...) therefore treats sibling workspaces as packages (resolved through node_modules / project references) instead of treating their source as part of the current package. Keeping them as packages matters: aliasing them into the build graph would compile/bundle another workspace's source into the output and increase the package size.

You can opt into build-time aliases by changing the build config to

tsconfig.build.json

{
    "extends": "./tsconfig.json",
    "include": ["src"]
}

It works, but sibling workspace source now participates in the build graph, so only do it when that is what you want.

Options

Option	Type	Default	Description
enabled	boolean	enabled when defined	Master switch (only meaningful with project.type: monorepo-root).
aliases	boolean	true	Inject compilerOptions.paths from the workspaces config.
refs	boolean	false	Wire project references between workspaces.
composite	boolean	false	Emit composite: true on the generated configs.
glob	string | string[]	**/tsconfig.default.json	Glob(s) for the workspace default tsconfig files to expand.
exclude	string | string[]	common ignored paths	Glob(s) excluded from glob.
gitignore	boolean	true	Respect .gitignore files (root + nested).
defaultFile	string	tsconfig.default.json	The workspace default tsconfig file name.
buildFile	string	tsconfig.build.json	The workspace build tsconfig file name.
indent	number	4	JSON indentation of the generated files.
rootFile	string	tsconfig.workspaces.json	The workspaces tsconfig file name.
baseFile	string	tsconfig.base.json	The root base tsconfig file name (the overrides.base target).
extends	{ base?, default?, build? }	template defaults	Per-file extends overrides for scaffolded tsconfig templates.
overrides	{ base?, default?, build?, root? }	none	Managed deep-merge overrides applied to the user-owned tsconfigs.

aliases

When on (the default), each generated tsconfig.json gets a compilerOptions.paths block derived from the workspaces tsconfig's paths. The generator rewrites every alias relative to the workspace it is writing, and drops any alias that resolves to the workspace itself (or into its own subtree) so a package never maps its own import back to a self-reference.

refs

When on, the workspaces references are merged with each workspace's own references, deduplicated, rewritten relative to the workspace, and pruned whenever the target config is not composite (a reference to a non-composite project is invalid). This is what lets tsc -b build the graph in order.

composite

When on, the generated configs spread the workspaces tsconfig's compilerOptions (including composite: true, declaration, emitDeclarationOnly, ...) and merge its types. Leave it off unless you build the graph with tsc --build.

refsAuto

refsAuto derives the workspaces references from the project graph. It defaults to auto; refs must also be enabled and each referenced workspace must be composite. References are only followed by tsc --build (tsc -b); tsc -p --noEmit ignores them. If your typecheck runs tsc -p --noEmit (as this repo's does), keep refsAuto: false and maintain the references in tsconfig.workspaces.json by hand, or switch the check to tsc -b.

glob

The glob(s) selecting the workspace default tsconfig files to expand. A single string or an array:

tsconfig: {
    glob: '**/tsconfig.default.json';
}
tsconfig: {
    glob: ['packages/*/tsconfig.default.json', 'apps/*/tsconfig.default.json'];
}

It defaults to **/<defaultFile>, so setting defaultFile alone is usually enough.

exclude / gitignore

exclude drops paths from glob; it adds to the common ignored paths the toolchain already skips (node_modules, .dbx, dist, build, coverage, .turbo, .git, .yarn, ...). gitignore (on by default) additionally honours the repo's .gitignore files — root and nested, each scoped to its own directory, like git — so an ignored workspace is never scanned:

tsconfig: {
    glob: '**/tsconfig.default.json',
    exclude: ['**/legacy/**'],
    gitignore: true,
}

Set gitignore: false to scan ignored paths anyway. The base list is exported as DEFAULT_IGNORE_PATTERNS from @deltabox/toolchain and @deltabox/toolchain/shared, so you can compose your own excludes from it.

Renaming the files

defaultFile, buildFile, rootFile and baseFile rename the files the generator reads and the overrides patch:

tsconfig: {
    defaultFile: 'tsconfig.src.json',          // expanded into tsconfig.json
    buildFile: 'tsconfig.dist.json',           // read, never rewritten by the generator
    rootFile: 'tsconfig.graph.json',           // the workspaces paths + references
    baseFile: 'config/tsconfig.shared.json',   // the shared base (`overrides.base`)
}

Only tsconfig.json is fixed (TypeScript's LSP requirement). rootFile and baseFile are paths relative to the repo root; defaultFile and buildFile are file names inside each workspace. The custom names are honoured everywhere the sync task looks: the generator, the overrides, the watched inputs (dbx watch) and the files it keeps. Project detection looks for tsconfig.workspaces.json / tsconfig.default.json by default, but honours rootFile / defaultFile when they are set in the config. Scaffolding (dbx project:init*) always writes the default names.

indent

The JSON indentation of every generated file (default 4).

extends

Overrides the extends field written into scaffolded tsconfig templates (dbx project:init*). This is separate from the tsconfig.workspaces.jsonextends chain used by the resolver. Set a value to add/replace the field, or false to remove it:

tsconfig: {
    extends: {
        base: '@tsconfig/node22',       // tsconfig.base.json currently has no extends
        default: './tsconfig.base.json', // keep/customize the normal default chain
        build: './tsconfig.json',       // opt into path aliases during builds
    },
}

Existing projects are user-owned by default: edit their tsconfig.base.json, tsconfig.default.json and tsconfig.build.json directly. dbx sync only rewrites the generated tsconfig.json unless you opt into overrides.

overrides

Deep-merges managed options into the user-owned tsconfigs during dbx sync, so a config can define those files programmatically:

tsconfig: {
    overrides: {
        base: { compilerOptions: { target: 'ES2022' } },
        root: { compilerOptions: { composite: true, types: ['node'] } },
        default: { compilerOptions: { strict: true } },
        build: { compilerOptions: { declaration: true } },
    },
}

Key	Target
base	the root base tsconfig (baseFile, tsconfig.base.json)
root	the workspaces tsconfig (rootFile, tsconfig.workspaces.json)
default	every workspace's default tsconfig (defaultFile)
build	every workspace's build tsconfig (buildFile)

Overrides are deep-merged: objects merge key by key, while arrays and scalars replace the target value. Keys the override does not mention are left alone. The patched files stay yours: they are not added to the manifest's managed files, so a sync never deletes them and dbx reset never removes them.

Snapshots

The first time an override touches a file, its original content is saved in .dbx/toolchain/manifest.json under a top-level snapshots field. The tree mirrors the repository with relative paths (the manifest is the tracked file under .dbx, so it never holds an absolute path), and the applied override per file is recorded under tsconfigOverrides:

.dbx/toolchain/manifest.json

{
    "files": ["packages/core/tsconfig.json"],
    "snapshots": {
        "tsconfig.workspaces.json": { "compilerOptions": { "composite": false } },
        "packages": {
            "core": { "tsconfig.build.json": { "extends": "./tsconfig.default.json" } }
        }
    },
    "tsconfigOverrides": {
        "tsconfig.workspaces.json": {
            "kind": "root",
            "override": { "compilerOptions": { "composite": true, "types": ["node"] } }
        }
    }
}

Removing an override

Removing an override (or one of its keys) reverts it on the next sync. For every key the override no longer sets, the sync compares the target file with the snapshot:

• the snapshot defines the key: the original value is restored (eg. dropping composite: true above brings back the original composite: false);
• the snapshot does not define it: the key is removed, along with any parent object the override created that is now empty (eg. types);
• the key holds another value than the override wrote: it was edited after the override applied it, so it is kept and a tsconfig.override-edited warning is logged.

Once no override targets a file anymore, its snapshot and tsconfigOverrides entry are dropped. A file is never deleted, even when nothing else is left in it: other tooling may depend on it.

Restoring

dbx tsconfig --restore removes the applied override content right away (with the same snapshot comparison), optionally for one kind only:

dbx tsconfig --restore           # every kind
dbx tsconfig --restore default   # base | root | default | build

If the overrides are still configured, the command warns (tsconfig.restore-reapply): the next dbx sync applies them again, so remove them from toolchain.tsconfig.overrides to keep the restored files. dbx reset does the same restore before it removes the manifest, so resetting a project never strands override content without its snapshots.

Notes

• A target that does not exist is not created: the sync warns (tsconfig.missing-file) and skips that file. A target outside the project root warns with tsconfig.outside-root.
• The user-owned files are read as JSONC but written back as plain JSON, so comments are dropped from a file the first time an override changes it. A file whose content would not change is never rewritten.
• dbx sync --check reports pending override changes (and reverts) as drift without writing them.

How generation works

For each workspace matched by glob, the generator:

1. reads its default tsconfig and, when present, the workspaces tsconfig;
2. writes a sibling tsconfig.json that extends: './<defaultFile>', layering the workspaces compilerOptions (aliases/types) and references on top;
3. leaves tsconfig.build.json alone — it is a user-owned input, like the default tsconfig.

Because the output only ever extends the default and adds the workspaces wiring, your workspace-specific options stay in the default tsconfig (the file the generator reads, not the one it writes).

Warnings

Id	When
tsconfig.missing-file	An override targets a file that does not exist (it is skipped).
tsconfig.outside-root	An override target resolves outside the project root.
tsconfig.override-edited	A reverted key was edited after the override set it (it is kept).
tsconfig.restore-reapply	--restore ran while the restored overrides are still configured.

Silence any of them with logger.suppress.

When a sync finds no workspace tsconfig files, it warns (in the CLI logs and as a VS Code notification) if either:

• refs or composite is enabled, or
• a tsconfig.workspaces.json is present,

because in those cases workspaces are clearly expected. Otherwise it logs a quiet "nothing to do" message.

no workspace tsconfig files found (looked for **/tsconfig.default.json), but project references + tsconfig.workspaces.json have nothing to wire.

The workspaces config

tsconfig.workspaces.json holds the paths and references the generator expands. Scaffold it with project:init:monorepo, or build it programmatically from a workspace list:

import { buildMonorepoTsconfig, renderMonorepoTsconfig } from '@deltabox/toolchain/tsconfig';

const config = buildMonorepoTsconfig({
    scope: '@acme',
    workspaces: [
        { alias: 'core', dir: 'packages/core' },
        { alias: 'cli', dir: 'packages/cli' },
    ],
});
// -> { compilerOptions: { composite, paths: { '@acme/core': ['./packages/core/src/index.ts'], ... } },
//      references: [{ path: './packages/core/tsconfig.json' }, ...] }
renderMonorepoTsconfig({ scope: '@acme', workspaces: [{ alias: 'core', dir: 'packages/core' }] });

CLI

dbx tsconfig                       # regenerate every workspace tsconfig.json
dbx tsconfig --no-aliases          # skip the workspaces path aliases
dbx tsconfig --refs                # wire project references
dbx tsconfig --composite           # emit composite: true
dbx tsconfig -i 2                  # JSON indentation
dbx tsconfig --glob "packages/*/tsconfig.default.json" "apps/*/tsconfig.default.json"
dbx tsconfig --exclude "**/legacy/**"     # exclude paths (on top of the defaults)
dbx tsconfig --no-gitignore               # do not respect .gitignore files
dbx tsconfig --default-file tsconfig.src.json
dbx tsconfig --build-file tsconfig.dist.json
dbx tsconfig --root-file tsconfig.workspaces.json
dbx tsconfig --restore [kind]             # remove applied overrides (base|root|default|build)

Every flag overrides the matching tsconfig option; with no flags the command uses the config defaults (including in-memory overrides, so the output matches dbx sync). dbx tsconfig --restore [kind] removes applied overrides instead (see Restoring). dbx sync runs the same generator through the tsconfig sync task.

Resolving a tsconfig

The same command can inspect a config instead of generating files. It follows extends per field, so a child can define paths while inheriting references (or the reverse):

dbx tsconfig --json               # { alias, paths, references }
dbx tsconfig --alias              # Vite/Vitest resolve.alias entries
dbx tsconfig --paths              # resolved compilerOptions.paths
dbx tsconfig --references         # resolved project references
dbx tsconfig --tsconfig tsconfig.build.json
dbx tsconfig --root packages/app  # root used for detection + relative tsconfig
dbx tsconfig --no-extends         # only the selected file

The output is machine-clean JSON (absolute paths). Exact alias keys are strings; wildcards are anchored regular expressions (rendered as /.../ strings in the CLI JSON), so @acme/core never captures @acme/core-utils. Exact keys sort before wildcards.

Programmatic API

import {
    generateTsconfigs,
    runTsconfigCli,
    resolveTsconfig,
    readTsconfig,
    renderTsconfigBase,
    renderTsconfigDefault,
    renderTsconfigBuild,
    renderTsconfigTemplates,
    buildMonorepoTsconfig,
    renderMonorepoTsconfig,
    tsconfigSyncTask,
    tsconfigFileNames,
    restoreTsconfigOverrides,
} from '@deltabox/toolchain/tsconfig';

Export	Description
generateTsconfigs(options)	Expand every default tsconfig (dry-run-able).
runTsconfigCli(argv?)	The dbx tsconfig entry point.
resolveTsconfig(options?)	Resolve { alias, paths, references } (extends-aware).
readTsconfig(file)	Read a JSONC tsconfig (comments + trailing commas).
renderTsconfigBase / renderTsconfigDefault / renderTsconfigBuild	Render a template with replacements.
renderTsconfigTemplates(replacements?)	Render every template keyed by file name.
buildMonorepoTsconfig(options) / renderMonorepoTsconfig(options)	The workspaces config (object / JSON text).
tsconfigSyncTask()	The sync task wired into dbx sync.
tsconfigFileNames(config)	The configured base/root/default/build file names.
restoreTsconfigOverrides(options)	Remove applied overrides ({ cwd, kind?, dryRun? }).
applyOverride / mergeOverride / revertOverride	The deep-merge + snapshot-aware revert helpers.
getSnapshot / setSnapshot / deleteSnapshot	Read/write the manifest snapshot tree by relative path.

resolveTsconfig accepts { tsconfig, cwd, root, extends, overrides }: tsconfig is resolved from root (default cwd), and extends defaults to true. Paths are resolved against the defining config's baseUrl (or its directory), matching TypeScript.

generateTsconfigs returns one result per workspace (with newTsconfig, originalConfig, ...); pass write: false for a dry run. The task-level options are documented in the Programmatic API reference.

renderTsconfigBase / renderTsconfigDefault / renderTsconfigBuild accept an optional second extends argument (string | string[] | false), and renderTsconfigTemplates accepts { base, default, build } as its second argument.

Sync & CI

At a monorepo root with the section enabled, dbx sync runs the tsconfig task and reports the regenerated files:

tsconfig: regenerated 6 workspace tsconfig(s).

The task watches the workspaces tsconfig and every default tsconfig (custom rootFile / defaultFile names included), keeps the build tsconfigs, and only applies to monorepo-root projects. Run dbx sync --check in CI to fail when a generated tsconfig.json drifts from its inputs.

Refresh aliases after builds

Auto-wired aliases and references are derived from each workspace's package.json (exports, then types/main, then a source scan). If a build step can change a workspace manifest (a generated package.json, a rewritten export map, ...), run the tsconfig-only sync once after all workspace builds:

dbx sync --only tsconfig

This regenerates the workspaces tsconfig and every managed tsconfig.json without running the other sync tasks, and it does not prune files owned by those tasks. Add it to the end of your root build script so the aliases always reflect the final package.json exports:

package.json

{
    "scripts": {
        "build": "yarn workspaces foreach -A run build && dbx sync --only tsconfig"
    }
}

The task is skipped when toolchain.tsconfig is omitted or false — including dbx tsconfig and dbx sync --only tsconfig — so a disabled section never generates files. A nested workspace that defines its own tsconfig section owns its generated file: the root still aliases/references it, but does not rewrite it.

Per-project configs

toolchain.tsconfig is repository-scoped: the root sync task expands every workspace tsconfig.json, so nested configs do not inherit it — inheriting it would make dbx tsconfig re-scan a workspace's own subtree. A nested config may still declare its own tsconfig section when it manages its own workspace tree (a nested monorepo); otherwise add the workspace's tsconfig.default.json and run dbx tsconfig / dbx sync from the root. Other sections still inherit as usual; see Configuration → Nested configs for the rules.

Scaffolding

dbx project:init:monorepo writes tsconfig.base.json + a tsconfig.workspaces.json; dbx project:init:workspace writes the workspace's tsconfig.default.json / tsconfig.build.json / tsconfig.json (and a dbx.config.ts). See the Monorepo Guide for the full flow.