Edge Runtime

Core Idea

Next.js has two server runtimes: the default Node.js runtime with full Node API access, and the Edge Runtime, a restricted Web-standard-APIs-only runtime used in Proxy (and legacy edge routes).

Key Concepts

• Node.js Runtime: default; full Node.js API access; renders the application.
• Edge Runtime: limited Web API set, used in Proxy; does not support ISR; no native Node.js APIs (no filesystem access); require is disallowed, must use ES Modules.
• unstable_allowDynamic: Proxy config glob (or array of globs) that whitelists files containing unreachable dynamic code evaluation statements, so Turbopack/webpack don't flag them.
• import.meta.env/Node polyfills: process.env works for both next dev/next build; AsyncLocalStorage is a supported Next.js-specific polyfill.

Code Examples

export const config = {
  unstable_allowDynamic: [
    '/lib/utilities.js',
    '**/node_modules/function-bind/**',
  ],
}

• O que demonstra: como liberar avaliação dinâmica de código em arquivos específicos sem quebrar o build do Edge Runtime.

Reference Tables

API category	Supported examples
Network	fetch, Request, Response, Headers, FormData, Blob, File, WebSocket, FetchEvent
Encoding	atob, btoa, TextEncoder/TextDecoder (+ Stream variants)
Streams	ReadableStream, WritableStream, TransformStream and their readers/writers
Crypto	crypto, CryptoKey, SubtleCrypto
Web Standard	URL, URLPattern, URLSearchParams, Intl, typed arrays, JSON, Promise, structuredClone, standard error types, etc.
Next.js polyfill	AsyncLocalStorage

Unsupported/disabled	Note
Native Node.js APIs	No filesystem access, etc.
require()	Use ES Modules instead
eval, new Function(evalString)	Disabled
WebAssembly.compile / .instantiate	Disabled

Anti-patterns

• Relying on native Node.js APIs (fs, etc.) in Edge code: unsupported entirely; will fail at runtime or build.
• Leaving unreachable dynamic-eval statements unaddressed: they throw at runtime on the Edge even if unreachable in practice — either remove them or whitelist via unstable_allowDynamic, understanding execution still throws.
• Using node_modules packages that rely on native Node APIs: only ESM packages without native Node dependencies work on Edge.

Key Takeaways

1. Edge Runtime is a Web-standard-APIs sandbox, not a subset of Node.js: expect fetch/streams/crypto to work, filesystem and require to fail.
2. ISR is not supported on the Edge Runtime — a hard constraint when choosing a runtime for a route.
3. unstable_allowDynamic only suppresses the build-time warning for unreachable dynamic code; it does not make dynamic eval safe to actually execute on Edge.

Connects To

• ch278 invoking-entrypoints: Edge handler signature and edgeRuntime invocation metadata.
• ch285 glossary: "Proxy" and "Middleware" glossary entries reference the Edge Runtime's primary use case.