0Pricing
TypeScript Academy · Lesson

Profiling Slow TypeScript Compilation

Use --extendedDiagnostics and --generateTrace to find bottlenecks.

Profiling Slow TypeScript Compilation is a free TypeScript Academy lesson on CoddyKit — lesson 1 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the TypeScript Academy learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

Why TypeScript Can Be Slow

Complex conditional types, large union distributions, and deeply recursive mapped types can cause TypeScript's type checker to slow dramatically on big projects.

// Expensive: distributive conditional on large union
type Slow = LargeUnion extends infer T ? T extends string ? T : never : never;

--extendedDiagnostics Flag

Run tsc --extendedDiagnostics to see a breakdown of compilation time: parsing, binding, type checking, and emit phases.

tsc --extendedDiagnostics 2>&1 | head -40
# Output:
# Files:             212
# Lines:            48320
# Check time:       8.23s  ← focus here

--generateTrace Flag

tsc --generateTrace ./trace produces a Chrome DevTools-compatible trace file you can load in the Performance tab to see which types are expensive.

tsc --generateTrace ./trace-output
# Open trace-output/trace.json in Chrome DevTools > Performance

Analyzing the Trace

In the trace, look for long horizontal bars representing expensive type instantiations. The type name and source location tell you what to optimize.

# Common culprits in traces:
# - Recursive mapped types with large inputs
# - Distributive conditionals over 50+ member unions
# - Deep infer chains on complex generics

--listFiles Flag

tsc --listFiles shows every file included in the compilation. Large node_modules folders accidentally included are a common performance culprit.

tsc --listFiles 2>&1 | grep node_modules | wc -l
# If this is large, check your include/exclude settings

Reducing File Inclusion

Use include and exclude in tsconfig to limit which files TypeScript processes.

{
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist", "**/*.test.ts"]
}

skipLibCheck for Quick Wins

skipLibCheck: true skips type checking of all .d.ts declaration files, which can significantly speed up compilation in projects with many dependencies.

{
  "compilerOptions": {
    "skipLibCheck": true
  }
}

Isolating Expensive Types

Extract expensive type computations into named intermediate types so TypeScript can cache them rather than recomputing at every use site.

// Slow: recomputed at each usage
type Result = ComplexUnion extends string ? ComplexUnion : never;

// Fast: cached
type FilteredUnion = ComplexUnion extends string ? ComplexUnion : never;
type Result = FilteredUnion;

Checking with transpileOnly

In development, use ts-jest or esbuild with transpileOnly: true to skip type checking for faster iteration. Run full type checks separately in CI.

// jest.config.js with ts-jest
{
  transform: {
    "^.+\.tsx?$": ["ts-jest", { diagnostics: false }]
  }
}

Editor Performance

TypeScript language server slowdowns in VS Code often trace back to the same expensive types. Check TypeScript: Restart TS Server and the TS trace from the language server.

// VS Code settings.json to enable detailed TS server log:
// "typescript.tsserver.log": "verbose"

Recap: Profiling Compilation

Use --extendedDiagnostics for high-level timing, --generateTrace for per-type analysis, and reduce file inclusion, deep conditionals, and large union distributions to speed up compilation.

Quick Check

Which flag generates a Chrome DevTools-compatible trace file?

What You Learned

Profile TypeScript compilation with --extendedDiagnostics and --generateTrace. Reduce compile time by limiting file inclusion, using skipLibCheck, caching intermediate types, and avoiding deeply recursive or distributive type operations.

Frequently asked questions

Is the “Profiling Slow TypeScript Compilation” lesson free?

Yes — the full text of “Profiling Slow TypeScript Compilation” is free to read here on the web, and the TypeScript Academy course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the TypeScript Academy course, upgrade to CoddyKit PRO.

What will I learn in “Profiling Slow TypeScript Compilation”?

Use --extendedDiagnostics and --generateTrace to find bottlenecks. You practise TypeScript Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start TypeScript Academy?

No prior experience is required. TypeScript Academy on CoddyKit is structured for beginners through advanced learners; this is — lesson 1 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “Profiling Slow TypeScript Compilation” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this TypeScript Academy lesson?

Yes. Every TypeScript Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

  1. Profiling Slow TypeScript Compilation
  2. Avoiding Expensive Type Operations
  3. skipLibCheck and Isolated Declarations
  4. Type-Checking in CI: Strategies and Tools
← Back to TypeScript Academy