Node.js — Administrator & Developer Guide

An exhaustive reference for engineers, SREs, distribution maintainers, and platform architects who build, deploy, operate, harden, and extend Node.js — the open-source, cross-platform JavaScript runtime built on the V8 engine and libuv asynchronous I/O library. This guide covers everything beneath the application layer: compilation, configuration, security hardening, performance tuning, diagnostics, and deep internals.

For everyday usage — running scripts, installing packages, using the REPL, HTTP servers, and the built-in test runner — see the User Guide.

1. Architecture Overview

1.1 What Node.js Is

Node.js is a single-binary, event-driven JavaScript runtime that executes JavaScript outside the browser. It embeds Google's V8 JavaScript engine for JIT compilation of JavaScript and WebAssembly, couples it with libuv for cross-platform asynchronous I/O, and wraps both in a C++ binding layer that exposes operating system primitives — file systems, networking, cryptography, process management, and more — to JavaScript applications through a standard library of built-in modules.

The runtime follows a single-threaded event loop model for JavaScript execution, delegating blocking operations (file I/O, DNS resolution, compression) to a thread pool managed by libuv. This architecture delivers high concurrency for I/O-bound workloads without the complexity of shared-memory threading. For CPU-bound work, the worker_threads module provides true parallelism with message-passing between isolates.

Node.js ships as a single statically-linked executable (node or node.exe) that bundles 20+ C/C++ dependencies, a JavaScript standard library of 55+ modules, and tooling including a CLI debugger, a built-in test runner, an HTTP/2 server, experimental QUIC support, the Chrome DevTools inspector protocol, and npm (installed alongside). The codebase spans 12,024 files at commit 978a8c40.

Note

Node.js is not a web framework. It is a runtime — the layer that frameworks like Express, Fastify, Koa, and Nest.js run on top of. This guide covers the runtime itself.

1.2 Architecture Diagram

┌─────────────────────────────────────────────────────────────────────┐
│                     JavaScript Application                          │
├─────────────────────────────────────────────────────────────────────┤
│              Node.js Standard Library (lib/)                        │
│  fs, http, https, net, crypto, stream, child_process, worker_threads│
│  path, url, os, util, events, buffer, dns, tls, zlib, vm, assert   │
│  test, readline, cluster, dgram, http2, perf_hooks, diagnostics_ch │
├──────────────┬──────────────────────────────────────────────────────┤
│  Internal    │          Internal Modules (lib/internal/)             │
│  Bindings    │  abort_controller, blob, buffer, child_process,      │
│  (C++ ↔ JS)  │  crypto, encoding, errors, event_target, fs, http,   │
│              │  modules/{cjs,esm}, process, streams, test_runner,   │
│              │  timers, tls, url, util, v8, vm, watch_mode, worker  │
├──────────────┴──────────────────────────────────────────────────────┤
│                   C++ Binding Layer (src/ — 151 files)               │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌───────────┐ ┌─────────┐ │
│  │  crypto/  │ │  quic/   │ │inspector/│ │permission/ │ │tracing/ │ │
│  │ 31 files  │ │ 18 files │ │ 20 files │ │ 10 files   │ │ 6 files │ │
│  │  138K ch  │ │  159K ch │ │  39K ch  │ │  19K ch    │ │ 115K ch │ │
│  └──────────┘ └──────────┘ └──────────┘ └───────────┘ └─────────┘ │
├─────────────────────────────────────────────────────────────────────┤
│                       Dependencies (deps/)                          │
│  ┌────┐ ┌─────┐ ┌───────┐ ┌──────┐ ┌─────┐ ┌────┐ ┌───────────┐ │
│  │ V8 │ │libuv│ │OpenSSL│ │llhttp│ │c-ares│ │zlib│ │  nghttp2  │ │
│  └────┘ └─────┘ └───────┘ └──────┘ └─────┘ └────┘ └───────────┘ │
│  ┌────────┐ ┌───────┐ ┌─────────┐ ┌───┐ ┌──────┐ ┌────────────┐ │
│  │simdutf │ │simdjson│ │ brotli  │ │ada│ │sqlite│ │ngtcp2/ngh3 │ │
│  └────────┘ └───────┘ └─────────┘ └───┘ └──────┘ └────────────┘ │
├─────────────────────────────────────────────────────────────────────┤
│                    Operating System (via libuv)                      │
│           epoll / kqueue / IOCP / event ports / poll                 │
└─────────────────────────────────────────────────────────────────────┘

1.3 Component Inventory

1.4 Technology Stack

1.5 Data Flow

Event Loop Cycle

   ┌───────────────────────────┐
   │      timers (setTimeout,  │
   │      setInterval)         │
   └───────────┬───────────────┘
               │
   ┌───────────▼───────────────┐
   │   pending callbacks       │
   │   (deferred I/O callbacks)│
   └───────────┬───────────────┘
               │
   ┌───────────▼───────────────┐
   │   idle, prepare           │
   │   (internal use)          │
   └───────────┬───────────────┘
               │
   ┌───────────▼───────────────┐
   │   poll                    │  ← epoll/kqueue/IOCP waits here
   │   (I/O callbacks)         │    for new I/O events
   └───────────┬───────────────┘
               │
   ┌───────────▼───────────────┐
   │   check (setImmediate)    │
   └───────────┬───────────────┘
               │
   ┌───────────▼───────────────┐
   │   close callbacks         │
   │   (socket.on('close'))    │
   └───────────┘
               │
   process.nextTick() and      ← runs between EVERY phase
   microtask queue (Promises)

Module Resolution Flow

1. require('module') or import 'module' invoked
2. If node: prefix, load built-in module directly from lib/
3. Check node_modules/ hierarchy (CJS) or resolve via package.json exports map (ESM)
4. CJS: lib/internal/modules/cjs/loader.js — synchronous Module._resolveFilename() → Module._load() → compile → cache
5. ESM: lib/internal/modules/esm/ — async resolve() → load() → translate() → instantiate() through loader chain
6. Native addons (.node files): process.dlopen() → dynamic library load → napi_register_module_v1 init

HTTP Request Lifecycle

1. TCP connection arrives → libuv accepts → net.Socket created
2. Data arrives → libuv callback → llhttp parses HTTP headers/body
3. http.IncomingMessage + http.ServerResponse objects created
4. User handler invoked (request event)
5. Response written → buffered by streams → flushed to socket
6. Socket drained → keep-alive or close

2. System Requirements

2.1 Supported Platforms

2.2 Architecture Support Matrix

2.3 Build Prerequisites

Linux (Debian/Ubuntu):

sudo apt-get install -y python3 g++ make git nasm pkg-config

Linux (RHEL/Fedora):

sudo dnf install -y python3 gcc-c++ make git nasm pkg-config

macOS:

xcode-select --install  # Installs clang, make, git
brew install python nasm

Windows:

Install Visual Studio 2022 with "Desktop development with C++" workload. Python 3 must be on PATH. The build uses vcbuild.bat instead of configure.py/make.

2.4 Build Configuration — configure.py Reference

The configure.py script accepts 190+ flags via argparse, generating GYP build files. Flags are grouped by category below.

General Build Options

Debug Options

Shared Library Options

For each --shared-* flag, corresponding --shared-*-includes and --shared-*-libpath flags specify custom include and library paths.

Crypto / SSL Options

Important

Building with --without-ssl disables the crypto, tls, https, and http2 modules entirely. Most production applications require TLS. Only use this for deeply embedded or constrained environments.

ICU / Internationalization Options

Platform-Specific Options

Experimental Options

2.5 Building from Source

Standard build:

git clone https://github.com/nodejs/node.git
cd node
./configure
make -j$(nproc)
# Binary at ./out/Release/node

Ninja build (faster):

./configure --ninja
ninja -C out/Release

Debug build:

./configure --debug
make -j$(nproc)
# Binary at ./out/Debug/node

Installation:

sudo make install
# Installs to /usr/local by default
# Change with: ./configure --prefix=/opt/node

Windows build:

vcbuild.bat release x64
:: Binary at Release\node.exe

Profile-Guided Optimization (PGO):

# Step 1: Build instrumented binary
./configure --enable-pgo-generate
make -j$(nproc)
# Step 2: Run workload to generate profile data
./out/Release/node your-benchmark.js
# Step 3: Build optimized binary using profile
./configure --enable-pgo-use
make -j$(nproc)

3. Configuration Reference

3.1 Runtime Environment Variables

Important

NODE_OPTIONS is a powerful injection point. In multi-tenant or shared hosting environments, restrict it by building Node.js with --without-node-options or by clearing it in process startup scripts.

3.2 package.json Configuration

3.3 OpenSSL Configuration

Node.js loads OpenSSL configuration from the section specified by --openssl-conf-name (default: nodejs_conf) in the OpenSSL config file. Override the config file path with the OPENSSL_CONF environment variable.

# /etc/ssl/openssl.cnf (excerpt)
[nodejs_conf]
ssl_conf = ssl_sect

[ssl_sect]
system_default = system_default_sect

[system_default_sect]
MinProtocol = TLSv1.2
CipherString = DEFAULT:@SECLEVEL=2

3.4 V8 Flags Passthrough

V8 accepts hundreds of tuning flags passed through --v8-options or via NODE_OPTIONS:

# List all V8 flags
node --v8-options

# Pass specific V8 flags
node --max-old-space-size=8192 --max-semi-space-size=64 app.js

# Experimental V8 features
node --harmony-temporal app.js

Key V8 flags for production tuning are covered in Section 6 (Performance).

4. Deployment & Scaling

4.1 Production Deployment Patterns

Process Manager Deployment (PM2)

# Install PM2
npm install -g pm2

# Start application with clustering
pm2 start app.js -i max --name my-app

# Save process list for system restart
pm2 save
pm2 startup systemd

systemd Service

# /etc/systemd/system/node-app.service
[Unit]
Description=Node.js Application
After=network.target

[Service]
Type=simple
User=nodeapp
WorkingDirectory=/opt/app
ExecStart=/usr/local/bin/node --max-old-space-size=4096 app.js
Restart=on-failure
RestartSec=5
Environment=NODE_ENV=production
# Security hardening
NoNewPrivileges=true
ProtectSystem=strict
ReadWritePaths=/opt/app/data
PrivateTmp=true

[Install]
WantedBy=multi-user.target

sudo systemctl enable node-app
sudo systemctl start node-app

4.2 Docker Deployment

# Multi-stage build
FROM node:22-slim AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .

FROM node:22-slim
WORKDIR /app
COPY --from=build /app .
USER node
EXPOSE 3000
ENV NODE_ENV=production
CMD ["node", "app.js"]

Tip

Use node:22-slim (Debian slim) or node:22-alpine for smaller images. The slim variant is ~200MB vs ~1GB for the full image. Alpine uses musl libc, which can cause subtle compatibility issues with native addons.

Docker health check:

HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
  CMD node -e "require('http').get('http://localhost:3000/health', (r) => process.exit(r.statusCode === 200 ? 0 : 1))"

4.3 Cluster Module (Multi-Process)

The cluster module forks the Node.js process to utilize multiple CPU cores:

import cluster from 'node:cluster';
import http from 'node:http';
import os from 'node:os';

if (cluster.isPrimary) {
  const cpuCount = os.cpus().length;
  for (let i = 0; i < cpuCount; i++) {
    cluster.fork();
  }
  cluster.on('exit', (worker, code, signal) => {
    console.error(`Worker ${worker.process.pid} died (${signal || code}). Restarting...`);
    cluster.fork();
  });
} else {
  http.createServer((req, res) => {
    res.writeHead(200);
    res.end('OK');
  }).listen(3000);
}

Scheduling policy is controlled by NODE_CLUSTER_SCHED_POLICY:

• rr (default on all platforms except Windows): Round-robin distribution by the primary process.
• none: OS decides which worker gets the connection (can lead to uneven distribution).

4.4 Worker Threads (Multi-Threaded)

Worker threads share the same process and can share memory via SharedArrayBuffer:

import { Worker, isMainThread, parentPort, workerData } from 'node:worker_threads';

if (isMainThread) {
  const worker = new Worker(new URL(import.meta.url), {
    workerData: { input: [1, 2, 3, 4, 5] }
  });
  worker.on('message', (result) => console.log('Result:', result));
} else {
  const sum = workerData.input.reduce((a, b) => a + b, 0);
  parentPort.postMessage(sum);
}

Worker threads are best for CPU-intensive operations (image processing, compression, ML inference). For I/O-bound work, the event loop with async I/O is more efficient.

4.5 Single Executable Applications (SEA)

Build a standalone binary that bundles the application into the Node.js executable:

// sea-config.json
{
  "main": "app.js",
  "output": "sea-prep.blob",
  "disableExperimentalSEAWarning": true,
  "useSnapshot": false,
  "useCodeCache": true,
  "assets": {
    "icon.png": "assets/icon.png"
  }
}

# 1. Generate the SEA preparation blob
node --experimental-sea-config sea-config.json

# 2. Copy the Node.js binary
cp $(which node) my-app

# 3. Inject the blob into the binary
# Linux:
npx postject my-app NODE_SEA_BLOB sea-prep.blob \
  --sentinel-fuse NODE_SEA_FUSE_fce680ab2cc467b6e072b8b5df1996b2

# macOS: add --macho-segment-name NODE_SEA
# Windows: use signtool for code signing after injection

4.6 Startup Snapshots

Build a snapshot of application startup state into the binary for near-instant cold starts:

# Build Node.js with custom snapshot
./configure --node-snapshot-main=app.js
make -j$(nproc)
# The resulting binary starts with app.js already initialized

Runtime snapshot building:

node --build-snapshot --snapshot-blob snapshot.blob app.js
node --snapshot-blob snapshot.blob

Note

Snapshots capture the V8 heap state at snapshot time. Not all objects serialize correctly — avoid capturing open file descriptors, network sockets, or native addon state in the snapshot.

5. Operations

5.1 Health Monitoring

// health.js — production health check endpoint
import http from 'node:http';
import v8 from 'node:v8';
import os from 'node:os';

http.createServer((req, res) => {
  if (req.url === '/health') {
    const heap = v8.getHeapStatistics();
    res.writeHead(200, { 'Content-Type': 'application/json' });
    res.end(JSON.stringify({
      status: 'ok',
      uptime: process.uptime(),
      memory: {
        rss: process.memoryUsage.rss(),
        heapUsed: heap.used_heap_size,
        heapTotal: heap.total_heap_size,
        heapLimit: heap.heap_size_limit,
        external: process.memoryUsage().external
      },
      cpu: process.cpuUsage(),
      eventLoopLag: performance.now(), // measure with perf_hooks for real lag
      pid: process.pid,
      loadAvg: os.loadavg()
    }));
  }
}).listen(9090);

Tip

Use perf_hooks.monitorEventLoopDelay() for production-grade event loop monitoring. A histogram-based approach is more accurate than sampling:

import { monitorEventLoopDelay } from 'node:perf_hooks';
const h = monitorEventLoopDelay({ resolution: 20 });
h.enable();
// h.percentile(99) gives p99 event loop delay in nanoseconds

5.2 Diagnostic Reports

Diagnostic reports produce a JSON summary of process state (stack traces, heap stats, libuv handles, environment, loaded modules) for post-mortem debugging:

# Generate on signal
node --report-on-signal app.js
kill -USR2 <pid>

# Generate on fatal error (uncaught exception, OOM)
node --report-on-fatalerror app.js

# Generate on uncaught exception
node --report-uncaught-exception app.js

# Generate programmatically
node -e "process.report.writeReport('report.json')"

# Configure report directory and filename
node --report-directory=/var/log/node-reports --report-filename=diag-{pid}-{datetime}.json app.js

# Compact report format
node --report-compact app.js

Report output includes:

• Header (event, date, PID, Node.js/V8/libuv versions)
• JavaScript stack trace
• Native stack trace
• Heap statistics
• Resource usage (user CPU, system CPU, max RSS)
• libuv handle summary (active handles/requests)
• Environment variables
• Loaded shared libraries
• Workers (if any)

5.3 CPU Profiling

# V8 CPU profiler (outputs .cpuprofile for Chrome DevTools)
node --cpu-prof --cpu-prof-dir=./profiles --cpu-prof-interval=100 app.js

# V8 tick processor profiling (lower level)
node --prof app.js
node --prof-process isolate-0x*.log > profile.txt

# Linux perf integration
perf record -g node --perf-basic-prof app.js
perf report

5.4 Heap Analysis

# Heap snapshot on signal
node --heapsnapshot-signal=SIGUSR2 app.js
kill -USR2 <pid>
# Produces Heap.*.heapsnapshot — load in Chrome DevTools

# Programmatic heap snapshot
node -e "
const v8 = require('v8');
const fs = require('fs');
const snapshotStream = v8.writeHeapSnapshot();
console.log('Heap snapshot written to:', snapshotStream);
"

# Heap profiling (allocation tracking)
node --heap-prof --heap-prof-dir=./profiles app.js

Tip

For memory leak detection in production, use --heapsnapshot-signal to take snapshots on demand without restarting. Compare snapshots in Chrome DevTools to identify retained objects.

5.5 Tracing

Node.js includes a built-in tracing system compatible with Chrome's chrome://tracing:

# Enable trace events
node --trace-events-enabled --trace-event-categories=v8,node,node.async_hooks app.js

# Available trace categories:
# v8                    - V8 engine events (GC, compilation)
# node                  - Node.js core events
# node.async_hooks      - Async hooks trace events
# node.bootstrap        - Bootstrap/startup events
# node.environment      - Environment lifecycle
# node.fs.sync          - Synchronous fs operations
# node.fs.async         - Asynchronous fs operations
# node.net.native       - Network events (TCP, DNS)
# node.dns.native       - DNS resolution events
# node.perf             - Performance events
# node.perf.usertiming  - User timing marks/measures
# node.perf.timerify    - Timerified function traces

# Output is written to node_trace.*.log in the current directory

The tracing subsystem is implemented in src/tracing/ (6 files, 115K chars) and integrates with V8's trace event infrastructure.

5.6 Inspector Protocol

Node.js implements the Chrome DevTools Protocol (CDP) for debugging, profiling, and automation:

# Start with inspector (accepts connections on 127.0.0.1:9229)
node --inspect app.js

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

# Listen on all interfaces (CAUTION: security risk)
node --inspect=0.0.0.0:9229 app.js

# Wait for debugger to attach before starting
node --inspect-wait app.js

# Inspect in a running process
kill -SIGUSR1 <pid>  # Opens inspector on default port

Warning

Never expose the inspector port to untrusted networks. The inspector protocol allows arbitrary code execution. Use SSH tunneling or a reverse proxy with authentication for remote debugging:

ssh -L 9229:localhost:9229 user@remote-host

The inspector implementation lives in src/inspector/ (20 files, 39K chars) and includes WebSocket transport, V8 inspector client bindings, and the inspector module API.

5.7 Watch Mode

# Restart on file changes (built-in, no external tools needed)
node --watch app.js

# Watch mode with path filtering
node --watch-path=./src --watch-path=./config app.js

# Watch mode preserves the process state (experimental)
node --watch-preserve-output app.js

Watch mode is implemented in lib/internal/watch_mode/ and uses fs.watch() (backed by inotify/FSEvents/ReadDirectoryChangesW) for efficient file system monitoring.

5.8 Graceful Shutdown

// Graceful shutdown pattern
const server = http.createServer(handler);
server.listen(3000);

const connections = new Set();
server.on('connection', (conn) => {
  connections.add(conn);
  conn.on('close', () => connections.delete(conn));
});

function shutdown(signal) {
  console.log(`Received ${signal}. Graceful shutdown...`);

  // Stop accepting new connections
  server.close(() => {
    console.log('Server closed. Exiting.');
    process.exit(0);
  });

  // Set a hard timeout
  setTimeout(() => {
    console.error('Forced shutdown after timeout');
    process.exit(1);
  }, 30000).unref();

  // Destroy idle connections
  for (const conn of connections) {
    conn.end();
  }
}

process.on('SIGTERM', () => shutdown('SIGTERM'));
process.on('SIGINT', () => shutdown('SIGINT'));

Note

.unref() on the timeout timer prevents it from keeping the event loop alive. Without it, the process would wait the full 30 seconds even if all connections close immediately.

6. Performance

6.1 Event Loop Optimization

The event loop is the heart of Node.js performance. Key principles:

1. Never block the event loop — long synchronous operations (JSON.parse on large payloads, RegExp backtracking, synchronous crypto) stall all concurrent connections.
2. Partition CPU work — use setImmediate() to break large synchronous tasks across event loop ticks.
3. Offload to worker threads — CPU-intensive operations (image encoding, hashing large files) should use worker_threads.
4. Monitor event loop delay — p99 > 100ms indicates problems.

// Partition a large array operation
function processChunk(items, index, chunkSize, callback) {
  const end = Math.min(index + chunkSize, items.length);
  for (let i = index; i < end; i++) {
    // process items[i]
  }
  if (end < items.length) {
    setImmediate(() => processChunk(items, end, chunkSize, callback));
  } else {
    callback();
  }
}

6.2 Large Pages

Large pages (huge pages) reduce TLB misses for the V8 code region, improving performance by 5-10% for some workloads:

# Linux: configure huge pages
sudo sysctl -w vm.nr_hugepages=100
echo 'vm.nr_hugepages=100' | sudo tee -a /etc/sysctl.conf

# Run Node.js with large pages
node --use-largepages=on app.js
# Options: on, silent (don't warn on failure), off

The large pages implementation lives in src/large_pages/ and maps the V8 code region to 2MB pages on Linux (or equivalent on other platforms).

6.3 V8 Tuning

# Production: 8GB heap, aggressive semi-space for high-throughput server
node --max-old-space-size=8192 --max-semi-space-size=64 app.js

# Memory-constrained environment (container with 512MB limit)
node --max-old-space-size=384 --optimize-for-size app.js

# Debug GC behavior
node --trace-gc --trace-gc-verbose app.js 2>gc.log

6.4 Startup Optimization

# Enable module compile cache
export NODE_COMPILE_CACHE=/tmp/node-compile-cache
node app.js  # First run: compiles and caches
node app.js  # Subsequent: loads from cache

6.5 Thread Pool Tuning

libuv's thread pool handles fs operations, dns.lookup(), and some crypto/zlib calls:

# Default: 4 threads. Max: 1024.
export UV_THREADPOOL_SIZE=16  # Must be set BEFORE process starts
node app.js

Guidelines:

• Increase if fs or dns.lookup() latency is high under load
• Don't over-provision — each thread consumes ~1MB stack. 64 threads = 64MB just for stacks
• Use dns.resolve() (c-ares, async, not threadpool) instead of dns.lookup() (getaddrinfo, threadpool) for high-volume DNS

6.6 Benchmark Infrastructure

The benchmark/ directory contains a comprehensive benchmark suite:

# Run a specific benchmark
node benchmark/http/simple.js

# Run benchmark comparison between two Node.js builds
node benchmark/compare.js --old /path/to/old/node --new /path/to/new/node -- benchmark/http/

# Common benchmark categories:
# benchmark/http/       HTTP server throughput
# benchmark/fs/         File system operations
# benchmark/streams/    Stream throughput
# benchmark/buffers/    Buffer operations
# benchmark/url/        URL parsing
# benchmark/crypto/     Cryptographic operations
# benchmark/child_process/ Process spawning
# benchmark/events/     EventEmitter performance
# benchmark/net/        TCP networking
# benchmark/path/       Path operations
# benchmark/string_decoder/ String decoding
# benchmark/timers/     Timer performance

7. Security

7.1 Permission Model

Node.js implements an experimental permission model (since v20) that restricts what a Node.js process can do:

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

# Grant specific permissions
node --experimental-permission \
  --allow-fs-read=/app/data \
  --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

# Allow native addons
node --experimental-permission \
  --allow-addons \
  app.js

# Wildcard patterns
node --experimental-permission \
  --allow-fs-read=/app/* \
  --allow-fs-write=/tmp/* \
  app.js

Warning

The permission model is experimental. It provides defense-in-depth but is not a security sandbox. Malicious native addons or V8 exploits can bypass it. Do not rely on it as the sole security boundary.

The permission system is implemented in src/permission/ (10 files, 19K chars):

Check permissions programmatically:

if (process.permission.has('fs.read', '/etc/passwd')) {
  // Permission granted
}

7.2 TLS/SSL Configuration

import tls from 'node:tls';
import https from 'node:https';
import fs from 'node:fs';

const server = https.createServer({
  key: fs.readFileSync('private-key.pem'),
  cert: fs.readFileSync('certificate.pem'),
  ca: fs.readFileSync('ca-chain.pem'),

  // Minimum TLS version (default: TLSv1.2)
  minVersion: 'TLSv1.2',

  // Cipher suite configuration
  ciphers: [
    'TLS_AES_256_GCM_SHA384',
    'TLS_CHACHA20_POLY1305_SHA256',
    'TLS_AES_128_GCM_SHA256',
    'ECDHE-RSA-AES256-GCM-SHA384',
    'ECDHE-RSA-AES128-GCM-SHA256'
  ].join(':'),

  // ECDH curve
  ecdhCurve: 'auto',

  // Request client certificate
  requestCert: true,
  rejectUnauthorized: true,

  // Session resumption
  sessionTimeout: 300,

  // ALPN protocols
  ALPNProtocols: ['h2', 'http/1.1'],

  // Disable renegotiation (prevents DoS)
  // Node.js disables renegotiation by default since v16

  // OCSP stapling
  // Handled via 'OCSPRequest' event on tls.Server
}, handler);

Caution

Never set NODE_TLS_REJECT_UNAUTHORIZED=0 in production. It disables all certificate validation, making every TLS connection vulnerable to man-in-the-middle attacks. For self-signed certificates, use NODE_EXTRA_CA_CERTS or the ca option.

7.3 OpenSSL and FIPS Mode

Node.js links against OpenSSL 3.x for all cryptographic operations. FIPS 140-2/3 compliance requires:

# Build-time: configure with FIPS
./configure --openssl-fips

# Or: mark as FIPS-capable
./configure --openssl-is-fips

# Runtime: enable FIPS mode
node --enable-fips app.js

# Or force FIPS (error if cannot enable)
node --force-fips app.js

// Check FIPS status
import crypto from 'node:crypto';
console.log('FIPS enabled:', crypto.getFips());

// Enable FIPS programmatically
crypto.setFips(1);

7.4 Crypto Module Security

The src/crypto/ subsystem (31 files, 138K chars) wraps OpenSSL and exposes:

7.5 Supply Chain Security

# Audit dependencies for known vulnerabilities
npm audit

# Fix automatically where possible
npm audit fix

# Production install (no devDependencies, no scripts)
npm ci --only=production --ignore-scripts

# Lock file integrity
npm ci  # Always uses package-lock.json exactly

# Verify package signatures (npm v9+)
npm audit signatures

7.6 Known Security-Related Issues

7.7 Security Best Practices

1. Run as non-root — use a dedicated service account with minimal privileges
2. Drop capabilities — on Linux, use setcap or systemd CapabilityBoundingSet
3. Disable inspector in production — never expose --inspect ports
4. Freeze prototypes — use --frozen-intrinsics (experimental) to prevent prototype pollution
5. Policy-based module loading — use --experimental-policy with integrity checks
6. Limit NODE_OPTIONS — build with --without-node-options or clear before launch
7. HTTP header limits — --max-http-header-size (default 16KB) prevents header-based DoS
8. Request timeout — set server.requestTimeout and server.headersTimeout

8. Developer Internals

8.1 Repository Structure

nodejs/node/
├── src/                    C++ binding layer (151 files, 1.3M chars)
│   ├── crypto/             OpenSSL wrappers (31 files, 138K)
│   ├── quic/               QUIC/HTTP3 protocol (18 files, 159K)
│   ├── inspector/          Chrome DevTools Protocol (20 files, 39K)
│   ├── permission/         Permission model (10 files, 19K)
│   ├── tracing/            Trace event infrastructure (6 files, 115K)
│   └── large_pages/        Huge page support
├── lib/                    JavaScript standard library
│   ├── *.js                55 top-level modules (898K chars)
│   └── internal/           52 internal modules (568K chars)
├── deps/                   Bundled C/C++ dependencies
│   ├── v8/                 V8 JavaScript engine
│   ├── uv/                 libuv async I/O
│   ├── openssl/            OpenSSL
│   ├── llhttp/             HTTP parser
│   ├── cares/              Async DNS
│   ├── icu-small/          ICU internationalization
│   ├── nghttp2/            HTTP/2
│   ├── ngtcp2/             QUIC
│   ├── nghttp3/            HTTP/3
│   ├── zlib/               Compression
│   ├── brotli/             Brotli compression
│   ├── simdutf/            SIMD UTF conversion
│   ├── simdjson/           SIMD JSON parsing
│   ├── ada/                URL parser
│   ├── sqlite/             SQLite
│   ├── undici/             HTTP client (fetch)
│   └── ...
├── test/                   Test suite (4,000+ files)
├── tools/                  Build and development tools
├── benchmark/              Performance benchmarks
├── doc/                    API documentation source
├── typings/                TypeScript type definitions for internal C++ bindings
└── configure.py            Build configuration script (190+ flags)

8.2 C++ Binding Layer (src/)

The C++ layer bridges V8 and the operating system. Key patterns:

Environment and Isolate

Every Node.js instance creates an Environment object (src/env.h, src/env.cc) that owns:

• The V8 Isolate (single-threaded JS execution context)
• The libuv event loop
• All built-in module bindings
• The async hooks state
• The permission model

// Simplified binding registration pattern
void Initialize(Local<Object> target, Local<Value> unused,
                Local<Context> context, void* priv) {
  Environment* env = Environment::GetCurrent(context);
  // Register methods on target object
  SetMethod(context, target, "methodName", MethodCallback);
}
NODE_MODULE_CONTEXT_AWARE_INTERNAL(module_name, Initialize)

Key C++ Subsystems

8.3 JavaScript Standard Library (lib/)

55 top-level modules (898K chars total):

8.4 Internal Modules (lib/internal/)

52 internal module directories/files (568K chars) — not accessible via require() from user code. Loaded via internalBinding() or internal require.

8.5 Error System

The error system (lib/internal/errors.js) defines 907 error types organized by category. Every Node.js error has a unique code (e.g., ERR_INVALID_ARG_TYPE) and a corresponding class.

Error Class Hierarchy

Error
├── NodeError (extends Error)
│   ├── ERR_INVALID_ARG_TYPE
│   ├── ERR_INVALID_ARG_VALUE
│   ├── ERR_MISSING_ARGS
│   ├── ERR_OUT_OF_RANGE
│   └── ... (hundreds more)
├── TypeError (NodeTypeError extends TypeError)
│   ├── ERR_INVALID_THIS
│   ├── ERR_INVALID_CALLBACK
│   └── ...
├── RangeError (NodeRangeError extends RangeError)
│   ├── ERR_BUFFER_OUT_OF_BOUNDS
│   ├── ERR_INDEX_OUT_OF_RANGE
│   └── ...
├── SystemError (extends NodeError)
│   ├── errno (libuv error code)
│   ├── syscall (system call name)
│   ├── path (file path, if applicable)
│   └── ... (wraps OS errors)
├── UVException (libuv errors)
│   ├── EACCES, ENOENT, EEXIST, EPERM, ...
│   └── ... (maps libuv errno → Node.js error)
└── AbortError (for AbortSignal cancellations)

Error Categories and Selected Codes

Argument Validation Errors:

Module System Errors:

File System Errors:

Network Errors:

HTTP Errors:

Crypto Errors:

Stream Errors:

Worker Thread Errors:

TLS/SSL Errors:

Encoding Errors:

VM (Virtual Machine) Errors:

Assertion and Validation Errors:

Permission Model Errors:

Miscellaneous Errors:

8.6 Key Classes

8.7 Code Patterns and Conventions

Primordials

Node.js protects against prototype pollution by capturing built-in functions at startup:

// lib/internal/per_context/primordials.js captures everything:
const {
  ArrayPrototypeMap,
  ObjectDefineProperty,
  StringPrototypeSlice,
  PromisePrototypeThen,
  SafeMap,
  SafeSet,
  SafeWeakMap,
} = primordials;

// Usage in internal modules — never call Array.prototype.map directly
const result = ArrayPrototypeMap(items, transform);

This prevents user code from breaking Node.js internals by modifying Array.prototype.map, Object.keys, etc.

Internal Bindings

C++ modules are exposed to JavaScript via internalBinding():

// In lib/internal/crypto/hash.js
const { Hash: _Hash } = internalBinding('crypto');
// _Hash is a C++ class from src/crypto/crypto_hash.cc

Public modules use process.binding() (deprecated) or internalBinding() (internal only, not accessible from user code).

Lazy Loading

Expensive modules are loaded on first use:

let crypto;
function getCrypto() {
  if (crypto === undefined) {
    crypto = require('crypto');
  }
  return crypto;
}

Validators

lib/internal/validators.js provides standardized argument validation:

const {
  validateFunction,
  validateInteger,
  validateObject,
  validateString,
  validateBoolean,
  validateAbortSignal,
  validateBuffer,
  validateEncoding,
  validatePort,
} = require('internal/validators');

// Usage
function myFunction(path, options) {
  validateString(path, 'path');
  validateObject(options, 'options');
  validateInteger(options.timeout, 'options.timeout', 0);
}

8.8 Testing Infrastructure

The test suite contains 4,000+ test files organized by category:

Running Tests

# Run all tests
make test

# Run parallel tests only
make test-parallel

# Run a specific test
python3 tools/test.py test/parallel/test-http-server.js

# Run with verbose output
python3 tools/test.py -v test/parallel/test-http-server.js

# Run linting
make lint
make lint-js    # JavaScript only
make lint-cpp   # C++ only
make lint-md    # Markdown only

# Run C++ tests
make cctest

# Run with code coverage
make coverage

# Run benchmarks
make bench

8.9 Contributing — Build and Test Workflow

# 1. Clone and build
git clone https://github.com/nodejs/node.git
cd node
./configure --ninja
ninja -C out/Release -j$(nproc)

# 2. Run tests
make test

# 3. After making changes, run affected tests
python3 tools/test.py test/parallel/test-your-feature.js

# 4. Lint
make lint

# 5. Generate documentation
make doc

9. Integration Points

9.1 Node-API (N-API)

Node-API is the stable ABI for building native addons that work across Node.js versions without recompilation:

// addon.c
#include <node_api.h>

napi_value MyFunction(napi_env env, napi_callback_info info) {
  napi_value result;
  napi_create_string_utf8(env, "hello from C", NAPI_AUTO_LENGTH, &result);
  return result;
}

napi_value Init(napi_env env, napi_value exports) {
  napi_property_descriptor desc = {
    "myFunction", NULL, MyFunction, NULL, NULL, NULL, napi_default, NULL
  };
  napi_define_properties(env, exports, 1, &desc);
  return exports;
}

NAPI_MODULE(NODE_GYP_MODULE_NAME, Init)

// Usage
const addon = require('./build/Release/addon.node');
console.log(addon.myFunction()); // "hello from C"

Node-API tests live in test/node-api/ and exercise all API surface areas. The API is versioned (currently up to version 9+), with each version adding new functions while maintaining backward compatibility.

9.2 V8 Embedding API

Node.js can be embedded in other C++ applications:

#include "node.h"
#include "uv.h"

int main(int argc, char* argv[]) {
  // Initialize Node.js
  std::vector<std::string> args(argv, argv + argc);
  std::unique_ptr<node::InitializationResult> result =
      node::InitializeOncePerProcess(args);

  // Create isolate and environment
  node::EmbedderSnapshotData::Pointer snapshot;
  v8::Isolate* isolate = node::NewIsolate(
      node::CreateArrayBufferAllocator(), &loop, platform.get());

  // Run Node.js event loop
  node::LoadEnvironment(env, "const http = require('http');"
                             "http.createServer((req, res) => {"
                             "  res.end('embedded');"
                             "}).listen(3000);");

  // Spin the event loop
  node::SpinEventLoop(env).FromJust();

  // Cleanup
  node::Stop(env);
  return 0;
}

Embedding tests are in test/embedding/ (14 test files).

9.3 Foreign Function Interface (FFI)

Experimental FFI allows calling native shared library functions without compiling a native addon:

// Experimental — requires --experimental-permission and --allow-ffi
import { dlopen, FFIType } from 'node:ffi';

const lib = dlopen('libm.so.6', {
  ceil: {
    args: [FFIType.f64],
    returns: FFIType.f64,
  },
});

console.log(lib.symbols.ceil(1.2)); // 2

The FFI implementation is minimal (2 files, 2.6K chars in src/) and wraps libffi. Tests are in test/ffi/ (10 files).

9.4 WASI (WebAssembly System Interface)

WASI provides a sandboxed system interface for WebAssembly modules:

import { readFile } from 'node:fs/promises';
import { WASI } from 'node:wasi';

const wasi = new WASI({
  version: 'preview1',
  args: process.argv,
  env: process.env,
  preopens: {
    '/sandbox': '/tmp/wasi-sandbox'
  }
});

const wasm = await WebAssembly.compile(await readFile('./module.wasm'));
const instance = await WebAssembly.instantiate(wasm, wasi.getImportObject());
wasi.start(instance);

WASI tests are in test/wasi/ (27 files). The implementation wraps uvwasi (in deps).

9.5 Inspector Protocol (CDP)

The Chrome DevTools Protocol enables programmatic debugging, profiling, and automation:

import inspector from 'node:inspector/promises';

const session = new inspector.Session();
session.connect();

// Take heap snapshot
await session.post('HeapProfiler.takeHeapSnapshot');

// Enable CPU profiler
await session.post('Profiler.enable');
await session.post('Profiler.start');
// ... run workload ...
const { profile } = await session.post('Profiler.stop');

// Evaluate expressions
const { result } = await session.post('Runtime.evaluate', {
  expression: 'process.memoryUsage()'
});

session.disconnect();

The inspector can also be accessed over WebSocket (port 9229 by default) for remote debugging with Chrome DevTools, VS Code, or any CDP-compatible client.

9.6 Diagnostics Channel

Named publish/subscribe channels for instrumenting Node.js core and third-party modules:

import diagnostics_channel from 'node:diagnostics_channel';

// Subscribe to HTTP request events
const channel = diagnostics_channel.channel('http.client.request.start');
channel.subscribe((message) => {
  console.log('HTTP request:', message.request.method, message.request.path);
});

// Built-in channels include:
// http.client.request.start / .error
// http.client.response.finish
// http.server.request.start / .error
// http.server.response.finish
// net.client.socket / net.server.socket
// worker_threads (various)
// module.require.start / .end
// module.import.start / .end

Note

Diagnostics channels have near-zero overhead when no subscribers are attached. They are the recommended way to instrument Node.js applications for monitoring and tracing, replacing monkey-patching approaches used by older APM tools.