Edge Runtime and Frontend Deployment

Introduction#

For most of the history of web development, servers lived in data centers. A request from a user in Jakarta to an application hosted in Virginia would travel thousands of kilometers, wait for the server to process it, and travel back. The round-trip latency was the cost of doing business.

Edge Runtime changes this model fundamentally. Instead of a single server in a single region, Edge Runtime distributes your application logic across dozens or hundreds of nodes globally. The code that handles a request runs in the data center closest to the user, reducing latency from hundreds of milliseconds to single digits.

This is not just a performance optimization. It changes what is architecturally possible for frontend applications and how engineers think about the boundary between client and server.

1. What Edge Runtime Is#

Edge Runtime is a lightweight JavaScript execution environment designed to run at CDN edge nodes. Unlike a traditional Node.js server, Edge Runtime is intentionally constrained. It does not have access to the full Node.js API surface. There is no file system access, no native modules, and limited memory. What it does have is fast startup time, often measured in microseconds rather than the milliseconds of a Node.js cold start, and global distribution.

The major providers of Edge Runtime infrastructure are Vercel Edge Functions, Cloudflare Workers, Deno Deploy, and AWS Lambda@Edge. Each has slightly different API compatibility, but they all converge on the WinterCG specification, a community effort to standardize the subset of Web APIs available in edge environments.

The WinterCG API Surface#

Edge Runtime environments expose a consistent set of Web APIs:

Fetch API: fetch, Request, Response, Headers

Web Crypto: crypto.subtle for encryption and hashing

URL API: URL, URLSearchParams

Encoding: TextEncoder, TextDecoder

Streams: ReadableStream, WritableStream, TransformStream

Timers: setTimeout, setInterval (limited)

Code written against this API surface is portable across edge providers. The constraint is real: you cannot use most npm packages that depend on Node.js built-ins. This forces a more disciplined approach to dependency selection.

2. Edge Middleware#

The most immediately practical application of Edge Runtime for frontend engineers is middleware. Edge middleware runs before a request reaches your application, at the CDN layer, and can inspect, modify, redirect, or rewrite the request with near-zero latency overhead.

Common Middleware Use Cases#

Authentication and authorization checks before serving protected routes

Geolocation-based routing and content personalization

A/B testing by rewriting requests to different page variants

Bot detection and rate limiting

Locale detection and redirect to the appropriate language route

Feature flags evaluated at the edge without a round trip to the application server

Next.js Edge Middleware#

// middleware.ts
import { NextRequest, NextResponse } from "next/server";
import { verifyToken } from "@/lib/auth";

export const config = {
  matcher: ["/dashboard/:path*", "/account/:path*", "/api/protected/:path*"],
};

export async function middleware(request: NextRequest) {
  const token = request.cookies.get("auth_token")?.value;

  if (!token) {
    const loginUrl = new URL("/login", request.url);
    loginUrl.searchParams.set("redirect", request.nextUrl.pathname);
    return NextResponse.redirect(loginUrl);
  }

  const payload = await verifyToken(token);

  if (!payload) {
    const loginUrl = new URL("/login", request.url);
    return NextResponse.redirect(loginUrl);
  }

  // Pass user info to the application via headers
  const response = NextResponse.next();
  response.headers.set("x-user-id",   payload.userId);
  response.headers.set("x-user-role",  payload.role);
  return response;
}

Geolocation-Based Routing#

// middleware.ts
import { NextRequest, NextResponse } from "next/server";

const LOCALE_MAP: Record<string, string> = {
  US: "en-US",
  GB: "en-GB",
  DE: "de",
  FR: "fr",
  JP: "ja",
  ID: "id",
};

export async function middleware(request: NextRequest) {
  const country  = request.geo?.country ?? "US";
  const locale   = LOCALE_MAP[country] ?? "en-US";
  const pathname = request.nextUrl.pathname;

  // Skip if already has a locale prefix
  if (pathname.startsWith(`/${locale}`)) {
    return NextResponse.next();
  }

  // Redirect to locale-prefixed path
  return NextResponse.redirect(
    new URL(`/${locale}${pathname}`, request.url)
  );
}

3. Edge API Routes#

Beyond middleware, Edge Runtime can serve full API routes. These are lightweight handlers that run at the edge and are ideal for use cases that do not require Node.js-specific capabilities.

// app/api/geo/route.ts
import { NextRequest } from "next/server";

export const runtime = "edge";

export async function GET(request: NextRequest) {
  const geo = {
    country: request.geo?.country    ?? "Unknown",
    city:    request.geo?.city       ?? "Unknown",
    region:  request.geo?.region     ?? "Unknown",
    lat:     request.geo?.latitude   ?? null,
    lng:     request.geo?.longitude  ?? null,
  };

  return Response.json(geo, {
    headers: {
      "Cache-Control": "no-store",
    },
  });
}

// app/api/flags/route.ts: Feature flags at the edge
import { NextRequest } from "next/server";

export const runtime = "edge";

const FLAGS = {
  newCheckout:     true,
  aiRecommendations: false,
  betaDashboard:   true,
};

export async function GET(request: NextRequest) {
  const userId = request.headers.get("x-user-id");

  // Deterministic flag evaluation based on user ID
  // No round trip to a feature flag service required
  const userFlags = Object.entries(FLAGS).reduce((acc, [flag, defaultValue]) => {
    acc[flag] = defaultValue;
    return acc;
  }, {} as Record<string, boolean>);

  return Response.json({ flags: userFlags, userId });
}

4. Edge-Compatible Data Access#

The constraint that eliminates most traditional database drivers from edge environments is the lack of persistent TCP connections. Most relational databases use long-lived connection pools. An edge function that spins up in microseconds and handles thousands of concurrent invocations globally cannot maintain a connection pool.

The solution is HTTP-based database access. Several database providers now offer edge-compatible connection methods.

Neon Postgres with HTTP Driver#

// lib/db-edge.ts
import { neon } from "@neondatabase/serverless";

// HTTP-based Postgres driver, compatible with Edge Runtime
const sql = neon(process.env.DATABASE_URL!);

export async function getUserById(id: string) {
  const rows = await sql`
    SELECT id, name, email, role, created_at
    FROM users
    WHERE id = ${id}
    LIMIT 1
  `;
  return rows[0] ?? null;
}

Upstash Redis at the Edge#

// lib/cache-edge.ts
import { Redis } from "@upstash/redis";

const redis = new Redis({
  url:   process.env.UPSTASH_REDIS_URL!,
  token: process.env.UPSTASH_REDIS_TOKEN!,
});

export async function getCachedUser(id: string) {
  const cached = await redis.get<User>(`user:${id}`);
  if (cached) return cached;

  const user = await getUserById(id);
  if (user) {
    await redis.set(`user:${id}`, user, { ex: 300 }); // 5-minute TTL
  }
  return user;
}

5. Streaming Responses from the Edge#

Edge Runtime supports streaming responses using the Web Streams API. This is particularly powerful for AI-generated content, where a language model produces tokens progressively and the user experience improves dramatically when tokens are streamed as they are generated rather than waiting for the complete response.

// app/api/stream/route.ts
export const runtime = "edge";

export async function POST(request: Request) {
  const { prompt } = await request.json();

  const stream = new ReadableStream({
    async start(controller) {
      const encoder = new TextEncoder();

      const response = await fetch("https://api.openai.com/v1/chat/completions", {
        method: "POST",
        headers: {
          "Content-Type":  "application/json",
          "Authorization": `Bearer ${process.env.OPENAI_API_KEY}`,
        },
        body: JSON.stringify({
          model:  "gpt-4",
          stream: true,
          messages: [{ role: "user", content: prompt }],
        }),
      });

      const reader = response.body?.getReader();
      if (!reader) return;

      while (true) {
        const { done, value } = await reader.read();
        if (done) break;
        controller.enqueue(value);
      }

      controller.close();
    },
  });

  return new Response(stream, {
    headers: {
      "Content-Type":  "text/event-stream",
      "Cache-Control": "no-cache",
    },
  });
}

6. When Not to Use Edge Runtime#

Edge Runtime is the right choice for latency-sensitive, stateless workloads. It is the wrong choice when your code requires:

Node.js native modules or packages that depend on Node.js built-ins

Long-running computations that exceed the edge execution time limits (typically 30 seconds maximum)

Direct access to a database that does not support HTTP-based connections

File system operations

Large memory footprints that exceed the edge environment limits (typically 128MB)

For these use cases, a traditional Node.js serverless function or a dedicated server is the appropriate choice. The practical approach is to run middleware, authentication, geolocation, and lightweight API handlers at the edge, and delegate data-heavy or compute-intensive workloads to Node.js functions.

7. Migrating to Edge Runtime#

Migrating an existing Next.js application to use Edge Runtime for appropriate routes is incremental. You do not need to migrate everything at once.

// Step 1: Add runtime export to routes that are edge-compatible
export const runtime = "edge";

// Step 2: Run the build and check for edge compatibility errors
// next build will flag incompatible imports automatically

// Step 3: Replace incompatible imports
// Before: import { sign } from "jsonwebtoken"; // Node.js only
// After:  import { SignJWT } from "jose";       // Edge-compatible

// Step 4: Replace database drivers with HTTP-compatible alternatives
// Before: import { Pool } from "pg";            // TCP connection, Node.js only
// After:  import { neon } from "@neondatabase/serverless"; // HTTP, edge-compatible

// Step 5: Verify and deploy

Conclusion#

Edge Runtime represents a genuine shift in how frontend applications are deployed and how performance is achieved. The constraints it imposes, no file system, no native modules, no connection pools, are not limitations to work around. They are the discipline that produces applications that start fast, scale horizontally without configuration, and serve users from the nearest possible location.

The migration path is incremental. Start with middleware. Move authentication checks to the edge. Add edge API routes for latency-sensitive endpoints. Adopt HTTP-compatible database drivers where needed. Each step delivers measurable performance improvements without requiring a full rewrite.

The future of frontend deployment is distributed. Edge Runtime is how you get there today.