F-7 — Route Handlers and the Backend-for-Frontend Pattern

---

Caching Behaviour

GET Route Handlers are cached by default when they return a static response (no dynamic data access). They become dynamic — and bypass the cache — when they:

• Read from the incoming Request object (headers, cookies, body)
• Use dynamic functions like cookies() or headers()
• Use export const dynamic = 'force-dynamic'

// This GET handler is static — can be cached
export async function GET() {
  const data = await getStaticData();
  return NextResponse.json(data);
}
 
// This GET handler is dynamic — accesses cookies, never cached
export async function GET(request: NextRequest) {
  const session = request.cookies.get('session')?.value;
  const userData = await getUserData(session);
  return NextResponse.json(userData);
}

Force a Route Handler to always revalidate after a period:

export const revalidate = 60; // revalidate every 60 seconds
 
export async function GET() {
  const products = await getProducts();
  return NextResponse.json(products);
}

---

Webhook Handlers — The Real-World Pattern

Webhooks from Stripe, GitHub, or any other service have two requirements: they need to be accessible from the outside (no auth cookie, no session — these are server-to-server requests), and they often need signature verification to ensure the request actually came from the service you expect.

// app/api/webhooks/stripe/route.ts
 
import { headers } from 'next/headers';
import Stripe from 'stripe';
 
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
 
export async function POST(request: NextRequest) {
  const body = await request.text(); // ← get raw body for signature verification
  const headersList = await headers();
  const signature = headersList.get('stripe-signature');
 
  if (!signature) {
    return NextResponse.json({ error: 'No signature' }, { status: 400 });
  }
 
  let event: Stripe.Event;
 
  try {
    event = stripe.webhooks.constructEvent(
      body,
      signature,
      process.env.STRIPE_WEBHOOK_SECRET!
    );
  } catch (err) {
    return NextResponse.json({ error: 'Invalid signature' }, { status: 400 });
  }
 
  // Handle the event
  switch (event.type) {
    case 'payment_intent.succeeded':
      await handlePaymentSuccess(event.data.object as Stripe.PaymentIntent);
      break;
    case 'customer.subscription.deleted':
      await handleSubscriptionCancelled(event.data.object as Stripe.Subscription);
      break;
  }
 
  return NextResponse.json({ received: true });
}

Two things to notice:

Raw body for signature verification. await request.text() gives you the raw request body as a string. This is essential for webhook signature verification — Stripe (and most other services) sign the raw body bytes. If you parse it as JSON first, the bytes change and signature verification fails.

Return 200 quickly. Webhook providers typically require a response within 30 seconds and will retry on timeout or error status. Do your heavy processing asynchronously (queue it, use after() from Next.js 15, or fire a background job) and respond immediately with { received: true }.

---

Server-Sent Events — Streaming from Route Handlers

Route Handlers can stream responses, which is how you implement Server-Sent Events (SSE) for real-time updates:

// app/api/events/route.ts
 
export async function GET(request: NextRequest) {
  const encoder = new TextEncoder();
 
  const stream = new ReadableStream({
    async start(controller) {
      // Send initial data
      controller.enqueue(
        encoder.encode(`data: ${JSON.stringify({ type: 'connected' })}\n\n`)
      );
 
      // Set up a subscription or polling loop
      const intervalId = setInterval(async () => {
        const update = await getLatestUpdate();
        controller.enqueue(
          encoder.encode(`data: ${JSON.stringify(update)}\n\n`)
        );
      }, 2000);
 
      // Clean up when client disconnects
      request.signal.addEventListener('abort', () => {
        clearInterval(intervalId);
        controller.close();
      });
    },
  });
 
  return new Response(stream, {
    headers: {
      'Content-Type': 'text/event-stream',
      'Cache-Control': 'no-cache',
      'Connection': 'keep-alive',
    },
  });
}

// Client Component consuming SSE
'use client';
 
import { useEffect, useState } from 'react';
 
export function LiveUpdates() {
  const [updates, setUpdates] = useState<string[]>([]);
 
  useEffect(() => {
    const eventSource = new EventSource('/api/events');
 
    eventSource.onmessage = (event) => {
      const data = JSON.parse(event.data);
      setUpdates(prev => [...prev, data]);
    };
 
    return () => eventSource.close();
  }, []);
 
  return <ul>{updates.map((u, i) => <li key={i}>{u}</li>)}</ul>;
}

A note on serverless and SSE: long-lived connections like SSE are problematic in serverless environments (Vercel Functions, AWS Lambda) because functions terminate after a response. Vercel's streaming support has improved, but for sustained real-time connections, consider Pusher, Ably, or Upstash for server-less-friendly pub/sub — or self-host on a platform that supports persistent connections. Module A-14 covers this in depth.

---

Proxying an External API — the BFF Pattern

A common Route Handler use case: your browser calls your own Next.js API, and your server adds a secret API key before forwarding to the real upstream service. The API key never reaches the browser. There's no dedicated declarative file convention for this in Next.js — for a route-scoped proxy, you write the Route Handler directly (for whole-app path rewriting, rewrites() in next.config.ts is the declarative option; see P-10 for configuration):

// app/api/proxy/[...path]/route.ts
export async function GET(
  request: NextRequest,
  { params }: { params: Promise<{ path: string[] }> }
) {
  const { path } = await params;
  const upstreamUrl = `https://api.someservice.com/${path.join('/')}`;
 
  const response = await fetch(upstreamUrl, {
    headers: {
      Authorization: `Bearer ${process.env.SOMESERVICE_API_KEY}`,
      ...Object.fromEntries(request.headers),
    },
  });
 
  return new Response(response.body, {
    status: response.status,
    headers: response.headers,
  });
}

This is more boilerplate than a one-line config entry, but it's also the honest amount of control you need the moment you want to filter which headers get forwarded, transform the body, add rate limiting, or only proxy specific methods — all of which are just more code in the same handler, not a separate mechanism.

---

userAgent() — Device Detection

Route Handlers can use userAgent() from next/server to detect the requesting device type — useful for serving different content, redirecting mobile users to a different experience, or A/B testing:

import { userAgent } from 'next/server';
 
export async function GET(request: NextRequest) {
  const { device, browser, os, isBot } = userAgent(request);
 
  if (isBot) {
    // Serve simplified content or return early for crawlers
    return NextResponse.json({ simplified: true });
  }
 
  if (device.type === 'mobile') {
    return NextResponse.redirect(new URL('/m/home', request.url));
  }
 
  return NextResponse.json({ device: device.type });
}

userAgent is more commonly used in Middleware (which you'll cover in P-6) since Middleware runs before every request. In Route Handlers, it's useful when you need device-aware API responses.

---

CORS Configuration

If your Route Handlers will be called from a different origin (a mobile app, a third-party frontend, Postman during development), you need CORS headers:

// lib/cors.ts
 
const ALLOWED_ORIGINS = [
  'https://yourapp.com',
  'https://staging.yourapp.com',
  process.env.NODE_ENV === 'development' ? 'http://localhost:3000' : '',
].filter(Boolean);
 
export function corsHeaders(origin: string | null) {
  const isAllowed = origin && ALLOWED_ORIGINS.includes(origin);
  return {
    'Access-Control-Allow-Origin': isAllowed ? origin! : ALLOWED_ORIGINS[0],
    'Access-Control-Allow-Methods': 'GET, POST, PUT, PATCH, DELETE, OPTIONS',
    'Access-Control-Allow-Headers': 'Content-Type, Authorization',
    'Access-Control-Max-Age': '86400',
  };
}

// app/api/products/route.ts
 
import { corsHeaders } from '@/lib/cors';
 
export async function OPTIONS(request: NextRequest) {
  const origin = request.headers.get('origin');
  return new Response(null, {
    status: 204,
    headers: corsHeaders(origin),
  });
}
 
export async function GET(request: NextRequest) {
  const origin = request.headers.get('origin');
  const products = await getProducts();
  return NextResponse.json(products, { headers: corsHeaders(origin) });
}

The OPTIONS export handles the CORS preflight request. Every other method needs the CORS headers in its response too.

---

Route Handler vs Server Action — The Decision

The question comes up constantly and the answer is clean once you understand what each tool is for:

The rule: Server Actions for your own frontend. Route Handlers for everything else.

Server Actions don't require you to write fetch calls or define endpoint URLs — they're called like functions. Route Handlers require explicit HTTP requests — the caller constructs a URL and makes a fetch call. For internal mutations in your own app, Server Actions win on simplicity. For external consumers, you need the explicit HTTP contract of a Route Handler.

---

Where We Go From Here

F-8 is the capstone module for the Foundation phase — you'll build a complete content site from scratch using everything covered in F-1 through F-7: the file system, Server Components, data fetching, dynamic routes, built-in components, and Route Handlers. Think of it as a supervised first real application.

After F-8, the Practitioner phase begins. P-1 goes deep on advanced data fetching patterns — the use cache directive, tag-based invalidation at scale, and eliminating the waterfall chains that make apps feel slow. P-2 covers Server Actions properly — not just how to write them but how they're compiled, the security implications, useActionState, optimistic UI, and the after() API.

---