Next.js App Router cheat sheet

• Each folder in app/ is a URL segment. It is public only with a page (or route) file. (group) adds no URL part. _private is skipped.
• [slug] one segment. [...parts] one or more. [[...rest]] zero or more.
• params and searchParams are Promises: const { slug } = await props.params.
• generateStaticParams builds known values (●). dynamicParams = false makes the rest 404.
• Use the Link component for internal links (no reload, prefetch, layout state kept). A plain anchor reloads the page.

layout.tsx

Wraps pages, stays mounted, keeps state

template.tsx

Like layout, new instance per navigation

loading.tsx

Suspense fallback for the whole page

error.tsx

Error boundary: must be 'use client'

not-found.tsx

404 screen, also for notFound()

route.ts

HTTP endpoint. Never beside page.tsx

proxy.ts

Runs before requests (was middleware.ts)

• 'use client' marks a boundary: the file and its imports ship. Keep it on small interactive leaves, never on a page or layout.
• A Server Component goes inside a Client one only as children or a prop, never by import.
• Props crossing the boundary: plain data, Date, Map, Set, bigint work. Functions and class instances give a 500.
• Stream a promise: start it on the server, pass it down, read it with use inside Suspense.

Watch out: Props are public (the RSC payload is in the page). Never pass a whole DB row: send a DTO. Add import 'server-only' to server files.

• Fetch in an async Server Component. No effect, no loading state, secrets stay on the server.
• Identical fetch calls in one render run once (memoization, one render only). Wrap DB reads in React cache().
• Independent requests: Promise.all or one Suspense box each. Sequential awaits took 1.5 s, parallel 0.5 s.
• Do not fetch your own route handler from a Server Component. Share a function.

// next.config.ts
const nextConfig = {
  cacheComponents: true };

async function getPosts() {
  "use cache";
  cacheLife("hours");
  cacheTag("posts");
  return db.posts.findMany();
}

• Uncached or runtime data outside Suspense fails the build: stream it, cache it, or block on purpose.
• cookies() inside use cache fails: read outside, pass as an argument. Date.now() needs connection() or caching.
• dynamic and revalidate exports are build errors when cacheComponents is on.

• Layers: request memoization (one render), use cache (server), prerendered output (build or CDN), router cache (browser, 5 min).
• One-argument revalidateTag('x') is deprecated. Test caching with build + start, never dev.
• Default use cache store is in memory: serverless instances do not share it.

"use server";
export async function addTodo(_p, fd) {
  const u = await verifySession();
  const r = Schema.safeParse(
    { t: fd.get("t") });
  if (!r.success)
    return { errors: r.error.flatten() };
  await db.todo.create(
    { ...r.data, owner: u.id });
  updateTag("todos"); // before redirect
  return { ok: true };
}

• Works with JavaScript off (plain POST). With JS it is one fetch round trip that also returns the fresh page.
• An action is a public POST endpoint: authenticate, authorize the row (IDOR), validate, in every action. Hidden button is not security.
• Next.js checks Origin vs host, caps the body at 1 MB, hides action ids. curl skips the origin check.
• redirect() throws: never inside try/catch. Revalidate before it. Actions run one at a time.
• Extra argument: action.bind(null, id). Treat it as client input.

• route.ts exports GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS. A missing method gives 405.
• In the default model GET handlers are dynamic. Cache with dynamic = 'force-static' or revalidate. Only GET caches.
• Validate query, body (400 bad JSON, 422 bad fields), headers. Use 201, 204, 404. Keep one error shape.
• Webhooks: HMAC the raw body, compare with timingSafeEqual, then parse.
• CORS is a browser rule, not a firewall. Allow-list the origin, send Vary: Origin.
• Auth, validation and rate limiting inside every handler.

• proxy.ts (renamed from middleware.ts) can redirect, rewrite, set headers. One file per project.
• Always set a matcher, or it also runs on _next/static, images and public/.
• NextResponse.next({ request: { headers } }) changes what the app receives. response.headers.set changes what the client gets.
• Not for slow work, DB calls or fetch caching. Config redirects run before Proxy.

Watch out: Proxy is an optimistic filter, not a lock. A client can forge any header Proxy does not overwrite (an excluded route let x-user-hint: admin through).

• Authentication proves who. Session remembers it (cookie). Authorization decides what they may do.
• Session cookie set on the server: httpOnly, secure, sameSite, expiry. await cookies(). A signed token is readable, so keep secrets out.
• Pin the algorithm (algorithms: ['HS256']) when verifying. Bad token gives null.
• Hash passwords with a slow hash (bcrypt). Give one vague login error.

Tip: Stateless cookie: cannot revoke early. Database session: instant logout and role change. Wrong owner: 403, or 404 to hide it exists.

• Static pages are frozen: new Date() shows build time. revalidate = 5 means stale after 5 s, next visit rebuilds (x-nextjs-cache: HIT, STALE, MISS).
• Streaming: shell first, each Suspense box when ready, siblings in parallel. Prefer small boundaries. Do not await request data at the top of a layout.
• Status code is fixed after the first chunk: notFound() inside Suspense gives 200 plus noindex. Decide 404 and redirects before the boundary.

• Export metadata or generateMetadata (Server Component). viewport is separate. Set metadataBase once, or social images point at localhost.
• Metadata merges shallowly: a page's openGraph replaces the layout's. Share data with cache().
• Bots wait for the title in the head: keep generateMetadata fast.
• opengraph-image.tsx, sitemap.ts, robots.ts make real files. Disallow is not noindex and not security.
• next/image: set width/height (no shift), AVIF/WebP, remotePatterns. priority is deprecated: use preload or fetchPriority.
• next/font self-hosts and adds a size-matched fallback.

1. Env load order: real environment, .env.$(NODE_ENV).local, .env.local, .env.$(NODE_ENV), .env.
2. Server variables stay on the server. NEXT_PUBLIC_ values are inlined at build time; docker run -e cannot change them.
3. Static pages read env at build. Dynamic routes read it per request.
4. output: 'standalone': run node server.js, copy public and .next/static yourself (402 MB to 67 MB).
5. Docker: multi-stage, non-root user, HOSTNAME=0.0.0.0, ARG for public values.
6. instrumentation.ts: register() once, onRequestError for errors. Add a cheap dynamic health route.

Watch out: Several instances need a shared cache handler, the same NEXT_SERVER_ACTIONS_ENCRYPTION_KEY and a deployment ID. Proxies that buffer break streaming (X-Accel-Buffering: no).