0Pricing
Next.js 15 Fullstack (App Router + Server Actions) · Lesson

Node Runtime vs Edge Runtime Tradeoffs

Choose between Node and Edge per-route based on cold starts, APIs available, and geographic latency.

Node Runtime vs Edge Runtime Tradeoffs is a free Next.js 15 Fullstack (App Router + Server Actions) lesson on CoddyKit — lesson 2 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the Next.js 15 Fullstack (App Router + Server Actions) learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

Two Runtimes, One Route Handler

In Next.js 15, every Route Handler (app/api/.../route.ts) runs on one of two runtimes: the Node.js runtime (the default) or the Edge runtime.

  • Node runtime — a full Node.js server. Access to all Node APIs, npm packages, file system, TCP sockets.
  • Edge runtime — a lightweight V8-based environment (Web APIs only) that deploys to many locations close to your users.

You pick the runtime per route with a single export, so different endpoints in the same app can use different runtimes.

// app/api/hello/route.ts
import { NextResponse } from 'next/server';

// Opt this route into the Edge runtime
export const runtime = 'edge';

export async function GET() {
  return NextResponse.json({ message: 'Hello from the Edge' });
}

The Default Is Node

If you do not set runtime, the handler runs on the Node.js runtime. This is the safe default for most fullstack work because it supports your database drivers, ORMs (Prisma, Drizzle), and any npm library.

You only opt into Edge when its specific benefits (low latency, fast cold starts, geographic distribution) matter more than the APIs you'd give up.

// app/api/users/route.ts
import { NextResponse } from 'next/server';
import { db } from '@/lib/db'; // e.g. Prisma / Drizzle

// No runtime export => Node.js runtime (default)
export async function GET() {
  const users = await db.user.findMany();
  return NextResponse.json(users);
}

Cold Starts: Why Edge Feels Faster

A cold start is the delay when a serverless function has to boot before handling a request.

  • Node functions boot a Node.js process — heavier, slower cold starts (often tens to hundreds of ms).
  • Edge functions run on a V8 isolate that spins up in roughly a millisecond — near-zero cold starts.

For low-traffic or bursty routes (webhooks, auth checks, redirects), Edge avoids the "first request is slow" penalty that Node functions can suffer.

Geographic Latency

Node serverless functions usually run in one region (the region you deployed to). A user in Tokyo hitting a function in Virginia pays a full round-trip across the planet.

Edge functions are replicated globally and run at the location nearest the user. For latency-sensitive, compute-light work this dramatically cuts response time.

Caveat: if your Edge function then calls a database in a single far-away region, you've just moved the latency. Edge wins most when it needs little or no origin data, or talks to a globally distributed data store.

What Edge Can't Do

The Edge runtime exposes only Web standard APIs (fetch, Request, Response, crypto.subtle, TextEncoder, ...). It does not include Node built-ins.

  • No fs, no net, no raw TCP sockets.
  • Native/C++ addon packages won't run.
  • Many database drivers that use TCP (the default pg, mysql2) won't work directly.

If a route imports a library that needs these, keep it on Node.

// This FAILS on the Edge runtime:
// import fs from 'node:fs';   // 'fs' is not available
// import { Pool } from 'pg';  // raw TCP socket not supported

// Edge-friendly work uses Web APIs only:
export const runtime = 'edge';

export async function GET() {
  const data = await fetch('https://api.example.com/feed').then(r => r.json());
  return Response.json(data);
}

Databases on the Edge

Because Edge can't open raw TCP connections, you reach databases over HTTP-based drivers instead.

  • Neon serverless driver (@neondatabase/serverless) — Postgres over HTTP/WebSocket.
  • Vercel Postgres / Turso (libSQL) / Upstash Redis — all HTTP-fetch based.
  • Prisma with its Accelerate or a serverless adapter.

If your stack uses a classic pooled TCP connection, that route belongs on Node.

// app/api/count/route.ts
import { neon } from '@neondatabase/serverless';

export const runtime = 'edge';

const sql = neon(process.env.DATABASE_URL!); // HTTP-based, Edge-safe

export async function GET() {
  const rows = await sql`SELECT count(*) AS total FROM visits`;
  return Response.json({ total: rows[0].total });
}

Streaming and Long Work

Both runtimes can stream responses, but their execution limits differ.

  • Edge is optimized for short, fast responses and streaming (great for proxying AI token streams). It has stricter limits on CPU time and bundle size.
  • Node can run longer, heavier compute and large dependency trees, and supports background-friendly patterns better.

A route that crunches a big payload, generates a PDF, or runs a heavy library should stay on Node.

// Streaming a response works on either runtime
export const runtime = 'edge';

export async function GET() {
  const stream = new ReadableStream({
    start(controller) {
      const enc = new TextEncoder();
      controller.enqueue(enc.encode('chunk-1\n'));
      controller.enqueue(enc.encode('chunk-2\n'));
      controller.close();
    },
  });
  return new Response(stream, { headers: { 'Content-Type': 'text/plain' } });
}

A Pure-Web Snippet You Can Run

Edge code sticks to Web APIs, which means the core logic is plain TypeScript that runs anywhere. Here's a standalone example using crypto.subtle and TextEncoder — exactly the kind of code that's Edge-safe because it needs no Node built-ins.

// Standalone: hash a string using only Web Crypto APIs
async function sha256Hex(input: string): Promise<string> {
  const data = new TextEncoder().encode(input);
  const digest = await crypto.subtle.digest('SHA-256', data);
  return Array.from(new Uint8Array(digest))
    .map((b) => b.toString(16).padStart(2, '0'))
    .join('');
}

async function main() {
  const hash = await sha256Hex('edge-runtime');
  console.log(hash);
}

main();

A Decision Helper

Sometimes it helps to encode the tradeoff as a simple rule. The function below returns a runtime recommendation from a few facts about a route. This is just plain TypeScript logic you can reason about and run.

type RouteNeeds = {
  usesNodeApis: boolean;     // fs, net, native addons
  usesTcpDatabase: boolean;  // classic pg/mysql driver
  latencySensitive: boolean; // users worldwide, light compute
  heavyCompute: boolean;     // big payloads, PDF, large deps
};

function recommendRuntime(r: RouteNeeds): 'node' | 'edge' {
  if (r.usesNodeApis || r.usesTcpDatabase || r.heavyCompute) return 'node';
  if (r.latencySensitive) return 'edge';
  return 'node';
}

console.log(recommendRuntime({ usesNodeApis: false, usesTcpDatabase: false, latencySensitive: true, heavyCompute: false }));
console.log(recommendRuntime({ usesNodeApis: false, usesTcpDatabase: true, latencySensitive: true, heavyCompute: false }));

Mixing Runtimes in One App

The big win of per-route runtimes is that you can mix them. A typical Next.js 15 app might keep:

  • Auth/session checks, redirects, A/B flags, lightweight proxies → Edge.
  • Database writes via Prisma, file processing, third-party SDKs → Node.

Note: Server Actions run on the Node.js runtime in the App Router — the Edge opt-in shown here applies to Route Handlers and Middleware, not to Server Actions.

// app/api/flag/route.ts  -> Edge: fast, global, no DB
export const runtime = 'edge';
export async function GET(req: Request) {
  const country = req.headers.get('x-vercel-ip-country') ?? 'US';
  return Response.json({ promoEnabled: country === 'US' });
}

Reading Edge Geo Context

Edge runs near the user, so it's the natural place for geo-aware logic. On Vercel, geo data arrives as request headers (x-vercel-ip-country, x-vercel-ip-city). You can localize content or redirect without a round-trip to a central server.

If you needed a database lookup for every request, the Edge advantage shrinks — so reserve Edge for cases where the decision is cheap and data is local or cached.

// app/api/welcome/route.ts
export const runtime = 'edge';

export async function GET(req: Request) {
  const country = req.headers.get('x-vercel-ip-country') ?? 'unknown';
  const greeting = country === 'FR' ? 'Bonjour' : 'Hello';
  return Response.json({ greeting, country });
}

Quick Check

Pick the route most appropriate for the Edge runtime.

Recap: Choosing Per Route

You now choose the runtime per route based on real tradeoffs:

  • Edge — near-zero cold starts, global low latency, Web APIs only. Best for lightweight, geo-aware, data-light routes (flags, redirects, auth checks, stream proxies).
  • Node (default) — full Node APIs, npm packages, TCP databases, heavy compute and large dependencies.

Decide with concrete questions: Does it need Node APIs or a TCP DB driver? Is it heavy compute? If yes → Node. Is it light and latency-sensitive worldwide? → Edge. And remember: Server Actions run on Node; the runtime = 'edge' opt-in is for Route Handlers and Middleware.

Frequently asked questions

Is the “Node Runtime vs Edge Runtime Tradeoffs” lesson free?

Yes — the full text of “Node Runtime vs Edge Runtime Tradeoffs” is free to read here on the web, and the Next.js 15 Fullstack (App Router + Server Actions) course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the Next.js 15 Fullstack (App Router + Server Actions) course, upgrade to CoddyKit PRO.

What will I learn in “Node Runtime vs Edge Runtime Tradeoffs”?

Choose between Node and Edge per-route based on cold starts, APIs available, and geographic latency. You practise Next.js 15 Fullstack (App Router + Server Actions) with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start Next.js 15 Fullstack (App Router + Server Actions)?

No prior experience is required. Next.js 15 Fullstack (App Router + Server Actions) on CoddyKit is structured for beginners through advanced learners; this is — lesson 2 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “Node Runtime vs Edge Runtime Tradeoffs” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this Next.js 15 Fullstack (App Router + Server Actions) lesson?

Yes. Every Next.js 15 Fullstack (App Router + Server Actions) lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

  1. Designing RESTful Route Handlers with the Web Request API
  2. Node Runtime vs Edge Runtime Tradeoffs
  3. Streaming Responses and ReadableStream in Handlers
  4. Request Validation and Typed JSON Responses with Zod
← Back to Next.js 15 Fullstack (App Router + Server Actions)