Node.js Optimizer

Audit a Node.js codebase, report what is slow or fragile and why, agree a plan with the user, then fix it. Order: evidence, approval, edits. Node is single-threaded per process, so one blocking call, one unbounded promise fan-out or one missing timeout can ruin every request; those changes alter concurrency and failure behavior, so nothing is edited before approval.

Workflow

1. Scope (quick)

• Find the root (package.json). Record: Node version (engines, .nvmrc, Dockerfile), module system ("type": "module" vs CJS), TypeScript strategy (tsc build, tsx, type stripping), framework (Express/Fastify/Nest/Koa/Hono), database and queue clients, process model (single process, cluster, pm2, containers), and package manager.
• Run python <skill-dir>/scripts/audit.py <project-root> -- static scan of package.json, Docker/env files and .js/.mjs/.cjs/.ts/.tsx sources for EOL Node, blocking calls, async traps, unbounded loops, missing timeouts/pool limits, injection and secret risks, with file:line evidence. Use --json to post-process.
• Classify the pain: latency/throughput (event loop, DB, upstream), memory growth/leaks, CPU saturation, startup/deploy, or code health/safety. Ask which hurts if unclear.
• Read references/tooling.md once: what can be measured here (--cpu-prof, heap snapshots, autocannon/k6, event-loop delay).

2. Audit

The script finds cheap leads; you find the rest by reading the hot path. Read package.json, the server bootstrap (listen/plugin/shutdown), the 3-5 routes or jobs the user cares about, and the DB/HTTP client setup. Load only what applies:

Measure, never guess. Run the production start command with NODE_ENV=production and the same Node major, under a fixed load (autocannon or k6), and profile that. Dev mode, ts-node/tsx and a single curl request are not representative. Take a CPU profile before micro-optimizing and a heap snapshot before raising the memory limit.

Mark each finding Confirmed (profile/load/code evidence) or Suspected (needs measuring).

3. Report

Fill assets/report-template.md, save it as NODE_OPTIMIZATION_REPORT.md in the project root, and show the user. Five-line summary, findings table by impact/effort, then per-finding detail (evidence, why it hurts, fix, risk, behavior impact). Group near-duplicates.

4. Plan -- then stop for approval

Use plan mode: EnterPlanMode (load with ToolSearch if deferred), write the plan, present with ExitPlanMode; if unavailable show it in chat and wait for an explicit "go". Structure:

1. Quick wins -- server/client timeouts, AbortSignal.timeout, bounded body sizes, pool limits, missing await, removing sync fs/crypto from handlers, for-loop awaits to Promise.all where safe, cache headers, .env hygiene. Low risk.
2. Structural -- bound concurrency with a limiter, batch N+1 queries, stream large payloads, move CPU work to worker threads/Piscina, proper graceful shutdown, split hot routes, fix leaks in caches/listeners, replace exec with execFile. Name each behavior change.
3. Heavy -- Node 20/22 to 24/26, Express 4 to 5, Fastify 4 to 5, Nest 11 to 12, framework or ORM swap, cluster/worker architecture change, TypeScript build strategy. Separately approved. Each step: files touched, expected effect, how to verify, how to roll back.

5. Fix

Only approved items, in small groups. After each: the project's lint, tsc --noEmit (if TS), node --test/Vitest/Jest, then the production build/start. A break must trace to one change. Do not mix a Node/framework upgrade with optimization edits. If an approved change alters ownership (shared pool, global cache), request semantics or shutdown behavior, stop and ask.

6. Verify and wrap up

Re-run the same load for the same duration with the same Node binary: p50/p95/p99 latency, RPS, error rate, CPU, RSS/heap, event-loop delay, and DB pool wait. State plainly what could not be measured. End with deferred items and one suggested next step.

Principles

• Algorithm and I/O first. A missing index, an N+1, a full-table scan or a sequential await beats any micro-optimization.
• Never block the event loop. One readFileSync, execSync, sync crypto call or huge JSON.parse stalls every request in that process.
• Every await needs an exit. Outbound HTTP, DB queries and queue jobs get a timeout and an abort path; otherwise a hung dependency becomes your outage.
• Bound concurrency. Pools, outbound calls, Promise.all fan-out and worker queues all need explicit limits; the default is usually unbounded or "wait forever".
• Find the retainer before raising the limit. A heap snapshot that shows what holds the memory beats --max-old-space-size.
• Measure production behavior. Dev servers, transpilers and warm caches hide the cost; use realistic payloads and data.
• Keep correctness. Don't trade error handling, backpressure, shutdown or validation for a benchmark.
• Node versions move. Node 20 is EOL, 22/24 are Maintenance LTS and 26 is Active LTS (Nov 2026); upgrades are their own approved step. Check the docs for the version in engines/Dockerfile, not memory.