Performance Optimization
TypeScript offers several advanced features and compiler options designed to optimize compilation performance, especially for large projects. Understanding these options can significantly reduce build times.Incremental Compilation
Incremental compilation allows TypeScript to save information about the project graph from the last compilation to speed up subsequent builds.Enabling Incremental Mode
tsconfig.json
The
incremental flag is automatically enabled when composite is set to true.How It Works
When incremental compilation is enabled, TypeScript:- Saves a
.tsbuildinfofile containing information about the project structure - Tracks which files have changed since the last compilation
- Only recompiles affected files and their dependents
- Reuses type information from unchanged files
.tsbuildinfo file stores:
- File hashes and timestamps
- Program structure information
- Semantic diagnostics
- Emit signatures
Customizing the Build Info File
tsconfig.json
Project References
Project references enable TypeScript to work with multiple interconnected projects efficiently, allowing for faster builds and better code organization.Setting Up Project References
Root Project:tsconfig.json
packages/core/tsconfig.json
The composite Option
The composite option enables constraints that allow a TypeScript project to be used with project references:
tsconfig.json
Composite projects automatically enable
incremental and require declaration to be true.Benefits of Project References
Faster Builds
Only rebuild changed projects and their dependents
Better Structure
Enforce logical separation between project components
Editor Performance
Improved IDE responsiveness in large codebases
Parallel Builds
Independent projects can be built concurrently
Building with Project References
Watch Mode Optimizations
Watch mode monitors source files and recompiles when changes are detected. TypeScript includes several optimizations to make watch mode efficient.Basic Watch Configuration
tsconfig.json
Watch Strategy Options
watchFile Strategies
watchFile Strategies
useFsEvents: Use the operating system’s file watching mechanism (recommended)useFsEventsOnParentDirectory: Watch parent directories to reduce file watchersdynamicPriorityPolling: Less frequent polling for less frequently changed filesfixedPollingInterval: Check files at fixed intervalspriorityPollingInterval: Use heuristics to check files at different intervals
watchDirectory Strategies
watchDirectory Strategies
useFsEvents: Use OS native directory watching (default on most systems)dynamicPriorityPolling: Dynamic polling based on directory change frequencyfixedPollingInterval: Fixed interval polling for all directories
Watch Mode Performance Tips
tsconfig.json
Performance Compiler Options
skipLibCheck
Skip type checking of declaration files (.d.ts) to significantly improve compilation speed:
tsconfig.json
This is one of the most impactful performance optimizations. It’s enabled by default in many starter configurations.
- Large projects with many dependencies
- When you trust the type definitions in
node_modules - To reduce initial compilation time
- May miss type errors in third-party declarations
- Errors in
.d.tsfiles won’t be reported
assumeChangesOnlyAffectDirectDependencies
In watch and incremental mode, assume changes only affect files that directly import the changed file:tsconfig.json
disableSourceOfProjectReferenceRedirect
When referencing composite projects, use declaration files instead of source files:tsconfig.json
- Working in large monorepos
- Referenced projects are stable
- You don’t need to navigate to source in referenced projects
Other Performance-Related Options
tsconfig.json
Measuring Performance
TypeScript provides built-in tools to measure compilation performance.Using —diagnostics
Using —extendedDiagnostics
- Time spent in each compilation phase
- Memory usage per phase
- File I/O statistics
- Type checking time per file
Performance Trace
Generate a detailed performance trace:- Chrome DevTools Performance tab
- analyze-trace
Best Practices
Common Performance Issues
Slow initial compilation
Slow initial compilation
- Enable
skipLibCheck - Use
typesto include only needed@typespackages - Consider splitting into project references
Slow incremental builds
Slow incremental builds
- Check if
.tsbuildinfois being preserved - Verify watch mode exclusions are set correctly
- Consider
assumeChangesOnlyAffectDirectDependencies
High memory usage
High memory usage
- Split project using project references
- Enable
isolatedModulesif using a bundler - Check for circular dependencies
Slow IDE/editor experience
Slow IDE/editor experience
- Use project references to scope type checking
- Enable
disableSourceOfProjectReferenceRedirect - Consider workspace-level
excludes
Related Resources
Compiler Options
Complete compiler options reference
Project References
Multi-project setup and configuration