Incremental compilation: should editing tsconfig.json invalidate the .tsbuildinfo cache in watch mode?

Short answer

With current versions of the TypeScript compiler, a change to tsconfig.json while tsc --watch is running automatically forces a full recompilation of the program. The incremental state stored in .tsbuildinfo is considered stale and is discarded. The same applies to --build --watch; the build system marks the affected project (and any dependents) as out‑of‑date and rebuilds them.

How it works

The compiler keeps the compilerOptions that were in effect when .tsbuildinfo was written. On startup or when the config file changes, the current options are compared with the stored ones. If any option differs, the incremental data is ignored and a new program graph is built from scratch. This logic is part of the core watchHost implementation.

Plain tsc --watch

• Watches tsconfig.json as a normal file.
• On edit, a full program rebuild is triggered; the previous .tsbuildinfo is not reused.
• There is no separate flag to “invalidate” the cache – the change itself does it.

tsc --build --watch

• Each project in the build has its own .tsbuildinfo.
• A config change updates the timestamp of the tsconfig.json and marks the project as dirty.
• All dirty projects (and dependents) are rebuilt; the old incremental data is discarded.

No‑Emit and outFile

• noEmitOnError simply suppresses output when errors exist; it does not affect the cache.
• When outFile is used, the entire bundle is regenerated on any change, which is expected behavior.

Force a rebuild without deleting the file

# Full rebuild in build mode
$ tsc --build --force

# Clean all incremental data
$ tsc --build --clean

These commands are the documented ways to invalidate the cache programmatically.

Practical verification

1. Run tsc --watch --extendedDiagnostics and note the files emitted.
2. Change a compiler option (e.g., target) in tsconfig.json.
3. Observe that the next compilation reports a full rebuild and all files are emitted again.
4. Check the .tsbuildinfo JSON to confirm that the stored compilerOptions differ from the current ones.

Missing detail

To tailor the recommendation more precisely, could you tell me which TypeScript version you are running (e.g., tsc --version)? Older releases pre‑3.x had a known gap where config edits were ignored in watch mode.