Skip to main content
Node.js is built on a sophisticated multi-layer architecture that combines JavaScript execution with low-level system capabilities. This page explores the core architectural components that make Node.js a powerful runtime for server-side JavaScript.

​
Architectural Layers

1

V8 JavaScript Engine

The foundation of Node.js is Google’s V8 engine, which compiles JavaScript to native machine code using just-in-time (JIT) compilation. V8 provides the JavaScript runtime environment, garbage collection, and the execution context for all JavaScript code.
2

libuv Event Loop

libuv is a multi-platform C library that provides asynchronous I/O operations. It implements the event loop, thread pool, and handles file system operations, network I/O, timers, and child processes.
3

C++ Bindings Layer

Node.js core is written in C++ and provides bindings between JavaScript and low-level system APIs. This layer exposes native functionality to JavaScript through the N-API and internal bindings.
4

JavaScript Core Modules

High-level APIs implemented in JavaScript that provide familiar interfaces for developers. These modules are located in the lib/ directory and use C++ bindings when needed.

​
V8 Engine Integration

Node.js embeds the V8 JavaScript engine to execute JavaScript code. The integration happens through several key components:

​
Isolate and Context

Every Node.js process creates a V8 Isolate, which represents an isolated instance of the V8 engine with its own heap. Within an isolate, contexts provide separate JavaScript execution environments. 
// From src/node.h
v8::Isolate* isolate = v8::Isolate::New(params);
v8::HandleScope handle_scope(isolate);
v8::Local<v8::Context> context = v8::Context::New(isolate);
The V8 isolate is the fundamental unit of isolation in Node.js. Worker threads each get their own isolate, ensuring complete memory isolation between threads.

​
Just-In-Time Compilation

V8 uses multiple compilation tiers:
  • Ignition: The interpreter for initial execution
  • TurboFan: The optimizing compiler for hot code paths
  • Sparkplug: A fast non-optimizing compiler (intermediate tier)
Code starts in the interpreter and gets promoted to optimized code based on runtime profiling.

​
libuv and the C++ Layer

The libuv library provides the asynchronous I/O capabilities that make Node.js non-blocking. It’s responsible for:

​
Event Loop Management

The event loop is implemented entirely in libuv. Node.js initializes the loop during startup: 
// From src/node.cc - simplified
uv_loop_t* event_loop = uv_default_loop();
uv_run(event_loop, UV_RUN_DEFAULT);

​
Thread Pool

libuv maintains a thread pool (default size: 4 threads) for operations that don’t have native async APIs:
  • File system operations
  • DNS lookups (getaddrinfo, getnameinfo)
  • Certain crypto operations
  • User-land code via crypto.pbkdf2, zlib, etc.
The thread pool size is controlled by the UV_THREADPOOL_SIZE environment variable (max 1024). Blocking operations in the thread pool can cause performance bottlenecks.

​
Platform Abstractions

libuv provides a consistent API across platforms:
  • Linux/Unix: Uses epoll, kqueue for I/O polling
  • Windows: Uses IOCP (I/O Completion Ports)
  • File watchers: inotify (Linux), kqueue (BSD), FSEvents (macOS), ReadDirectoryChangesW (Windows)

​
Native Modules and Addons

Node.js supports extending functionality through native C++ addons.

​
Internal Bindings

Node.js core uses internal bindings to expose C++ functionality to JavaScript: 
// From lib/timers.js
const binding = internalBinding('timers');
const { immediateInfo } = binding;
These bindings are registered in the C++ layer: 
// From src/node_binding.cc
static void RegisterBuiltinModules() {
  NODE_BUILTIN_MODULES(V)
}
Internal bindings are private APIs not exposed to userland. They provide the bridge between JavaScript core modules and C++ implementations.

​
N-API (Node-API)

N-API is the stable API for building native addons, designed to be ABI-stable across Node.js versions: 
// From src/js_native_api_v8.cc
napi_status napi_create_function(napi_env env,
                                  const char* utf8name,
                                  size_t length,
                                  napi_callback cb,
                                  void* data,
                                  napi_value* result) {
  // Implementation
}

​
Addon Architecture

  1. Module loads via require('addon.node')
  2. Node.js calls dlopen() to load the shared library
  3. Addon’s NAPI_MODULE_INIT macro registers the module
  4. Node.js creates JavaScript wrapper around C++ exports
  5. Module becomes available to JavaScript code

​
Environment and Realm

Node.js uses the concept of Environment and Realm to manage execution contexts:

​
Environment (env.h)

The Environment class represents the state of a Node.js instance: 
// From src/env.h
class Environment : public MemoryRetainer {
 public:
  inline uv_loop_t* event_loop() const;
  inline v8::Isolate* isolate() const;
  // ... many other methods
};
Each Environment contains:
  • Reference to the V8 isolate
  • libuv event loop
  • Async hooks state
  • Module loading state
  • Performance timing data

​
Realm (node_realm.h)

Realms represent separate JavaScript execution contexts: 
// From src/node_realm.h
class Realm : public MemoryRetainer {
 public:
  inline v8::Local<v8::Context> context() const;
  // Principal realm, shadow realm support
};
Worker threads each have their own Environment, while ShadowRealms share an Environment but have separate Realm instances.

​
Process Lifecycle

The Node.js process goes through several phases:
1

Initialization

  • Initialize V8 platform and isolate
  • Set up libuv event loop
  • Load internal bindings
  • Initialize environment
2

Bootstrap

  • Load pre-execution modules
  • Set up process object
  • Initialize module system
  • Load user script
3

Execution

  • Run user code
  • Process event loop
  • Handle async callbacks
  • Execute microtasks
4

Teardown

  • Emit ‘exit’ event
  • Clean up resources
  • Dispose V8 isolate
  • Close event loop

​
Memory Management

Node.js uses V8’s garbage collector with additional memory tracking:

​
Heap Structure

  • New Space: Young generation (short-lived objects)
  • Old Space: Long-lived objects
  • Large Object Space: Objects larger than 512KB
  • Code Space: JIT compiled code

​
External Memory

Node.js tracks external memory (Buffers, etc.) and reports it to V8: 
// From src/node_buffer.cc
env->isolate()->AdjustAmountOfExternalAllocatedMemory(length);
Buffer allocations are external to V8’s heap. Large Buffer allocations may not trigger garbage collection immediately, potentially leading to memory issues.

​
Platform-Specific Implementations

Node.js handles platform differences through:
  • Conditional compilation: #ifdef blocks in C++ code
  • Platform modules: Windows vs Unix implementations
  • libuv abstractions: Unified API across platforms
Key platform files:
  • src/node_platform.cc - Threading and task scheduling
  • src/node_file.cc - File system operations with platform-specific syscalls