Skip to content
Tutorials Center
My learning

Topics

Lesson 2 of 133 ยท Getting Started

How Node.js Works

Understand how Node.js works inside - V8, libuv, the single-threaded event loop, the thread pool, non-blocking I/O, native addons and why Node suits I/O work.

You can write Node programs for a long time without knowing what happens underneath, but a rough mental model saves you from the most common mistakes: freezing a server with a long loop, expecting code to run in the wrong order, or wondering why one request makes all others slow. This lesson builds that model in plain words. Later lessons, such as the event loop and worker threads, add detail.

The one-sentence version: Node runs your JavaScript on a single thread, and hands everything that would make that thread wait (files, network, timers) to the operating system or to helper threads, then comes back to your code when the result is ready.

The pieces inside Node

Node is a C++ program that embeds several libraries and glues them to a JavaScript API.

  • V8 parses and runs JavaScript. It owns the JavaScript objects and the garbage collector. V8 knows nothing about files or sockets; it only knows the language.
  • libuv is a cross-platform C library. It provides the event loop, timers, asynchronous file operations, TCP/UDP sockets, child processes and a pool of worker threads. It hides the differences between Linux, macOS and Windows.
  • Node's C++ bindings connect the two: when you call fs.readFile, JavaScript calls a C++ function, which asks libuv to do the read.
  • Node's JavaScript core is the part of the standard library written in JavaScript (most of node:fs, node:http, node:stream...). It is compiled into the Node binary and sits on top of the bindings.
  • Other C and C++ libraries do the heavy specialized work: OpenSSL for crypto and TLS, zlib for compression, an HTTP parser, ICU for internationalization.

When you write import fs from 'node:fs', you get a JavaScript module whose functions eventually reach one of those C and C++ layers. That layering is why Node can be fast even though your own code is "just JavaScript".

Node.js Peek at the pieces

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

process.versions reports the version of every embedded component. The exact numbers change with each Node release, so we only check that they exist.

One thread for your code

Your JavaScript runs on one thread, the main thread. Only one piece of your code runs at a time, so you never need locks for ordinary variables, and two callbacks can never interrupt each other in the middle. That makes programs easier to reason about.

The price is that if your code keeps the thread busy, nothing else can happen. No new request is accepted, no timer fires, no callback runs. The next example proves it: a timer asks to run after 0 milliseconds, but it has to wait until the synchronous loop finishes.

Node.js A busy loop blocks everything

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The timer was due immediately, yet "timer callback ran" prints only after the loop is done. Node cannot run the callback while your loop holds the thread. In a server, that loop would be a pause for every connected user. Keep this picture in mind: blocking the thread blocks everyone.

Non-blocking I/O: let someone else wait

Most of what servers do is waiting: for a disk, a database, another service. Node's answer is to start an operation, give it a callback (or a promise), and go on to other work. The waiting happens outside your JavaScript thread.

Node.js Starting a read does not wait for it

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Line 2 prints before the file contents arrive. Between starting the read and receiving the result, the main thread could have served other requests. This is non-blocking I/O, and it is the reason one Node process can keep thousands of connections open at once.

The event loop

How does Node know when to come back? Through the event loop, a loop provided by libuv that runs for as long as the program has pending work. In simplified terms, each turn of the loop:

  1. runs expired timers (setTimeout, setInterval),
  2. runs callbacks for completed I/O (a file was read, a socket received data),
  3. runs setImmediate callbacks (a "right after I/O" slot),
  4. runs close callbacks, then checks whether any work remains. If none does, the loop ends and the process exits.

Between callbacks, Node also empties two queues of very small tasks: process.nextTick callbacks and promise callbacks (microtasks). That is why a promise continuation runs before a setTimeout(..., 0) callback.

Node.js The order things run in

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Read the numbers in order. Synchronous code always finishes first. Then the two small queues are emptied, and the loop proper takes over. Inside the file-read callback, setImmediate beats the 0 ms timer every time; at the top level of a script the two can come in either order, so do not rely on that.

One surprise: in an ES module the promise callback ran before nextTick, whereas in a CommonJS script nextTick comes first. The reason is that an ES module's top-level code is itself running inside a promise job, so the microtask queue is drained before Node gets back to the nextTick queue. The practical rule is simple: both run before any timer or I/O callback, and you should not depend on their order relative to each other. The event loop explains each phase.

Microtasks and nextTick callbacks run to completion before the loop moves on. A promise chain that keeps adding new microtasks can starve timers and I/O just like a busy loop. Long work should yield by going through a real macrotask such as setImmediate.

The reactor pattern, in forty lines

The event loop is Node's implementation of a classic design called the reactor pattern. It has four parts:

  1. An event demultiplexer (the operating system facility epoll on Linux, kqueue on macOS, IOCP on Windows) that watches many resources at once and reports which ones are ready.
  2. A handler (your callback) registered for each resource and each kind of event.
  3. A queue of events that are ready, each paired with its handler.
  4. The event loop, which takes events from the queue one by one and runs their handlers to completion.

One thread does all of it. Work that has to wait (network, disk, timers) is handed to the demultiplexer, so the thread is never parked while it waits. The sketch below builds a toy reactor. It does not use real I/O, but you can see the same moving parts: register stores a handler, ready is what the "operating system" reports, and the loop drains the queue.

Node.js A toy reactor: demultiplexer, handlers and loop

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The handlers ran in the order the events became ready (B, C, A), not in the order they were registered. While nothing was ready, the thread had nothing to do and could have served other work. That is why one Node process can keep thousands of idle connections open, and also why a handler that computes for a long time delays every other event: the loop only continues when your handler returns.

Real Node adds refinements to the pattern. libuv has the phases you saw above, a thread pool for work that has no non-blocking OS API, and two extra queues (process.nextTick and promise jobs) that are emptied after each callback. See The Event Loop for the phases and Worker Threads for CPU-heavy work.

Tracing what the runtime is doing

When a program is slow or behaves oddly, you can ask the runtime to report what it is doing. Most of these tools are command-line flags, so the examples are read-only; run them on your machine.

Terminal
node --trace-warnings app.js          # full stack trace for every process warning
node --trace-deprecation app.js       # where a deprecated API was called
node --trace-uncaught app.js          # stack for exceptions that reach the top
node --trace-sync-io app.js           # warn when synchronous I/O runs after startup
node --trace-event-categories node.perf,v8 app.js   # write node_trace.1.log for chrome://tracing
node --trace-gc app.js                # one line per garbage collection
node --trace-exit app.js              # stack trace of whoever called process.exit

--trace-sync-io is a good tool for the reactor idea: it prints a warning whenever a synchronous call such as fs.readFileSync blocks the loop after the program has started. --trace-event-categories writes a JSON file in the Chrome trace format; open it in Chrome at chrome://tracing or in the Perfetto viewer to see timelines. The same facility is available from code through the trace_events module, which also works with NODE_DEBUG for printing internal module logs (NODE_DEBUG=http,net node app.js).

Node.js The trace_events module

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

While tracing is enabled, the runtime records events and writes them to a node_trace.1.log file in the current directory (in the editor that is a throwaway sandbox). Tracing is for diagnosis, not for production traffic: it adds overhead. For everyday measurements use Performance Hooks and for deeper investigations see Diagnostics and Debugging.

The thread pool: the helpers

Not every operating system offers truly asynchronous versions of every operation. For some jobs libuv uses a thread pool, four threads by default, to run blocking C code off the main thread. The pool serves:

  • most file system calls (fs.readFile, fs.stat, ...),
  • DNS lookups through dns.lookup,
  • some crypto work (pbkdf2, scrypt, randomBytes),
  • zlib compression.

Network sockets do not use the pool; they rely on the operating system's own notification system (epoll on Linux, kqueue on macOS, IOCP on Windows), which scales to a huge number of connections. You can resize the pool with the UV_THREADPOOL_SIZE environment variable, up to 1024:

Terminal
UV_THREADPOOL_SIZE=8 node server.mjs

This snippet is read-only: environment variables for the process are set by the shell before Node starts. Four threads are enough for most programs, but a service that does many parallel disk or crypto jobs can queue behind them, which is a classic reason for mysterious latency.

The next example shows that crypto work really leaves the main thread: while PBKDF2 hashes in the pool, the main thread keeps running a timer.

Node.js Crypto work runs in the pool

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The interval kept firing while the hash was computed. If we had used the synchronous pbkdf2Sync, ticks would stay at zero, because the main thread itself would be doing the work. The number of ticks varies, so we print only whether any happened.

Modules and native addons

Everything you import is a module, a file with its own scope. Node loads each module once, caches it and gives every importer the same instance. Node supports two systems: modern ES modules and the older CommonJS (require). Built-in modules carry the node: prefix, such as node:fs, which makes clear that they are not packages from npm.

When JavaScript is not fast enough or you need an operating-system library, a package can ship a native addon: compiled C, C++ or Rust code loaded as a .node file. Addons use a stable interface called Node-API (N-API), so they survive Node upgrades. Packages that wrap image processing, databases or password hashing often contain addons. They cannot run in our editor; this is read-only:

JavaScript
// Loading a native addon (read-only): the file is compiled code, not JavaScript.
import { createRequire } from 'node:module';
const require = createRequire(import.meta.url);
const addon = require('./build/Release/fast_math.node');
console.log(addon.add(2, 3));

You will rarely write an addon yourself, but knowing they exist explains why some packages need a compiler or download prebuilt binaries during install.

Why Node suits I/O and struggles with CPU work

Put the pieces together and the strengths and weaknesses follow:

Kind of work What happens Fit
Many network connections, mostly waiting Main thread starts operations and sleeps in the loop Excellent
Reading and writing files, calling APIs Delegated to the OS or the thread pool Excellent
Heavy computation in JavaScript (image resizing, big loops) Holds the single thread; everyone waits Poor on the main thread

For CPU-heavy jobs you have good options: move them to a worker thread, run several processes with cluster, or call a native addon. Here is a small worker doing the heavy loop while the main thread stays free.

Node.js Move CPU work to a worker thread

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

With eval: true the worker's code is a string run as CommonJS, which is why it uses require. The sandbox has a single CPU, so a worker cannot make the total time shorter here, but the main thread was not blocked.

Release lines and LTS

Node ships a new major version every April and October. Releases in October with even numbers (22, 24, 26) become LTS: they enter "Active LTS" for about a year, then "Maintenance LTS" until they reach end of life roughly thirty months after release. Production systems should run an LTS line and plan an upgrade before it ends. The odd-numbered releases are short-lived and meant for trying new features early.

Node.js compared with Django, Spring and PHP

"Which backend should I use?" has no universal answer, but the differences are not random. They follow from how each platform handles concurrent requests, and that is exactly what the sections above explained.

Node.js Django (Python) Spring Boot (Java) PHP (php-fpm)
Language JavaScript / TypeScript Python Java / Kotlin PHP
Concurrency model One event loop plus a small thread pool; async I/O Worker processes or threads (async views also possible) Pool of threads, one per request (virtual threads available) One short-lived process per request
Idle connection cost Very low One worker busy per blocked request (sync mode) One thread, which is cheap with virtual threads One process
CPU-heavy work Blocks the loop; use worker threads or other services Blocks one worker Runs in parallel on many cores Blocks one worker
State between requests Possible in memory (careful with scaling) Possible in memory per worker Possible in memory, shared by threads Nothing is kept; start fresh each time
Batteries included Small standard library; you assemble packages Admin, ORM, auth, forms, migrations Large ecosystem, dependency injection, data access Frameworks such as Laravel bring most pieces
Startup time Fast Fast Slower (JVM warm-up), much better with native images Instant per request
Typical sweet spot APIs, real-time, I/O-bound services, one language across front and back end Content-heavy sites, admin tools, data apps Large enterprise systems with strict structure Websites and CMS-style apps on simple hosting

The table is a generalization: every platform can be pushed outside its sweet spot, and a well-built system in any of them beats a badly built one in the "right" one. The simulation below shows the one difference that most affects the choice. It uses 200 simulated requests that each wait 50 ms for a database, handled two ways: by a thread-per-request style worker pool limited to 8 workers, and by the event loop, which simply starts every wait and picks up the results.

Node.js 200 requests that mostly wait: pool of 8 versus event loop

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The pool needs about 200 / 8 x 50 ms = 1,250 ms, the event loop finishes in roughly one wait, around 50 ms. The last test shows the other side: when requests burn the CPU instead of waiting, the single thread serves them one by one. Platforms with real parallel threads, or Node with worker threads and clustering, do better there. Modern Java (virtual threads), Python (asyncio) and PHP (Swoole, RoadRunner, FrankenPHP) have closed much of the gap for I/O-bound work, so concurrency alone should rarely decide the choice.

When Node is a good fit: APIs and gateways that mostly wait for databases and other services, real-time features (chat, notifications, live dashboards), streaming, tooling, teams that already write JavaScript or TypeScript, and projects where one language across browser and server removes friction. When to think twice: heavy numeric computation, long CPU-bound jobs in the request path, and teams that need a large opinionated framework with admin and auth on day one (Django, Laravel or Spring save weeks there). Hybrid systems are normal: Node for the real-time edge, another language for the batch or machine-learning parts. See Scalability Patterns for how those pieces are combined, and the Django, Spring Boot and PHP tutorials on this site for the other stacks.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does the main thread do while a file read is in progress?

    The read is handed to the operating system or the libuv thread pool. The main thread stays free and is called back when the result is ready.
  2. 2. Which library provides Node's event loop and thread pool?

    libuv is the cross-platform C library behind the event loop, timers, sockets and the thread pool. V8 only runs JavaScript.
  3. 3. A busy for loop runs for two seconds in a server. What is the effect?

    JavaScript runs on one thread. While the loop holds it, no other JavaScript can run, so every user waits.
  4. 4. Which runs first: a setTimeout(fn, 0) callback or a resolved promise's .then callback?

    After synchronous code, Node empties the microtask queues, and only then does the loop run timers.
  5. 5. Which work uses the libuv thread pool?

    File system calls, some crypto, zlib and dns.lookup run on the pool. Sockets use operating-system notifications instead.

Summary

  • Node = V8 (runs JavaScript) + libuv (event loop, thread pool, I/O) + C++ bindings + a JavaScript standard library.
  • Your code runs on one thread; blocking it blocks every request.
  • I/O is non-blocking: start it, keep working, get called back through the event loop.
  • Order of execution: synchronous code, then nextTick and promise microtasks, then event loop phases.
  • The thread pool (4 threads by default) serves file system, some crypto, zlib and dns.lookup; sockets use the OS.
  • Use worker threads, clusters or native addons for CPU-heavy work, and run an even-numbered LTS release in production.

Next: Running Node: Files, REPL and Flags