Skip to content

Topics

Jump to a topic.

Search questions

Find a question by title, tag, or summary.

Why is the Edge Runtime deprecated, and what did it trade away?

Questions in this chapter (5)
  • Draft
  • medium
  • Askedoften
  • Verified November 2026

Answer

The Edge Runtime is a sandbox with web APIs only: fetch, Request/Response, streams, crypto.subtle, TextEncoder, plus an AsyncLocalStorage polyfill. It was designed to start fast close to users. You opted a page, layout or route handler into it with export const runtime = 'edge'.

The deprecation. It landed in v16.3.0 (PR #93369; v16.2.0 doesn't contain it). The PR's whole rationale is that Edge "is being deprecated in favor of the Node.js runtime (the default)", and the message page says to delete the export, since "no replacement is needed". Neither names a removal version. What the docs show is that new work targets Node.js: Proxy runs only on Node.js since 16, and Cache Components rejects any runtime export.

What it traded away, measured on Next.js 16.4.5 (next build && next start):

  • Node.js APIs. import { readFileSync } from 'node:fs' or createHash from node:crypto failed the build: Native module not found: node:fs. process.version was undefined, and new Function() threw EvalError: Code generation from strings disallowed for this context.
  • Static generation and ISR. The build warned Using edge runtime on a page currently disables static generation for that page. A page with revalidate = 60 was listed as ƒ and rendered anew on every request, with no Cache-Control header at all.
  • Packages that need Node built-ins or require at runtime.

What still works: edge routes build with a warning and run. next start runs them inside a vm sandbox in its own Node process, so NEXT_RUNTIME was edge.

Example

// app/api/e/route.js — copied to app/api/n/route.js without the runtime line
export const runtime = 'edge';

export async function GET() {
  const hash = await crypto.subtle.digest('SHA-256', new TextEncoder().encode('x'));
  return Response.json({
    runtime: process.env.NEXT_RUNTIME,
    version: typeof process.version,
    secret: process.env.SECRET ?? null,
    sha: new Uint8Array(hash)[0].toString(16),
  });
}

// next build
// ⚠ The Edge Runtime is deprecated. You can use the "nodejs" runtime instead.
//   Learn more: https://nextjs.org/docs/messages/edge-runtime-deprecated
// ├ ƒ /api/e
// ├ ƒ /api/n

// SECRET=s3 next start
// GET /api/e → {"runtime":"edge","version":"undefined","secret":"s3","sha":"2d"}
// GET /api/n → {"runtime":"nodejs","version":"string","secret":"s3","sha":"2d"}

Migrating is deleting the first line: web APIs such as crypto.subtle work the same on Node.js, which adds node:* modules and caching.

Pitfalls

  • Moving an edge runtime export into proxy.js. The build failed: Route segment config is not allowed in Proxy file at "./proxy.js". Proxy always runs on Node.js runtime. Proxy logged NEXT_RUNTIME=nodejs; a middleware.js with the same code logged edge.
  • Turning on Cache Components with edge routes left in. Each failed the build: Route segment config "runtime" is not compatible with `nextConfig.cacheComponents`. Please remove it.
  • Treating local next start as proof that code runs on a real edge platform. With Turbopack, require('fs') inside an edge handler built silently and worked in the local sandbox; with --webpack the build warned Can't resolve 'fs' and the call threw Cannot find module 'fs'.
  • Expecting revalidate to cache an edge page. It was ignored; every request rendered.

Follow-ups

Does middleware.js trigger the Edge deprecation warning?
Not on its own. A build with only middleware.js printed The "middleware" file convention is deprecated. Please use "proxy" instead. The 16.0 release post says middleware stays for Edge use cases but will be removed in a future version.
Is preferredRegion affected?
Yes. PR #93369 deprecated it in the same change, because it only applied to Edge routes; it has its own message page and build warning.
Why did Edge routes ever exist, then?
The Next.js 14 docs pitched it for "dynamic, personalized content at low latency with small, simple functions", starting faster than Node.js functions on platforms that deploy each route separately. Self-hosted there was no such gain: the handler ran in a sandbox inside the same Node process.

Comments

Comments are GitHub Discussions: you sign in with GitHub to post or react.