Nodejs

Node.js runtime best practices.

by claude-dev-suite · MIT

The skill

Node.js runtime best practices. Covers event loop, async patterns, streams, worker threads, memory management, and production optimization. USE WHEN: user mentions "node.js", "event loop", "streams", "worker threads", asks about "process.nextTick", "memory leaks", "cluster mode", "async patterns" DO NOT USE FOR: reviewing existing Node code - use `review/nodejs`, which covers event loop, stream and process defects that have no diagnostic DO NOT USE FOR: Express/NestJS frameworks - use framework-specific skills DO NOT USE FOR: Language syntax - use `javascript` or `typescript` skills DO NOT USE FOR: Package management - use npm/pnpm/yarn skills

Node.js Best Practices

Full Reference: See advanced.md for worker pool pattern, memory management, cluster mode, graceful shutdown, and performance flags.

Deep Knowledge: Use mcp__documentation__fetch_docs with technology: nodejs for comprehensive documentation.

Event Loop

Phases

   ┌───────────────────────────┐
┌─>│           timers          │  ← setTimeout, setInterval
│  └─────────────┬─────────────┘
│  ┌─────────────┴─────────────┐
│  │     pending callbacks     │  ← I/O callbacks
│  └─────────────┬─────────────┘
│  ┌─────────────┴─────────────┐
│  │           poll            │  ← incoming I/O
│  └─────────────┬─────────────┘
│  ┌─────────────┴─────────────┐
│  │           check           │  ← setImmediate
│  └─────────────┬─────────────┘
│  ┌─────────────┴─────────────┐
└──┤      close callbacks      │
   └───────────────────────────┘

Priority Order

sync code > process.nextTick > Promises (microtasks) > timers > setImmediate

Don't Block the Event Loop

// BAD - blocks event loop
function hashSync(data: string): string {
  return crypto.pbkdf2Sync(data, 'salt', 100000, 64, 'sha512').toString('hex');
}

// GOOD - use async version
async function hashAsync(data: string): Promise<string> {
  return new Promise((resolve, reject) => {
    crypto.pbkdf2(data, 'salt', 100000, 64, 'sha512', (err, key) => {
      if (err) reject(err);
      else resolve(key.toString('hex'));
    });
  });
}

Async Patterns

// GOOD - parallel execution
const [users, posts] = await Promise.all([
  fetchUsers(),
  fetchPosts()
]);

// BAD - sequential when parallel is possible
const users = await fetchUsers();
const posts = await fetchPosts(); // waits unnecessarily

// Handle unhandled rejections
process.on('unhandledRejection', (reason, promise) => {
  console.error('Unhandled Rejection:', reason);
});

Streams (Pipeline)

import { pipeline } from 'stream/promises';
import { createReadStream, createWriteStream } from 'fs';
import { createGzip } from 'zlib';

// GOOD - handles errors and cleanup
await pipeline(
  createReadStream('input.txt'),
  createGzip(),
  createWriteStream('output.txt.gz')
);

When NOT to Use This Skill

Scenario	Use Instead
Express.js framework	`backend-express` skill
NestJS framework	`backend-nestjs` skill
JavaScript/TypeScript syntax	`javascript` or `typescript` skills
Testing	`testing-vitest` or `testing-jest` skills
Database operations	Database-specific skills

Anti-Patterns

Anti-Pattern	Why It's Bad	Correct Approach
Blocking the event loop	Freezes all requests	Use async APIs or workers
Not handling rejections	Silent failures	Use process.on('unhandledRejection')
Synchronous file I/O	Blocks event loop	Use async fs methods
Unbounded caches	Memory leaks	Use LRU cache with limits
Not removing event listeners	Memory leaks	Use .off() or .removeListener()
Nested callbacks	Callback hell	Use async/await
Large sync JSON.parse	Blocks event loop	Stream parsing or workers
No concurrency limits	Resource exhaustion	Use p-limit or semaphores

Quick Troubleshooting

Issue	Cause	Solution
High event loop lag	Blocking operations	Profile with --inspect, use workers
Memory leak	Unbounded cache/listeners	Use heap snapshots, fix leaks
"EADDRINUSE"	Port already in use	Kill process or use different port
"EMFILE: too many open files"	File descriptor leak	Close files, increase ulimit
Process crashes on error	Uncaught exception	Add error handlers
Slow startup	Too many sync operations	Make initialization async
High CPU usage	Infinite loop or blocking	Profile with --cpu-prof
"MaxListenersExceededWarning"	Too many listeners	Remove old listeners

Checklist

Development

[ ] Use async/await over callbacks
[ ] Handle all Promise rejections
[ ] Use streams for large data
[ ] Limit concurrent operations
[ ] Remove event listeners when done

Production

[ ] Use cluster mode or PM2
[ ] Implement graceful shutdown
[ ] Set appropriate heap size
[ ] Monitor memory usage
[ ] Use connection pooling
[ ] Enable keep-alive for HTTP

Metrics

Metric	Target
Event loop lag	< 100ms
Heap usage	< 70% of limit
Active handles	Stable
GC pause	< 100ms

Reference Documentation

Use this skill

Connect your agent to the Skill Store MCP server and ask for it by ref: claude-dev-suite/nodejs-68718477664.

Download SKILL.md · Markdown version

Details

Publisher: claude-dev-suite
Category: Software Development › Languages & frameworks
License: MIT
Updated: 2026-10-19

References

Related skills

Nodejs Development Comprehensive Node.js development skill covering event loop, async patterns, streams, file system…
Nodejs Review Reviewing Node.js runtime code - what to flag beyond the language, and what the toolchain already…
Nodejs Best Practices Node.js development principles and decision-making.
Nodejs Expert Node.js runtime and ecosystem expert with deep knowledge of async patterns, module systems, perfo…
Nodejs Profiling Node.js performance profiling with V8 CPU profiler, heap analysis, and perf_hooks.