Switchable Runtime (Alpha)

Next.js has two server runtimes to run your application: the Node.js Runtime (default) and the Edge Runtime. When server-rendering or serving API routes, the application code will be executed in the Node.js Runtime by default; and for Middleware, it will be running in the Edge Runtime.

Node (server)Node (lambda)Edge
Cold Boot/~250msInstant
HTTP StreamingYesNoYes
IOAllAllfetch
Scalability/HighHighest
SecurityNormalHighHigh
LatencyNormalLowLowest
Code Size/50MB1MB
NPM PackagesAllAllA smaller subset

Next.js' default runtime configuration is good for most use cases, but there’re still many reasons to change to one runtime over the other one. For example, to enable React 18's SSR streaming feature, you need to use a runtime that is compatible with Web Streams. For API routes that rely on native Node.js APIs, they need to run with the Node.js Runtime. However, if an API only uses something like cookie-based authentication, using Middleware and the Edge Runtime will be a better choice due to its lower latency as well as better scalability.

Starting with 12.2, Next.js enables you to customize the runtime for each Next.js route, for both Pages and API routes.

Global Runtime Option

You can set the experimental option runtime to either 'nodejs' or 'experimental-edge' in your next.config.js file:

// next.config.js
module.exports = {
  experimental: {
    runtime: 'experimental-edge',
  },
}

This option determines which runtime should be used as the default rendering runtime for all pages.

You can detect which runtime you're using by looking at the process.env.NEXT_RUNTIME Environment Variable during runtime, and examining the options.nextRuntime variable during webpack compilation.

Page Runtime Option

On each page, you can optionally export a runtime config set to either 'nodejs' or 'experimental-edge':

// pages/index.js
export default function Index () { ... }

export function getServerSideProps() { ... }

export const config = {
  runtime: 'experimental-edge',
}

When both the per-page runtime and global runtime are set, the per-page runtime overrides the global runtime. If the per-page runtime is not set, the global runtime option will be used.

Edge API Routes

Edge API Routes enable you to build high performance APIs with Next.js using the Edge Runtime.

export const config = {
  runtime: 'experimental-edge',
}

export default (req) => new Response('Hello world!')

Related