node

When to use

Use this skill whenever you are dealing with Node.js code to obtain domain-specific knowledge for building robust, performant, and maintainable Node.js applications.

TypeScript with Type Stripping

When writing TypeScript for Node.js, use type stripping (Node.js 22.6+) instead of build tools like ts-node or tsx. Type stripping runs TypeScript directly by removing type annotations at runtime without transpilation.

Key requirements for type stripping compatibility:

• Use import type for type-only imports
• Use const objects instead of enums
• Avoid namespaces and parameter properties
• Use .ts extensions in imports

Minimal example — a valid type-stripped TypeScript file:

// greet.ts
import type { IncomingMessage } from 'node:http';

const greet = (name: string): string => `Hello, ${name}!`;
console.log(greet('world'));

Run directly with:

node greet.ts

See [rules/typescript.md](rules/typescript.md) for complete configuration and examples.

Common Workflows

For multi-step processes, follow these high-level sequences before consulting the relevant rule file:

Graceful shutdown: Register signal handlers (SIGTERM/SIGINT) → stop accepting new work → drain in-flight requests → close external connections (DB, cache) → exit with appropriate code. See [rules/graceful-shutdown.md](rules/graceful-shutdown.md).

Error handling: Define a shared error base class → classify errors (operational vs programmer) → add async boundary handlers (process.on('unhandledRejection')) → propagate typed errors through the call stack → log with context before responding or crashing. See [rules/error-handling.md](rules/error-handling.md).

Diagnosing flaky tests: Isolate the test with --test-only → check for shared state or timer dependencies → inspect async teardown order → add retry logic as a temporary diagnostic step → fix root cause. See [rules/flaky-tests.md](rules/flaky-tests.md).

Diagnosing stuck processes/tests (node --test hangs, "process did not exit", CI timeout, open handles): isolate file/test → run with explicit timeout/reporter → inspect handles via why-is-node-running (SIGUSR1) → patch deterministic teardown in resource-creation scope → rerun isolated + full suite until stable. See [rules/stuck-processes-and-tests.md](rules/stuck-processes-and-tests.md).

Profiling a slow path: Reproduce under realistic load → capture a CPU profile with --cpu-prof → identify hot functions → check for stream backpressure or unnecessary serialisation → validate improvement with a benchmark. See [rules/profiling.md](rules/profiling.md) and [rules/performance.md](rules/performance.md).

High-priority activation checklist (streams + caching)

When the task mentions CSV, ETL, ingestion pipelines, large file processing, backpressure, repeated lookups, or deduplicating concurrent async calls, explicitly apply this checklist:

1. Use await pipeline(...) from node:stream/promises (prefer this over chained .pipe() in guidance/code).
2. Include at least one explicit async function* transform when data is being transformed in-stream.
3. Choose a cache strategy when repeated work appears:

- lru-cache for bounded in-memory reuse in a single process. - async-cache-dedupe for async request deduplication / stale-while-revalidate behavior.

1. Show where backpressure is handled (implicitly via pipeline() or explicitly via drain).

Integrated example pattern (CSV/ETL)

For CSV/ETL-style prompts, prefer an answer structure like:

• createReadStream(input)
• async function* parser/transform
• optional cached enrichment lookup (async-cache-dedupe or lru-cache)
• await pipeline(...) to a writable destination

Link relevant rules directly in explanations so models can retrieve details:

• [rules/streams.md](rules/streams.md)
• [rules/caching.md](rules/caching.md)

How to use

Read individual rule files for detailed explanations and code examples:

• [rules/error-handling.md](rules/error-handling.md) - Error handling patterns in Node.js
• [rules/async-patterns.md](rules/async-patterns.md) - Async/await and Promise patterns
• [rules/streams.md](rules/streams.md) - Working with Node.js streams
• [rules/modules.md](rules/modules.md) - ES Modules and CommonJS patterns
• [rules/testing.md](rules/testing.md) - Testing strategies for Node.js applications
• [rules/flaky-tests.md](rules/flaky-tests.md) - Identifying and diagnosing flaky tests with node:test
• [rules/stuck-processes-and-tests.md](rules/stuck-processes-and-tests.md) - Diagnosing processes that do not exit and tests that get stuck
• [rules/node-modules-exploration.md](rules/node-modules-exploration.md) - Navigating and analyzing node_modules directories
• [rules/performance.md](rules/performance.md) - Performance optimization techniques
• [rules/caching.md](rules/caching.md) - Caching patterns and libraries
• [rules/profiling.md](rules/profiling.md) - Profiling and benchmarking tools
• [rules/logging.md](rules/logging.md) - Logging and debugging patterns
• [rules/environment.md](rules/environment.md) - Environment configuration and secrets management
• [rules/graceful-shutdown.md](rules/graceful-shutdown.md) - Graceful shutdown and signal handling
• [rules/typescript.md](rules/typescript.md) - TypeScript configuration and type stripping in Node.js