Heap growth in TypeScript Builder during incremental compilation with project references

Memory usage in composite projects

Heap growth during incremental compilation in composite projects is typically caused by the TypeScript compiler retaining SourceFile and Program objects in the Builder or language-service internal caches. While TypeScript 4.5+ improved disposal of stale nodes, deep dependency chains in watch mode can prevent the garbage collector from reclaiming memory if transitive references are not explicitly invalidated or disposed of.

Likely Cause of Heap Growth

The Builder uses a reference-counting mechanism to manage dependencies. In a composite project setup, when one project references another, the compiler relies on .tsbuildinfo files. If a transitive dependency changes frequently, the language service may keep older versions of the project graph in memory to ensure type-checking consistency during the rebuild cycle. If the dependency graph is complex, the Program object may not be de-referenced quickly enough for the heap to be cleared, leading to the observed memory growth.

Confirmed Facts

• The --incremental and --composite flags enable the use of .tsbuildinfo to track file hashes and dependencies.
• TypeScript uses project references to avoid re-compiling upstream projects that haven't changed.
• The language service maintains its own cache of the program state to provide real-time feedback in IDEs.

Steps to Mitigate Heap Growth

1. Ensure all projects in the graph have "composite": true properly set to allow the compiler to use declaration files for references.
2. Check for stale tsbuildinfo files; sometimes deleting the output directories can force a clean state that resets the reference counting logic.
3. Use the --max-old-space-size flag in Node to limit the heap, though this may impact performance if set too low.
4. Verify if any custom transformers or plugins are holding onto references to SourceFile objects, which prevents the GC from reclaiming them.

To provide a more specific recommendation, are you using any custom TypeScript plugins or specific IDE extensions (like VS Code) when observing this memory growth?