Node.js Reference ยท Concepts and Pitfalls
Node.js versus browser APIs
Which globals Node.js shares with browsers, which exist only in one of them, and how to detect the environment and write code that runs in both.
Node.js and browsers run the same language, and a growing set of web-standard APIs is implemented in both: fetch, URL, AbortController, TextEncoder, structuredClone, timers, Blob, web streams and crypto.subtle. What differs is everything tied to a page (the DOM, window, localStorage) on one side and to the machine (files, processes, sockets) on the other.
Knowing exactly where the line falls helps you avoid ReferenceError crashes, choose portable APIs and write libraries that run in both places. This page lists what is shared, what is not, and how to feature-detect safely.
Try 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.
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.
Shared APIs
These are available as globals in current Node.js LTS versions and in modern browsers, with matching behavior for everyday use:
- Network and URLs:
fetch(),Request,Response,Headers,FormData,URL,URLSearchParams,WebSocket(client). - Control flow:
AbortController,AbortSignal,setTimeout,setInterval,queueMicrotask(),Promise. - Data and text:
TextEncoder,TextDecoder,Blob,File,structuredClone(),atob(),btoa(), typed arrays,Intl. - Streams and messaging:
ReadableStream,WritableStream,TransformStream,MessageChannel,BroadcastChannel,EventTarget,Event. - Platform services:
crypto(Web Crypto andrandomUUID()),performance,console,navigator(a small subset in Node).
Node only
| Area | APIs | Why a browser lacks it |
|---|---|---|
| Files and OS | node:fs, node:os, node:path |
Browsers sandbox the machine. |
| Processes | process, node:child_process, node:cluster |
No process control from a page. |
| Raw networking | node:net, node:dgram, node:http servers |
Pages cannot open arbitrary sockets or listen. |
| Binary and modules | Buffer, require, module, __dirname |
Node-specific conventions. |
| Low-level | node:vm, node:worker_threads, node:v8 |
Different threading and engine hooks. |
Browser only
The DOM (document, elements, events such as click), window, location, history, localStorage, sessionStorage, alert(), requestAnimationFrame(), canvas, IndexedDB, geolocation, the clipboard and other permission-gated device APIs. In Node they are undefined; using them throws a ReferenceError.
Same name, different behavior
- Timers. In browsers
setTimeout()returns a number; in Node it returns aTimeoutobject withref(),unref()andhasRef(). Store the value but do not assume its type. globalThis. It iswindowin a page and the Node global object in a process. UseglobalThisin portable code instead ofwindoworglobal.crypto. Both exposecrypto.subtleandgetRandomValues(); Node also has the richernode:cryptomodule (hashes, ciphers, KDFs) with no browser equivalent.fetch(). No CORS rules, no cookie jar and no cache in Node, and you can request any host you can reach. Seefetch().WebSocketandEventSource. Node has a client; the server side needs a module or a library.navigator. Node exposes a few properties such asnavigator.hardwareConcurrencyandnavigator.userAgent(starts withNode.js/); do not useuserAgentfor browser detection.- Modules. Browsers load ES modules by URL; Node resolves bare names (
node:fs, package names) and supports CommonJS too. - Storage. There is no
localStorageby default in Node; code that needs persistence uses files or a database such asnode:sqlite.
Usage notes
- Feature-detect, do not sniff. Check
typeof fetch === 'function'or'document' in globalThisinstead of parsing user agents. - Use
typeoffor globals that may not exist. Reading an undeclared name likewindowthrows;typeof windowis safe. - Prefer the web API when both exist.
fetch,URLandTextEncodermake code portable to browsers, Deno and edge runtimes; reach fornode:http,Bufferornode:urlonly when you need their extras. - Isolate Node-specific code. Put file and process access in separate modules and load them with dynamic
import()behind a guard so bundlers can leave them out of browser builds. - Mind
Buffer. It is aUint8Arraysubclass, so it works whereUint8Arrayis expected, but a browser has noBuffer; useUint8ArrayandTextDecoderin shared code. - Server rendering needs guards. Code that runs during server-side rendering must not touch
windowordocumentat import time. - Watch for newer APIs. Browsers add features faster than Node in some areas and vice versa; check the version notes for each global before relying on it.