Node.js — User Guide

Node.js is a JavaScript runtime built on Chrome's V8 engine that executes JavaScript outside the browser, enabling server-side applications, command-line tools, and general-purpose scripting. It uses an event-driven, non-blocking I/O model that makes it lightweight and efficient for data-intensive real-time applications. With over 12,000 source files and a comprehensive standard library, Node.js provides everything needed to build production systems without third-party dependencies for core functionality.

1. Quick Start

1.1 What You Get with Node.js

• Full-featured JavaScript runtime — run JavaScript anywhere, not just in browsers
• Comprehensive standard library — HTTP/HTTPS servers, file system, crypto, streams, DNS, and 30+ built-in modules
• Two module systems — CommonJS (require) and ES Modules (import) with full interoperability
• Built-in test runner — node:test module with assertions, mocking, coverage, and reporters
• TypeScript support — native type stripping via --experimental-strip-types (powered by Amaro)
• Permission model — fine-grained control over file system, child process, and worker access
• Watch mode — automatic restart on file changes with --watch
• Modern web APIs — fetch(), WebSocket, Blob, FormData, structuredClone, and more built in

Tip

If you already have Node.js installed, jump straight to the HTTP server example below. For version management across projects, install nvm or fnm first — it saves significant headaches down the road.

1.2 Prerequisites

1.3 Install in One Command

macOS / Linux:

curl -fsSL https://fnm.vercel.app/install | bash && fnm install --lts

Windows (PowerShell):

winget install Schniz.fnm
fnm install --lts

1.4 Hello World

Create hello.js:

console.log("Hello from Node.js", process.version);

Run it:

node hello.js

Expected output:

Hello from Node.js v22.14.0

1.5 Hello World HTTP Server

Create server.js:

const http = require("node:http");

const server = http.createServer((req, res) => {
  res.writeHead(200, { "Content-Type": "text/plain" });
  res.end("Hello, World!\n");
});

server.listen(3000, "127.0.0.1", () => {
  console.log("Server running at http://127.0.0.1:3000/");
});

Run it:

node server.js

Expected output:

Server running at http://127.0.0.1:3000/

Test it:

curl http://127.0.0.1:3000/

Hello, World!

Tip

During development, use node --watch server.js to automatically restart the server when you edit the file. No external tools like nodemon required.

2. Installation

2.1 System Requirements

2.2 Platform-Specific Installation

macOS

Homebrew (recommended):

brew install node

Official installer:

Download the .pkg from nodejs.org and run it.

Verify:

node --version
npm --version

v22.14.0
10.9.2

Linux

Ubuntu / Debian:

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

RHEL / Fedora / CentOS:

curl -fsSL https://rpm.nodesource.com/setup_22.x | sudo bash -
sudo dnf install -y nodejs

Alpine:

apk add nodejs npm

Important

Distribution-provided Node.js packages are often severely outdated. Use NodeSource, fnm, or nvm to get current versions. Running an unsupported Node.js version means no security patches.

Windows

winget (Windows 10+):

winget install OpenJS.NodeJS.LTS

Chocolatey:

choco install nodejs-lts

Official installer:

Download the .msi from nodejs.org. The installer adds node and npm to your PATH automatically.

Warning

On Windows, building native addons (packages with C++ bindings) requires the "Desktop development with C++" workload from Visual Studio Build Tools. Install it with: npm install --global windows-build-tools or download Visual Studio Build Tools directly.

Docker

docker run -it --rm node:22-alpine node -e "console.log('Node', process.version)"

Dockerfile for production:

FROM node:22-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .

FROM node:22-alpine
WORKDIR /app
COPY --from=builder /app .
USER node
EXPOSE 3000
CMD ["node", "server.js"]

2.3 Version Managers

Version managers let you switch Node.js versions per project. Two popular choices:

fnm (Fast Node Manager)

# Install fnm
curl -fsSL https://fnm.vercel.app/install | bash

# Install a specific version
fnm install 22
fnm install 20

# Use a version
fnm use 22

# Set default
fnm default 22

# Auto-switch per directory (.node-version or .nvmrc)
fnm env --use-on-cd

nvm (Node Version Manager)

# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

# Restart terminal, then:
nvm install --lts
nvm install 22
nvm install 20

# Switch versions
nvm use 22

# Set default
nvm alias default 22

# Use .nvmrc file
echo "22" > .nvmrc
nvm use

Create a .node-version file in your project root:

echo "22" > .node-version

Both fnm and nvm will detect this file and switch automatically (with shell integration enabled).

2.4 Building from Source

Building from source is necessary when targeting unsupported platforms, enabling custom build flags, or debugging Node.js internals.

Prerequisites:

Build steps:

git clone https://github.com/nodejs/node.git
cd node
git checkout v22.14.0

# Configure (see below for flags)
./configure

# Build (use -j for parallel compilation)
make -j$(nproc)

# Test (optional)
make test

# Install
sudo make install

Common configure.py flags:

Note

The full list of configure flags is available via ./configure --help. For architecture details, security hardening options, and advanced build configurations, see the Admin Guide.

2.5 Post-Install Verification

Run these commands to confirm everything works:

# Check versions
node --version
npm --version

# Test JavaScript execution
node -e "console.log('Node.js works!')"

# Test module loading
node -e "const os = require('node:os'); console.log(os.platform(), os.arch())"

# Test npm
npm --version
npm init -y

Expected output pattern:

v22.14.0
10.9.2
Node.js works!
linux x64

2.6 Installation Troubleshooting

node: command not found

Cause: Node.js is not in your system PATH.

Solution:

1. If installed via nvm/fnm: run nvm use default or fnm use default
2. If installed from package: check /usr/local/bin/node exists
3. Add to PATH manually: export PATH="/usr/local/bin:$PATH" in your shell profile

npm ERR! EACCES permission denied

Cause: npm is trying to write to a global directory owned by root.

Solution:

1. Use a version manager (nvm/fnm) — this avoids the problem entirely
2. Or configure npm to use your home directory: npm config set prefix '~/.npm-global' and add ~/.npm-global/bin to PATH

gyp ERR! stack Error: Could not find any Python installation

Cause: Native addon compilation requires Python.

Solution:

# macOS
xcode-select --install

# Ubuntu/Debian
sudo apt install python3 build-essential

# Windows
npm install --global windows-build-tools

Error: Cannot find module 'node:...'

Cause: You are running a Node.js version too old for the node: prefix (added in v16.0.0).

Solution: Upgrade to Node.js 16+ or remove the node: prefix from imports.

N-API version mismatch

Cause: Native addon was compiled for a different Node.js version.

Solution:

npm rebuild
# or
rm -rf node_modules && npm install

Error: ENOSPC: System limit for number of file watchers reached

Cause: Linux inotify watcher limit is too low (common with large projects or --watch mode).

Solution:

echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

GLIBC_2.28 not found

Cause: Your Linux distribution has an older glibc than Node.js requires.

Solution: Upgrade your distribution or use the Alpine/musl build, or build Node.js from source.

ERR_OSSL_EVP_UNSUPPORTED

Cause: OpenSSL 3.0 dropped support for some legacy algorithms. Common when upgrading to Node.js 17+.

Solution:

# Temporary workaround (not recommended for production)
node --openssl-legacy-provider your-script.js

# Permanent fix: update the affected package
npm update

Digital envelope routines::unsupported

Cause: Same root cause as above — OpenSSL 3.0 incompatibility with older packages using MD4/MD5 for hashing.

Solution:

export NODE_OPTIONS=--openssl-legacy-provider

MODULE_NOT_FOUND after nvm use

Cause: Global packages were installed under a different Node.js version.

Solution:

nvm install <version> --reinstall-packages-from=<old-version>

Multiple Node.js installations conflicting

Cause: System package manager and version manager both installed Node.js.

Solution:

# Find all node binaries
which -a node

# Remove system version
sudo apt remove nodejs  # Debian/Ubuntu
brew uninstall node     # macOS

# Use only the version manager
nvm use default

3. Configuration

3.1 Environment Variables

Node.js behavior is controlled through environment variables. These are the most commonly used:

Warning

Setting NODE_TLS_REJECT_UNAUTHORIZED=0 disables TLS certificate verification globally. Never do this in production — it makes your application vulnerable to man-in-the-middle attacks. Use NODE_EXTRA_CA_CERTS to add custom CA certificates instead.

Setting environment variables:

# Inline for one command
NODE_ENV=production node server.js

# Export for the session
export NODE_ENV=production
export UV_THREADPOOL_SIZE=8
node server.js

# In package.json scripts
{
  "scripts": {
    "start": "NODE_ENV=production node server.js",
    "dev": "NODE_ENV=development node --watch server.js"
  }
}

3.2 The .env File Support

Node.js has built-in .env file loading via the --env-file flag:

node --env-file=.env server.js

.env file format:

# Comments start with #
NODE_ENV=production
DATABASE_URL=postgres://localhost:5432/mydb
API_KEY=sk-abc123
PORT=3000

# Multi-line values use quotes
PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----
MIIEowIBAAKCAQEA...
-----END RSA PRIVATE KEY-----"

You can load multiple .env files (later files override earlier):

node --env-file=.env --env-file=.env.local server.js

Note

The --env-file flag loads variables into process.env before your code runs. It does not override existing environment variables — system-set variables take precedence.

3.3 Package.json Configuration

The package.json file controls project metadata, dependencies, and module resolution:

{
  "name": "my-app",
  "version": "1.0.0",
  "type": "module",
  "main": "./src/index.js",
  "exports": {
    ".": "./src/index.js",
    "./utils": "./src/utils.js"
  },
  "engines": {
    "node": ">=20.0.0"
  },
  "scripts": {
    "start": "node src/index.js",
    "dev": "node --watch src/index.js",
    "test": "node --test"
  }
}

Key fields:

3.4 TypeScript Configuration

Node.js supports TypeScript via --experimental-strip-types, which removes type annotations at load time (powered by Amaro/SWC):

node --experimental-strip-types app.ts

For projects using TypeScript, create a tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "esModuleInterop": true,
    "outDir": "./dist",
    "rootDir": "./src",
    "declaration": true,
    "sourceMap": true
  },
  "include": ["src/**/*"]
}

Important

The --experimental-strip-types flag only removes type annotations — it does not support TypeScript features that require code transformation, such as enum, namespace, or legacy decorators. Use tsc or a bundler for those features.

3.5 NODE_OPTIONS

NODE_OPTIONS lets you set CLI flags via environment variable, useful for production deployments where you cannot modify the node command:

# Increase heap memory
export NODE_OPTIONS="--max-old-space-size=4096"

# Enable source maps
export NODE_OPTIONS="--enable-source-maps"

# Combine multiple flags
export NODE_OPTIONS="--max-old-space-size=4096 --enable-source-maps"

Not all flags are allowed in NODE_OPTIONS for security reasons. Flags like --eval, --print, and --input-type are disallowed.

For complete configuration reference, runtime tuning, V8 flags, and memory management, see the Admin Guide.

4. Core Usage

4.1 Running JavaScript

Basic Execution

# Run a file
node app.js

# Evaluate code inline
node --eval "console.log(2 + 2)"
# Output: 4

# Evaluate and print the result (no console.log needed)
node --print "Math.PI * 2"
# Output: 6.283185307179586

# Read from stdin
echo 'console.log("from stdin")' | node
# Output: from stdin

The REPL

Start an interactive Read-Eval-Print Loop:

node

Welcome to Node.js v22.14.0.
Type ".help" for more information.
> 2 + 2
4
> const fs = require('node:fs')
undefined
> fs.readdirSync('.').length
12
> .exit

REPL special commands:

Tab completion works for globals, modules, and object properties. Press Tab twice to see all completions.

Watch Mode

Automatically restart when files change:

# Watch the entry file and its dependencies
node --watch app.js

# Watch specific paths
node --watch-path=./src --watch-path=./config app.js

# Watch mode with inspect
node --watch --inspect app.js

[watch] restarting due to changes...
[watch] restarted successfully

Tip

Watch mode is built into Node.js since v18.11. It monitors the entry file and all transitively imported/required files. Use --watch-path to include configuration files or directories not directly imported.

4.2 Module Systems

Node.js supports two module systems: CommonJS (the original) and ES Modules (the standard).

CommonJS (CJS)

// math.js — exporting
function add(a, b) {
  return a + b;
}

function multiply(a, b) {
  return a * b;
}

module.exports = { add, multiply };

// app.js — importing
const { add, multiply } = require("./math.js");

console.log(add(2, 3));       // 5
console.log(multiply(4, 5));  // 20

CommonJS characteristics:

• require() is synchronous
• module.exports defines what a module exposes
• Files are wrapped in a function: (function(exports, require, module, __filename, __dirname) { ... })
• Circular dependencies are handled (partial exports returned)

ES Modules (ESM)

// math.mjs — exporting
export function add(a, b) {
  return a + b;
}

export function multiply(a, b) {
  return a * b;
}

export default { add, multiply };

// app.mjs — importing
import { add, multiply } from "./math.mjs";
import math from "./math.mjs";

console.log(add(2, 3));          // 5
console.log(math.multiply(4, 5)); // 20

How Node.js decides which system to use:

Important

ES Modules are asynchronous and have different scoping rules. require(), __filename, __dirname, module, and exports are NOT available in ES Modules. Use import.meta.url and import.meta.dirname (v21.2+) instead.

ES Module equivalents for CommonJS globals:

// __filename equivalent
import { fileURLToPath } from "node:url";
const __filename = fileURLToPath(import.meta.url);

// __dirname equivalent
import { dirname } from "node:path";
const __dirname = dirname(fileURLToPath(import.meta.url));

// Or in Node.js 21.2+:
const __dirname = import.meta.dirname;
const __filename = import.meta.filename;

// require() equivalent for JSON
import { readFileSync } from "node:fs";
const pkg = JSON.parse(readFileSync("./package.json", "utf-8"));

// Or with import attributes (experimental)
import pkg from "./package.json" with { type: "json" };

Importing CommonJS from ESM and Vice Versa

// ESM can import CommonJS
import cjsModule from "./legacy.cjs";

// CommonJS can import ESM (async)
async function main() {
  const esmModule = await import("./modern.mjs");
}
main();

4.3 File System Operations

The node:fs module provides file system access. It offers three API styles: callback, synchronous, and promise-based.

Reading Files

import { readFile, readFileSync } from "node:fs";
import { readFile as readFileAsync } from "node:fs/promises";

// Callback style
readFile("data.txt", "utf-8", (err, data) => {
  if (err) throw err;
  console.log(data);
});

// Synchronous (blocks the event loop)
const content = readFileSync("data.txt", "utf-8");
console.log(content);

// Promise style (recommended)
const data = await readFileAsync("data.txt", "utf-8");
console.log(data);

Writing Files

import { writeFile, appendFile } from "node:fs/promises";

// Write (creates or overwrites)
await writeFile("output.txt", "Hello, World!\n", "utf-8");

// Append
await appendFile("log.txt", `${new Date().toISOString()} Event occurred\n`);

// Write with options
await writeFile("config.json", JSON.stringify(config, null, 2), {
  encoding: "utf-8",
  mode: 0o644,
  flag: "wx", // fail if file exists
});

Directory Operations

import { readdir, mkdir, rm, stat } from "node:fs/promises";

// List directory contents
const files = await readdir("./src");
console.log(files); // ['index.js', 'utils.js', 'lib']

// List with file types
const entries = await readdir("./src", { withFileTypes: true });
for (const entry of entries) {
  console.log(`${entry.name} - ${entry.isDirectory() ? "dir" : "file"}`);
}

// Recursive directory listing
const allFiles = await readdir("./src", { recursive: true });

// Create directory (recursive)
await mkdir("./data/logs/2026", { recursive: true });

// Remove directory (recursive)
await rm("./temp", { recursive: true, force: true });

// File/directory info
const info = await stat("./package.json");
console.log(`Size: ${info.size} bytes`);
console.log(`Modified: ${info.mtime}`);
console.log(`Is file: ${info.isFile()}`);

Watching for File Changes

import { watch } from "node:fs/promises";

const watcher = watch("./src", { recursive: true });

for await (const event of watcher) {
  console.log(`${event.eventType}: ${event.filename}`);
}

Note

The fs.watch() API is platform-dependent. On Linux, it uses inotify; on macOS, FSEvents; on Windows, ReadDirectoryChangesW. Behavior for recursive watching varies — it is fully supported on macOS and Windows, and on Linux since Node.js 19.

File Operations

import { copyFile, rename, access, constants } from "node:fs/promises";

// Copy a file
await copyFile("source.txt", "dest.txt");

// Rename / move
await rename("old.txt", "new.txt");

// Check if file exists and is readable
try {
  await access("config.json", constants.R_OK);
  console.log("File is readable");
} catch {
  console.log("File is not readable or does not exist");
}

4.4 HTTP/HTTPS Servers

Basic HTTP Server

import http from "node:http";

const server = http.createServer((req, res) => {
  const { method, url, headers } = req;

  if (method === "GET" && url === "/") {
    res.writeHead(200, { "Content-Type": "text/html" });
    res.end("<h1>Welcome</h1>");
    return;
  }

  if (method === "GET" && url === "/api/health") {
    res.writeHead(200, { "Content-Type": "application/json" });
    res.end(JSON.stringify({ status: "ok", uptime: process.uptime() }));
    return;
  }

  if (method === "POST" && url === "/api/data") {
    let body = "";
    req.on("data", (chunk) => (body += chunk));
    req.on("end", () => {
      const data = JSON.parse(body);
      res.writeHead(201, { "Content-Type": "application/json" });
      res.end(JSON.stringify({ received: data }));
    });
    return;
  }

  res.writeHead(404, { "Content-Type": "text/plain" });
  res.end("Not Found");
});

server.listen(3000, () => {
  console.log("Listening on http://localhost:3000");
});

HTTPS Server

import https from "node:https";
import { readFileSync } from "node:fs";

const options = {
  key: readFileSync("./certs/server.key"),
  cert: readFileSync("./certs/server.cert"),
};

const server = https.createServer(options, (req, res) => {
  res.writeHead(200);
  res.end("Secure connection established\n");
});

server.listen(443, () => {
  console.log("HTTPS server running on port 443");
});

Making HTTP Requests

Using the global fetch (recommended):

// GET request
const response = await fetch("https://api.example.com/data");
const data = await response.json();
console.log(data);

// POST request
const result = await fetch("https://api.example.com/submit", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ name: "Node.js", version: 22 }),
});
console.log(result.status); // 201

Using http.get (lower level):

import http from "node:http";

http.get("http://example.com", (res) => {
  let data = "";
  res.on("data", (chunk) => (data += chunk));
  res.on("end", () => console.log(data));
});

4.5 Streams

Streams are fundamental to Node.js — they let you process data piece by piece without loading it all into memory.

Stream Types

Reading a Large File with Streams

import { createReadStream } from "node:fs";

const stream = createReadStream("large-file.log", { encoding: "utf-8" });

let lineCount = 0;
let remainder = "";

stream.on("data", (chunk) => {
  const lines = (remainder + chunk).split("\n");
  remainder = lines.pop(); // last partial line
  lineCount += lines.length;
});

stream.on("end", () => {
  if (remainder) lineCount++;
  console.log(`Total lines: ${lineCount}`);
});

Pipeline (Recommended for Connecting Streams)

import { pipeline } from "node:stream/promises";
import { createReadStream, createWriteStream } from "node:fs";
import { createGzip } from "node:zlib";

// Compress a file
await pipeline(
  createReadStream("input.txt"),
  createGzip(),
  createWriteStream("input.txt.gz")
);

console.log("Compression complete");

Caution

Never pipe streams manually with .pipe() in production without error handling. Use stream.pipeline() instead — it properly handles errors and cleans up resources (destroys streams) when any stream in the chain fails or the destination closes prematurely.

Custom Transform Stream

import { Transform } from "node:stream";

const upperCase = new Transform({
  transform(chunk, encoding, callback) {
    callback(null, chunk.toString().toUpperCase());
  },
});

process.stdin.pipe(upperCase).pipe(process.stdout);

4.6 Child Processes

The node:child_process module lets you run shell commands, other programs, and Node.js scripts as separate processes.

import { exec, execFile, spawn, fork } from "node:child_process";
import { execSync } from "node:child_process";

exec — Run a Shell Command

import { exec } from "node:child_process";

exec("ls -la", (error, stdout, stderr) => {
  if (error) {
    console.error(`Error: ${error.message}`);
    return;
  }
  console.log(stdout);
});

// Promise version
import { exec as execCb } from "node:child_process";
import { promisify } from "node:util";
const execAsync = promisify(execCb);

const { stdout } = await execAsync("git log --oneline -5");
console.log(stdout);

spawn — Stream Output from a Long-Running Process

import { spawn } from "node:child_process";

const child = spawn("find", [".", "-name", "*.js"]);

child.stdout.on("data", (data) => {
  console.log(`stdout: ${data}`);
});

child.stderr.on("data", (data) => {
  console.error(`stderr: ${data}`);
});

child.on("close", (code) => {
  console.log(`Process exited with code ${code}`);
});

fork — Run a Node.js Script with IPC

// parent.js
import { fork } from "node:child_process";

const child = fork("./worker.js");

child.on("message", (msg) => {
  console.log("From child:", msg);
});

child.send({ task: "compute", data: [1, 2, 3, 4, 5] });

// worker.js
process.on("message", (msg) => {
  if (msg.task === "compute") {
    const result = msg.data.reduce((a, b) => a + b, 0);
    process.send({ result });
  }
});

execFile — Run a Binary Directly (No Shell)

import { execFile } from "node:child_process";

execFile("python3", ["--version"], (error, stdout) => {
  console.log(stdout.trim()); // Python 3.12.0
});

Synchronous Execution

import { execSync, spawnSync } from "node:child_process";

// Quick shell command
const output = execSync("whoami", { encoding: "utf-8" });
console.log(output.trim());

// With error handling
try {
  execSync("false");
} catch (error) {
  console.log(`Command failed with code ${error.status}`);
}

4.7 Worker Threads

Worker threads enable true parallelism for CPU-intensive tasks without the overhead of separate processes.

// main.js
import { Worker, isMainThread, parentPort, workerData } from "node:worker_threads";

if (isMainThread) {
  // Main thread — create workers
  const worker = new Worker(new URL(import.meta.url), {
    workerData: { start: 0, end: 1_000_000 },
  });

  worker.on("message", (result) => {
    console.log(`Sum: ${result}`);
  });

  worker.on("error", (err) => {
    console.error("Worker error:", err);
  });

  worker.on("exit", (code) => {
    if (code !== 0) console.error(`Worker exited with code ${code}`);
  });
} else {
  // Worker thread — do computation
  const { start, end } = workerData;
  let sum = 0;
  for (let i = start; i < end; i++) {
    sum += i;
  }
  parentPort.postMessage(sum);
}

Worker pool pattern:

import { Worker } from "node:worker_threads";
import { cpus } from "node:os";

class WorkerPool {
  #workers = [];
  #queue = [];

  constructor(workerFile, poolSize = cpus().length) {
    for (let i = 0; i < poolSize; i++) {
      this.#addWorker(workerFile);
    }
  }

  #addWorker(workerFile) {
    const worker = new Worker(workerFile);
    worker.busy = false;
    worker.on("message", (result) => {
      worker.busy = false;
      worker.currentResolve(result);
      this.#processQueue();
    });
    this.#workers.push(worker);
  }

  #processQueue() {
    if (this.#queue.length === 0) return;
    const freeWorker = this.#workers.find((w) => !w.busy);
    if (!freeWorker) return;
    const { data, resolve } = this.#queue.shift();
    freeWorker.busy = true;
    freeWorker.currentResolve = resolve;
    freeWorker.postMessage(data);
  }

  run(data) {
    return new Promise((resolve) => {
      const freeWorker = this.#workers.find((w) => !w.busy);
      if (freeWorker) {
        freeWorker.busy = true;
        freeWorker.currentResolve = resolve;
        freeWorker.postMessage(data);
      } else {
        this.#queue.push({ data, resolve });
      }
    });
  }
}

Tip

Use worker threads for CPU-bound tasks (image processing, compression, heavy math). For I/O-bound tasks (HTTP requests, file reads, database queries), async/await with the event loop is more efficient and simpler.

4.8 Events and EventEmitter

import { EventEmitter } from "node:events";

class OrderSystem extends EventEmitter {
  placeOrder(order) {
    // Process order...
    this.emit("order:placed", order);
  }

  cancelOrder(orderId) {
    // Cancel order...
    this.emit("order:cancelled", { orderId });
  }
}

const orders = new OrderSystem();

orders.on("order:placed", (order) => {
  console.log(`New order: ${order.id}`);
});

orders.on("order:placed", (order) => {
  // Send notification email...
});

orders.once("order:cancelled", (info) => {
  console.log(`First cancellation: ${info.orderId}`);
});

// Async event handling
import { once } from "node:events";

const [order] = await once(orders, "order:placed");
console.log("Got order:", order);

Key methods:

4.9 Buffers and Binary Data

Buffers represent fixed-length raw binary data. Essential for file I/O, network protocols, and binary formats.

import { Buffer } from "node:buffer";

// Create buffers
const buf1 = Buffer.alloc(10);          // 10 zero-filled bytes
const buf2 = Buffer.from("Hello");      // From string (UTF-8)
const buf3 = Buffer.from([0x48, 0x69]); // From byte array
const buf4 = Buffer.from("SGVsbG8=", "base64"); // From base64

// Read buffer content
console.log(buf2.toString());          // "Hello"
console.log(buf2.toString("hex"));     // "48656c6c6f"
console.log(buf2.toString("base64"));  // "SGVsbG8="
console.log(buf3.toString());          // "Hi"

// Buffer operations
console.log(buf2.length);              // 5
console.log(buf2[0]);                  // 72 (ASCII 'H')
console.log(buf2.includes("ell"));     // true
console.log(Buffer.compare(buf1, buf2)); // -1, 0, or 1

// Concatenate
const combined = Buffer.concat([buf2, Buffer.from(" "), buf3]);
console.log(combined.toString()); // "Hello Hi"

// Slice (shares memory!)
const slice = buf2.subarray(0, 3);
console.log(slice.toString()); // "Hel"

4.10 URL and Query String Parsing

import { URL, URLSearchParams } from "node:url";

// Parse a URL
const url = new URL("https://example.com:8080/path/to/page?name=Node&v=22#section");

console.log(url.hostname);    // "example.com"
console.log(url.port);        // "8080"
console.log(url.pathname);    // "/path/to/page"
console.log(url.search);      // "?name=Node&v=22"
console.log(url.hash);        // "#section"
console.log(url.origin);      // "https://example.com:8080"

// Work with query parameters
const params = url.searchParams;
console.log(params.get("name"));   // "Node"
console.log(params.has("v"));      // true
params.append("lang", "en");
console.log(url.toString());
// https://example.com:8080/path/to/page?name=Node&v=22&lang=en#section

// Build a URL
const apiUrl = new URL("/api/v1/users", "https://example.com");
apiUrl.searchParams.set("page", "1");
apiUrl.searchParams.set("limit", "50");
console.log(apiUrl.toString());
// https://example.com/api/v1/users?page=1&limit=50

4.11 Path Manipulation

import path from "node:path";

// Join path segments safely
const fullPath = path.join("/home", "user", "documents", "file.txt");
// Linux: /home/user/documents/file.txt
// Windows: \home\user\documents\file.txt

// Resolve to absolute path
const abs = path.resolve("src", "utils", "index.js");
// e.g., /Users/dev/project/src/utils/index.js

// Parse path components
const parsed = path.parse("/home/user/file.txt");
console.log(parsed);
// { root: '/', dir: '/home/user', base: 'file.txt', ext: '.txt', name: 'file' }

// Common operations
console.log(path.basename("/path/to/file.js"));      // "file.js"
console.log(path.basename("/path/to/file.js", ".js")); // "file"
console.log(path.dirname("/path/to/file.js"));        // "/path/to"
console.log(path.extname("archive.tar.gz"));          // ".gz"
console.log(path.relative("/a/b/c", "/a/d/e"));       // "../../d/e"
console.log(path.isAbsolute("/home/user"));            // true
console.log(path.isAbsolute("./relative"));            // false

// Platform-specific separator
console.log(path.sep); // "/" on POSIX, "\\" on Windows

// Normalize messy paths
console.log(path.normalize("/foo/bar//baz/./quux/..")); // "/foo/bar/baz"

Warning

Always use path.join() or path.resolve() instead of string concatenation for paths. Concatenation with "/" breaks on Windows; path.join() uses the correct separator automatically.

4.12 Crypto Operations

The node:crypto module provides cryptographic functionality including hashing, encryption, signing, and random number generation.

Hashing

import { createHash, randomBytes, randomUUID } from "node:crypto";

// SHA-256 hash
const hash = createHash("sha256")
  .update("Hello, World!")
  .digest("hex");
console.log(hash);
// dffd6021bb2bd5b0af676290809ec3a53191dd81c7f70a4b28688a362182986f

// File hash
import { createReadStream } from "node:fs";

async function hashFile(filepath) {
  const hash = createHash("sha256");
  const stream = createReadStream(filepath);
  for await (const chunk of stream) {
    hash.update(chunk);
  }
  return hash.digest("hex");
}

// Random values
const token = randomBytes(32).toString("hex");    // 64-char hex token
const uuid = randomUUID();                        // v4 UUID

Encryption and Decryption

import { createCipheriv, createDecipheriv, randomBytes, scryptSync } from "node:crypto";

const algorithm = "aes-256-gcm";
const password = "super-secret-password";
const salt = randomBytes(16);
const key = scryptSync(password, salt, 32);

function encrypt(plaintext) {
  const iv = randomBytes(16);
  const cipher = createCipheriv(algorithm, key, iv);

  let encrypted = cipher.update(plaintext, "utf-8", "hex");
  encrypted += cipher.final("hex");
  const authTag = cipher.getAuthTag().toString("hex");

  return { encrypted, iv: iv.toString("hex"), authTag };
}

function decrypt({ encrypted, iv, authTag }) {
  const decipher = createDecipheriv(algorithm, key, Buffer.from(iv, "hex"));
  decipher.setAuthTag(Buffer.from(authTag, "hex"));

  let decrypted = decipher.update(encrypted, "hex", "utf-8");
  decrypted += decipher.final("utf-8");
  return decrypted;
}

const encrypted = encrypt("Hello, World!");
console.log("Encrypted:", encrypted);

const decrypted = decrypt(encrypted);
console.log("Decrypted:", decrypted); // "Hello, World!"

HMAC Signing

import { createHmac } from "node:crypto";

const secret = "webhook-secret-key";
const payload = JSON.stringify({ event: "push", repo: "myrepo" });

const signature = createHmac("sha256", secret)
  .update(payload)
  .digest("hex");

console.log(`sha256=${signature}`);
// Verify: recompute and compare with timing-safe equality

4.13 DNS Resolution

import { promises as dns } from "node:dns";

// Resolve hostname to IP
const addresses = await dns.resolve4("nodejs.org");
console.log(addresses); // ['104.20.22.46', '104.20.23.46']

// Reverse lookup
const hostnames = await dns.reverse("8.8.8.8");
console.log(hostnames); // ['dns.google']

// MX records
const mx = await dns.resolveMx("gmail.com");
console.log(mx);
// [{ exchange: 'alt1.gmail-smtp-in.l.google.com', priority: 10 }, ...]

// All record types
const allRecords = await dns.resolveAny("example.com");

// Lookup (uses OS resolver, respects /etc/hosts)
const result = await dns.lookup("localhost");
console.log(result); // { address: '127.0.0.1', family: 4 }

Note

dns.lookup() uses the operating system's DNS resolution (getaddrinfo), which respects /etc/hosts and system DNS configuration. dns.resolve*() methods connect directly to DNS servers, bypassing the OS resolver. In most application code, dns.lookup() is what you want.

4.14 Timers

// setTimeout — run once after delay
const timeoutId = setTimeout(() => {
  console.log("Runs after 2 seconds");
}, 2000);

// clearTimeout — cancel
clearTimeout(timeoutId);

// setInterval — run repeatedly
const intervalId = setInterval(() => {
  console.log("Every 5 seconds:", new Date().toISOString());
}, 5000);

// Stop after 30 seconds
setTimeout(() => clearInterval(intervalId), 30000);

// setImmediate — run at end of current event loop iteration
setImmediate(() => {
  console.log("Runs after I/O callbacks");
});

// Promise-based timers (Node.js 16+)
import { setTimeout as sleep } from "node:timers/promises";

await sleep(1000);
console.log("1 second later");

// AbortController integration
const controller = new AbortController();
try {
  await sleep(60000, null, { signal: controller.signal });
} catch (err) {
  if (err.name === "AbortError") {
    console.log("Timer was cancelled");
  }
}
// Cancel from elsewhere: controller.abort();

// Scheduling timer with ref/unref
const timer = setTimeout(() => {}, 60000);
timer.unref(); // Don't keep the process alive for this timer

4.15 Built-in Test Runner

Node.js includes a test runner in the node:test module. No external testing framework required.

Writing Tests

// test/math.test.js
import { describe, it, before, after, beforeEach, mock } from "node:test";
import assert from "node:assert/strict";

import { add, multiply, divide } from "../src/math.js";

describe("Math module", () => {
  describe("add()", () => {
    it("should add two positive numbers", () => {
      assert.strictEqual(add(2, 3), 5);
    });

    it("should handle negative numbers", () => {
      assert.strictEqual(add(-1, -2), -3);
    });

    it("should handle zero", () => {
      assert.strictEqual(add(0, 5), 5);
    });
  });

  describe("divide()", () => {
    it("should divide numbers", () => {
      assert.strictEqual(divide(10, 2), 5);
    });

    it("should throw on division by zero", () => {
      assert.throws(() => divide(1, 0), {
        message: "Division by zero",
      });
    });
  });
});

Running Tests

# Run all tests in test/ directory
node --test

# Run specific test files
node --test test/math.test.js test/utils.test.js

# Run with glob pattern
node --test "test/**/*.test.js"

# Watch mode — rerun on changes
node --test --watch

# With coverage
node --test --experimental-test-coverage

# Specific reporter
node --test --test-reporter=spec
node --test --test-reporter=dot
node --test --test-reporter=tap

# Only run tests matching a name pattern
node --test --test-name-pattern="add"

# Concurrency control
node --test --test-concurrency=4

Expected output (spec reporter):

▶ Math module
  ▶ add()
    ✔ should add two positive numbers (0.5ms)
    ✔ should handle negative numbers (0.1ms)
    ✔ should handle zero (0.1ms)
  ▶ divide()
    ✔ should divide numbers (0.1ms)
    ✔ should throw on division by zero (0.2ms)

ℹ tests 5
ℹ suites 3
ℹ pass 5
ℹ fail 0
ℹ duration_ms 45

Mocking

import { describe, it, mock } from "node:test";
import assert from "node:assert/strict";

describe("Mocking", () => {
  it("should mock a function", () => {
    const fn = mock.fn((x) => x * 2);

    assert.strictEqual(fn(5), 10);
    assert.strictEqual(fn.mock.calls.length, 1);
    assert.deepStrictEqual(fn.mock.calls[0].arguments, [5]);
  });

  it("should mock timers", (t) => {
    t.mock.timers.enable({ apis: ["setTimeout"] });

    let called = false;
    setTimeout(() => { called = true; }, 5000);

    t.mock.timers.tick(5000);
    assert.strictEqual(called, true);
  });

  it("should mock a method", (t) => {
    const obj = {
      getValue() { return "real"; }
    };

    t.mock.method(obj, "getValue", () => "mocked");
    assert.strictEqual(obj.getValue(), "mocked");
  });
});

Subtests, Hooks, and Lifecycle

import { describe, it, before, after, beforeEach, afterEach } from "node:test";

describe("Database tests", () => {
  let db;

  before(async () => {
    db = await connectToTestDb();
  });

  after(async () => {
    await db.close();
  });

  beforeEach(async () => {
    await db.clear();
  });

  it("should insert a record", async () => {
    await db.insert({ name: "test" });
    const count = await db.count();
    assert.strictEqual(count, 1);
  });
});

4.16 TypeScript Support

Node.js supports TypeScript directly via the --experimental-strip-types flag, which strips type annotations at load time:

node --experimental-strip-types app.ts

// app.ts
interface User {
  name: string;
  age: number;
}

function greet(user: User): string {
  return `Hello, ${user.name}! You are ${user.age} years old.`;
}

const user: User = { name: "Alice", age: 30 };
console.log(greet(user));

Hello, Alice! You are 30 years old.

What works:

• Type annotations (: string, : number, etc.)
• Interfaces
• Type aliases
• Generics
• as type assertions
• Optional chaining and nullish coalescing (these are JavaScript too)

What does NOT work (requires a build step):

• enum declarations
• namespace declarations
• Legacy decorators (Stage 2 decorators work)
• const enum
• Implicit file extensions (must use .ts)
• import type transformation

Important

Type stripping does not perform type checking. Run tsc --noEmit separately for type validation. The --experimental-strip-types flag is for runtime convenience, not as a replacement for the TypeScript compiler.

4.17 Debugging

Inspector Protocol (Chrome DevTools)

# Start with inspector on default port 9229
node --inspect app.js

# Break on first line
node --inspect-brk app.js

# Custom port
node --inspect=0.0.0.0:9230 app.js

Debugger listening on ws://127.0.0.1:9229/6f8c1e3a-...
For help, see: https://nodejs.org/en/docs/inspector

Open chrome://inspect in Chrome, click "Open dedicated DevTools for Node", and connect.

Built-in Debugger (CLI)

node inspect app.js

< Debugger listening on ws://127.0.0.1:9229/...
connecting to 127.0.0.1:9229 ... ok
Break on start in app.js:1
> 1 const http = require('node:http');
  2
  3 const server = http.createServer((req, res) => {
debug>

Debugger commands:

Programmatic Debugging

// Add debugger statement in code
function processData(data) {
  debugger; // Execution pauses here when inspector is attached
  return data.map((item) => item * 2);
}

Debug Logging with NODE_DEBUG

# Enable debug output for specific modules
NODE_DEBUG=http,net node app.js

HTTP 12345: call onSocket 0 0
HTTP 12345: createConnection example.com:80
NET 12345: connect: find host example.com
NET 12345: connect: dns options ...

4.18 Permission Model

The permission model restricts what a Node.js application can access, providing defense in depth.

# Enable the permission model (denies everything by default)
node --experimental-permission app.js

# Allow reading specific directories
node --experimental-permission --allow-fs-read=/app/data --allow-fs-read=/app/config app.js

# Allow writing to specific directory
node --experimental-permission --allow-fs-write=/app/output app.js

# Allow child process spawning
node --experimental-permission --allow-child-process app.js

# Allow worker threads
node --experimental-permission --allow-worker app.js

# Combine permissions
node --experimental-permission \
  --allow-fs-read=/app \
  --allow-fs-write=/app/output \
  --allow-child-process \
  app.js

# Allow all reads (wildcard)
node --experimental-permission --allow-fs-read=* app.js

Permission types:

Runtime permission checking:

// Check if a permission is granted
if (process.permission.has("fs.read", "/etc/passwd")) {
  console.log("Can read /etc/passwd");
} else {
  console.log("No read access to /etc/passwd");
}

Caution

The permission model is experimental. While it provides useful sandboxing, do not rely on it as your sole security boundary. Combine it with OS-level sandboxing (containers, seccomp, AppArmor) for defense in depth. Native addons can bypass the permission model entirely unless --allow-addons restrictions are used.

5. Common Tasks

5.1 Create an HTTP REST API Server

import http from "node:http";

const todos = [];
let nextId = 1;

function parseBody(req) {
  return new Promise((resolve, reject) => {
    let body = "";
    req.on("data", (chunk) => (body += chunk));
    req.on("end", () => {
      try {
        resolve(body ? JSON.parse(body) : {});
      } catch (e) {
        reject(new Error("Invalid JSON"));
      }
    });
    req.on("error", reject);
  });
}

function sendJson(res, statusCode, data) {
  res.writeHead(statusCode, {
    "Content-Type": "application/json",
    "Access-Control-Allow-Origin": "*",
  });
  res.end(JSON.stringify(data));
}

const server = http.createServer(async (req, res) => {
  const url = new URL(req.url, `http://${req.headers.host}`);
  const path = url.pathname;
  const method = req.method;

  try {
    // GET /api/todos
    if (method === "GET" && path === "/api/todos") {
      return sendJson(res, 200, todos);
    }

    // GET /api/todos/:id
    const idMatch = path.match(/^\/api\/todos\/(\d+)$/);
    if (method === "GET" && idMatch) {
      const todo = todos.find((t) => t.id === parseInt(idMatch[1]));
      if (!todo) return sendJson(res, 404, { error: "Not found" });
      return sendJson(res, 200, todo);
    }

    // POST /api/todos
    if (method === "POST" && path === "/api/todos") {
      const body = await parseBody(req);
      const todo = { id: nextId++, title: body.title, done: false };
      todos.push(todo);
      return sendJson(res, 201, todo);
    }

    // PATCH /api/todos/:id
    if (method === "PATCH" && idMatch) {
      const todo = todos.find((t) => t.id === parseInt(idMatch[1]));
      if (!todo) return sendJson(res, 404, { error: "Not found" });
      const body = await parseBody(req);
      Object.assign(todo, body);
      return sendJson(res, 200, todo);
    }

    // DELETE /api/todos/:id
    if (method === "DELETE" && idMatch) {
      const index = todos.findIndex((t) => t.id === parseInt(idMatch[1]));
      if (index === -1) return sendJson(res, 404, { error: "Not found" });
      todos.splice(index, 1);
      return sendJson(res, 204, null);
    }

    sendJson(res, 404, { error: "Not found" });
  } catch (err) {
    sendJson(res, 400, { error: err.message });
  }
});

server.listen(3000, () => console.log("API on http://localhost:3000"));