Skip to content
Tutorials Center
My learning

Topics

Lesson 33 of 72 ยท Rendering Strategies

Node.js and Edge Runtimes

Learn the two Next.js runtimes: the full Node.js runtime and the lightweight Edge runtime, what Edge cannot do, how regions matter and when to pick each.

Every piece of server code in a Next.js app has to run somewhere. When a visitor asks for a page or calls a route handler, your code executes inside a runtime: a JavaScript environment with a certain set of built-in APIs and certain limits. Next.js supports two of them. The Node.js runtime is the familiar one, with the full Node standard library. The Edge runtime is a smaller, lighter environment built on web-standard APIs, designed to start almost instantly and to run in many locations around the world.

For most code the choice is invisible, because the default is Node.js and it can do everything. But you will meet the Edge runtime in older tutorials, in hosting dashboards and in the history of middleware, so you should know what it is, what it cannot do, and why the default is usually the right answer. This lesson finishes the rendering chapter. It builds on SSG, SSR, ISR and Streaming Compared, because the runtime decides where and how fast the "R" in each of those strategies happens.

Two runtimes at a glance

Two places your server code can run

Node.js runtime The default. Full Node APIs and npm packages.
Edge runtime A small web-standard sandbox that starts fast.

Same React components, different environment underneath.

1 / 3

The Node.js runtime is a normal Node process on a server (or a serverless function that behaves like one). You can read files, open database connections through any driver, use crypto from the Node standard library, spawn child processes, and install almost any package from npm.

The Edge runtime is closer to a browser service worker than to Node. It exposes the web platform APIs you already know from the browser (fetch, Request, Response, Headers, URL, TextEncoder, Web Crypto, streams) and very little else. The trade is deliberate: because the environment is small, the platform can boot it in milliseconds and replicate it to many data centers.

Choosing a runtime per route

By default every page, layout and route handler uses the Node.js runtime. You opt a segment into Edge with a route segment config export:

TypeScript
// app/api/hello/route.ts
export const runtime = 'edge'; // 'nodejs' is the default

export async function GET(request: Request) {
  return Response.json({ hello: 'from the edge', url: request.url });
}

The export applies to that route segment (a page, layout or route file) and what it renders. A few facts to keep in mind:

  • The value is read at build time, so it must be a plain string literal, not a computed value.
  • A page that uses runtime = 'edge' must not import anything the Edge sandbox lacks, anywhere in its dependency tree. One careless import in a shared helper breaks the build.
  • Features that depend on Node, such as the file system access used by some of the caching and static generation machinery, are not available to Edge routes. The newer caching model built on Cache Components (see The use cache Directive and Cache Components) is documented for the Node.js runtime, so check the current docs before combining it with runtime = 'edge'.
  • The proxy.ts file (called middleware.ts before Next.js 16) is covered in Middleware and the Proxy File. Middleware historically ran on Edge. In Next.js 16 the proxy file runs on the Node.js runtime and the runtime is not configurable there, so much of the old reason to learn Edge limits has gone away.

Real or stand-in? The runtime export above is real Next.js, shown read-only because the site cannot start a Next.js server. The two live examples below are stand-ins: one imitates the build-time check for unsupported imports, and the other is a simple arithmetic model of network latency. They follow the documented ideas but are not the real build or a real network.

What breaks on Edge

Suppose a route handler needs to read a template from disk. On Node.js this just works:

TypeScript
import { readFile } from 'node:fs/promises';

export async function GET() {
  const template = await readFile('templates/welcome.html', 'utf8');
  return new Response(template, { headers: { 'content-type': 'text/html' } });
}

Add export const runtime = 'edge' to that file and the build fails, because there is no fs in the sandbox. The same happens with packages that call fs, net, child_process, or load native add-ons (many database drivers and image libraries fall in this group), and with code that calls eval() or new Function().

This stand-in scans a few small modules the way a build step might and reports which ones could run on Edge. The real check is done by the bundler, which follows every import through your whole dependency graph. Here we only look at one file's own imports and a few dangerous calls.

Node.js Could this module run on the Edge runtime?

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.

Notice lib/greeting.ts passes because next/headers is a framework import, and lib/hash.ts passes because Web Crypto (crypto.subtle) is a web-standard API. Compare that with the Node crypto module: createHash and friends are Node APIs, and their availability on Edge is limited to a small compatible subset, so prefer Web Crypto in code that may run in either place.

Why "closer to the user" is not automatically faster

The big selling point of Edge is location. A Node.js server often runs in one region, for example the US east coast. A visitor in Sydney then pays for a long round trip on every request. Edge code can run in a data center near the visitor, which cuts that distance.

But your code usually needs data, and data lives somewhere. If a function runs in Sydney and your database sits in Virginia, every query now crosses the ocean. A page that makes three sequential queries pays that long trip three times, while a Node.js function placed next to the database pays almost nothing per query and one long trip to the user.

Here is a model that makes this visible. It uses an idealized rule (light in fiber covers about 100 km of round trip per millisecond) and ignores everything else, so treat the numbers as an illustration of the shape, not a benchmark.

Edge near the user vs a server near the database

Leave the visitor in Sydney and set queries to 0: the edge function wins easily because it serves a response without needing any remote data. Raise the queries to 3 and the picture flips, because each query from the edge function travels to Virginia and back. The lesson is not that Edge is slow. It is that the best place to run code is near whatever it talks to most.

Regions and how hosts handle them

Where your Node.js code runs is set by your host, not by Next.js. A few common patterns:

  • A single region, such as one server or one serverless region next to your database. Simple and often fastest for data-heavy pages.
  • Static and cached output on a CDN. Pages produced at build time, or cached responses, are served from locations near the visitor without running your code at all. This is the strongest "edge" benefit and it works with the Node.js runtime. See Static Generation and generateStaticParams.
  • Region pinning. Some hosts let you say where a function should run. On Vercel, for example, a route segment config such as export const preferredRegion = 'iad1' places the function near a database. That option, its values, and whether it applies at all are host-specific, so read your host's documentation.

How to choose

For most apps the answer is: stay on Node.js and put your effort into caching, which gives you the "fast everywhere" result for pages. Reach for Edge only when all of these are true:

  • The code is small and uses only web-standard APIs.
  • It needs little or no data from a far-away database (redirects, header-based routing, simple A/B decisions, personalization from a cookie, calling a globally distributed API).
  • Cold starts or distance to the visitor are measurably a problem for that route.

Keep Node.js when you use a database driver or ORM, read files, use native add-ons, rely on Cache Components, or simply want the fewest surprises. You can mix both in one project, one route at a time.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which runtime does a Next.js route use if you do not configure anything?

    The default is the Node.js runtime. You opt a segment into Edge with export const runtime = 'edge'.
  2. 2. Which of these is NOT available in the Edge runtime?

    Edge exposes web-standard APIs but not the Node file system, network sockets or child processes.
  3. 3. A function runs at the edge in Sydney but makes five queries to a database in Virginia. What is the likely result?

    Being near the visitor does not help when the code spends its time talking to a far-away database. Place compute near its data.
  4. 4. Which approach gives visitors worldwide fast pages without running your code per request?

    Pre-built or cached responses are delivered from locations near the visitor, and this works with the default Node.js runtime.

Summary

  • Next.js can run server code on the Node.js runtime (the default, full Node APIs) or the Edge runtime (a small web-standard sandbox).
  • Set it per segment with export const runtime = 'edge'; the value must be a literal string.
  • Edge lacks the file system, many native Node modules and dynamic code evaluation, and has tight bundle size limits.
  • Running near the visitor only helps if the code does not depend on a distant database; place compute near its data.
  • Caching and static output already give worldwide speed, so stay on Node.js unless a small, data-light route clearly benefits from Edge.
  • In Next.js 16 the proxy file runs on Node.js, so the old Edge-only middleware limits matter less.

Next: Server Actions