Node.js Reference

CommonJS uses require() to import and module.exports to export, and modules load synchronously. ES Modules use import/export syntax and support top-level await. In Node.js, files with .mjs extension or packages with "type": "module" in package.json use ESM. CommonJS files use .cjs or no extension with the default "type": "commonjs". You cannot mix the two directly — require() cannot import ESM, but ESM can use createRequire() to load CommonJS.

Use the fs/promises module for async file operations. Import it with const fs = require("fs/promises") or import fs from "fs/promises". Then use await fs.readFile("path", "utf-8") to read a file as a string. Use await fs.writeFile("path", content) to write (overwriting the file) or await fs.appendFile("path", content) to add to the end. Always wrap in try/catch to handle ENOENT or permission errors.

Node.js uses a single JavaScript thread with a non-blocking event loop backed by libuv, which offloads I/O operations (file reads, network requests, DNS lookups) to the OS or a thread pool. This allows thousands of concurrent connections without creating OS threads for each. CPU-intensive work blocks the event loop, so for heavy computation use worker_threads to run JavaScript in parallel worker threads, or cluster to fork multiple processes each running their own event loop.

Streams are objects that emit data in chunks rather than loading everything into memory at once. Use Readable streams for data sources (fs.createReadStream), Writable streams for data sinks (fs.createWriteStream), and Transform streams to process data as it flows (compression, encryption, parsing). Use the pipeline function from stream/promises to connect streams with proper error handling and automatic cleanup — it throws if any stream errors, unlike the older pipe() method which could leak.

Use exec() from child_process for short commands where you want the full output as a string — it buffers stdout and stderr and calls your callback when done. Use spawn() for long-running processes or when you need to stream stdout/stderr in real time — it returns a ChildProcess with .stdout and .stderr streams. Use execSync() or spawnSync() for synchronous execution that blocks the event loop, which is acceptable in CLI scripts but not in servers.

worker_threads creates additional JavaScript threads within the same process, sharing memory through SharedArrayBuffer and communicating via postMessage. Use them for CPU-intensive tasks like image processing, cryptography, or parsing large files — offloading computation without the overhead of a new process. cluster forks the entire Node.js process multiple times (one per CPU core) and uses IPC for communication. Use cluster for scaling HTTP servers to utilize all CPU cores.

EventEmitter is the base class for Node.js objects that emit named events. You subscribe with emitter.on("event", handler) for persistent listeners or emitter.once("event", handler) for one-time listeners. You remove listeners with emitter.off("event", handler) or removeAllListeners(). You trigger an event with emitter.emit("event", ...args) which synchronously calls all registered listeners in registration order. The async for-await events.on(emitter, "event") creates an async iterable for consuming events one at a time.

Access environment variables through process.env.VARIABLE_NAME. For local development, use a .env file and a library like dotenv (require("dotenv").config()) to load variables before your app code runs. In Node 20.6+, you can pass --env-file=.env on the command line without dotenv. Never hardcode secrets in source code and never commit .env files. In production, set variables through your hosting platform, Docker environment flags, or a secrets manager like AWS Secrets Manager or Vault.