Next.js as a backend for your frontend

The tea shop in front of its services

The tea shop's Next.js app isn't the only software the shop runs. The warehouse team runs a stock service that knows how many boxes of each tea are left, and another team runs a reviews service. Each is an HTTP API on its own server: send GET /stock/mint, get JSON back. The page for Mint tea needs both.

The browser could call both services itself. Then the stock service's key would have to be in the page, where anyone can read it; the visitor would wait for two more requests after the page arrived; and the browser would get every field the services send, reviewers' emails included. Instead, the Next.js app calls them, on the server, and sends the browser one page made for it. A server that stands between one frontend and the services behind it, built for that frontend, is called a backend for frontend, or BFF. Next.js's docs have a guide for using it this way, and point out that its server features are an API layer that anyone can reach, not a full replacement for a backend. Here is the tea page:

1import { notFound } from "next/navigation";2import { Suspense } from "react";3import { getTeaSummary } from "@/lib/tea-summary";4 5export default function TeaPage({ params }: PageProps<"/teas/[id]">) {6  return (7    <main>8      <h1>Tea details</h1>9      <Suspense fallback={<p>Loading…</p>}>10        <Details params={params} />11      </Suspense>12    </main>13  );14}15 16async function Details({ params }: { params: Promise<{ id: string }> }) {17  const { id } = await params;18  const summary = await getTeaSummary(id);19  if (!summary) notFound();20  const { stock, reviews } = summary;21  return (22    <>23      <p>{stock ? `${stock.boxes} boxes in stock` : "Stock unknown right now."}</p>24      {!reviews ? (25        <p>Reviews are unavailable right now.</p>26      ) : reviews.latest ? (27        <p>28          Rated {reviews.average} from {reviews.count} reviews. {reviews.latest.author}: {reviews.latest.text}29        </p>30      ) : (31        <p>No reviews yet.</p>32      )}33    </>34  );35}

This is a real Next.js 16.4.3 project, built with next build and run with next start; what it sent back was recorded. In app/teas/[id]/page.tsx, lines 9 to 11 wrap Details in Suspense, so the page's heading can be sent before the services answer. Line 17 reads the tea's id from the address, and line 18 asks getTeaSummary in lib/tea-summary.ts for both services' answers. Line 19 handles a tea that doesn't exist, and lines 23 to 32 show each answer, or a sentence for when it's missing. The Browser tab shows 12 boxes in stock and Rated 4.5 from 2 reviews. Asha: Fresh and bright. Pick /teas/green above the page: 4 boxes in stock and No reviews yet. The Terminal tab lists ◐ /teas/[id]: a static shell with the details streamed in for each request.

/teas/oolong is a tea neither service knows: both answered 404, so getTeaSummary returned null and line 19 called notFound(). The heading had already been sent, so the status stayed 200, and Next.js added <meta name="robots" content="noindex"> to the HTML, as Not-found and access errors recorded for streamed pages.

The services in these recordings are a stand-in: one small server that plays both, whose address the recorder gave the app in STOCK_API_URL and REVIEWS_API_URL, the way a deployment sets them. It kept every request it received, with some of its headers. During the three visits, it received these:

Two requests for each page, both from the shop's server: each stock request carried the shop's key in x-api-key, and the reviews requests carried none. Nothing reached the services while the app was being built. The browser only ever asked the shop.

Route Handlers as a public API

The shop's phone app needs the same summary, as JSON. A Route Handler, a route.ts file, answers it. Unlike a page's server code, it's an API that other programs depend on: anyone who knows the address can call it, and old versions of the phone app keep calling it for months. So the shop puts the checks every endpoint needs in one module. The data here is the public catalog; a phone user's own data, like their orders, would need them to sign in, with a session or a token checked in the data access layer (Authorization), like on the website.

1import "server-only";2 3// The apps that call this API. A client id says which app it is. It ships inside the app,4// so anyone can copy it: it's for counting and coarse limits, never for deciding who sees what.5const clients = new Set(["phone-app"]);6 7// A stand-in rate limit: 4 requests a minute for each client id, counted in this server's memory.8const calls = new Map<string, { start: number; count: number }>();9const minute = 60_000;10 11// Recording fixture: FIXED_NOW freezes the clock, so the recording never depends on timing. Never set it in production.12const now = () => (process.env.FIXED_NOW ? Number(process.env.FIXED_NOW) : Date.now());13 14export function limitClient(request: Request) {15  const client = request.headers.get("x-client-id");16  if (!client || !clients.has(client)) return Response.json({ error: "Send a known x-client-id" }, { status: 400 });17  const time = now();18  const current = calls.get(client);19  if (!current || time - current.start >= minute) {20    calls.set(client, { start: time, count: 1 });21    return null;22  }23  current.count += 1;24  if (current.count <= 4) return null;25  const retryAfter = Math.ceil((current.start + minute - time) / 1000);26  return Response.json({ error: "Too many requests" }, { status: 429, headers: { "retry-after": String(retryAfter) } });27}28 29export const teaId = /^[a-z-]{1,30}$/;30 

• Line 5 lists the apps the shop knows. Line 15 reads the x-client-id header, and line 16 answers 400 when it's missing or unknown. A client id says which app is calling, but it ships inside the app, so anyone can copy it and send it. It isn't a credential: it's a label for counting and coarse limits, never for deciding who sees what.
• Lines 17 to 26 are a rate limit: at most 4 calls a minute for each client id. Line 19 starts a new minute, line 25 works out how many seconds of that minute are left, and line 26 answers 429, "too many requests", with that number in retry-after. Since anyone can change their client id, it only slows careless callers down. It counts in this server's memory, a stand-in: with several copies of the app, each would count on its own (Securing Server Actions said the same), so use your host's rate limiting or a shared store.
• Line 12 reads the time. With FIXED_NOW set, the clock stands still: that's a recording fixture, set in this example's .env so the recording never depends on how fast the requests were sent. It's never set in production.
• Line 29, teaId, is a regular expression for a valid id: 1 to 30 lowercase letters and dashes.

1import { limitClient, teaId } from "@/lib/public-api";2import { getTeaSummary } from "@/lib/tea-summary";3 4export async function GET(request: Request, { params }: RouteContext<"/api/v1/teas/[id]">) {5  const refused = limitClient(request);6  if (refused) return refused;7  const { id } = await params;8  if (!teaId.test(id)) return Response.json({ error: "Not a tea id" }, { status: 400 });9  const summary = await getTeaSummary(id);10  if (!summary) return Response.json({ error: "No such tea" }, { status: 404 });11  return Response.json(summary);12}

{"stock":{"boxes":12},"reviews":{"average":4.5,"count":2,"latest":{"author":"Asha","text":"Fresh and bright."}}}

In app/api/v1/teas/[id]/route.ts, lines 5 and 6 refuse a call before anything else. Line 8 answers 400 for an id that isn't one, before any service is called. Line 9 calls getTeaSummary, the same function the page uses, and line 10 answers 404 when both services say there's no such tea, instead of an empty 200. The Network tab shows the six recorded calls, in order:

• From the phone app: 200, with the stock and the reviews as JSON.
• Without a client id: 400, {"error":"Send a known x-client-id"}.
• With the id MINT: 400, {"error":"Not a tea id"}.
• With the id oolong, which the shop doesn't sell: 404, {"error":"No such tea"}.
• /api/v2/teas/mint: 200, {"inStock":true,"rating":4.5}, the smaller shape that the new phone app asks for.
• A fifth call in the same minute: 429, with retry-after: 60, because the frozen clock left the whole minute.

Each row is one thing a public API has to decide, what the shop does, and what the recording showed:

One thing the page never does: fetch /api/v1/teas/mint. A Server Component calls getTeaSummary directly, as Fetching data in Server Components recorded; the Route Handler is for callers that can't import your functions. And error answers say little on purpose: Next.js's guide warns against sending internal details in them.

Proxying with rewrites

Sometimes you want one of your own addresses to answer with another service's answer, unchanged. The reviews team has built a widget that fetches reviews in the browser. CORS, cross-origin resource sharing, is the browser's rule for whether a page from another origin may read a response; it decides nothing about who may call. Calling the shop's own domain avoids it. A rewrite in next.config.ts sends a request for one path to another address, while the visitor's address stays the same. Its destination can be another server. Allow only the paths that are public:

1import type { NextConfig } from "next";2 3const nextConfig: NextConfig = {4  /* config options here */5  cacheComponents: true,6  partialPrefetching: true,7  async rewrites() {8    return [9      {10        // Only the public reviews of a tea, for ids like "mint". No other path on the service.11        source: "/reviews-api/reviews/:tea([a-z-]{1,30})",12        destination: `${process.env.REVIEWS_API_URL}/reviews/:tea`,13      },14    ];15  },16};17 18export default nextConfig;

{"tea":"mint","reviews":[{"author":"Asha","email":"asha@example.com","stars":5,"text":"Fresh and bright."},{"author":"Ben","email":"ben@example.com","stars":4,"text":"Calm and grassy."}]}

Lines 7 to 15 of next.config.ts add the rewrite. Line 11 matches /reviews-api/reviews/ followed by a tea id, 1 to 30 lowercase letters and dashes, named tea. Line 12 sends it to that tea's reviews on the reviews service, and nowhere else. A pattern like /reviews-api/:path* would have sent every path, the service's private ones too: here, /reviews-api/staff/notes and /reviews-api/reviews/..%2Fstaff%2Fnotes matched no rewrite and answered 404. The recorder asked for /reviews-api/reviews/mint the way a signed-in visitor's browser would, on the address teashop.example, with a session cookie and an Authorization header. The Network tab shows the answer: the reviews service's JSON, exactly as it sent it, both emails included. And the service received this:

host is the service's own address, and x-forwarded-host is the one the visitor used: teashop.example. In Next.js 16.4.3, a rewrite to another server is passed on by a proxy that sets both (lines 30 to 41 of proxy-request.ts). The visitor's cookie and authorization headers went along too, untouched: a rewrite in next.config.ts has no way to remove them. And a service should only trust x-forwarded-host when a server you run in front of it, like your load balancer, overwrites it: anyone can send that header, so it never decides who may do what (Self-hosting and Multi-tenant apps show where it comes from). Also, rewrites() runs during next build, and next start reads the list the build saved (lines 540 to 560 of filesystem.ts), so changing REVIEWS_API_URL means building again.

Here are four ways to reach the reviews service: the rewrite above; a rewrite in proxy.ts (proxy.ts) that sends a copy of the visitor's headers without the cookie and the Authorization header; a Route Handler that builds the service's address from the query; and one that checks the id first. The recorder sent each one Mint tea from the signed-in visitor, then a path to the staff notes. Guess what the second request does to the unchecked Route Handler.

1import type { NextConfig } from "next";2 3const nextConfig: NextConfig = {4  /* config options here */5  cacheComponents: true,6  partialPrefetching: true,7  async rewrites() {8    return [9      {10        // Only the public reviews of a tea, for ids like "mint". No other path on the service.11        source: "/reviews-api/reviews/:tea([a-z-]{1,30})",12        destination: `${process.env.REVIEWS_API_URL}/reviews/:tea`,13      },14    ];15  },16};17 18export default nextConfig;

{"tea":"mint","reviews":[{"author":"Asha","email":"asha@example.com","stars":5,"text":"Fresh and bright."},{"author":"Ben","email":"ben@example.com","stars":4,"text":"Calm and grassy."}]}

Each row is one request the stand-in reviews service received, in each version, with the headers it kept:

The unchecked handler, on line 5, put the query straight into the address: /reviews/../staff/notes. A URL's .. means "the folder above", and it's resolved before the request leaves (URL objects), so the reviews service received GET /staff/notes, and the handler passed its staff notes to whoever asked. Building a request's address from what a caller sent is how SSRF, server-side request forgery, happens: your server, inside your network, asks for what an attacker chose. Letting the caller pick the whole address, like ?url=, is the worst case. The checked handler builds the address from fixed parts: line 8 lets only a valid id through, and getReviews also escapes it with encodeURIComponent. It sent no cookie and no Authorization header, because its fetch doesn't add them. The proxy.ts version sent neither too: lines 9 to 11 copy the headers and delete both, and line 12 passes the copy to NextResponse.rewrite as the request's headers.

Each row compares the two ways to put a service behind one of the shop's addresses:

Combining several services

The page and the phone app's endpoint both get their data from one function, which calls both services at once:

1import "server-only";2import { NoSuchTea } from "@/services/errors";3import { getReviews } from "@/services/reviews";4import { getStock } from "@/services/stock";5 6export async function getTeaSummary(id: string) {7  const [stock, reviews] = await Promise.allSettled([getStock(id), getReviews(id)]);8  // A 404 says there's no such tea: an answer to pass on, not a failure to hide.9  if ([stock, reviews].some((result) => result.status === "rejected" && result.reason instanceof NoSuchTea)) return null;10  return {11    stock: stock.status === "fulfilled" ? stock.value : null,12    reviews: reviews.status === "fulfilled" ? reviews.value : null,13  };14}15 

Line 7 starts both calls before it waits for either, so they run at the same time (Parallel and sequential fetching showed why that matters). It waits with Promise.allSettled, which waits until every promise has finished, and says for each one whether it was fulfilled or rejected (Promise combinators). Line 9 tells two kinds of failure apart: a NoSuchTea error, from a service that answered 404, means the tea doesn't exist, so the summary is null and the page and the API answer "not found". Anything else, like a timeout or a 503, is a passing problem: lines 11 and 12 turn it into null for that service alone, so one broken service never breaks the other's part of the page. Each service's module also decides how long to wait, and checks what it got back:

1import "server-only";2import { z } from "zod";3import { NoSuchTea } from "./errors";4 5const Stock = z.object({ boxes: z.number().int().min(0) });6 7export async function getStock(id: string) {8  const response = await fetch(`${process.env.STOCK_API_URL}/stock/${encodeURIComponent(id)}`, {9    headers: { "x-api-key": process.env.STOCK_API_KEY ?? "" },10    signal: AbortSignal.timeout(1000),11  });12  if (response.status === 404) throw new NoSuchTea(id);13  if (!response.ok) throw new Error(`The stock service answered ${response.status}`);14  const stock = Stock.parse(await response.json());15  return { boxes: stock.boxes };16}17 

• Line 5 describes the answer the shop expects, with Zod: a whole number of boxes, 0 or more.
• Line 8 builds the address from the service's address and the id, escaped with encodeURIComponent. Line 9 sends the shop's key, from a server environment variable.
• Line 10 gives the request a signal: an object that can stop it. AbortSignal.timeout(1000) makes one that stops the request after 1000 ms, and fetch then rejects (fetch).
• Line 12 turns 404 into NoSuchTea, from services/errors.ts. Line 13 turns any other failed answer, like 503, into an error, because fetch only rejects when there's no answer at all.
• Line 14 checks the JSON against the schema, and throws if the service sent something else, so a changed or broken answer is a failure, not a page full of undefined.

services/reviews.ts does the same, with its own 1-second timeout. Now make the services misbehave. Each button below is the same app, recorded with the stand-in services answering differently. Before you click, guess what the page shows when the reviews take 5 seconds.

1import { notFound } from "next/navigation";2import { Suspense } from "react";3import { getTeaSummary } from "@/lib/tea-summary";4 5export default function TeaPage({ params }: PageProps<"/teas/[id]">) {6  return (7    <main>8      <h1>Tea details</h1>9      <Suspense fallback={<p>Loading…</p>}>10        <Details params={params} />11      </Suspense>12    </main>13  );14}15 16async function Details({ params }: { params: Promise<{ id: string }> }) {17  const { id } = await params;18  const summary = await getTeaSummary(id);19  if (!summary) notFound();20  const { stock, reviews } = summary;21  return (22    <>23      <p>{stock ? `${stock.boxes} boxes in stock` : "Stock unknown right now."}</p>24      {!reviews ? (25        <p>Reviews are unavailable right now.</p>26      ) : reviews.latest ? (27        <p>28          Rated {reviews.average} from {reviews.count} reviews. {reviews.latest.author}: {reviews.latest.text}29        </p>30      ) : (31        <p>No reviews yet.</p>32      )}33    </>34  );35}

With the reviews service waiting 5 seconds, the reviews call was aborted by its timeout, and the page showed 12 boxes in stock and Reviews are unavailable right now. It waited for the slow service only as long as its timeout. With the stock service answering 503, the page showed Stock unknown right now. and the reviews. Either way, the visitor got everything that worked.

This page has one Suspense boundary around both parts, so the stock waits too: both show once the reviews call has answered or timed out. To show the stock as soon as it arrives, give each part its own component and its own Suspense, so the reviews stream in later (Streaming); a timeout still decides how long the slowest part may keep the page open. And the phone app's endpoint combines the services the same way, because it calls the same getTeaSummary: the recorded JSON from /api/v1/teas/mint has both parts.

Shaping data for the UI

Here is what the reviews service sends for Mint tea:

{
  "tea": "mint",
  "reviews": [
    {
      "author": "Asha",
      "email": "asha@example.com",
      "stars": 5,
      "text": "Fresh and bright."
    },
    {
      "author": "Ben",
      "email": "ben@example.com",
      "stars": 4,
      "text": "Calm and grassy."
    }
  ]
}

Every review, each with its reviewer's email. The page shows an average, a count and the latest review. Turning a service's answer into exactly what one screen needs is a backend for frontend's main job, and it happens in the service's module:

1import "server-only";2import { z } from "zod";3import { NoSuchTea } from "./errors";4 5const Reviews = z.object({6  reviews: z.array(z.object({ author: z.string(), stars: z.number().min(1).max(5), text: z.string() })),7});8 9export async function getReviews(id: string) {10  const response = await fetch(`${process.env.REVIEWS_API_URL}/reviews/${encodeURIComponent(id)}`, {11    signal: AbortSignal.timeout(1000),12  });13  if (response.status === 404) throw new NoSuchTea(id);14  if (!response.ok) throw new Error(`The reviews service answered ${response.status}`);15  const { reviews } = Reviews.parse(await response.json());16  const stars = reviews.reduce((total, review) => total + review.stars, 0);17  return {18    average: reviews.length ? stars / reviews.length : null,19    count: reviews.length,20    latest: reviews[0] ? { author: reviews[0].author, text: reviews[0].text } : null,21  };22}23 

Lines 5 to 7 describe the fields the shop uses: each review's author, stars from 1 to 5, and text. Line 15 checks the answer against them. Zod's parse also drops every field the schema doesn't name, so the emails are gone from here on. Line 16 adds up the stars, and lines 17 to 21 return a new object: the average on line 18 ((5 + 4) / 2, 4.5), the count on line 19, and on line 20 the latest review with only its author and text. A tea with no reviews gets null for both, instead of a division by zero, and the page shows No reviews yet., as the recorded /teas/green does. An object made only to carry data out of a layer like this is a DTO, a data transfer object, as in Authorization and the data access layer. Anything a Server Component renders, or passes to a Client Component, is sent to the browser, so leaving fields out here is how they stay out of the page.

The recordings show the difference. The recorder searched the tea page's HTML and its JavaScript: no asha@example.com in either. The phone app's JSON has no email either. Only the rewrite, which passes the service's answer on as it is, sent the emails to the browser.

Keeping secrets on the server

The stock service's key lives in an environment variable without the NEXT_PUBLIC_ prefix, so only server code can read it (Server-only code and environment variables). In these recordings, it's in the project's .env file:

# A key made up for the recordings. A real one lives in your host's settings.
STOCK_API_KEY=stock-key-for-recordings

Line 2 sets STOCK_API_KEY. The value is made up for the recordings; a real key lives in your host's settings, never in the repository. Line 9 of services/stock.ts sends it. That module starts with import "server-only", so no Client Component can import it. The stand-in stock service answers 401 to a request without the right key, and it answered 200: the key arrived. The recorder also searched the tea page's HTML and its JavaScript for the key, and found it in neither.

Writing works the same way. A Server Action can stand in front of a service too: here, a form posts a review, and the action sends it to the reviews service with the shop's second key.

1"use server";2 3import { cookies } from "next/headers";4import { redirect } from "next/navigation";5import { teaId } from "@/lib/public-api";6import { postReview } from "@/services/reviews";7 8export async function addReview(id: string, formData: FormData) {9  // A stand-in for the signed session cookie from the authentication lesson.10  const session = (await cookies()).get("session")?.value;11  if (session !== "asha-session") throw new Error("Sign in to write a review.");12  const text = String(formData.get("text") ?? "").trim().slice(0, 500);13  if (!teaId.test(id) || !text) throw new Error("Write a review of a tea.");14  await postReview(id, { author: "Asha", text });15  redirect(`/teas/${id}`);16}

In app/teas/[id]/actions.ts, line 10 reads the session cookie and line 11 refuses anyone who isn't signed in. The cookie check is a stand-in for the signed session of Authentication; an action is a public endpoint, so it always checks who is asking. Line 13 checks the tea's id, which travels back in the form as a bound argument, and the text. Line 14 calls postReview, which sends it with REVIEWS_API_KEY. The Network tab shows the form posted without JavaScript: 303, back to /teas/mint. The reviews service received this:

The last row is the review, with the shop's key, and its body was {"author":"Asha","text":"Lovely with honey."}. The browser posted to the shop's own address; the shop talked to the service. Neither key is in the page's JavaScript.

When to use a separate backend

A backend for frontend is good at short requests: read from a service or a database, shape the answer, send it. Next.js's guide says plainly that its server features aren't a full backend replacement, and lists what some hosts do to Route Handlers: they may run them as short-lived functions that can't share data between requests, may stop long-running ones on a timeout, and close the connection after the answer, so WebSockets won't work. Each row is one kind of work, and where it fits best:

Many apps end up with both: services that own the data and the rules, and a Next.js app in front of them that owns the pages and the shape of the data for those pages. Small jobs that can happen after the answer, like logging, fit in the app with after() (after() and background work). Jobs that take minutes, live connections, and rules that several clients share are worth a backend of their own.

Planning the tea shop's backend

The shop has eight jobs to place. Sort them: does each one belong in the Next.js app, or in a separate backend?

A quick test: if the job ends with an answer to one request within a few seconds, the Next.js app can do it. If it runs for minutes, keeps a connection open, or holds rules other clients need too, give it a backend.

Common mix-ups

• "A rewrite only changes the path." No. The service got the visitor's cookie and Authorization header, and its answer reached the browser unchanged, emails included.
• "CORS keeps other programs out of my API." No. CORS only decides which pages a browser lets read the answer. The phone app isn't a browser; the key check and the rate limit are what refuse it.
• "Promise.all is fine for independent services." No. It rejects as soon as one call fails. With the stock service down, the recorded HTML held only Loading….
• "A client id proves which app is calling." No. It ships inside the app, so anyone can copy it and send it. It's only a label for counting; people prove who they are by signing in.
• "Putting the id in the path keeps the request inside /reviews." No. ../staff/notes reached /staff/notes. Check ids and escape them.
• "A Server Component should fetch the API like the phone app." No. It calls getTeaSummary directly; the Route Handler is for callers that can't.
• "Next.js can replace every backend." No. Its own guide says it isn't a full replacement: long jobs, live connections and shared rules belong elsewhere.

Practice exercises

These exercises are about Next.js projects, which can't run inside this page. Answer first, then use the hints.

import { notFound } from "next/navigation";
import { Suspense } from "react";
import { getTeaSummary } from "@/lib/tea-summary";

export default function TeaPage({ params }: PageProps<"/teas/[id]">) {
  return (
    <main>
      <h1>Tea details</h1>
      <Suspense fallback={<p>Loading…</p>}>
        <Details params={params} />
      </Suspense>
    </main>
  );
}

async function Details({ params }: { params: Promise<{ id: string }> }) {
  const { id } = await params;
  const summary = await getTeaSummary(id);
  if (!summary) notFound();
  const { stock, reviews } = summary;
  return (
    <>
      <p>{stock ? `${stock.boxes} boxes in stock` : "Stock unknown right now."}</p>
      {!reviews ? (
        <p>Reviews are unavailable right now.</p>
      ) : reviews.latest ? (
        <p>
          Rated {reviews.average} from {reviews.count} reviews. {reviews.latest.author}: {reviews.latest.text}
        </p>
      ) : (
        <p>No reviews yet.</p>
      )}
    </>
  );
}

import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  /* config options here */
  cacheComponents: true,
  partialPrefetching: true,
  async rewrites() {
    return [
      {
        // Only the public reviews of a tea, for ids like "mint". No other path on the service.
        source: "/reviews-api/reviews/:tea([a-z-]{1,30})",
        destination: `${process.env.REVIEWS_API_URL}/reviews/:tea`,
      },
    ];
  },
};

export default nextConfig;

import "server-only";

// The apps that call this API. A client id says which app it is. It ships inside the app,
// so anyone can copy it: it's for counting and coarse limits, never for deciding who sees what.
const clients = new Set(["phone-app"]);

// A stand-in rate limit: 4 requests a minute for each client id, counted in this server's memory.
const calls = new Map<string, { start: number; count: number }>();
const minute = 60_000;

// Recording fixture: FIXED_NOW freezes the clock, so the recording never depends on timing. Never set it in production.
const now = () => (process.env.FIXED_NOW ? Number(process.env.FIXED_NOW) : Date.now());

export function limitClient(request: Request) {
  const client = request.headers.get("x-client-id");
  if (!client || !clients.has(client)) return Response.json({ error: "Send a known x-client-id" }, { status: 400 });
  const time = now();
  const current = calls.get(client);
  if (!current || time - current.start >= minute) {
    calls.set(client, { start: time, count: 1 });
    return null;
  }
  current.count += 1;
  if (current.count <= 4) return null;
  const retryAfter = Math.ceil((current.start + minute - time) / 1000);
  return Response.json({ error: "Too many requests" }, { status: 429, headers: { "retry-after": String(retryAfter) } });
}

export const teaId = /^[a-z-]{1,30}$/;

import "server-only";
import { z } from "zod";
import { NoSuchTea } from "./errors";

const Reviews = z.object({
  reviews: z.array(z.object({ author: z.string(), stars: z.number().min(1).max(5), text: z.string() })),
});

export async function getReviews(id: string) {
  const response = await fetch(`${process.env.REVIEWS_API_URL}/reviews/${encodeURIComponent(id)}`, {
    // Give up after one second.
  });
  if (response.status === 404) throw new NoSuchTea(id);
  if (!response.ok) throw new Error(`The reviews service answered ${response.status}`);
  const { reviews } = Reviews.parse(await response.json());
  const stars = reviews.reduce((total, review) => total + review.stars, 0);
  return {
    average: reviews.length ? stars / reviews.length : null,
    count: reviews.length,
    latest: reviews[0] ? { author: reviews[0].author, text: reviews[0].text } : null,
  };
}

import "server-only";
import { z } from "zod";
import { NoSuchTea } from "./errors";

const Reviews = z.object({
  reviews: z.array(z.object({ author: z.string(), stars: z.number().min(1).max(5), text: z.string() })),
});

export async function getReviews(id: string) {
  const response = await fetch(`${process.env.REVIEWS_API_URL}/reviews/${encodeURIComponent(id)}`, {
    signal: AbortSignal.timeout(1000),
  });
  if (response.status === 404) throw new NoSuchTea(id);
  if (!response.ok) throw new Error(`The reviews service answered ${response.status}`);
  const { reviews } = Reviews.parse(await response.json());
  const stars = reviews.reduce((total, review) => total + review.stars, 0);
  return {
    average: reviews.length ? stars / reviews.length : null,
    count: reviews.length,
    latest: reviews[0] ? { author: reviews[0].author, text: reviews[0].text } : null,
  };
}

import type { NextRequest } from "next/server";

export async function GET(request: NextRequest) {
  const tea = request.nextUrl.searchParams.get("tea");
  const response = await fetch(`${process.env.REVIEWS_API_URL}/reviews/${tea}`);
  return Response.json(await response.json(), { status: response.status });
}

import type { NextRequest } from "next/server";
import { teaId } from "@/lib/public-api";
import { NoSuchTea } from "@/services/errors";
import { getReviews } from "@/services/reviews";

export async function GET(request: NextRequest) {
  const tea = request.nextUrl.searchParams.get("tea") ?? "";
  if (!teaId.test(tea)) return Response.json({ error: "Not a tea id" }, { status: 400 });
  try {
    return Response.json(await getReviews(tea));
  } catch (error) {
    if (error instanceof NoSuchTea) return Response.json({ error: "No such tea" }, { status: 404 });
    return Response.json({ error: "Reviews are unavailable" }, { status: 503 });
  }
}

import "server-only";
import { getReviews } from "@/services/reviews";
import { getStock } from "@/services/stock";

export async function getTeaSummary(id: string) {
  const [stock, reviews] = await Promise.all([getStock(id), getReviews(id)]);
  return { stock, reviews };
}

import "server-only";
import { NoSuchTea } from "@/services/errors";
import { getReviews } from "@/services/reviews";
import { getStock } from "@/services/stock";

export async function getTeaSummary(id: string) {
  const [stock, reviews] = await Promise.allSettled([getStock(id), getReviews(id)]);
  // A 404 says there's no such tea: an answer to pass on, not a failure to hide.
  if ([stock, reviews].some((result) => result.status === "rejected" && result.reason instanceof NoSuchTea)) return null;
  return {
    stock: stock.status === "fulfilled" ? stock.value : null,
    reviews: reviews.status === "fulfilled" ? reviews.value : null,
  };
}

Check your understanding

For each question, ask what each server received, and what reached the browser.

Key takeaways

• A backend for frontend stands between one frontend and the services behind it. In Next.js, Server Components, Route Handlers and Server Actions call the services on the server.
• A public Route Handler is an API: version it, check what it's sent, answer 404 for what doesn't exist, and rate-limit it. A client id only labels the app; people sign in. CORS is only about browsers.
• A rewrite in next.config.ts passes the visitor's request on, cookies and Authorization included, and returns the answer unchanged. Allow only public paths, and use proxy.ts or a Route Handler when a service mustn't get those headers.
• Never build a service's address from what a caller sent: check ids, escape them, and keep the rest of the address fixed.
• Call services in parallel with Promise.allSettled and a timeout for each, so a slow or broken service only costs its own part of the page.
• Shape each answer into a DTO and keep keys in server-only modules. Long jobs, live connections and rules shared by many clients belong in a separate backend.

Coming next: Monorepos. Several apps and shared packages in one repository, like a design system that the shop's website and its staff dashboard both use.