How Node.js Works

Node.js runs JavaScript on the server by combining the V8 engine, libuv, and an event-driven I/O model - understanding this stack explains most production surprises.

Recipe

Quick-reference recipe card - copy-paste ready.

import { performance, eventLoopUtilization } from 'node:perf_hooks';
 
const start = eventLoopUtilization();
setImmediate(() => {
  const elu = eventLoopUtilization(start);
  console.log('Event loop utilization:', elu.utilization.toFixed(3));
});

When to reach for this:

• Debugging latency spikes that do not show up in application logs
• Deciding whether to use worker threads vs child processes
• Explaining to teammates why a synchronous loop blocks all HTTP clients
• Sizing thread-pool defaults for crypto and compression workloads

Working Example

import { createServer } from 'node:http';
import { performance } from 'node:perf_hooks';
 
// Simulated CPU work - blocks the entire event loop
function hashSync(data: string, rounds: number): string {
  let result = data;
  for (let i = 0; i < rounds; i++) {
    result = Buffer.from(result).toString('base64');
  }
  return result;
}
 
const server = createServer((req, res) => {
  const t0 = performance.now();
 
  if (req.url === '/fast') {
    res.end('ok');
    return;
  }
 
  if (req.url === '/slow') {
    // 50M iterations block every other request in this process
    hashSync('payload', 50_000_000);
    res.end(`done in ${(performance.now() - t0).toFixed(0)}ms`);
    return;
  }
 
  res.writeHead(404).end();
});
 
server.listen(3000, () => {
  console.log('Try: curl localhost:3000/fast while /slow is running');
});

What this demonstrates:

• A single Node process has one JavaScript execution thread
• CPU-bound loops prevent the server from accepting or finishing other requests
• node:http callbacks run on the main thread - offload heavy work to workers
• performance.now() helps measure event-loop stall duration in dev

Deep Dive

How It Works

• V8 compiles JavaScript to machine code and manages the call stack and garbage collector.
• libuv provides the event loop, async I/O (sockets, files, DNS), and a default 4-thread worker pool for operations that cannot be fully async at the OS level.
• JavaScript runs on one thread per process; concurrency comes from non-blocking I/O and scheduling callbacks when operations complete.
• Native addons and some fs/crypto paths use the libuv thread pool - saturation shows up as queueing, not CPU on the main thread.

Architecture at a Glance

TypeScript Notes

import { Worker } from 'node:worker_threads';
 
// Offload CPU work so the main thread stays responsive
function runInWorker<T>(script: string, workerData: unknown): Promise<T> {
  return new Promise((resolve, reject) => {
    const worker = new Worker(script, { workerData });
    worker.on('message', resolve);
    worker.on('error', reject);
    worker.on('exit', (code) => {
      if (code !== 0) reject(new Error(`Worker exited ${code}`));
    });
  });
}

Gotchas

• Assuming multi-core by default - one Node process uses one core for JavaScript unless you cluster or spawn workers. Fix: use worker_threads for CPU tasks or cluster for HTTP fan-out.
• Synchronous file reads in request handlers - fs.readFileSync blocks the loop even though fs.promises.readFile does not. Fix: prefer node:fs/promises or streams.
• Thread pool starvation - many concurrent pbkdf2 or gzip operations queue behind the default 4 threads. Fix: set UV_THREADPOOL_SIZE (max 1024) or serialize heavy crypto.
• Treating setImmediate as "run ASAP" - it runs in the check phase after I/O polling, not before microtasks. Fix: read the event-loop ordering page before debugging timing bugs.
• Large JSON.parse on big payloads - parsing is synchronous and blocks the loop. Fix: stream-parse or cap payload size at the reverse proxy.

Alternatives

FAQs

import { monitorEventLoopDelay } from 'node:perf_hooks';
const h = monitorEventLoopDelay({ resolution: 20 });
h.enable();
setInterval(() => {
  console.log('p99 loop delay (ns):', h.percentile(99));
  h.reset();
}, 10_000);

Related

• Event Loop Basics - call stack and task queues in practice
• libuv Phases - timers, poll, check, and close phases
• worker_threads - CPU-bound work off the main thread
• Detecting Event-Loop Blockage - production lag metrics
• Node.js Basics - first commands and patterns

Stack versions: This page was written for Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5, and NestJS 11.