Next.js App Router skill for Claude Code

A well-built App Router app renders on the server by default, pushes "use client" to the leaves, states its caching intent explicitly for every data source, invalidates by tag after every mutation, and never relies on caching defaults it has not checked for the installed version.

Step 0 — establish the version and caching model

Caching rules changed in every major. Check before writing any data code:

npm ls next react            # Next 15.x vs 16.x
grep -n "cacheComponents\|dynamicIO\|ppr\|staleTimes" next.config.*
ls middleware.ts proxy.ts src/middleware.ts src/proxy.ts 2>/dev/null

Setup	Caching model
Next 16 with cacheComponents: true	Everything is dynamic unless marked "use cache"; uncached data must sit under <Suspense>; cacheLife/cacheTag control lifetime; segment config dynamic/revalidate not used
Next 15, or 16 without cacheComponents	fetch is not cached by default; opt in with next: { revalidate, tags } or force-cache; segment config (export const revalidate, dynamic) applies
Next 14 or older	fetch cached by default — read the project’s docs version; do not apply this skill’s defaults blindly

For the full caching matrix, invalidation APIs, and migration notes read references/caching-and-revalidation.md whenever a task touches caching, revalidation, or “stale data” bugs.

File conventions

app/
  layout.tsx            # root layout: <html>, <body>, providers; persists across navigation
  page.tsx              # route UI; Server Component by default
  loading.tsx           # Suspense fallback for the segment
  error.tsx             # "use client"; error boundary for the segment (receives error, reset)
  not-found.tsx         # rendered by notFound()
  global-error.tsx      # catches errors in the root layout; must render <html><body>
  (marketing)/          # route group: organizes without affecting the URL
  dashboard/
    layout.tsx          # nested layout; does NOT re-render on child navigation
    @analytics/         # parallel route slot; needs default.tsx (required in 16)
    [id]/page.tsx       # dynamic segment
  api/webhooks/route.ts # route handler (no page.tsx in the same segment)
proxy.ts                # Next 16 (was middleware.ts; middleware still works but is deprecated)

Workflow for a new route or feature

- [ ] 1. Sketch the segment tree: which layouts persist, where loading/error boundaries go
- [ ] 2. Fetch data in Server Components (page/layout), close to where it is used
- [ ] 3. Declare caching intent for each data source (cached + tag, or dynamic)
- [ ] 4. Mark only interactive leaves "use client"; pass serializable props
- [ ] 5. Mutations via Server Actions (or route handlers for external callers)
- [ ] 6. Invalidate tags/paths after every mutation
- [ ] 7. Add metadata, loading and error states, notFound()
- [ ] 8. next build — read the route table (static vs dynamic) and fix surprises

Pages, params, and types

params and searchParams are Promises since Next 15 (sync access removed in 16). cookies(), headers(), and draftMode() are async too.

// app/blog/[slug]/page.tsx
import { notFound } from "next/navigation";

export default async function Page({ params }: PageProps<"/blog/[slug]">) {
  const { slug } = await params;
  const post = await getPost(slug);
  if (!post) notFound();
  return <Article post={post} />;
}

export async function generateStaticParams() {
  return (await listPosts()).map((p) => ({ slug: p.slug }));
}

PageProps<"/route"> / LayoutProps<"/route"> are generated globally by next dev, next build, or next typegen (15.5+). If unavailable, type as { params: Promise<{ slug: string }> }. Upgrade sync access with the codemod: npx @next/codemod@latest upgrade latest.

Server/client boundary rules

• Default to Server Components. Add "use client" only for state, effects, event handlers, browser APIs, or client-only libraries.
• The directive marks a boundary: everything imported into a client file becomes client code. Put it on the smallest interactive component, not on a page or layout.
• Pass Server Components into client components as children or other props to keep them on the server.
• Import server-only in modules that read secrets or the database so an accidental client import fails the build.
• Only NEXT_PUBLIC_* env vars reach the browser, and they are inlined at build time — changing them requires a rebuild.
• Deeper RSC rules (serialization, Server Action security, streaming) live in react-server-components.

Data fetching

• Fetch in parallel; sequential awaits in one component create waterfalls:

const [user, invoices] = await Promise.all([getUser(id), getInvoices(id)]);

• Deduplicate non-fetch calls used by both generateMetadata and the page with React cache():

import { cache } from "react";
export const getPost = cache(async (slug: string) => db.post.findUnique({ where: { slug } }));

• Stream slow parts: wrap them in <Suspense fallback={...}> so the shell renders first.
• Never call your own route handlers from Server Components (fetch("/api/...")); call the data function directly. It saves a network hop and avoids absolute-URL bugs at build time.

Mutations

// app/posts/actions.ts
"use server";
import { revalidateTag } from "next/cache";
import { redirect } from "next/navigation";

export async function publishPost(formData: FormData) {
  const session = await auth();                      // authorize inside every action
  if (!session) throw new Error("Unauthorized");
  const id = String(formData.get("id"));
  await db.post.update({ where: { id, authorId: session.userId }, data: { published: true } });
  revalidateTag("posts", "max");                     // Next 16 signature; Next 15: revalidateTag("posts")
  redirect(`/posts/${id}`);                          // throws; call outside try/catch
}

• In Next 16, use updateTag("posts") inside Server Actions when the user must see their own write immediately (read-your-writes); revalidateTag(tag, "max") serves stale while refreshing in the background.
• redirect() and notFound() work by throwing; never wrap them in try/catch that swallows the error.
• Use route handlers (route.ts) for webhooks, third-party callers, file streams, and non-React clients; use Server Actions for your own forms and buttons.

Route handlers

// app/api/webhooks/stripe/route.ts
export async function POST(request: Request) {
  const body = await request.text();               // raw body for signature checks
  const sig = request.headers.get("stripe-signature");
  // verify, then process idempotently
  return Response.json({ received: true });
}

GET handlers are dynamic by default from Next 15. Opt a GET into static with export const dynamic = "force-static" (without cacheComponents) or "use cache" in a helper (with it).

Proxy (middleware)

• Next 16 renames middleware.ts to proxy.ts with an exported proxy function; it runs on the Node.js runtime. Codemod: npx @next/codemod@latest middleware-to-proxy .
• Keep it thin: redirects, rewrites, locale detection, coarse auth gating via cookie presence. Always re-check authorization in the page, action, or handler — proxy is not a security boundary on its own.
• Scope it with export const config = { matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"] }.

Metadata

export async function generateMetadata({ params }: PageProps<"/blog/[slug]">): Promise<Metadata> {
  const post = await getPost((await params).slug);          // deduped by cache()
  return { title: post?.title, alternates: { canonical: `/blog/${post?.slug}` } };
}

Set metadataBase in the root layout so relative OG URLs resolve. Use file conventions for opengraph-image.tsx, sitemap.ts, robots.ts, icon.png.

Gotchas

• useSearchParams() in a client component on a static route needs a <Suspense> boundary or the build bails out of static rendering for the whole page.
• Layouts do not receive searchParams and do not re-render on navigation between sibling pages — do not read per-page state there.
• error.tsx does not catch errors in the layout of the same segment; place it one level up or use global-error.tsx for the root.
• A single cookies() or headers() call makes the route dynamic (or, with Cache Components, requires a Suspense boundary). Read them as deep in the tree as possible.
• Parallel route slots without default.tsx 404 on hard refresh (and fail the build in 16).
• next lint is removed in 16 — run npx eslint . directly.
• Turbopack is the default bundler in 16; custom webpack config needs migration or next build --webpack.

Verification

1. npx next build succeeds. Read the route table: each route is static, ISR, or dynamic as you intended. Investigate every unexpected dynamic route.
2. npx next start (not dev — dev does not cache like production) and exercise the mutation: the changed data appears after the action, and a second browser session sees it after revalidation.
3. Check the network tab: no client-side waterfall of requests that the server could have done, no secrets in RSC payloads.
4. Type-check with npx tsc --noEmit.

Output when reporting changes

**Routes touched:** /dashboard (dynamic), /blog/[slug] (static, tag `posts`)
**Caching:** getPost → "use cache" + cacheTag("posts") + cacheLife("days")
**Invalidation:** publishPost → updateTag("posts")
**Client boundaries:** LikeButton, CommentForm (everything else server)
**Verified:** next build route table matches; mutation visible after action in next start