Next.js Runtimes: Edge vs. Node.js

WHY IT EXISTS: Not all server-side tasks are equal. Some need raw speed and low latency above all else (like personalization), while others need power and access to a full system environment (like generating a complex report). Next.js provides two runtimes to let developers match the right tool to the right job.

THE MENTAL MODEL: Think of it as choosing between a local convenience store and a central superstore. The Edge runtime is the convenience store: it's right on the corner (close to the user), super fast for grabbing simple items (data), but has a limited selection (no heavy computation or specialized APIs). The Node.js runtime is the superstore: it's further away (centralized server), takes longer to get to, but has everything you could possibly need (full Node.js API, any npm package).

HOW IT WORKS: In a Next.js App Router project, you can specify the runtime for a specific route by exporting a constant. By default, all Route Handlers use the Node.js runtime. To opt into the Edge runtime, you add export const runtime = 'edge'; to your route file. The build tool then packages and deploys that specific function to the appropriate environment—either a standard serverless function or a globally distributed edge network.

WHEN TO USE IT: Use the Edge runtime for tasks where low latency is critical and the logic is simple. Good candidates include: checking authentication tokens, personalizing content based on geolocation, running A/B tests, redirecting users, and streaming data from a database. The goal is to respond to the user as quickly as possible.

WHEN NOT TO USE IT: Stick with the default Node.js runtime when your code needs to perform CPU-intensive tasks, requires long execution times, or depends on native Node.js APIs (like fs for file system access). Many npm packages are built exclusively for the Node.js environment; using them in an Edge function will cause runtime errors. If you're unsure about your dependencies, Node.js is the safer choice.

ONE CANONICAL EXAMPLE: To create an API route that returns the user's city based on their IP address, you would use the Edge runtime for the fastest possible response. In app/api/location/route.ts, you would add the line export const runtime = 'edge'; to ensure it's deployed as a lightweight edge function.