@lcabrera/tsconfig

Strict TypeScript config factories plus the generator that writes them to disk — one tsconfig.app.json / tsconfig.node.json per workspace, from a single typed source of truth.

It is deliberately not a set of extends bases. An extends chain still needs a file per workspace, and each of those files is hand-maintained, so the per-workspace differences drift. Here the differences are data: you write one module listing your workspaces, and the generator writes the JSON.

Install

npm install --save-dev @lcabrera/tsconfig

Needs Node 22.6+ if you run the generator with node --experimental-strip-types (Node 24+ strips types with no flag). Any TypeScript runner works too.

Generating configs in your repo

Create one module holding your workspace list — the package never sees it — and one line that runs the writer over it.

tools/tsconfig.entries.ts:

import path from 'node:path';
import { fileURLToPath } from 'node:url';

import {
  createAppTsConfig,
  createNodeTsConfig,
} from '@lcabrera/tsconfig/shared';

const repoRoot = path.resolve(
  path.dirname(fileURLToPath(import.meta.url)),
  '..',
);

export const entries = [
  {
    config: createAppTsConfig({
      tsBuildInfoFile: './node_modules/.tmp/tsconfig.app.tsbuildinfo',
    }),
    filePath: path.resolve(repoRoot, 'apps/web/tsconfig.app.json'),
  },
  {
    config: createNodeTsConfig({
      tsBuildInfoFile: './node_modules/.tmp/tsconfig.node.tsbuildinfo',
    }),
    filePath: path.resolve(repoRoot, 'apps/web/tsconfig.node.json'),
  },
  {
    // A library that must stay free of Node globals: no `process`, no `fs`.
    config: createNodeTsConfig({
      include: ['src'],
      tsBuildInfoFile: './node_modules/.tmp/tsconfig.app.tsbuildinfo',
      types: [],
    }),
    filePath: path.resolve(repoRoot, 'packages/pure-utils/tsconfig.app.json'),
  },
] as const;

tools/generate-tsconfigs.ts:

import { writeTsConfigs } from '@lcabrera/tsconfig/generate';

import { entries } from './tsconfig.entries.ts';

await writeTsConfigs({ entries });

Wire it up in package.json and run it:

{
  "scripts": {
    "tsconfig:generate": "node --experimental-strip-types ./tools/generate-tsconfigs.ts"
  }
}

npm run tsconfig:generate

Each workspace then keeps a thin, hand-written tsconfig.json holding only project references:

{
  "files": [],
  "references": [
    { "path": "./tsconfig.app.json" },
    { "path": "./tsconfig.node.json" }
  ]
}

The generated files are build artifacts. A hand-edit to one survives exactly until the next regeneration, which will not mention that it discarded it. Put the change in your entries module instead.

Run your formatter afterwards. renderTsConfig emits plain JSON.stringify(config, undefined, 2), one array element per line; most formatters collapse short arrays inline. Skip the format pass and every regenerated file is dirty against its committed copy on pure whitespace.

@lcabrera/tsconfig/shared — the factories

| Factory | For | What it sets | | -------------------- | -------------------------------------- | ------------------------------------------------------------------------------------------ | | createAppTsConfig | browser / React workspaces | jsx: react-jsx, DOM libs, types: [...baseTypes, ...types], a @/* → ./src/* alias | | createNodeTsConfig | Node services, tooling, Node-only libs | no JSX, no DOM lib, types: ['node'] by default, no aliases |

Both apply the same strictness — strict, noUncheckedIndexedAccess, noUnusedLocals, noUnusedParameters, noFallthroughCasesInSwitch, verbatimModuleSyntax, erasableSyntaxOnly. They are kept in lockstep on purpose: while the node variant lacked noUncheckedIndexedAccess, an unchecked arr[0] passed in Node-context packages and failed in browser ones, for no principled reason.

Options worth knowing, because each one exists to prevent a specific failure:

• baseTypes on createAppTsConfig — the ambient type roots types is appended to, defaulting to ['vite/client']. Pass [], or your own bundler's client types, outside a Vite project: vite/client does not resolve there, and a config naming a type root that does not exist fails to load. This is the one default in the package that is a toolchain fact rather than a config-variant fact, which is why it is an option rather than a constant.
• types: [] on createNodeTsConfig — for a package contractually barred from Node globals. The config then cannot hand it the APIs it must not reach for, so purity is checked rather than reviewed.
• srcAlias: false on createAppTsConfig — drops the @/* alias. A publishable package should pass this: @/ resolves only through a tsconfig, so an @/ import cannot survive publication, and dropping the alias makes tsc reject one instead of a reviewer having to spot it.
• paths — extra aliases, merged over @/* when srcAlias is on and emitted alone when it is off. When both are off and paths is empty, the key is omitted from the output entirely rather than written as {}.

paths accepts bare specifiers, and that is the point

paths is a plain Record<string, readonly string[]>, so a bare package name maps as readily as a wildcard:

createAppTsConfig({
  paths: {
    // Deep imports stay unmapped on purpose — see below.
    '@acme/design-system': ['../../packages/design-system/src/public-api.ts'],
    '@acme/server/*': ['../../packages/server/src/*'],
  },
  tsBuildInfoFile: './node_modules/.tmp/tsconfig.app.tsbuildinfo',
});

Mapping the bare specifier only, with no /* sibling, is a useful shape for a source-shipping package: tsc then resolves every deep import through that package's real exports map instead of short-circuiting it to src/. A subpath missing from exports fails your typecheck rather than a consumer's install. The factory does not enforce this — it has no idea which of your packages ship — it just refuses to make the shape unexpressible.

@lcabrera/tsconfig/generate — the writer

import { renderTsConfig, writeTsConfigs } from '@lcabrera/tsconfig/generate';

• renderTsConfig(config) → the exact bytes written for one config: two-space JSON with a trailing newline. Use it if your own build system owns the writing.
• writeTsConfigs({ entries, fileSystem? }) → writes every entry, creating each missing parent directory first. Every entry is rendered before any is written, so a config JSON cannot represent fails the whole run — naming that entry's filePath — rather than leaving a half-generated tree.

Both throw a TypeError for a config JSON.stringify cannot represent (undefined, a function, a symbol). Those return undefined from JSON.stringify rather than throwing, so without the guard they would reach disk as the literal text undefined and surface much later as a tsc parse error against the generated file. A circular structure already throws on its own.

fileSystem defaults to node:fs/promises. Pass your own { mkdir, writeFile } to dry-run a generation, to route writes through a virtual filesystem, or to assert what a run would produce without touching the disk:

const planned: Record<string, string> = {};

await writeTsConfigs({
  entries,
  fileSystem: {
    mkdir: async () => {},
    writeFile: async (filePath, contents) => {
      planned[filePath] = contents;
    },
  },
});

License

MIT