When you write server-side code in Next.js (like Route Handlers or Server Components), you have a choice of two environments, or "runtimes," where that code can execute.

1. The Serverless Runtime (Default)

This is the traditional server environment you're likely familiar with.

  • Where it runs: Your code is deployed as a "Serverless Function" to a single, specific cloud data center region (e.g., us-east-1 on AWS).
  • Key Characteristics:
  • Full Node.js Compatibility: You have access to all Node.js APIs and can use any npm package that relies on them (e.g., database drivers like Prisma, libraries that use the fs module).
  • Longer Timeouts: Functions can typically run for longer (e.g., 15-60 seconds), making them suitable for heavier computational tasks.
  • "Cold Starts": If the function hasn't been used recently, there can be a small delay (from milliseconds to a few seconds) on the first request while the environment spins up.
  • Higher Latency for Global Users: A user in Australia making a request to your server in the US will experience higher network latency.

Best for: Heavy data processing, generating large files, connecting to traditional databases, or using native Node.js dependencies.

2. The Edge Runtime

This is a newer, lightweight runtime designed for speed and low latency.

  • Where it runs: Your code is deployed to a global Edge Network (a distributed network of servers around the world, like a CDN). When a user makes a request, the code runs in the data center physically closest to them.
  • Key Characteristics:
  • Extremely Low Latency: Since the code runs close to the user, network travel time is minimized, resulting in very fast responses.
  • No Cold Starts: Edge functions are optimized to start instantly.
  • Limited Runtime: It does not support native Node.js APIs. It's a subset of browser APIs (like fetch, Request, Response). This means some npm packages may not work.
  • Shorter Timeouts: Functions have very short execution limits (typically under a few seconds).

Best for: Middleware, authentication checks, A/B testing, API routes that need to be fast (like fetching personalization data), and anything where low latency is critical.

How to Choose the Runtime

By default, all your server-side code uses the Serverless runtime. To opt a specific Route Handler or page into the Edge runtime, you export a constant:

Code Example (app/api/hello-edge/route.js):

JavaScript


import { NextResponse } from 'next/server';

// This line tells Next.js to deploy this function to the Edge Runtime
export const runtime = 'edge';

export async function GET(request) {
  // This code will run in the data center closest to the user
  return new NextResponse('Hello from the Edge!');
}

You can mix and match runtimes within the same application. Your /dashboard page might use the Serverless runtime to connect to your primary database, while your /api/feature-flags endpoint uses the Edge runtime to deliver configuration to users instantly.