Beyond the browser: Node.js, Deno & Bun

JavaScript outside the browser

So far, most of your JavaScript has run in a browser page. But JavaScript also runs on servers, in command-line tools, and on servers close to the people who use a website. This lesson shows what changes when JavaScript leaves the browser page.

Two earlier lessons set this up. In Engines, runtimes & hosts, you met the engine: the part that runs the JavaScript language. Chrome's engine is called V8. In Runtime overview, you saw how the engine, the host, and the event loop work together.

The table compares five runtimes. Read one row at a time: what runs the code, which extra tools it adds, and what people use it for.

Each runtime has a different set of global names. A global is a name you can use anywhere without importing it. A browser page has window, but plain Node.js does not. To check for a name that may be missing, use typeof. It gives the type of a value as a string. For a missing name, it gives "undefined" instead of throwing an error.

console.log(typeof window);
console.log(typeof process);
console.log(typeof globalThis);

In a browser page, line 1 prints object and line 2 prints undefined. Node.js prints them the other way round: undefined, then object. Line 3 prints object in both, because globalThis is the global object in every modern runtime.

This check is a clue, not proof. For example, a web worker is a script that runs in the background of a browser page. It is in a browser, but it has no window either.

Keep one rule in mind: code written only for Node.js does not run in a browser. So in this lesson, you can't run the Node.js, Deno, Bun, and terminal examples on the page. Instead, the lesson's tests run the Node.js examples in real Node.js to check what they print.

Node.js is not a new language. It runs normal JavaScript, outside a browser. It is built from these parts:

• V8 is the engine. It runs the language. Chrome uses the same engine.
• libuv is a helper library. It lets Node.js wait for files and network data without stopping other work.
• Built-in modules are ready-made tools for files, paths, and the computer. A module is a file of code you can import.
• npm is a huge online collection of packages. A package is code that someone wrote and shared. The npm & package.json lesson covers it.

Plain Node.js has no window, no document, and no page elements. Use globalThis when you need the global object. That name works in browsers and in Node.js. Use process for facts about the running Node.js program.

A command-line tool (CLI) is a program you start by typing a command in a terminal. In a Node.js CLI, process.argv is an array of the words in the command that started the program. process.env holds environment variables: named settings from the terminal, always stored as strings.

To try the code below, run it with node --input-type=module -e and put tea as the last word of the command. It can't run on this page.

process.env.RUNTIME_LESSON_NAME = "tea";
console.log(process.argv.slice(1).join(","));
console.log(typeof process.env.RUNTIME_LESSON_NAME);

Line 1 sets a sample environment variable. Line 2 prints tea, the last word of the command. Line 3 prints string, because environment variables are always strings. So check and convert a value before you use it as a number or as true or false. For example, the string "false" is truthy: an if treats it as true.

Node.js has many built-in modules. The table lists the ones that tools and servers use most. Each row says what one module lets you do.

The script below uses several of these modules. It reads a word from the command, writes a file, reads it back, and builds a file path. It can't run on this page, because the page runs in a browser, not in Node.js.

1import { readFile, writeFile } from "node:fs/promises";2import path from "node:path";3import os from "node:os";4 5process.env.RUNTIME_LESSON = "Node.js";6const name = process.argv[1] ?? "friend";7const file = path.join(process.cwd(), "message.txt");8 9await writeFile(file, `Hello ${name} from ${process.env.RUNTIME_LESSON}`);10const text = await readFile(file, "utf8");11process.exitCode = text.includes(name) ? 0 : 1;12 13console.log(path.basename(file));14console.log(text);15console.log(os.platform().length > 0);

• Line 1 imports readFile and writeFile. They read and write files, and they return promises.
• Line 2 imports path. Line 7 uses path.join to build a file path. It puts the right separator between the parts: / on Mac and Linux, \ on Windows.
• Line 6 reads the first word typed after the code, from process.argv.
• Lines 9 and 10 write the message to a file and read it back.
• Line 11 sets process.exitCode. An exit code is a number a program reports when it ends: 0 means success, and any other number means failure. Setting it does not stop the script.

Node.js has two ways to split code into modules. The code below shows both, doing the same job.

1// ECMAScript module2import { readFile } from "node:fs/promises";3export async function loadConfig(file) {4  return JSON.parse(await readFile(file, "utf8"));5}6 7// CommonJS module8const { readFileSync } = require("node:fs");9module.exports.loadConfigSync = (file) => {10  return JSON.parse(readFileSync(file, "utf8"));11};

• The top half is an ES module (ESM), the standard JavaScript module system. Line 2 uses import, and line 3 uses export.
• The bottom half is CommonJS, the older Node.js module system. Line 8 uses require, and line 9 uses module.exports.

Node.js supports both. The CommonJS & ESM lesson explains how Node.js picks between them.

Many Node.js programs are command-line tools. Node.js gives such a tool four things:

• the words typed in the command, in process.argv
• the environment variables, in process.env
• the folder the command was typed in, from process.cwd()
• a way to report success or failure, with process.exitCode

The parser below turns command words into an object. It uses no Node.js tools, so you can step through it here in the browser. In a real Node.js tool, you would pass it process.argv.slice(2): the words after node and the script name.

1function parseArgs(argv) {Run2  const options = { _: [] };3  for (const token of argv) {4    if (token.startsWith("--")) {5      const [key, value = "true"] = token.slice(2).split("=");6      options[key] = value;7    } else {8      options._.push(token);9    }10  }11  return options;12}13 14const parsed = parseArgs(["build", "--watch", "--out=dist"]);15console.log(JSON.stringify(parsed));

1function parseArgs(argv) {2  const options = { _: [] };3  for (const token of argv) {4    if (token.startsWith("--")) {5      const [key, value = "true"] = token.slice(2).split("=");6      options[key] = value;7    } else {8      options._.push(token);9    }10  }11  return options;12}13 14const parsed = parseArgs(["build", "--watch", "--out=dist"]);15console.log(JSON.stringify(parsed));

Reading a whole file at once is fine for a small settings file. For big files, such as logs or uploads, use a stream. A stream hands you the data in small pieces, called chunks, one after another. Your program never has to hold the whole file in memory.

The Streams & progress lesson covers browser streams in depth. Node.js has two kinds of stream: its own older streams, and the web streams that browsers use.

1import { createReadStream } from "node:fs";2import { writeFile } from "node:fs/promises";3import path from "node:path";4 5const file = path.join(process.cwd(), "access.log");6await writeFile(file, "GET /a\nGET /b\nGET /c\n");7 8let chunks = 0;9let characters = 0;10for await (const chunk of createReadStream(file, { encoding: "utf8", highWaterMark: 8 })) {11  chunks += 1;12  characters += chunk.length;13}14 15console.log(`${chunks} chunks`);16console.log(`${characters} characters`);

• Line 6 writes a small log file. It has 21 characters.
• Line 10 opens a stream that hands out 8 bytes at a time. The for await loop waits for each chunk, then runs its body once per chunk.
• Lines 11 and 12 count the chunks and the characters.
• Lines 15 and 16 print 3 chunks and 21 characters.

In a real program, the loop body might read one row of a spreadsheet file, or send each chunk on to a web response.

Web streams are the streams that browsers use. They are different from the older Node.js streams. A Response is an object that holds a web response: a status number, headers, and a body. A Response can read a web ReadableStream directly. This example works in browsers and in modern Node.js.

const stream = new ReadableStream({
  start(controller) {
    controller.enqueue(new TextEncoder().encode("tea"));
    controller.close();
  },
});
new Response(stream).text().then((text) => console.log(text));

Line 3 turns tea into bytes with TextEncoder, because a Response body is made of bytes, not strings. Line 4 closes the stream: no more chunks are coming. Line 7 reads the whole body as text and prints tea.

Reading everything with text() is fine for a tiny body. For a large body, read it chunk by chunk instead.

The next script does three more Node.js jobs. It makes a hash, starts a second program, and runs a tiny web server.

1import { spawnSync } from "node:child_process";2import { createHash } from "node:crypto";3import http from "node:http";4 5const digest = createHash("sha256").update("runtimes").digest("hex").slice(0, 8);6const child = spawnSync(process.execPath, ["-e", "process.exitCode = 7"]);7const server = http.createServer((request, response) => {8  response.end(`ok ${request.url}`);9});10 11await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));12const address = server.address();13const body = await new Promise((resolve, reject) => {14  http.get({ host: "127.0.0.1", port: address.port, path: "/health" }, (response) => {15    let data = "";16    response.setEncoding("utf8");17    response.on("data", (chunk) => { data += chunk; });18    response.on("end", () => resolve(data));19  }).on("error", reject);20});21await new Promise((resolve) => server.close(resolve));22 23console.log(digest);24console.log(child.status);25console.log(body);

• Line 5 uses the crypto module to make a hash: a short fingerprint of some text. Line 23 prints its first 8 characters, 8166e7dd.
• Line 6 starts a child process: a second program, started by this one. The child sets its exit code to 7, so line 24 prints 7.
• Lines 7 to 21 start a small web server, send it one request for /health, and close it. Line 25 prints the server's reply, ok /health.

Line 5 uses the older Node.js crypto module. The section on shared web APIs shows Web Crypto, the version that browsers also have.

Deno and Bun are two more runtimes for servers and tools. This lesson can't run them, so it shows no made-up output and no speed numbers. The commands below show what you would type. They follow the official Deno and Bun documentation.

Deno: safe by default and close to the web

Deno has these main features:

• It uses V8, the same engine as Node.js and Chrome.
• It is secure by default. A script can't read files, use the network, read environment variables, or start other programs until you allow it.
• It runs TypeScript files directly, with no extra setup. TypeScript is JavaScript with types added.
• It has the same web APIs that browsers have, such as fetch.
• It can import npm packages with an npm: prefix.
• It keeps project settings and tasks in a deno.json or deno.jsonc file.

You allow access with a permission flag on the command, such as --allow-read for files or --allow-net for the network. If a flag is missing and you are at a terminal, Deno may ask you. If no one can answer, as on a server, the action fails instead.

1deno run main.ts2deno run --allow-read=./data main.ts3deno run --allow-net=api.example.com server.ts4deno run -A trusted-tool.ts

• Line 1 has no flags, so the script gets no access to files or the network.
• Line 2 lets the script read only the ./data folder.
• Line 3 lets the script talk only to api.example.com.
• Line 4 uses -A, which allows everything, even starting other programs. Use -A only for code you trust.

Give a tool only the folder or website it needs. A script can also check a permission without asking for it:

const read = await Deno.permissions.query({ name: "read", path: "./data" });
if (read.state !== "granted") {
  console.log("No access to ./data yet");
}

Line 1 asks whether the script may read ./data. The answer has a state: granted, prompt, or denied. Line 2 checks for anything other than granted, so line 3 prints a message only when access is missing.

This code runs in Deno, not on this page. Checking a permission does not grant it. Also, every module your script imports gets the same permissions as the script.

A deno.json file keeps a project's settings in one place:

1{2  "tasks": {3    "start": "run --allow-read=./data --allow-net=api.example.com main.ts"4  },5  "imports": {6    "@std/path": "jsr:@std/path",7    "chalk": "npm:chalk@^5.0.0"8  },9  "compilerOptions": {10    "strict": true11  }12}

• Lines 2 to 4 make a task named start, with its permission flags.
• Line 6 links the name @std/path to a package on JSR, a package site made for Deno.
• Line 7 links the name chalk to a package on npm.
• Lines 9 and 10 turn on strict TypeScript checks.

Bun: one tool that does many jobs

Bun uses JavaScriptCore, the engine from Safari, instead of V8. Bun is four tools in one:

• a runtime that runs your code
• a package manager that installs packages
• a bundler that joins many code files into a few files for the browser
• a test runner that runs your tests

Bun also works to run code written for Node.js. Choose Bun because of these facts. Don't choose it from speed numbers copied from the internet, because those change with each version and each task.

1bun run index.ts2bun test3bun build ./src/app.ts --outdir=dist4bun add zod

Line 1 runs a file. Line 2 runs the tests. Line 3 bundles src/app.ts into the dist folder. Line 4 installs the zod package.

Bun also has its own global object, Bun. Use it only in code meant for Bun. Code that should also run in browsers or Node.js should use an API they all share, or keep the Bun part in a separate file.

const file = Bun.file("./cart.json");
if (await file.exists()) {
  const cart = await file.json();
  console.log(cart.items.length);
}

Line 1 points at a local file, cart.json. Line 2 checks that the file exists. Line 3 reads the file and turns its JSON into an object. Line 4 prints how many items the cart has. This code runs only in Bun, and what it prints depends on the file.

An edge runtime runs your code on many servers around the world, close to the people who use a site. Examples are Cloudflare Workers, Vercel Edge Functions, Netlify Edge Functions, and Deno Deploy.

Edge code is different from a normal Node.js program:

• It usually can't read or write files on the server.
• It is a small request handler: a function that gets a Request and returns a Response.
• It usually runs in an isolate: a small, sealed-off space inside the engine, kept apart from other people's code.

1function handleRequest(request) {Run2  const url = new URL(request.url);3  if (url.pathname === "/api/greet") {4    const name = url.searchParams.get("name") || "friend";5    return Response.json({ message: `Hello ${name}` }, {6      headers: { "x-runtime": "web-compatible" },7    });8  }9  return new Response("Not found", { status: 404 });10}11 12const request = new Request("https://lesson.test/api/greet?name=Ada");13const response = handleRequest(request);14console.log(response.status);15console.log(response.headers.get("x-runtime"));

1function handleRequest(request) {2  const url = new URL(request.url);3  if (url.pathname === "/api/greet") {4    const name = url.searchParams.get("name") || "friend";5    return Response.json({ message: `Hello ${name}` }, {6      headers: { "x-runtime": "web-compatible" },7    });8  }9  return new Response("Not found", { status: 404 });10}11 12const request = new Request("https://lesson.test/api/greet?name=Ada");13const response = handleRequest(request);14console.log(response.status);15console.log(response.headers.get("x-runtime"));

Not every response has a body. When a request works but there is nothing to send back, return status 204, which means "no content". Give it a body of null. You can test Request and Response objects in a browser or in Node.js, without putting any code on an edge platform.

const request = new Request("https://shop.test/cart");
const response = new Response(null, { status: 204, headers: { "x-cart-state": "empty" } });
console.log(new URL(request.url).pathname);
console.log(response.status);
console.log(response.headers.get("x-cart-state"));
console.log(response.body === null);

Line 1 makes a request for /cart. Line 2 makes a response with status 204, no body, and one custom header. Lines 3 to 6 print /cart, 204, empty, and true.

A 204 response must have no body. Passing a body with status 204 throws a TypeError. Each edge platform also has its own way to connect your handler to incoming requests.

Edge platforms set strict limits on purpose. Expect these:

• a limit on CPU time and memory for each request
• no local files
• no child processes
• only some of the Node.js built-in modules, or none

The exact limits depend on the platform and the price plan. So keep the work for each request short, send data as a stream when you can, and save data in the platform's storage, not on a local disk.

1export default {2  fetch(request, env, ctx) {3    return handleRequest(request);4  },5};6 7function handleRequest(request) {8  const country = request.headers.get("cf-ipcountry") || "unknown";9  return new Response(`Hello ${country}`, {10    headers: { "content-type": "text/plain" },11  });12}

• This code is in the style of Cloudflare Workers. For each request, the platform calls the fetch method on line 2.
• Line 3 passes the request to handleRequest, which returns a Response.
• Line 8 reads a header that the platform adds: the visitor's country.
• The env argument holds the platform's bindings. A binding is a link to the platform's storage or settings, handed to your code as an object.

handleRequest uses only shared web APIs. So you can reuse it on other runtimes, and test it without the platform.

Modern runtimes share more APIs than they used to. These work in browsers, Node.js, Deno, Bun, and most edge runtimes:

• requests and responses: fetch, Request, Response, Headers
• web addresses: URL, URLSearchParams
• data: web streams, TextEncoder, structuredClone
• security: Web Crypto, such as crypto.subtle and crypto.randomUUID
• timing and events: AbortController, setTimeout, EventTarget

A standards group works on this shared list. It is called WinterTC, and its official name is Ecma Technical Committee 55 (TC55). Ecma is the same group that publishes the JavaScript standard. WinterTC grew out of an earlier community group called WinterCG.

In December 2025, WinterTC published ECMA-429, the Minimum Common Web API. It lists the web APIs that server runtimes should all have. It is a goal for runtimes, not a promise that every runtime has every API in the list above. So check the runtime and version you will use for the exact API you need.

When your code needs one feature, use feature detection: check that the feature exists. Don't guess from the runtime's name. The code below checks that fetch is a function. It also shows that the page (document) and the running program (process) are two separate tools.

console.log(typeof fetch === "function");
console.log(typeof document === "object");
console.log(typeof process === "object");

In a browser page, lines 1 to 3 print true, true, false. In Node.js 22, they print true, false, true. Some cases are less clear:

• A web worker has fetch but no document.
• A platform can have a fetch that follows different network rules.
• In Deno, finding fetch does not give you permission to use the network.

1const request = new Request("https://lesson.test/search?q=edge");2const url = new URL(request.url);3const bytes = new TextEncoder().encode(url.searchParams.get("q"));4const copy = structuredClone({ q: url.searchParams.get("q"), bytes: bytes.length });5const response = new Response("ok", { headers: new Headers({ "x-api": "fetch" }) });6const stream = response.body;7const controller = new AbortController();8const target = new EventTarget();9let heard = false;10target.addEventListener("done", () => { heard = true; });11target.dispatchEvent(new Event("done"));12 13console.log(`${copy.q}:${copy.bytes}:${response.headers.get("x-api")}`);14console.log(stream instanceof ReadableStream);15console.log(typeof crypto.subtle?.digest);16console.log(crypto.randomUUID().length === 36);17console.log(controller.signal.aborted);18console.log(heard && typeof setTimeout === "function" && typeof fetch === "function");

An AbortController lets your code say that some work is no longer needed. You pass its signal to an API that can stop early, such as fetch. Aborting stops the work on your side. It does not promise that the server stopped too.

const controller = new AbortController();
controller.abort();
console.log(controller.signal.aborted);

Line 1 makes a controller. Line 2 aborts it. Line 3 prints true, because the signal is now aborted. You don't need a network request to see this.

Where you’ll use runtime knowledge

Real projects often use more than one runtime. Build tools and CLIs run in Node.js, Deno, or Bun. Web apps run in browsers. Server code may run in Node.js or on an edge platform. Some packages even ship one version for browsers and another for Node.js.

• CLIs: read process.argv, check the flags, set process.exitCode, and stream the output.
• Build tools: read project files, start compilers as child processes, hash files, and write bundles.
• Servers: use the Node.js http module, or a framework built on it, for code that keeps running.
• Edge pages: read a Request, read a platform binding, and quickly return a small Response made for that visitor.
• Shared helpers: use URL, Request, web streams, and Web Crypto when the code should run anywhere.

Common misconceptions

• “JavaScript outside the browser can use the DOM.” The DOM is the page, and only a browser page has one. A server can read HTML with a library, but it has no real page by default.
• “Node.js built-in modules are part of JavaScript.” Names like fs, path, and child_process are tools that Node.js adds. The language itself doesn't have them.
• “Deno and Bun are just Node.js with new commands.” They make different choices: Deno asks for permissions, and Bun uses a different engine and bundles many tools.
• “An edge runtime is a full server with no limits.” Edge code runs close to users, but it has strict limits on CPU time, memory, and which APIs it can use.
• “A shared web API works exactly the same everywhere.” The names and shapes match, but each runtime still has its own rules and limits.

The table asks four questions about each runtime. Read down a column to see one runtime, or across a row to compare them.

Key takeaways

• Node.js is the V8 engine plus libuv, built-in modules, process, and npm packages. It is not a browser page.
• Use process.argv, process.env, and process.exitCode in command-line tools. Use streams for big files.
• Deno asks for permissions, runs TypeScript directly, has web APIs, imports npm packages with npm:, and keeps settings in deno.json.
• Bun uses the JavaScriptCore engine. It is a runtime, package manager, bundler, and test runner in one, and it aims to run Node.js code.
• Edge runtimes run small handlers that turn a Request into a Response, with web APIs, platform bindings, and strict limits.
• For code that should run in browsers, Node.js, Deno, Bun, and edge runtimes, start with the shared web APIs.

Up next: Unit testing.