nodejs-expert_skill

Overview

This skill is a Node.js runtime and ecosystem expert focused on practical debugging, performance optimization, and robust async patterns. It helps diagnose event loop issues, memory leaks, module resolution problems, and HTTP server misconfigurations. Use it to harden production servers, resolve promise and stream errors, and improve resource usage.

How this skill works

The skill inspects runtime signals, package.json module settings, and common error patterns to propose targeted fixes and diagnostics. It recommends concrete CLI diagnostics (node flags, profilers, inspector) and code-level remedies (try/catch, Promise.allSettled, dynamic imports, streams). It also provides checklists for code reviews and production configuration snippets.

When to use it

• You see unhandled promise rejections or Promise.all failing fast.
• Application experiences high memory usage or ‘heap out of memory’ crashes.
• Module import/export errors occur across ESM and CommonJS boundaries.
• HTTP servers exhibit slow responses or connection errors under load.
• File I/O or many open files lead to EMFILE or permission errors.

Best practices

• Always handle promise rejections with try/catch or .catch and prefer Promise.allSettled for batch tasks.
• Avoid synchronous file and CPU-bound operations on the event loop; use async fs.promises and streams.
• Explicitly set package.json type for module resolution and use dynamic import() for ESM in CommonJS contexts.
• Monitor memory with process.memoryUsage, run node --inspect or --prof in staging, and tune --max-old-space-size when necessary.
• Implement graceful shutdown handlers for SIGINT/SIGTERM and validate critical environment variables at startup.

Example use cases

• Debugging intermittent OutOfMemory crashes by collecting a heap snapshot and adding memory monitoring hooks.
• Converting a blocking file-processing loop to a streaming pipeline to prevent event loop stalls and EMFILE errors.
• Resolving mixed ESM/CJS dependencies by updating package.json type, adding exports, or using dynamic import for specific packages.
• Hardening an HTTP server by setting timeouts, keep-alive settings, maxConnections, and handling clientError events.
• Performing a code review focused on async patterns: ensuring promises are handled, no sync I/O in async flows, and using Promise.allSettled.