Learn TypeScript - Compilation Performance and Incremental Builds

#Introduction

As a project grows, the tsc that used to be instant can turn into annoying seconds. Every compilation call restarts from zero, including files that didn't change at all. Episode 21 covers how to cut that waste.

The main principle is simple: don't repeat unnecessary work. TypeScript provides mechanisms to store intermediate results, mark changed files, and only compile the parts that actually changed. The build becomes incremental.

Episode 21 covers incremental and the tsbuildinfo file, project references for large projects, speed-up options like skipLibCheck, and strategies for using all of these in watch mode and CI.

#incremental and tsbuildinfo

#Storing Intermediate Results

The incremental option makes tsc store build information:

{
    "compilerOptions": {
        "incremental": true,
        "tsBuildInfoFile": "node_modules/.cache/tsbuildinfo",
        "outDir": "dist"
    }
}

With incremental: true, tsc writes a .tsbuildinfo file recording file versions and already-produced output. On the next build, unchanged files are not recompiled. As a result, the second build and those after it are much faster, especially in projects with many files.

#Using It in the CLI

The same behavior can be triggered with a command flag:

npx tsc --incremental --outDir dist

The --incremental flag makes the second build only process changes. It's important to understand that the speedup only shows when the tsbuildinfo file is kept. In CI, the cache must be restored between builds for the benefit to persist.

#Project References

Very large projects can be split into several TypeScript projects that reference each other:

{
    "files": [],
    "references": [
        { "path": "./packages/core" },
        { "path": "./packages/api" }
    ]
}

The root file above only holds a list of references, no code of its own. Each package becomes a project with its own tsconfig, for example with the composite: true option. Running tsc --build at the root only compiles the packages that changed, not the whole repository.

npx tsc --build

The command npx tsc --build processes references with dependency awareness: a change in core only rebuilds core and the packages that use it. Project references are the scaling answer for monorepos with many TypeScript packages.

#skipLibCheck and Speed-Up Options

Much compile time is spent checking library declaration files. This option reduces it:

{
    "compilerOptions": {
        "skipLibCheck": true,
        "skipDefaultLibCheck": true,
        "noEmit": true
    }
}

The skipLibCheck: true option skips type checking on .d.ts files, since those files don't change and are usually already correct. noEmit: true removes output writing, speeding up type checks in CI that only need validation. Both give large speedups with little risk.

#Watch Mode and CI Strategies

#Watch Mode for Development

During development, use watch mode:

npx tsc --watch --incremental

tsc --watch monitors files and recompiles only what changed. Combined with --incremental, every file save triggers a small compilation, not a full one. Editors and runners like tsx use the same pattern for fast feedback.

#Strategies in CI

In CI, caching determines speed:

The same pipeline compiles from scratch when the cache isn't available, and uses the cache when it is. That way, developers and CI alike enjoy fast builds as the project grows.

#Closing

Episode 21 keeps compilation feeling light in large projects: incremental with tsbuildinfo, project references for monorepos, skipLibCheck for speed, and watch mode and CI cache strategies that take advantage of all of them.

Key takeaways:

• incremental: true stores tsbuildinfo and skips unchanged files.
• The tsbuildinfo file must be kept for builds to stay fast.
• Project references only compile the packages that changed.
• tsc --build processes dependencies between projects correctly.
• skipLibCheck speeds up builds by skipping declaration files.
• CI caching makes incremental builds work in the pipeline.

In the next episode 22 we'll discuss strict mode, noImplicitAny, and type quality — tightening every setting for maximum type guarantees.