node-optimizer

---
name: node-optimizer
description: Audit and optimize Node.js services, APIs, CLIs and workers (Node 22-26, Express 5, Fastify 5, NestJS 12, Koa 3, Hono 4; JavaScript or TypeScript) for event-loop blocking, CPU and memory growth, leaks, async/concurrency bugs, HTTP and database latency, startup time, container limits and safety, with real before/after measurement. Always produces a written findings report and a fix plan for approval before touching code. Use this whenever the user mentions a slow Node.js API, p99 latency, event loop lag, high CPU or RSS, "JavaScript heap out of memory", a memory leak, worker threads or cluster, connection-pool exhaustion, N+1 queries, stream backpressure, slow JSON serialization, `--cpu-prof` or a heap snapshot, autocannon/clinic/0x, Node 20 EOL, type stripping, Express 4 to 5 or Fastify 4 to 5 upgrades, or "optimize my Node.js app" -- even if they never say "audit" or "optimize".
---

# 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:

| Area                                                            | Reference                        |
| --------------------------------------------------------------- | -------------------------------- |
| Node version, ESM/TS, startup, flags, containers, build         | `references/runtime-build.md`    |
| Heap growth, leaks, GC, Buffers, memory limits                  | `references/memory-gc.md`        |
| Event loop, promises, concurrency limits, workers, shutdown     | `references/async-concurrency.md` |
| HTTP servers/clients, timeouts, pools, N+1, caching, streaming  | `references/web-data.md`         |
| Injection, secrets, permissions, supply chain, types/tests      | `references/safety-quality.md`   |
| CPU/heap profiles, load tests, honest measurement               | `references/tooling.md`          |

**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.

• LICENSE 1 KB
• README.md 1 KB
• SKILL.md 7 KB
• assets/report-template.md 2 KB
• references/async-concurrency.md 5 KB
• references/memory-gc.md 4 KB
• references/runtime-build.md 5 KB
• references/safety-quality.md 5 KB
• references/tooling.md 4 KB
• references/web-data.md 6 KB
• scripts/audit.py 19 KB