Understanding the Node.js Runtime Environment

Run these five lines in Node.js and in a browser console, and the answers differ:

console.log(typeof window);    // the browser's global object
console.log(typeof document);  // the web page
console.log(typeof process);   // the running Node.js program
console.log(typeof require);   // the CommonJS module loader
console.log(globalThis === global);

Node.js prints:

undefined
undefined
object
function
true

The language is the same in both places, but the objects around it are not. Everything that your code can use besides the language itself is provided by the runtime environment. This lesson explains what the Node.js runtime environment contains and how its parts work together when your code reads a file.

What Changes from the Browser

A browser builds its environment around a web page. It provides window for the browser tab, document for the page content, and functions such as fetch and setTimeout. It also keeps the page away from your files, because the page comes from a website that you may not trust.

Node.js builds its environment around a program running on your computer. It has no page, so window and document do not exist. Instead it provides process, which describes the running program, and require, which loads modules. The global object is called global, and the standard name globalThis points to it, just as globalThis points to window in a browser. Some functions, such as setTimeout and console.log, exist in both environments, and fetch is also global in Node.js 18 and later.

The larger difference is access. A Node.js program can read and write any file that your user account can, open network ports, and start other programs. That access is the reason Node.js can be a web server, and it is also the reason to run only code that you trust.

The Parts of the Runtime

A runtime is made of several parts that each have one job. They are easiest to understand by following one operation through them. The running example is a script that reads a file:

const fs = require('fs');

fs.readFile('notes.txt', 'utf8', (err, text) => {
  console.log('File contents:', text);
});

console.log('Reading started');

When notes.txt contains the line Buy milk, the script prints the last line of its code first:

Reading started
File contents: Buy milk

Five parts take part in running it, in this order.

1. V8 runs your JavaScript. V8 is the JavaScript engine from Google's Chrome browser. It first translates your code into a compact form called bytecode and runs that bytecode with an interpreter named Ignition. When a function runs often, V8 compiles it into machine code for your processor with its just-in-time (JIT) compilers, the fastest of which is named TurboFan. V8 knows the JavaScript language but nothing about files or networks.

2. A built-in module receives the request. The call to fs.readFile goes to the fs module, one of the modules that come with Node.js. Its JavaScript code passes the request to C++ code inside Node.js, which is the part that is able to talk to the operating system.

3. libuv performs the operation. libuv is a C library inside Node.js that handles all I/O and contains the event loop. For network connections, libuv asks the operating system to report when data arrives, and nothing waits on a thread. Many operating systems have no such non-blocking method for files, so libuv reads files on a small group of background threads called the thread pool. Meanwhile fs.readFile has already returned, and V8 runs the next line, which prints Reading started.

4. The event loop queues the callback. When the read finishes, libuv records the event. The event loop sees it the next time it checks for finished work.

5. V8 runs the callback. The event loop calls your callback on the main thread, and V8 runs it with the file contents in text.