Edge Functions vs. API Routes: How to Choose and When to Combine Both

// Cloudflare Worker — runs at the edge, executes in <5ms
export default {
  async fetch(request: Request): Promise<Response> {
    const country = request.cf?.country;

    // Redirect UK users to the UK-specific subdomain
    if (country === 'GB') {
      return Response.redirect('https://uk.example.com' + new URL(request.url).pathname, 301);
    }

    // Check auth token without a database call
    const token = request.headers.get('Authorization')?.split(' ')[1];
    if (!token || !isValidJWT(token)) {
      return new Response('Unauthorized', { status: 401 });
    }

    // Pass to origin for actual processing
    return fetch(request);
  }
};

// Next.js API route — runs in a regional Node.js container
// app/api/orders/route.ts
import { db } from '@/lib/database';
import { NextRequest, NextResponse } from 'next/server';

export async function POST(request: NextRequest) {
  const body = await request.json();

  // Database write — this is what edge functions cannot do
  const order = await db.order.create({
    data: {
      userId: body.userId,
      items: body.items,
      total: body.total,
    },
  });

  // Trigger background job
  await queue.dispatch('send-order-confirmation', { orderId: order.id });

  return NextResponse.json({ orderId: order.id }, { status: 201 });
}

User Request
    ↓
Edge Function (Cloudflare Worker / Vercel Edge)
  - Validate JWT (stateless, no DB)
  - Check geolocation, apply redirects
  - Rewrite headers, add request ID
  - Block known malicious patterns
    ↓ (passes enriched request)
Regional API Route (Lambda / Vercel Function)
  - Connect to database
  - Execute business logic
  - Write records
  - Dispatch background jobs
    ↓
Response cached at edge for subsequent requests

// middleware.ts — runs at edge on every request
import { NextRequest, NextResponse } from 'next/server';
import { verifyJWT } from '@/lib/auth';

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

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

  if (!token) {
    return NextResponse.redirect(new URL('/login', request.url));
  }

  // JWT verification is CPU-fast — no DB call needed
  const payload = await verifyJWT(token);
  if (!payload) {
    return NextResponse.redirect(new URL('/login', request.url));
  }

  // Attach user ID to request headers for the API route
  const requestHeaders = new Headers(request.headers);
  requestHeaders.set('x-user-id', payload.sub);

  return NextResponse.next({ request: { headers: requestHeaders } });
}

# PgBouncer config — runs as a sidecar or separate instance
# /etc/pgbouncer/pgbouncer.ini

[databases]
mydb = host=rds.endpoint.amazonaws.com port=5432 dbname=mydb

[pgbouncer]
listen_port = 6432
listen_addr = 0.0.0.0
auth_type = md5
pool_mode = transaction        # transaction pooling — best for serverless
max_client_conn = 1000         # Lambda connections to PgBouncer
default_pool_size = 20         # PgBouncer connections to RDS

// 1. Edge middleware validates session token (no DB)
// middleware.ts
export async function middleware(request: NextRequest) {
  const sessionToken = request.cookies.get('session')?.value;
  const payload = sessionToken ? await verifyJWT(sessionToken) : null;

  if (!payload && request.nextUrl.pathname.startsWith('/dashboard')) {
    return NextResponse.redirect(new URL('/login', request.url));
  }

  return NextResponse.next();
}

// 2. API route reads user data from Postgres (regional, with connection pool)
// app/api/user/profile/route.ts
import { db } from '@/lib/db'; // Prisma + PgBouncer

export async function GET(request: NextRequest) {
  const userId = request.headers.get('x-user-id'); // set by edge middleware

  const user = await db.user.findUnique({
    where: { id: userId },
    select: { name: true, email: true, plan: true },
  });

  return NextResponse.json(user);
}

// 3. Static pages cached at edge — no function invocation needed
// app/blog/[slug]/page.tsx
export const revalidate = 3600; // Cache for 1 hour at CDN edge