The production checklist

The tea shop, the day before launch

The tea shop is ready to go live. Every page works on the developer's computer, and next build passes. A production checklist asks a different question: what will real visitors, search engines and attackers get from the running app? Its answer is a list of checks you can run, each linked to the lesson that teaches the fix.

Here is the shop as it was. It's a real Next.js 16.4.3 project: ESLint checked it, next build built it, and next start served the pages the audit asked for. Open the Terminal tab.

1import { getTea } from "../../supplier";2import BuyButton from "./buy-button";3 4// Left over from adopting Cache Components.5export const instant = false;6 7export default async function TeaPage({ params }: PageProps<"/teas/[id]">) {8  const { id } = await params;9  const tea = await getTea(id);10  if (!tea) return <p>We could not find that tea.</p>;11  return (12    <main>13      <h1>{tea.name}</h1>14      <p>${tea.price} a box</p>15      <BuyButton id={id} />16    </main>17  );18}

$ npx eslint ./my-app/app/layout.tsx  10:11  warning  Using `<img>` could result in slower LCP and higher bandwidth. Consider using `<Image />` from `next/image` or a custom image loader to automatically optimize images. This may incur additional usage or cost from your provider. See: https://nextjs.org/docs/messages/no-img-element  @next/next/no-img-element  10:11  warning  img elements must have an alt prop, either with meaningful text, or an empty string for decorative images                                                                                                                                                                                jsx-a11y/alt-text ✖ 2 problems (0 errors, 2 warnings) $ next build▲ Next.js 16.4.3 (Turbopack)- Environments: .env- Cache Components enabled- Partial Prefetching enabled   Creating an optimized production build ...✓ Compiled successfully  Running TypeScript ...  Finished TypeScript ...  Collecting page data ...✓ Generating static pages (4/4)  Finalizing page optimization ... Route (app)┌ ○ /├ ○ /_not-found└   /teas/[id]  └ ◐ /teas/[id] ○  (Static)             prerendered as static content◐  (Partial Prerender)  prerendered as static HTML with dynamic server-streamed content

ESLint printed two warnings, and the build passed. Nothing in the Terminal says the shop has a problem. Yet the audit found one in every group of checks: the payment key is in the JavaScript, the pages have no security headers, every tea is made on each visit, every page has the same title, and a tea that doesn't exist gets a normal page. A passing build checks that the code compiles and the pages render. It doesn't check what the running app sends.

Running the audit, before and after

An audit is a handful of commands, run in the project's folder:

npx eslint .
npm run build
npm run start
curl -s -D - -o /dev/null http://localhost:3000/teas/mint
curl -s -o /dev/null -w "%{http_code}\n" http://localhost:3000/teas/oolong
grep -rl "sk_tea_" .next/static
curl -s http://localhost:3000/teas/mint | grep -c "sk_tea_"
curl -s -H "rsc: 1" "http://localhost:3000/teas/mint?_rsc=" | grep -c "sk_tea_"

Line 1 runs ESLint, which next build no longer does since Next.js 16. Line 2 builds the app and prints the route table. Line 3 starts it. With the server running, in a second terminal, line 4 asks for /teas/mint and prints the response's status and headers (-D -), dropping the page itself (-o /dev/null). Line 5 asks for a tea the shop doesn't sell and prints only the status code. Line 6 searches every file the build made for the browser, under .next/static, and prints the names of the ones that contain sk_tea_, the start of each of the shop's secret keys. Lines 7 and 8 search what the server sends for a page, and print how many lines hold the key: its HTML, which also carries the RSC payload in inline scripts, and the RSC payload on its own, which rsc: 1 asks for, as the router does. A rendered value or a Client Component's prop would show up there, not in .next/static. The recordings in the playground asked for the same pages, and searched the JavaScript and the RSC payload of /teas/mint.

Pick each version. Read the Terminal first, then the Network tab, which opens on /teas/mint. Before you switch, guess which problems the fixes made disappear from the Terminal.

1import { getTea } from "../../supplier";2import BuyButton from "./buy-button";3 4// Left over from adopting Cache Components.5export const instant = false;6 7export default async function TeaPage({ params }: PageProps<"/teas/[id]">) {8  const { id } = await params;9  const tea = await getTea(id);10  if (!tea) return <p>We could not find that tea.</p>;11  return (12    <main>13      <h1>{tea.name}</h1>14      <p>${tea.price} a box</p>15      <BuyButton id={id} />16    </main>17  );18}

$ npx eslint ./my-app/app/layout.tsx  10:11  warning  Using `<img>` could result in slower LCP and higher bandwidth. Consider using `<Image />` from `next/image` or a custom image loader to automatically optimize images. This may incur additional usage or cost from your provider. See: https://nextjs.org/docs/messages/no-img-element  @next/next/no-img-element  10:11  warning  img elements must have an alt prop, either with meaningful text, or an empty string for decorative images                                                                                                                                                                                jsx-a11y/alt-text ✖ 2 problems (0 errors, 2 warnings) $ next build▲ Next.js 16.4.3 (Turbopack)- Environments: .env- Cache Components enabled- Partial Prefetching enabled   Creating an optimized production build ...✓ Compiled successfully  Running TypeScript ...  Finished TypeScript ...  Collecting page data ...✓ Generating static pages (4/4)  Finalizing page optimization ... Route (app)┌ ○ /├ ○ /_not-found└   /teas/[id]  └ ◐ /teas/[id] ○  (Static)             prerendered as static content◐  (Partial Prerender)  prerendered as static HTML with dynamic server-streamed content

Some of what the audit found is in the tabs, and some only in the recording: which JavaScript files hold the key, and when the supplier's API was asked. Each row is one check, and what it found in each version:

None of the fixes is new: each one has a lesson of its own, linked from its line of the checklist.

Performance checks

Performance is what visitors feel: how soon the main content shows, whether things jump, how fast a click answers. In the shop, ESLint pointed at line 10 of app/layout.tsx: the logo is a plain <img> with no alt. After the fix it's next/image with alt="", since the logo sits next to the shop's name and adds nothing a screen reader should say, and ESLint finds nothing. Each row is one check:

The recordings here are one visit on a fast computer, which is lab data. Only field data, from real visitors' devices, says whether a launch went well, which is why the first row comes first.

Security checks

Security checks ask what an attacker can read or do. The shop's Buy button called the payment provider from the browser, so it needed the key there, and the key's name started with NEXT_PUBLIC_:

1"use client";2 3export default function BuyButton({ id }: { id: string }) {4  async function buy() {5    await fetch("https://payments.example/checkout", {6      method: "POST",7      headers: { authorization: `Bearer ${process.env.NEXT_PUBLIC_PAYMENTS_KEY}` },8      body: JSON.stringify({ tea: id }),9    });10  }11  return <button onClick={buy}>Buy</button>;12}13 

Line 1 makes the file a Client Component, so its code goes to the browser. Line 7 reads process.env.NEXT_PUBLIC_PAYMENTS_KEY, and the prefix tells next build to write the value into that code. The recording found sk_tea_ in the JavaScript /teas/mint loads. The fix moves the call to a Server Action, and drops the prefix from the name in .env:

"use server";

import { menu } from "./menu";

// A Server Action is a public endpoint: check what it was sent.
export async function startCheckout(id: string) {
  if (!menu.some((tea) => tea.id === id)) throw new Error("Unknown tea");
  // A stand-in for the payment provider's API. The key never leaves the server.
  await fetch(`${process.env.PAYMENTS_API_URL}/checkout`, {
    method: "POST",
    headers: { authorization: `Bearer ${process.env.PAYMENTS_KEY}` },
    body: JSON.stringify({ tea: id }),
  });
}

Line 1 makes every function in the file a Server Action: the button calls it, and it runs on the server. Line 7 checks the tea id, because anyone can call the action with any value. Lines 9 to 13 call the provider, and line 11 reads process.env.PAYMENTS_KEY. Without the prefix, the build doesn't copy the value into any JavaScript, but the name alone doesn't keep it private. It stays private because only this server code reads it, and never renders it, returns it or passes it to a Client Component. The provider's address is a stand-in. After the fix, the recording found no sk_tea_ in the JavaScript, in the page, or in its RSC payload.

The Network tab showed the other finding. The recording keeps the headers that describe a page, and the ones the audit looked for. Before, /teas/mint sent these, with no security header among them:

Vary: rsc, next-router-state-tree, next-router-prefetch, next-router-segment-prefetch, Accept-Encoding
x-nextjs-stale-time: 300
x-nextjs-prerender: 1
x-nextjs-postponed: 1
X-Powered-By: Next.js
Cache-Control: private, no-cache, no-store, max-age=0, must-revalidate
Content-Type: text/html; charset=utf-8

After the fix, next.config.ts adds five headers to every response with headers(), and poweredByHeader: false removes X-Powered-By. Each row is one check:

Caching and rendering checks

Caching checks ask who waits, and for what. In the first build, the route table listed the tea pages only as ◐ /teas/[id]: a shell made during the build, and the whole tea made on every visit. The stand-in for the supplier's API kept a log, and it was asked while the server ran, on every visit to a tea page. The page fetched without a cache, and nothing in it said which teas to prerender. So why did the build allow it? Here is the same page without line 5:

1import { getTea } from "../../supplier";2import BuyButton from "./buy-button";3 4export default async function TeaPage({ params }: PageProps<"/teas/[id]">) {5  const { id } = await params;6  const tea = await getTea(id);7  if (!tea) return <p>We could not find that tea.</p>;8  return (9    <main>10      <h1>{tea.name}</h1>11      <p>${tea.price} a box</p>12      <BuyButton id={id} />13    </main>14  );15}

$ next build▲ Next.js 16.4.3 (Turbopack)- Environments: .env- Cache Components enabled- Partial Prefetching enabled   Creating an optimized production build ...✓ Compiled successfully  Running TypeScript ...  Finished TypeScript ...  Collecting page data ...Error: Route "/teas/[id]": Next.js encountered uncached or runtime data during prerendering. `fetch(...)`, `cookies()`, `headers()`, `params`, `searchParams`, or `connection()` accessed outside of `<Suspense>` prevents the route from being prerendered, blocking the page load and leading to a slower user experience. Ways to fix this:  - [stream] Provide a placeholder with `<Suspense fallback={...}>` around the data access  - [cache] For uncached data (`fetch`, database calls): cache the access with `"use cache"` (does not apply to `connection()`)  - [block] Set `export const instant = false` to allow a blocking route Learn more: https://nextjs.org/docs/messages/blocking-prerender-dynamic    at body (<anonymous>)    at html (<anonymous>)To get a more detailed stack trace and pinpoint the issue, try one of the following:  - Start the app in development mode by running `next dev`, then open "/teas/[id]" in your browser to investigate the error.  - Rerun the production build with `next build --debug-prerender` to generate better stack traces.Error occurred prerendering page "/teas/[id]". Read more: https://nextjs.org/docs/messages/prerender-errorExport encountered an error on /teas/[id]/page: /teas/[id], exiting the build.⨯ Next.js build worker exited with code: 1 and signal: null

Without it, the build stops: Route "/teas/[id]": Next.js encountered uncached or runtime data during prerendering, and the message lists three fixes. The third, [block], is export const instant = false. It turns off the check that a route has a static shell to send at once, so a migration can switch on Cache Components first and fix routes one by one. The shop's line 5 was left over from that. The fix is the second one, [cache]:

1import { cacheLife, cacheTag } from "next/cache";2 3export type Tea = { name: string; price: number };4 5// Each tea's name and price, from the supplier's API, kept for hours.6export async function getTea(id: string) {7  "use cache";8  cacheLife("hours");9  cacheTag(`tea-${id}`);10  const response = await fetch(`${process.env.SUPPLIER_API_URL}/teas/${id}`);11  if (!response.ok) return null;12  return (await response.json()) as Tea;13}14 

Line 7 caches what getTea returns, for each id. Line 8 keeps it for hours, and line 9 tags it, so a Server Action can refresh one tea with updateTag. With generateStaticParams listing the menu, the build asked the supplier once for each tea and printed ○ /teas/green and ○ /teas/mint. And /teas/mint now answers Cache-Control: s-maxage=3600, stale-while-revalidate=82800, which lets a CDN keep it for an hour.

Each row is one check:

Error pages and monitoring

Error checks ask what happens when something is missing or breaks, and who finds out. In the first version, a tea the shop doesn't sell got this, on line 10 of the page:

1import { getTea } from "../../supplier";2import BuyButton from "./buy-button";3 4// Left over from adopting Cache Components.5export const instant = false;6 7export default async function TeaPage({ params }: PageProps<"/teas/[id]">) {8  const { id } = await params;9  const tea = await getTea(id);10  if (!tea) return <p>We could not find that tea.</p>;11  return (12    <main>13      <h1>{tea.name}</h1>14      <p>${tea.price} a box</p>15      <BuyButton id={id} />16    </main>17  );18}19 

/teas/oolong answered 200 every time, with We could not find that tea. and no noindex. That's a soft 404: a page that says it's missing, with a status that says everything is fine, which search engines may keep in their results. The fix calls notFound(). Now the first visit answered 200 with <meta name="robots" content="noindex">, because the page had already started streaming when the supplier answered 404, and the second answered 404, from the result Next.js kept. Both pass the check. Not found, forbidden and unauthorized explains why the status can't change once streaming has started.

The rest of this group can't be seen in a recording that has no errors. Each row is one check:

SEO and metadata checks

SEO checks ask what search engines and link previews read. Before the fixes, every page's <title> was Tea shop, and /robots.txt and /sitemap.xml answered 404. After them, the root layout has a title template, %s | Tea shop, and the tea's page fills it in with generateMetadata: /teas/mint is Mint tea | Tea shop, with the description Mint tea, $3 a box.. app/robots.ts and app/sitemap.ts made the two files, and both answered 200. Each row is one check:

Checks that run on every release

A checklist you run once stops being true: the next Client Component can bring the key back. So put every check a script can make in one file, and let your CI service run it on every change:

#!/bin/sh
# Stop at the first command that fails.
set -e
npx eslint .
npx vitest run
npm run build
# Fail when any built file holds the start of a secret key.
if grep -rl "sk_tea_" .next/static; then exit 1; fi
npx playwright test

Line 3 stops the script at the first command that fails, which fails the CI job. Line 4 lints, and line 5 runs the unit tests. Line 6 builds, which also type-checks the project. Line 8 searches the built files: grep succeeds when it finds sk_tea_, and then exit 1 fails the job. Line 9 runs the end-to-end tests, whose Playwright config builds and starts the app, as in End-to-end testing, and they can ask for each page and check its status and headers too. Each row is one more check for the release:

Some checks need a person, though. Sort these:

Common mix-ups

• "The build passed, so the app is ready." No. The tea shop's build passed with a key in its JavaScript, no security headers and a soft 404. A build checks the code, not what the running app sends.
• "A secret no page shows is safe." No. The key never appeared on screen, but it was in the JavaScript of /teas/mint. Search .next/static too.
• "poweredByHeader: false makes the app secure." No. It removes one header. A Next.js app is still easy to recognize, so the protection is a patched version.
• "instant = false is harmless once the build passes." No. It turned off the check that would have stopped the build, and every visit to a tea waited for the supplier.
• "A missing page must always answer 404." No. Once a page has started streaming, its status is sent. Next.js adds noindex instead, and a later request can get 404.
• "One good Lighthouse score means visitors are happy." No. That's one visit in a lab. Field data from real visitors decides.
• "A checklist is for launch day." No. Each release can bring a problem back, so the checks a script can make run on every change.

Practice exercises

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

Route (app)
┌ ○ /
├ ○ /_not-found
├ ○ /robots.txt
├ ○ /sitemap.xml
└   /teas/[id]
  ├ ◐ /teas/[id]
  ├ ○ /teas/green
  └ ○ /teas/mint

"use client";

export default function BuyButton({ id }: { id: string }) {
  async function buy() {
    await fetch("https://payments.example/checkout", {
      method: "POST",
      headers: { authorization: `Bearer ${process.env.NEXT_PUBLIC_PAYMENTS_KEY}` },
      body: JSON.stringify({ tea: id }),
    });
  }
  return <button onClick={buy}>Buy</button>;
}

Vary: rsc, next-router-state-tree, next-router-prefetch, next-router-segment-prefetch, Accept-Encoding
x-nextjs-stale-time: 300
x-nextjs-prerender: 1
x-nextjs-postponed: 1
X-Powered-By: Next.js
Cache-Control: private, no-cache, no-store, max-age=0, must-revalidate
Content-Type: text/html; charset=utf-8

import { getTea } from "../../supplier";
import BuyButton from "./buy-button";

// Left over from adopting Cache Components.
export const instant = false;

export default async function TeaPage({ params }: PageProps<"/teas/[id]">) {
  const { id } = await params;
  const tea = await getTea(id);
  if (!tea) return <p>We could not find that tea.</p>;
  return (
    <main>
      <h1>{tea.name}</h1>
      <p>${tea.price} a box</p>
      <BuyButton id={id} />
    </main>
  );
}

import { getTea } from "../../supplier";
import BuyButton from "./buy-button";

// Left over from adopting Cache Components.
export const instant = false;

export default async function TeaPage({ params }: PageProps<"/teas/[id]">) {
  const { id } = await params;
  const tea = await getTea(id);
  if (!tea) return <p>We could not find that tea.</p>;
  return (
    <main>
      <h1>{tea.name}</h1>
      <p>${tea.price} a box</p>
      <BuyButton id={id} />
    </main>
  );
}

import { cacheLife, cacheTag } from "next/cache";

export type Tea = { name: string; price: number };

// Each tea's name and price, from the supplier's API, kept for hours.
export async function getTea(id: string) {
  "use cache";
  cacheLife("hours");
  cacheTag(`tea-${id}`);
  const response = await fetch(`${process.env.SUPPLIER_API_URL}/teas/${id}`);
  if (!response.ok) return null;
  return (await response.json()) as Tea;
}

Check your understanding

For each question, think about what the running app sends, not what the code says.

Key takeaways

• A passing build checks the code. The checklist checks what the running app sends, and what its JavaScript holds.
• The audit looks in four places: npx eslint ., the route table, requests to next start, and a search of .next/static.
• Each group protects something: performance what visitors feel, security what attackers get, caching who waits, errors what happens when things go wrong, SEO what search engines read.
• Leftover opt-outs like instant = false hide problems the build would otherwise report. Search for them.
• A missing page answers 404, or 200 with noindex once it has started streaming.
• Put every check a script can make in CI, run it on every release, and keep a short list for people.

Coming next: Upgrading Next.js. It reads release notes, runs real codemods on a shop written for Next.js 14, and moves it to 16.4.3 step by step.