Why is my build taking forever as my project grows, and can I stop TypeScript from re-checking everything?

We've all been there. You start a project, and tsc is nearly instant. But then you add a dozen services, a complex set of API types, and a few hundred components. Suddenly, every time you change one line of code, you're staring at a loading spinner for five seconds. It feels like TypeScript is starting from scratch every single time.

This is where the incremental flag comes in. When you set "incremental": true in your tsconfig.json, TypeScript stops acting like it has amnesia. Instead of re-analyzing every single file in your project, it tracks which files have changed and only re-compiles the parts of the graph that are actually affected.

{
  "compilerOptions": {
    "target": "ESNext",
    "module": "CommonJS",
    "incremental": true,
    "outDir": "./dist"
  }
}
Imagine you're building a large e-commerce platform. You have a massive UserAuth module and a separate ShoppingCart module. If you're just tweaking a validation regex in the ShoppingCart, there's absolutely no reason for TypeScript to spend CPU cycles re-verifying the complex OAuth logic in UserAuth. Enabling this flag tells the compiler to "remember" the state of the unchanged modules.

What is this .tsbuildinfo file that just appeared, and should I commit it to Git?
Once you flip that switch, you'll notice a new file appearing in your project root (or your output directory) called .tsbuildinfo. This is essentially the compiler's "save game" file. It stores the timestamps and hashes of the files it processed, along with a map of how they relate to each other.
As for Git—no, don't commit it. In 99% of cases, you should add *.tsbuildinfo to your .gitignore. This file is specific to the local environment and the absolute paths of the machine that ran the build. If you commit it, you'll just end up with merge conflicts every time two developers run a build, which is a headache you don't need.
If you hate having it clutter up your root directory, you can tell TypeScript exactly where to put it using the tsbuildinfoFile option:
{
  "compilerOptions": {
    "incremental": true,
    "tsbuildinfoFile": "./.cache/tsconfig.tsbuildinfo"
  }
}

How is this different from just using "watch mode"?
It's a common point of confusion. You might think, "I already use tsc --watch, so isn't that already doing this?" Not exactly.
Watch mode keeps the TypeScript compiler running in a persistent process. It holds the project graph in memory, which is why it's fast. But the moment you kill that process, restart your IDE, or run a build in your CI/CD pipeline, that memory is wiped. Everything is gone.
The incremental flag persists that information to the disk. This means if you stop working for the day and come back tomorrow, the first build of the morning will be significantly faster because it can read the .tsbuildinfo file and realize that 95% of your code hasn't changed since yesterday. I personally find it indispensable for CI pipelines where you can cache the .tsbuildinfo file between runs to shave minutes off your deployment time.

📋 Practical Task

Configuring Incremental Builds for a Multi-Module Order System

You have been handed a legacy Order Management System with three main files: orders.ts, customers.ts, and shipping.ts. Currently, the build process is slow because it's running a full compilation every time.

Your task:

• Create a tsconfig.json file that enables incremental compilation.
• Configure the build so that the .tsbuildinfo file is stored in a specific folder named .build_cache rather than the root directory.
• Run the tsc command twice. After the first run, locate the .tsbuildinfo file in the .build_cache directory to verify it was created correctly.
• Modify a single line in shipping.ts and run tsc again, observing that the build completes faster than the initial cold start.