How to configure TypeScript for a monorepo

· Category: TypeScript

Short answer

Use a shared base tsconfig.json, project references for each package, and consistent path mapping to maintain type safety and fast builds across a monorepo.

Steps

  1. Create a tsconfig.base.json with common compiler options.
  2. In each package, extend the base: "extends": "../../tsconfig.base.json".
  3. Enable composite and declaration in package tsconfigs.
  4. Reference dependent packages in each tsconfig's references array.
  5. Build from the root with tsc --build or integrate with tools like Nx or Turborepo.

Tips

  • Keep rootDir and outDir aligned per package to prevent output files from being scattered.
  • Use workspace protocols (pnpm, Yarn) alongside TypeScript references for robust dependency linking.

Common issues

  • Duplicate type definitions across packages cause conflicts; centralize shared types in a types or core package.
  • Inconsistent strict settings between packages break internal API contracts.