Node.js architecture

One runtime, several layers

Node.js is a runtime: it combines a JavaScript engine with platform code that lets JavaScript work with files, networks, timers, processes, and native libraries. V8 runs the language. Node adds the surrounding capabilities.

This lesson names the parts without turning them into one blurry box. V8 executes JavaScript. libuv helps Node manage event-loop and platform work. C++ bindings connect JavaScript APIs such as fs.readFile to native implementation code.

console.log(
  Object.keys(process.versions).includes("v8"),
  Object.keys(process.versions).includes("uv"),
);

Line 2 checks whether process.versions has a V8 key. Line 3 checks for libuv. In Node, this prints true true. It is small but useful evidence that Node includes both components.

Do not read a version key as a complete architecture diagram. It only identifies a compiled component. The sections below explain why Node needs each layer and where its public APIs cross into native code.

V8, libuv, and bindings

V8 parses and runs JavaScript and manages JavaScript memory. It does not, by itself, define Node's fs module or decide how a timer interacts with an operating system.

libuv is a C library Node uses for its event loop, worker threads, and cross-platform system abstractions. It helps Node present similar APIs across operating systems while native code handles platform differences.

const { node, v8, uv, napi } = process.versions;
console.log(Boolean(node), Boolean(v8), Boolean(uv), Boolean(napi));

Line 1 takes node, v8, uv, and napi from Node's version object. Line 2 prints four booleans, so the documented output is true true true true on the supported Node runtime.

node identifies the Node runtime, v8 the embedded engine, uv libuv, and napi the highest supported Node-API version. These are identifiers, not performance measurements or compatibility promises for arbitrary native code.

const layers = {
  v8: "run JavaScript",
  libuv: "coordinate event-loop and platform work",
  binding: "translate JavaScript values at a native boundary",
  module: "offer a documented JavaScript API",
};

console.log(layers.v8);
console.log(layers.binding);
console.log(layers.module);

Lines 2 through 5 give each layer one short job. Lines 8 through 10 print run JavaScript, translate JavaScript values at a native boundary, and offer a documented JavaScript API. The labels are deliberately narrow: they help you ask which layer owns a behavior without saying one layer does everything.

Notice that the module is the part application code usually touches. V8, libuv, and bindings are real and important, but a normal program should begin with a documented module such as node:fs or node:crypto.

Follow a file read

Start with the familiar call fs.readFile("menu.txt", callback). Your JavaScript calls a public Node API. Node's implementation crosses a native binding, arranges lower-level work, and later calls JavaScript back with a result or an error.

The exact path depends on the API, platform, and whether an operating-system API is already asynchronous. The model deliberately uses broad names instead of claiming every file read has identical hidden steps.

function callPath(api) {
  return ["JavaScript API", "C++ binding", "libuv or native subsystem", "operating system", "JavaScript callback"];
}

console.log(callPath("fs.readFile").join(" -> "));

Line 2 lists the layers in the model. Line 5 calls it and prints JavaScript API -> C++ binding -> libuv or native subsystem -> operating system -> JavaScript callback. This is a teaching route, not engine tracing output.

A callback does not start a second copy of your program. It is a function Node arranges to call after the request has a result. The JavaScript thread can continue with other work while the request is waiting.

For a file read, Node must also turn your friendly strings into a platform request. The next tiny Node-only example shows the public edge of that request. It is marked as Node-only because a browser sandbox cannot provide Node's file system.

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

fs.readFile("menu.txt", "utf8", (error, text) => {
  if (error) throw error;
  console.log(text);
});

Line 1 imports Node's file module. Line 3 asks it to read menu.txt as text. Line 4 receives either an error or the text, then line 5 prints that text. Between lines 3 and 4, Node crosses its native boundary and later schedules JavaScript again.

1function callPath(api) {Run2  return ["JavaScript API", "C++ binding", "libuv or native subsystem", "operating system", "JavaScript callback"];3}4 5console.log(callPath("fs.readFile").join(" -> "));

After the callback begins, it is ordinary JavaScript again. That is why a callback can update a cart, throw an error, resolve a promise, or start another Node API call. The native boundary does not make the callback a different language.

1function callPath(api) {2  return ["JavaScript API", "C++ binding", "libuv or native subsystem", "operating system", "JavaScript callback"];3}4 5console.log(callPath("fs.readFile").join(" -> "));

The C++ binding layer

A binding is native glue that exposes a JavaScript-shaped API while translating values and requests for lower-level Node code, V8, libuv, or another native library. It is the bridge, not a separate JavaScript engine.

For example, a JavaScript wrapper can validate arguments, create a request, and arrange where a callback or promise result returns. That work lets application code say fs.readFile instead of dealing with file descriptors and platform-specific system calls directly.

function invokeBinding(name, argument) {
  return { name, argument, nativeRequest: true };
}

const request = invokeBinding("readFile", "menu.txt");
console.log(request.name, request.argument, request.nativeRequest);

Line 1 defines a tiny model. Line 5 asks it to prepare readFile for menu.txt. Line 6 prints readFile menu.txt true, showing the request name, value, and its native-boundary marker.

In a real call, the binding has to preserve JavaScript rules while it talks to C++. It converts strings and callbacks into native representations, checks errors, and later converts a native result back into a JavaScript value. That is why the public API can stay simple even when the operating systems below it differ.

Bindings are also why an API can return a promise without exposing a file descriptor. Node owns the implementation details. Your application should use the documented module contract, then profile or inspect diagnostics when that contract is not meeting a real requirement.

1function invokeBinding(name, argument) {Run2  return { name, argument, nativeRequest: true };3}4 5const request = invokeBinding("readFile", "menu.txt");6console.log(request.name, request.argument, request.nativeRequest);

Real bindings have more responsibility: JavaScript exceptions, memory lifetimes, asynchronous completion, and platform differences. The small model has one job: make the boundary visible before you read native implementation code.

Node-API and native addons

Node-API, formerly N-API, is a C API for building native addons. Node documents an Application Binary Interface, or ABI, stability guarantee for addons that use Node-API rather than V8, libuv, or Node C++ APIs directly.

An addon is compiled native code loaded by Node. A common build tool is node-gyp. The resulting dynamically linked binary normally has a .node extension and can be loaded with require.

#include <node_api.h>

napi_value AddOne(napi_env env, napi_callback_info info) {
  napi_value result;
  napi_create_int32(env, 4, &result);
  return result;
}

NAPI_MODULE(NODE_GYP_MODULE_NAME, AddOne)

Line 1 includes the Node-API header. Lines 3 through 7 create a JavaScript number as a napi_value. Line 9 registers the addon entry point. This is a simplified sketch, not a complete buildable addon.

The ABI promise has an important boundary: direct V8, libuv, and Node C++ APIs do not get the same cross-major Node ABI guarantee. Native addons still need careful platform builds, tests, and cleanup.

ABI stability means a compiled addon that stays within Node-API does not need to be rebuilt merely because Node changes an implementation detail behind that API. It does not mean every operating system, CPU, or external native library can share one binary.

function chooseImplementation(needsNativeSpeed, needsBrowserPortability) {
  if (needsBrowserPortability) return "WebAssembly or pure JavaScript";
  if (needsNativeSpeed) return "Node-API addon";
  return "pure JavaScript package";
}

console.log(chooseImplementation(false, false));
console.log(chooseImplementation(true, false));
console.log(chooseImplementation(true, true));

Line 2 chooses a browser-friendly route first. Line 3 chooses a Node-API addon only when native speed is needed. The three calls print pure JavaScript package, Node-API addon, and WebAssembly or pure JavaScript. Prefer a pure-JavaScript package for ordinary work; prefer WebAssembly when the same compiled core should reach browsers and Node.

A native addon is a last-mile tool, not a badge of seriousness. It adds compiler toolchains, binary distribution, platform testing, and crash risk. Choose it when you have measured work that a documented Node-API boundary can genuinely improve.

Built-in modules

Built-in modules are modules supplied by Node itself. They include names such as fs, path, stream, and worker_threads. A node: prefix makes it clear that an import names a Node built-in.

The node:module API exposes a list of built-in module names. That list is useful when tooling needs to distinguish a core module from a package found in a project's node_modules folder.

const { builtinModules } = require("node:module");
console.log(builtinModules.includes("fs"));
console.log(builtinModules.includes("worker_threads"));

Line 1 gets Node's built-in module list. Lines 2 and 3 check for fs and worker_threads. The child-process test proves both lines print true.

Built-in modules are public JavaScript APIs, but their implementations can move between JavaScript and C++ as Node evolves. Code should depend on documented API behavior, not on an assumed internal file layout.

Primordials in Node core

Primordials are internal Node-core references and wrappers for JavaScript built-ins. Node core can use them so a later replacement of a global or prototype method by application code does not change every internal lookup.

const before = ["tea", "milk"].join(",");
Array.prototype.join = () => "changed by app code";
console.log(before);
console.log(["tea", "milk"].join(","));

Line 1 runs the original join and saves tea,milk. Line 2 replaces Array.prototype.join. Lines 3 and 4 print tea,milk and then changed by app code. The example proves why a saved original matters; it does not expose Node's internal primordials.

const savedJoin = Array.prototype.join;
Array.prototype.join = () => "changed by app code";

console.log(savedJoin.call(["tea", "milk"], ","));
console.log(["tea", "milk"].join(","));

Line 1 saves the original method before the replacement. Line 4 calls that saved method with the array as its receiver, so it prints tea,milk. Line 5 performs a normal lookup after the replacement and prints changed by app code. This is a visible teaching model of why Node core avoids depending on later mutable lookups.

Node's contributor documentation is careful here. Primordials are internal only, and some mutations still break built-ins or application code. Treat them as a reliability technique in core, not as an app feature or a reason to modify prototypes.

Startup snapshots

A startup snapshot is prepared heap state that Node can load when starting. It can avoid repeating allowed initialization work, but it is not a general backup for open sockets, current requests, or arbitrary live process state.

Node can build a blob with --build-snapshot and later load it with --snapshot-blob. Node checks that the Node binary version, platform, architecture, V8 flags, and CPU features are compatible before loading a blob.

node --snapshot-blob snap.blob --build-snapshot entry.js
node --snapshot-blob snap.blob main.js

// entry.js
const v8 = require("node:v8");
console.log(v8.startupSnapshot.isBuildingSnapshot());

The first command writes snap.blob while building a snapshot. The second command loads that blob before running main.js. In entry.js, v8.startupSnapshot.isBuildingSnapshot() returns true while Node builds the snapshot.

// builder.js
const v8 = require("node:v8");
globalThis.menuName = "tea";
v8.startupSnapshot.setDeserializeMainFunction(() => {
  console.log(globalThis.menuName);
});

// Build: node --snapshot-blob app.blob --build-snapshot builder.js
// Load:  node --snapshot-blob app.blob

Line 3 creates small prepared state. Line 4 registers the function Node should run after deserializing the snapshot. Its line 5 prints tea when that restored program starts. Keep the builder deterministic: do not treat an open socket, current request, or a clock reading as reusable startup state.

function canLoadSnapshot(saved, running) {
  return saved.node === running.node
    && saved.platform === running.platform
    && saved.arch === running.arch
    && saved.v8Flags === running.v8Flags;
}

const saved = { node: "22", platform: "linux", arch: "x64", v8Flags: "default" };
console.log(canLoadSnapshot(saved, saved));
console.log(canLoadSnapshot(saved, { ...saved, arch: "arm64" }));

Lines 2 through 5 compare the saved build with the running Node environment. Line 9 compares the saved data with itself and prints true. Line 10 changes the CPU architecture and prints false. Node performs real compatibility checks rather than loading an arbitrary blob as though it were portable application data.

Keep snapshot code simple and deterministic. Node documents limits on user-land snapshots, including which modules can safely be loaded while building. A snapshot prepared by one incompatible binary is rejected instead of being treated as portable data.

Choose the right layer

Most Node developers stay at the public JavaScript API layer. You use fs, http, timers, streams, and promises. Understanding the lower layers helps you form better questions when performance, portability, or native dependencies matter.

When an operation feels slow, first name the API and its contract. Is it a file read, DNS lookup, crypto operation, timer, or JavaScript computation? Then use the right Node and operating-system tools rather than guessing from the word “asynchronous.”

For portable packages, prefer documented public APIs. For a native addon, prefer Node-API when its C interface covers the work you need. For routine application code, changing an internal binding is almost never the first answer.

Read evidence in a useful order

A crash report is a useful boundary object: it tells you what Node process failed without pretending that every field explains the cause. Begin with the runtime version and JavaScript stack. Only then inspect native handles or resource information that supports the concrete failure you found.

// Start a process so an uncaught exception writes a report.
node --report-uncaught-exception server.js

// In the JSON report, read these in order:
// 1. header.nodejsVersion: identify the runtime.
// 2. javascriptStack: find application frames.
// 3. libuv: inspect active handles only after finding the failure.
// 4. resourceUsage: compare CPU or memory with a measured baseline.

Line 2 starts Node with report creation for an uncaught exception. The numbered comments are an investigation order, not a magic fix. They stop a slow investigation from jumping straight to libuv when the JavaScript stack already points at a missing value or application bug.

For slow startup, write down the stages before changing flags. Measure configuration loading, client creation, and module loading separately. A snapshot may help repeated deterministic setup, but it cannot fix a network call or unnecessary application work.

const startedAt = performance.now();
require("./load-config.js");
require("./create-client.js");
console.log(Math.round(performance.now() - startedAt));

Line 1 starts a timer. Lines 2 and 3 name two startup stages, and line 4 prints their combined elapsed time. Split those stages further only after this first measurement shows where the time is going. This is Node.js-only: run it from the app's startup directory, where load-config.js and create-client.js exist. The browser editor cannot provide Node's require.

Common misconceptions

• “Node is just V8.” V8 runs JavaScript; Node adds modules, platform APIs, native code, and runtime policy.
• “Async means a new JavaScript thread.” Node uses several mechanisms. Do not infer the implementation from the word async.
• “Node-API makes any native library portable.” Its ABI guarantee covers Node-API; external libraries and direct V8/libuv use have separate compatibility concerns.
• “Primordials are public safety tools.” They are internal Node-core machinery with documented limits.
• “A snapshot stores a running server.” It stores permitted prepared startup state, not arbitrary live resources.

A useful debugging habit is to state which layer you mean before proposing a fix. “V8 is slow,” “a file API is queued,” and “a binding translates values” are different claims that need different evidence.

Practice exercises

console.log(
  Object.keys(process.versions).includes("v8"),
  Object.keys(process.versions).includes("uv"),
);

Check your understanding

Answer from the layer's job, not from a vague idea that all Node work is the same kind of work.

Key takeaways

• V8 runs JavaScript; Node surrounds it with platform capabilities.
• libuv supports the event loop and cross-platform async work, while bindings connect APIs to native implementation.
• Node-API gives compatible addons a stable C interface, unlike direct V8/libuv APIs.
• Built-ins are public Node modules; primordials are internal defensive tools for Node core.
• Startup snapshots can restore prepared compatible state and avoid repeat initialization.

Coming next: Inside Deno, Bun & edge runtimes, where runtime authors make different engine and platform choices.