Speed Up TypeScript Builds: tsconfig Tips, Project References, and SWC/Esbuild Strategies

Summary: TypeScript can be optimized for faster feedback loops. This guide covers tsconfig flags, project references, incremental builds, and when to use SWC or esbuild for faster transpilation.

“Faster builds improve iteration and developer morale. Optimize where it matters.”

1. Use incremental compilation

Enable incremental and tsBuildInfoFile in tsconfig.json. This allows tsc to reuse previous work across builds:

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

2. Project references for monorepos

Project references let you split a large codebase into smaller compilable units. Each package has its own tsconfig and references its dependencies. This reduces full rebuilds and helps parallelize compilation in CI.

3. Configure skipLibCheck and skipDefaultLibCheck

Library type checking can be time-consuming. Use skipLibCheck to avoid re-checking @types packages during builds. This is usually safe for production builds if you control your own types.

4. Be conservative with complex types

Avoid exploding types that cause the compiler to do heavy inference work. Break giant unions into simpler branded types and avoid excessive recursive conditional types in hot parts of the codebase.

5. Use transpilers for faster dev builds

SWC and esbuild provide lightning-fast transpilation to JavaScript. Pair them with a separate type-check step in CI to maintain correctness. During development, run the fast transpiler for bundling and a background tsc --noEmit for type checking.

6. Parallelize checks in CI

Run type checks and tests in parallel where possible. Use build caches and restore caches based on package lock files to avoid re-installing dependencies every run.

7. Watch mode and editors

In local development, use the compiler in watch mode (tsc -w) or leverage incremental servers built into editor integrations. Keep noEmit on while relying on fast transpilers for bundling.

8. Cache and artifact strategies

Save .tsbuildinfo between CI runs using cache keys that include your TypeScript version and lockfile hash. This can drastically reduce build times on unchanged modules.

9. Configure module resolution wisely

Prefer moduleResolution: 'node' and exact path settings to avoid expensive lookups. Avoid globbing includes that bring unrelated files into the type-check scope.

10. Profiling and measuring

Use --extendedDiagnostics to see where the compiler spends time. This helps identify particularly heavy files or types that need refactoring.

Putting it together: a recommended workflow

1. Local dev: fast transpiler (esbuild/swc) + background tsc --noEmit --watch
2. Pull requests: run incremental type check per package and full build on merge
3. CI: cached artifacts, parallelized test and type-check pipelines

Conclusion

Optimizing TypeScript build speed is both a configuration and architectural effort. Small tsconfig tweaks plus modularization (project references) give large wins. Use fast transpilers for iteration and keep a full type-checking gate in CI for correctness.

Actionable checklist: enable incremental builds, add skipLibCheck, split into project references, and adopt SWC/esbuild for local transpilation.