TypeScript Config Patterns

Configure tsconfig with extends, project references, composite builds, and incremental compilation

When to Use

• Setting up tsconfig.json for a new project
• Organizing shared TypeScript configuration across a monorepo
• Enabling project references for faster builds in multi-package repos
• Troubleshooting TypeScript compilation issues

Instructions

1. Minimal modern tsconfig for a Node.js/Next.js project:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "isolatedModules": true,
    "noEmit": true,
    "jsx": "react-jsx",
    "incremental": true,
    "paths": { "@/*": ["./src/*"] }
  },
  "include": ["src"],
  "exclude": ["node_modules", "dist"]
}

2. Extend a shared base config:

// tsconfig.base.json
{
  "compilerOptions": {
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "isolatedModules": true
  }
}

// packages/api/tsconfig.json
{
  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "outDir": "./dist",
    "rootDir": "./src"
  },
  "include": ["src"]
}

3. Project references for monorepo builds:

// tsconfig.json (root)
{
  "references": [
    { "path": "packages/shared" },
    { "path": "packages/api" },
    { "path": "packages/web" }
  ],
  "files": []
}

// packages/shared/tsconfig.json
{
  "compilerOptions": {
    "composite": true,
    "declaration": true,
    "outDir": "./dist"
  },
  "include": ["src"]
}

// packages/api/tsconfig.json
{
  "references": [{ "path": "../shared" }],
  "compilerOptions": {
    "composite": true,
    "outDir": "./dist"
  }
}

Build with:

tsc --build

4. Incremental compilation — cache type check results:

{
  "compilerOptions": {
    "incremental": true,
    "tsBuildInfoFile": ".tsbuildinfo"
  }
}

5. Separate configs for different concerns:

// tsconfig.json — IDE and type checking (no emit)
{
  "compilerOptions": { "noEmit": true },
  "include": ["src", "tests"]
}

// tsconfig.build.json — production build (emit, no tests)
{
  "extends": "./tsconfig.json",
  "compilerOptions": { "noEmit": false, "outDir": "dist" },
  "include": ["src"],
  "exclude": ["**/*.test.ts", "**/*.spec.ts"]
}

6. Key options explained:

   • target

     — JavaScript version to emit. Use

     ES2022

     for Node 18+,

     ES2021

     for broader compat

   • module

     — Module system.

     ESNext

     for bundler-based projects,

     NodeNext

     for Node.js packages

   • moduleResolution

     —

     bundler

     for Vite/webpack/Next.js,

     NodeNext

     for Node.js libraries

   • isolatedModules

     — required for esbuild/swc transpilation (one file at a time)

   • skipLibCheck

     — skip type checking

     .d.ts

     files from dependencies. Almost always enable

7. Configure for testing:

// vitest needs jsdom types
{
  "compilerOptions": {
    "types": ["vitest/globals"]
  }
}

Details

tsconfig.json

noEmit: true

composite: true

• declaration: true

  must be set
• All input files must be matched by

  include

  or listed in

  files

• rootDir

  defaults to the directory containing

  tsconfig.json

• Enables

  tsc --build

  mode for dependency-aware compilation

moduleResolution

• bundler

  — best for projects using Vite, webpack, esbuild, Next.js. Allows extensionless imports,

  index.ts

  resolution, and

  package.json

  exports

• NodeNext

  /

  Node16

  — for pure Node.js packages. Requires

  .js

  extensions in imports (even for

  .ts

  files). Enforces ESM/CJS boundaries

• node

  (legacy) — Node.js CommonJS resolution. Avoid for new projects

paths

baseUrl

paths

baseUrl

paths

baseUrl

Trade-offs:

• skipLibCheck: true

  speeds up compilation significantly — but hides type errors in

  .d.ts

  files from dependencies

• incremental: true

  speeds up subsequent builds — but creates a

  .tsbuildinfo

  file that should be gitignored
• Project references enable parallel builds — but add complexity to the monorepo configuration

• isolatedModules

  is required for fast transpilers — but prevents

  const enum

  and namespace merging across files

Source

https://typescriptlang.org/tsconfig

Process

1. Read the instructions and examples in this document.
2. Apply the patterns to your implementation, adapting to your specific context.
3. Verify your implementation against the details and edge cases listed above.

Harness Integration

• Type: knowledge — this skill is a reference document, not a procedural workflow.
• No tools or state — consumed as context by other skills and agents.

Success Criteria

• The patterns described in this document are applied correctly in the implementation.
• Edge cases and anti-patterns listed in this document are avoided.