Edge vs Node Runtimes

Your route handler reads a JSON config with fs.readFileSync and works. You copy the same helper into middleware and the build dies before the dev server answers a request. The difference is not your code — it is which of Next.js's two server runtimes executes it.

The Node.js runtime is the default: the full Node standard library, native modules, require, long-running processes, ISR. The Edge runtime is a different animal — the API surface you would get inside a worker/JavaScript isolate: ECMAScript plus Web APIs, no host operating system behind it. The docs are blunt about the boundary: "Native Node.js APIs are not supported. For example, you can't read or write to the filesystem."

What the edge runtime actually provides:

And what it refuses:

• No native Node APIs — fs, net, tls, child_process. No sockets, no disk, no subprocesses.
• No CommonJS require() — ES modules only; node_modules are usable only if they ship ESM and avoid native APIs.
• No dynamic code evaluation — eval, new Function, WebAssembly.compile, and WebAssembly.instantiate are disabled and throw if reached.
• No ISR — the edge runtime does not support incremental static regeneration.
• No fetch caching in proxy — options.cache, options.next.revalidate, and options.next.tags are documented as having no effect there, because there is no shared cache layer behind the isolate.

Those restrictions are the price of the benefit: an isolate cold-starts in single-digit milliseconds and can be instantiated in hundreds of locations near your users, which is why request-level code (the middleware chain from Redirects and Rewrites) was moved onto it. An environment that must spin up per request cannot link a native binary, block on disk I/O, or hold a process open — so it does not let you. A synchronous readFileSync is not merely unsupported but conceptually wrong there: one isolate serves many concurrent requests on a single thread, and a blocking call stalls all of them. Dropping fs entirely is simpler than shipping a half-capable async version. ISR has the same problem — it assumes a persistent filesystem-backed cache and a long-lived process, which is why the docs list it as unsupported.

Where each runtime executes, as of the current conventions:

Two practical consequences. First, unstable_allowDynamic in your proxy/middleware config can silence bundler complaints about dynamic-evaluation code you never execute, but if it does run, it throws — the escape hatch is for dead code paths only. Second, portability cuts both ways: anything you put in a shared module must run under the smaller of the two runtimes, because the same import may be reached from an edge segment and from a Node route handler. The mechanics of picking which runtime a route gets — and the deprecation now reshaping that choice — is the next problem.

A route segment config export tells Next.js which runtime executes one file:

// app/report/route.ts  (or page.tsx / layout.tsx)
export const runtime = 'nodejs'   // default
// export const runtime = 'edge'  // Next.js ≤ 15 — deprecated in 16

The export belongs in page.tsx, layout.tsx, or route.ts, applies to that segment, cascades to everything beneath it, and a child segment may override its parent — so one export const runtime = 'edge' on a layout moves the whole subtree, while a single API route can opt back into Node:

// app/layout.tsx          → every page under it runs on edge (Next.js ≤ 15)
export const runtime = 'edge'

// app/report/route.ts      → this route alone runs Node.js
export const runtime = 'nodejs'

Read that as a policy tool: put the expensive choice on the layout, where it is visible and reviewable in one place, then make narrow exceptions per route instead of sprinkling the export across fifty files.

The version history is the part interviews actually probe, because the rule changed:

On Next.js 16, setting export const runtime in a proxy/middleware file makes the build throw, and keeping 'edge' on a route produces the documented warning — "One or more routes in your application use export const runtime = 'edge', which is deprecated" — whose migration is simply to delete the export, since Node.js is the default. If you still need edge execution, the upgrade guide says to keep the middleware convention rather than renaming it to proxy. The headline: the runtime is chosen by framework convention, and the set of values you may declare is shrinking.

So when does each environment earn its place?

Getting it wrong fails loudly, and each failure has a signature:

One subtlety worth stating: choosing edge never makes your route handler code portable by itself. The handler may use Web APIs happily while the shared module it imports quietly uses Buffer — and the failure surfaces only at build, in the one segment you flipped. The defense is writing shared logic against the smaller runtime, which is what the last chapter covers.

The cheapest way to survive both runtimes is to write shared modules against the edge contract from the start: if it runs on the edge, it runs on Node, but never the reverse. Validation helpers, URL builders, JWT logic, serialization — none of them should know which host they live in.

The translations you will actually use:

A session check illustrates the split. Token verification is pure computation over bytes, so it belongs in a shared module using Web Crypto — the jose package implements exactly that and runs in both runtimes, which is why it is the standard choice inside middleware. Token issuance against a database, password hashing with bcrypt, and anything touching fs stays in a route handler or Server Action running on Node. The middleware makes the cheap decision; the handler does the expensive one:

// lib/session.ts — safe to import from middleware AND from route handlers
import { jwtVerify } from 'jose'
const key = new TextEncoder().encode(process.env.SESSION_SECRET!)
export async function verifySession(token: string) {
  const { payload } = await jwtVerify(token, key)
  return payload.sub as string
}

// app/api/settings/route.ts — Node.js only; never reached from middleware
import { hash } from 'bcrypt'
export async function POST(req: Request) {
  return Response.json({ hash: await hash(await req.text(), 12) })
}

Note where the boundary sits: it is the import graph, not the file you edited. If lib/session.ts ever imports lib/db.ts "just to look up a user", every consumer inherits the database driver — and the edge build fails somewhere you did not touch. Keep the shared layer leaf-only: no side effects at import time, no environment assumptions beyond process.env, no transitive reach into Node territory.

Two habits catch the rest before production does:

1. Audit dependencies for the edge. A grep over the built output says more than the README — flag CommonJS and native touches before they reach the bundle:

   grep -rlE "require\(|process\.binding|readFileSync|child_process" node_modules/acme/dist | head
   

   ESM output alone does not guarantee safety — it must also avoid native APIs.
2. Let next build be your test. Edge-compatible code usually passes unit tests in Node (modern Node ships fetch, crypto.subtle, and TextEncoder, so the test runner is more permissive than the edge), and the mismatch only surfaces when the edge bundle is compiled. Failing the build in CI is the cheap place to find it.

For the escape hatch, config.unstable_allowDynamic globs silence bundler complaints about dynamic evaluation in files you never execute — with the documented caveat that execution on the edge throws. Use it for proven-dead paths, not as a workaround for a dependency you actually call.

Once your code is portable, you can exploit the edge for what it is good at: making a decision per request, near the user, before the first byte of HTML exists. That is A/B Tests and Personalization at the Edge.