Zthxxx's base tsconfig

Files

tsconfig.json

The basic tsconfig. Designed to be inherited by package root tsconfig.json, used for IDE type inference.

build.esm.json / build.cjs.json

Designed to be as symlink / copied beside package root tsconfig.json, use for build esm/cjs and .d.ts files.

build.types.json

Designed to be as symlink / copied beside package root tsconfig.json, use for build ONLY .d.ts files.

TypeScript compatibility

The configs support TypeScript 6 and 7. The CJS template uses module: "CommonJS" with moduleResolution: "Bundler", a combination supported since TypeScript 6.0. It preserves CommonJS output and extensionless imports while respecting package exports and imports. Dependencies must expose the entry points the consumer imports.

The ESM and CJS templates emit JavaScript, source maps, and declarations. The types template emits declarations only. The base config performs type checking without emitting files.

Set rootDir in the consuming project to control output paths, and list ambient packages such as node in types; TypeScript 6+ no longer includes all installed @types packages by default. See the migration guide. Neither option is fixed in the shared config because source layouts and runtime environments vary by consumer.

The ts-node override also uses CommonJS with Bundler resolution. ts-node 10.9.2 requires TypeScript 6's JavaScript API; TypeScript 7.0 does not provide that API. Use TypeScript 6 for ts-node and install TypeScript 7 under a separate npm alias when using both.

Tests

Requires Node.js 22+, pnpm 9.15.9, and Bun 1.4+.

pnpm install --frozen-lockfile
pnpm test

The tests/* workspace consumers link this package with workspace:* and use the published build templates through symlinks. Each test runs with TypeScript 6.0.3 and 7.0.2.

| Project | Verification | | --- | --- | | tests/base | No emit, strict null checking, React JSX, DOM/Node types, legacy decorators | | tests/esm | ESM execution in Node, JS/maps/declarations, downstream declaration consumer, test-file exclusion | | tests/cjs | CommonJS execution in Node, extensionless imports, JS/maps/declarations, test-file exclusion, ts-node | | tests/types | Declaration-only output and downstream type checking | | tests/exports | Dependency available only through its package exports map |

Runtime checks use fast-check 4.10.2 to verify string round trips with 100 generated inputs per run.

Usage

install

npm i -D @zthxxx/tsconfig

Example in package root tsconfig.json:

{
  "extends": "@zthxxx/tsconfig/tsconfig.json",
  "compilerOptions": {
    "rootDir": "src",
    "outDir": "dist/esm",

    // some external types
    "types": [
      "node",
    ],
  },
  "include": [
    "src",
  ],
  "references": [
    // relative path reference to other monorepo package
    // use for IDE `Go to Source Definition`
    { "path": "..." },
  ],
}

composite and references

Notice that I don't use composite:true for monorepo, even if use references with each other,

since composite will make tsc compile all of references packages at once and depend on their source code,

but in monorepo usually it's wrong,

I want compile packages independent and every package in compiling should use output .d.ts with others.

references without composite:true maybe cause IDE warn you some error,

like Referenced project '...' must have setting "composite": true.,

DON'T worry, it makes no influence to tsc or any other compiler or bundler.

references is useful in IDE for the function Go to Source Definition in monorepo,

like via Ctrl/Command + Click, will jump to source code file with correct line.

That also needs to set outDir path point to types field paths in package.json.

Otherwise without references, the Go to Source Definition only jump to node_modules/ or compiled output file .d.ts in such as dist/ or es/.

references or paths

Although use paths in tsconfig also support IDE Go to Source Definition to monorepo source files,

but it's just make other package's source code files as source files in the current package, NOT ONLY type declaration.

So while tsc compiling, it will also output product of compilation(.d.ts/.js) beside their source files in other packages