nodejs

Node.js

Respect the event loop. Every blocking operation is a scalability bug.

Node.js rewards async-first, stream-oriented code. If your Node.js code fights the event loop, it's wrong.

References

• Module system — [${CLAUDE_SKILL_DIR}/references/modules.md]: ESM/CJS comparison tables, file extension rules, conditional exports patterns
• Event loop — [${CLAUDE_SKILL_DIR}/references/event-loop.md]: Phase order, execution priority, blocking operations table, worker pool
• Streams — [${CLAUDE_SKILL_DIR}/references/streams.md]: Stream types table, pipeline patterns, backpressure details
• Error handling — [${CLAUDE_SKILL_DIR}/references/errors.md]: Error categories table, global handlers, centralized error handling
• Security — [${CLAUDE_SKILL_DIR}/references/security.md]: Supply chain threats table, HTTP security headers, process hardening

Module System

• Use ESM. Set "type": "module" in package.json. Use .mjs/.cjs only when mixing module systems within one package.
• Use node: prefix for all built-in imports: import fs from 'node:fs'. Prevents package name collision attacks and is unambiguous.
• Import process explicitly. import process from 'node:process'. Never rely on the process global — explicit imports make dependencies visible.
• Define "exports" in package.json for libraries. Encapsulates internals — only paths listed in "exports" are importable by consumers.
• Imports at module top. No dynamic import() for statically-known dependencies.
• Use import.meta.dirname/import.meta.filename instead of __dirname/__filename.
• Use import.meta.resolve() instead of require.resolve() in ESM.
• Always set "type" explicitly in package.json, even in CJS packages — future-proofs the package and helps tooling.
• Use conditional exports for dual CJS/ESM packages. Order: types > import > require > default. Always include "default" as fallback.
• Place "types" first in conditional exports when publishing TypeScript declarations.
• Use # imports ("imports" in package.json) for clean internal paths without ../../../. Supports conditional resolution for platform-specific implementations.
• Keep "main" alongside "exports" only for backward compatibility with old Node.js or bundlers. Never use "main" alone for new packages.
• JSON imports in ESM require with { type: 'json' } attribute.
• Use createRequire() from node:module only when you must require() in ESM (e.g., native addons).
• CJS interop: default import from CJS always works. Named imports work if CJS uses static export patterns; otherwise destructure the default.
• require() can load synchronous ESM (no top-level await). For ESM with top-level await, use dynamic import().
• Self-referencing: a package can import its own exports by name when "exports" is defined.