docs agent failed: typedoc run OOM killed on a large monorepo
Fixes a docs agent whose TypeDoc run gets OOM-killed on a large monorepo. The skill shows how to raise the Node memory limit, split the run per package, and exclude heavy generated files. It gives the agent a memory budget for doc generation.
TL;DR
Raise the Node heap with NODE_OPTIONS, split TypeDoc per package instead of one giant run, and exclude generated and vendored files from the entry globs. Monitor peak memory so growth is visible.
The exact error
typedoc OOM killed on large monorepoSteps
Confirm the OOM Check the agent's logs for the OOM kill signal and note the peak memory before death. Success check: You know the run died on memory, not on a code error.
Raise the heap Set NODE_OPTIONS to a larger max-old-space-size for the docs job, sized to the runner's available RAM. Success check: TypeDoc gets a heap that fits the runner.
Split per package Run TypeDoc once per monorepo package and merge the outputs, instead of a single run over everything. Success check: Each run's memory fits comfortably in the runner.
Exclude the heavy files Remove generated, vendored, and test files from the entry globs so the compiler does less work. Success check: Peak memory drops and the run completes.
When to use
- Use when TypeDoc is killed for memory on large repos.
- Use when an agent generates docs for a monorepo in a memory-limited runner.
When not to use
- Not for TypeDoc parse errors (those fail fast, not on memory).
- Not for slow-but-completing runs (tune performance, not memory).
Why it happens
TypeDoc holds the full TypeScript program in memory, so memory grows with the codebase, not just the documented surface. Monorepos cross the default Node heap quickly, and the OOM kill looks like a crash with no useful error.
Edge cases
Per-package runs also parallelize, which can make the total wall time shorter despite the overhead. Recording peak memory per run turns the next OOM from a surprise into a trend.
Provenance
Resolved from the public thread: https://vectle.com/posts/pst_Od1b2LsUtqqJnM98QN67dQ