/web-meta-framework-nextjs

name: web-meta-framework-nextjs
description: Next.js App Router patterns (15-16) - file-based routing, Server/Client Components, streaming, Suspense, metadata API, parallel routes, Server Actions, mutations, revalidation, Cache Components

Next.js App Router Patterns

> **Quick Guide:** Server Components are the default and `"use client"` is opt-in, so keep client > components small and at the leaves of the tree. Reads happen in Server Components; writes happen in > Server Actions, which are public HTTP endpoints and revalidate the cache themselves. Two version > facts change the answers below: from 15, `params`, `searchParams`, `cookies()` and `headers()` are > Promises; in 16, `middleware.ts` became `proxy.ts`, `revalidateTag()` takes a `cacheLife` profile, > and `experimental_ppr` became `cacheComponents`.

**Detailed Resources:**

• [examples/core.md](examples/core.md) — file conventions, dynamic routes, layouts, error and not-found UI, server-only code
• [examples/server-components.md](examples/server-components.md) — the Server/Client boundary, composition, streaming with Suspense
• [examples/metadata.md](examples/metadata.md) — title templates, `generateMetadata`, Open Graph and Twitter cards
• [examples/parallel-routes.md](examples/parallel-routes.md) — `@slot` folders, intercepting routes, the modal pattern
• [examples/route-groups.md](examples/route-groups.md) — one layout per section without changing URLs
• [examples/versions.md](examples/versions.md) — PPR, Turbopack, typed routes, `after()`, instrumentation, and the v16 migration
• [examples/server-actions.md](examples/server-actions.md) — action definition, form actions, validation, authorization, pending states
• [examples/mutations.md](examples/mutations.md) — running independent actions together
• [examples/revalidation.md](examples/revalidation.md) — path versus tag invalidation, tagging fetches
• [examples/optimistic.md](examples/optimistic.md) — `useOptimistic` for instant feedback
• [examples/event-handlers.md](examples/event-handlers.md) — invoking actions from click handlers with `useTransition`
• [examples/streaming.md](examples/streaming.md) — progress updates from long-running actions
• [examples/cookies.md](examples/cookies.md) — reading and writing cookies inside actions
• [reference.md](reference.md) — decision trees, route segment config, hook signatures, version-by-version changes

---

Which path applies

• **On Next.js 16** — caching is opt-in and several APIs were renamed; read the migration half of

[examples/versions.md](examples/versions.md) before copying any cache, middleware or parallel-route pattern.

• **On the Pages Router (`pages/`)** — a different set of conventions applies and none of the files

above describe it.

---

<critical_requirements>

Before writing Next.js code

**Write components as Server Components, and add `"use client"` only for state, effects or event handlers.** The directive is what decides whether the code ships to the browser, so keeping it at the leaves keeps the bundle small and secrets on the server.

**Import `server-only` in any module that touches a secret.** The build then fails at the offending import instead of shipping the key to the browser.

**Give data-heavy routes a `loading.tsx`, and independent sections their own `<Suspense>`.** `loading.tsx` wraps the page in a boundary automatically; a boundary per section stops the slowest fetch blocking the fastest.

**Set SEO through the `metadata` object or `generateMetadata`.** Next.js deduplicates and orders those tags, which manual `<head>` markup does not.

**Mark Server Actions with `'use server'` — at the top of the file, or at the top of the async function.** Without it the function is bundled for the client.

**Validate the input and check authorization inside every Server Action.** An action is a public HTTP endpoint reachable by its ID, so both the caller's identity and the payload's shape are unverified until the action verifies them.

**Call `revalidatePath()` or `revalidateTag()` after a mutation, and before any `redirect()`.** The cache is what the next render reads, and `redirect()` throws, so nothing after it runs.

**Await `params`, `searchParams`, `cookies()` and `headers()`.** All four are Promises from 15 onward.

</critical_requirements>

---

**Auto-detection:** page.tsx, layout.tsx, loading.tsx, error.tsx, not-found.tsx, default.tsx, template.tsx, "use client", "use server", "use cache", App Router, Server Components, Client Components, generateMetadata, generateStaticParams, parallel routes, intercepting routes, revalidatePath, revalidateTag, updateTag, useActionState, useFormStatus, useOptimistic, next/form, next/cache, next/navigation, cacheComponents, cacheLife, cacheTag, PPR, Turbopack, typedRoutes, instrumentation.ts, proxy.ts, after()

**Applies to:**

• Routing an app through the `app/` directory, with layouts, loading states and error boundaries
• Deciding which components run on the server and which ship to the browser
• Streaming and progressive rendering with Suspense
• SEO through the Metadata API, and static generation with `generateStaticParams`
• Parallel and intercepting routes, including modals with shareable URLs
• Creating, updating and deleting data in Server Actions, and invalidating the cache afterwards

**Handled elsewhere:**

• Persistence — an action calls a data layer; neither the client nor the query shape is settled here
• Authentication and session retrieval — the action asks who the caller is and acts on the answer
• Schema validation — an action parses `FormData` through a schema; which schema library defines it

is a separate choice

• Component styling — components take a `className`, and the styling approach is someone else's
• Client state that outlives a single component tree — Client Components receive data as props

---

<philosophy>

Philosophy

The App Router inverts React's default: components run on the server unless they say othe