Next.js 16 Cheat Sheet: 75 App Router Patterns for Production

Create a new App Router project

create-next-app configures Next.js, React, TypeScript, and the selected tooling. Commit package-lock.json with the project.

npx create-next-app@latest my-app --ts --app --src-dir

Use the current Node.js baseline

Next.js 16 requires Node.js 20.9 or newer. Pin a supported version in local development and CI so builds do not depend on a runner's changing default.

Know the four normal scripts

next dev starts development, next build creates the production output, next start serves that output, and your configured linter runs separately.

"scripts": {
  "dev": "next dev",
  "build": "next build",
  "start": "next start",
  "lint": "eslint ."
}

Install reproducibly in CI

Use npm ci when package-lock.json is committed. It rejects lockfile drift and installs the resolved dependency tree without rewriting the lockfile.

npm ci && npm run build

Use Turbopack by default

In Next.js 16, both next dev and next build use Turbopack by default. Remove old --turbo flags unless a script needs to support another version.

Temporarily keep a webpack build

A project with custom webpack configuration can explicitly opt out while that configuration is migrated. Test both output and performance before switching the production builder.

next build --webpack

Keep application code under src

src/app and src/lib separate application code from root configuration. The public directory and files such as next.config.ts remain at the project root.

Use an import alias

A stable alias avoids long relative paths when code moves between route folders. Keep the alias in tsconfig.json or jsconfig.json.

import { getUser } from "@/lib/data";

Create a page

A page.tsx file makes its folder's route publicly accessible. The default export is the UI for that URL.

export default function Page() {
  return <h1>About</h1>;
}

Create a required root layout

app/layout.tsx wraps every route and must render html and body. Put global CSS, language, site-wide providers, and metadata defaults here.

Nest layouts by route segment

A layout inside app/dashboard wraps the dashboard page and all descendants. Layouts persist across client navigation within their subtree.

Group routes without changing the URL

Parentheses create a route group. app/(marketing)/pricing/page.tsx still resolves to /pricing.

app/(marketing)/pricing/page.tsx

Create a dynamic segment

Square brackets capture one URL segment. In Next.js 16, await params before reading the value.

export default async function Page({ params }) {
  const { slug } = await params;
  return <h1>{slug}</h1>;
}

Capture several segments

[...parts] is a required catch-all and [[...parts]] is optional. Use them for hierarchical docs or other paths whose depth is data-driven.

Prebuild known dynamic paths

generateStaticParams returns parameter objects for routes Next.js should generate at build time.

export function generateStaticParams() {
  return posts.map((post) => ({ slug: post.slug }));
}

Reject unknown dynamic paths

Set dynamicParams to false when only values returned by generateStaticParams should resolve. Other parameter values return 404.

export const dynamicParams = false;

Render a missing resource

Call notFound when the route exists but its requested entity does not. Next.js renders the nearest not-found.tsx boundary.

if (!post) notFound();

Reset state with a template

template.tsx looks like a layout but remounts on navigation. Use it when state and effects should reset; keep persistent shells in layouts.

Render simultaneous route slots

Folders such as @team and @analytics define parallel route slots passed to a parent layout. Supply default.tsx fallbacks for unmatched slots on a hard navigation.

Open a route as a modal

Intercepting routes can show another route inside the current layout during soft navigation while preserving its full-page result for refreshes and shared links.

Keep pages server-side by default

A Server Component can await data, use private environment variables, and render without sending its component code to the browser.

Declare a Client Component

Place the directive before imports. The client boundary includes that module and the client-side dependency graph it imports.

"use client";

import { useState } from "react";

Use clients for interaction

State, effects, event handlers, custom hooks, window, localStorage, and other browser APIs belong in Client Components.

Use servers for private work

Database queries, service credentials, large server-only libraries, and most content rendering belong in Server Components or server-only modules.

Pass serializable props to clients

Strings, numbers, booleans, arrays, plain objects, and supported React values can cross the boundary. Shape data narrowly and do not pass full private records.

Mark private modules server-only

The side-effect import makes a client import fail at build time, which protects data-access code from accidental browser use.

import "server-only";

Move the client boundary downward

Keep a server-rendered page and layout, then isolate a search box, menu, picker, or chart as the smallest practical Client Component.

Pass server UI through client children

A Client Component can receive a Server Component as a child or another prop. This keeps the server-rendered subtree out of the client's own module graph.

Add providers as deep as possible

Context is unavailable in Server Components. Render a focused Client Component provider around only the subtree that consumes it, not the whole document by default.

Fetch in an async Server Component

Call an API, ORM, or database from the component that renders the result. You do not need an internal Route Handler only to call your own server.

export default async function Page() {
  const products = await getProducts();
  return <ProductList products={products} />;
}

Start independent work together

Promise.all prevents an avoidable request waterfall when neither operation needs the other's result.

const [user, projects] = await Promise.all([
  getUser(),
  getProjects(),
]);

Stream with a route loading file

loading.tsx wraps the segment in a Suspense boundary and provides immediate fallback UI during navigation and request-time rendering.

Stream one slow region

Place Suspense around the slow component so the rest of the page can render first. Make the fallback resemble the final dimensions.

<Suspense fallback={<ActivitySkeleton />}>
  <RecentActivity />
</Suspense>

Memoize one render pass

React cache can deduplicate the same server-side data function and arguments during a render. It is not a persistent application data cache.

import { cache } from "react";

export const getUser = cache(async (id) => db.user.findUnique({ where: { id } }));

Enable Cache Components

Next.js 16's use cache APIs require the cacheComponents setting. Migrate intentionally because this changes rendering and caching behavior.

const nextConfig = { cacheComponents: true };
export default nextConfig;

Cache an async function

With Cache Components enabled, place use cache at the top of an async function or component body. Serializable arguments become part of the cache key.

export async function getProducts() {
  "use cache";
  return db.product.findMany();
}

Set a cache lifetime

cacheLife accepts a named profile or custom timing values. Pick a lifetime from the content's acceptable staleness, not from convenience.

"use cache";
cacheLife("hours");

Tag related cached work

cacheTag gives several entries a shared invalidation label, such as products or post-42.

"use cache";
cacheTag("products");

Expire a path

Call revalidatePath from a Server Function or Route Handler after a change makes a page or layout stale.

revalidatePath("/blog");

Revalidate by tag

Use revalidateTag when tagged content may use stale-while-revalidate behavior. Select the cache profile that matches the freshness requirement.

Read your own write with updateTag

Call updateTag inside a Server Action when the action's user must see fresh tagged data immediately after the mutation.

await savePost(input);
updateTag("posts");

Declare a Server Action

Put use server at the top of an async function or action module. Exported Server Actions must be treated as remotely callable mutation endpoints.

"use server";

export async function createPost(formData: FormData) {
  // validate, authorize, mutate, invalidate
}

Bind an action to a form

A form can call a Server Action without a custom client submit handler. The browser's form behavior also gives you a progressive-enhancement path.

<form action={createPost}>...</form>

Validate FormData on the server

Treat names, IDs, files, hidden inputs, and client-side validation as untrusted. Parse into an explicit schema before writing.

Return expected form errors

Use a serializable result and useActionState for validation or business errors the user can correct. Do not throw for every expected outcome.

Show pending form state

useFormStatus reads the status of the parent form submission. Disable repeat submits and give the button an honest pending label.

Create a Route Handler

route.ts exports HTTP verb functions and uses the Web Request and Response APIs. A route.ts file cannot share the same segment as page.tsx.

export async function GET() {
  return Response.json({ status: "ok" });
}

Read a dynamic Route Handler parameter

Route context params are asynchronous in current Next.js. Await them before querying the resource.

export async function GET(request, { params }) {
  const { id } = await params;
  return Response.json(await getItem(id));
}

Redirect after a mutation

Use redirect for a temporary navigation after a successful create or update, and permanentRedirect only when the resource has a lasting new canonical URL.

redirect("/dashboard");

Keep retries safe

Webhooks and network requests can arrive more than once. Store provider event IDs or idempotency keys before repeating payments, emails, or other side effects.

Use Link for internal navigation

next/link enables client-side transitions and can prefetch routes as they enter the viewport. Use a normal anchor for downloads and links whose browser behavior you do not want Next.js to manage.

<Link href="/pricing">Pricing</Link>

Navigate after an event

In a Client Component, use useRouter from next/navigation for imperative push, replace, refresh, back, or forward behavior.

const router = useRouter();
router.push("/dashboard");

Read the current pathname

usePathname is a Client Component hook. Use it for active navigation state, not as a substitute for server route parameters.

Read query parameters

A page receives searchParams on the server. Interactive client controls can use useSearchParams and update the URL through the router.

Catch uncaught route errors

error.tsx is a Client Component error boundary for its route subtree. Log the error and offer a meaningful retry or safe navigation action.

Handle root failures

global-error.tsx catches errors in the root layout and must render its own html and body elements because the normal root shell failed.

Distinguish empty, missing, and failed

An empty list is valid data, a missing entity is a 404, an expected rejected input is a normal result, and an uncaught exception belongs in an error boundary.

Set static metadata

Export metadata from a Server Component layout or page when the values do not depend on route data.

export const metadata = {
  title: "Pricing",
  description: "Simple plans for growing teams.",
};

Generate dynamic metadata

Use generateMetadata for entity-specific titles, descriptions, canonical URLs, and social images. Reuse the route's data access function where possible.

Set metadataBase once

A root metadataBase lets canonical links and image fields use relative paths while Next.js resolves absolute URLs.

metadataBase: new URL("https://example.com")

Generate a sitemap

app/sitemap.ts returns public URLs and optional lastModified, changeFrequency, and priority fields. Build it from the real content catalog; Google ignores changeFrequency and priority, so keep lastModified accurate instead of manufacturing freshness.

Publish robots rules

app/robots.ts returns crawl rules and the sitemap location. Robots rules are crawl hints, not access control for private routes.

Use optimized images

next/image needs intrinsic dimensions or a fill container. Supply accurate alt text and responsive sizes; use priority only for genuinely critical above-the-fold images.

Load fonts with next/font

next/font self-hosts the selected font files and reduces external requests. Limit weights and subsets to the styles the interface actually uses.

Schedule third-party scripts

next/script controls when external JavaScript loads. Choose afterInteractive or lazyOnload unless the integration truly belongs on the critical path.

Keep secrets server-side

Environment values are server-only unless their name starts with NEXT_PUBLIC_. Anything public-prefixed should be treated as browser-visible and fixed according to the build environment.

Authorize every server entry point

Check the current identity and its permission in Server Actions, Route Handlers, and protected data access. A hidden button or Proxy redirect is not a security boundary.

Use Proxy for request-bound routing logic

Next.js 16 uses proxy.ts for rewrites, redirects, and optimistic checks before a request reaches a route. Keep secure authorization near the data too.

Use secure session cookies

Set HTTP-only, secure, same-site, path, and expiry attributes to match the session design. Rotate and invalidate sessions through the authentication system.

Send narrow data to the browser

Convert records into DTOs that contain only fields the interface needs. Taint APIs can add defense in depth, but do not replace careful output shaping.

Run checks separately

Next.js 16 does not rely on next build to run linting. Make lint, TypeScript, tests, and the production build separate CI steps.

npm run lint
npx tsc --noEmit
npm test
npm run build

Test the production server

Run next build and next start locally or in a preview. Development behavior can hide production-only import, cache, environment, and rendering problems.

Read the route build summary

The next build output identifies prerendered and request-rendered routes. Investigate a route that becomes dynamic or grows unexpectedly instead of treating the build as a pass/fail box.

Expose a truthful health route

Return a small successful response only when the process is ready for traffic. Keep secrets and detailed dependency information out of the public body.

export function GET() {
  return Response.json({ status: "ok" });
}

Deploy the normal production process

A standard server deployment installs from the lockfile, runs next build, starts with next start, injects runtime secrets, checks health, and promotes only a healthy release.

build_cmd: npm ci && npm run build
start_cmd: npm start

runtime:
  name: node@24
  port: 3000
  health_path: /api/health