--- 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:** Use Server Components by default, add `"use client"` only for interactivity. Use `loading.tsx` for route-level loading states, `` for granular streaming. Keep Client Components small and leaf-level. Use Server Actions for mutations with `'use server'` directive, revalidate cache after every mutation. --- ## CRITICAL: Before Using This Skill > **All code must follow project conventions in CLAUDE.md** (kebab-case, named exports, import ordering, `import type`, named constants) **(You MUST use Server Components by default - add `"use client"` ONLY when you need state, effects, or event handlers)** **(You MUST keep `"use client"` components small and push them to the leaves of your component tree)** **(You MUST use `loading.tsx` for route-level loading states and `` for granular streaming)** **(You MUST use the Metadata API (`metadata` object or `generateMetadata`) for SEO - never manual `` tags)** **(You MUST use `server-only` package for code with secrets to prevent accidental client exposure)** **(You MUST add `'use server'` directive at the top of the file OR at the top of the async function for Server Actions)** **(You MUST revalidate the cache after mutations using `revalidatePath()` or `revalidateTag()`)** **(You MUST validate all input data on the server - client-side validation is NOT sufficient for security)** **(You MUST perform authorization checks inside EVERY Server Action - they are public HTTP endpoints)** **(You MUST call `revalidatePath()` BEFORE `redirect()` to ensure fresh data)** --- **Auto-detection:** Next.js App Router, page.tsx, layout.tsx, loading.tsx, error.tsx, Server Components, Client Components, "use client", streaming, Suspense, parallel routes, intercepting routes, generateMetadata, generateStaticParams, Turbopack, next/form, use cache, cacheComponents, cacheLife, cacheTag, PPR, instrumentation.ts, after(), typedRoutes, proxy.ts, updateTag, refresh, Server Actions, use server directive, revalidatePath, revalidateTag, formAction, useActionState, useFormStatus, useOptimistic, server mutation **When to use:** - Building Next.js applications with the App Router (`app/` directory) - Implementing file-based routing with layouts, loading states, and error boundaries - Deciding when to use Server Components vs Client Components - Implementing streaming and progressive rendering with Suspense - Setting up SEO with the Metadata API - Building advanced routing patterns (parallel routes, intercepting routes, modals) - Creating, updating, or deleting data with Server Actions - Performing server-side mutations triggered by user actions - Invalidating cached data after state changes **Key patterns covered:** - File conventions (page.tsx, layout.tsx, loading.tsx, error.tsx, not-found.tsx) - Server Components vs Client Components boundary decisions - Streaming with Suspense and loading.tsx - Parallel Routes and Intercepting Routes for modals - Route Groups and Dynamic Routes - Metadata API for SEO optimization - generateStaticParams for static generation - Next.js 15.5+ features (PPR, Turbopack builds, typed routes, after() API) - Next.js 16 features (Cache Components, proxy.ts, updateTag, refresh, React 19.2) - Server Action definition (`'use server'` directive) - Form actions with progressive enhancement - Cache revalidation patterns (revalidatePath, revalidateTag) - Pending states (useActionState, useFormStatus) - Optimistic updates (useOptimistic) - Error handling and validation in Server Actions **When NOT to use:** - Pages Router (`pages/` directory) - different patterns apply - Pure React without Next.js framework - Non-App Router Next.js projects **Detailed Resources:** - For decision frameworks and anti-patterns, see [reference.md](reference.md) **App Router patterns:** - [examples/core.md](examples/core.md) - File conventions, dynamic routes, layouts, error handling, server-only code - [examples/server-components.md](examples/server-components.md) - Server vs Client Components, composition patterns, streaming with Suspense - [examples/metadata.md](examples/metadata.md) - Static metadata, dynamic generateMetadata, Open Graph, SEO - [examples/parallel-routes.md](examples/parallel-routes.md) - Parallel routes, intercepting routes, modal patterns - [examples/route-groups.md](examples/route-groups.md) - Route groups for different layouts per section - [examples/nextjs-15-features.md](examples/nextjs-15-features.md) - PPR, Turbopack builds, typed routes, after() API, instrumentation, Next.js 16 migration **Server Actions & Mutations:** - [examples/server-actions.md](examples/server-actions.md) - Server Action definition, form actions, validation, authorization, pending states - [examples/mutations.md](examples/mutations.md) - Parallel mutations, running independent actions concurrently - [examples/revalidation.md](examples/revalidation.md) - Cache invalidation strategies, path vs tag revalidation - [examples/optimistic.md](examples/optimistic.md) - useOptimistic for instant UI feedback - [examples/event-handlers.md](examples/event-handlers.md) - Calling Server Actions from click handlers, useTransition - [examples/streaming.md](examples/streaming.md) - Streaming progress updates for long-running operations - [examples/cookies.md](examples/cookies.md) - Cookie manipulation in Server Actions --- ## Philosophy The App Router represents a paradigm shift from traditional React: **Server Components are the default**, and client-side JavaScript is opt-in. This reduces bundle size, improves initial load performance, and allows data fetching directly in components without client-server waterfalls. **Core principles:** 1. **Server-first rendering** - Components run on the server by default, shipping zero JavaScript to the client 2. **Streaming and progressive rendering** - HTML streams to the browser as it becomes available 3. **Colocation** - Data fetching, styling, and metadata live alongside the components that need them 4. **Nested layouts** - Layouts persist across navigations, preserving state and avoiding re-renders 5. **File-based conventions** - Special files define behavior (page.tsx, layout.tsx, loading.tsx, error.tsx) 6. **Server-side mutations** - Server Actions execute on the server with integrated cache revalidation 7. **Progressive enhancement** - Form-based actions work without JavaScript enabled **Server Actions are asynchronous functions that execute on the server**, invoked via network requests from the client. They integrate with Next.js caching and revalidation, enabling single-roundtrip updates where both UI and data refresh together. Server Actions are ideal for form submissions and mutations tightly coupled to UI. Use Route Handlers for external API consumers, webhooks, or complex multi-step operations requiring parallel execution. **React 19 Integration:** - `useActionState`, `useFormStatus`, and `useOptimistic` are React 19 hooks (not Next.js-specific) - `useActionState` replaces the deprecated `ReactDOM.useFormState` from React Canary - These hooks work with Server Actions for form state management --- ## Core Patterns ### Pattern 1: File-Based Routing Conventions The App Router uses a file-system based router where folders define routes and special files define UI and behavior. #### File Conventions | File | Purpose | Required | | --------------- | -------------------------------------------------------------- | -------- | | `page.tsx` | Unique UI for a route, makes the route publicly accessible | Yes | | `layout.tsx` | Shared UI for a segment and its children, preserves state | No | | `loading.tsx` | Loading UI for a segment, automatically wraps page in Suspense | No | | `error.tsx` | Error UI for a segment, catches runtime errors | No | | `not-found.tsx` | Not found UI, triggered by `notFound()` function | No | | `template.tsx` | Re-rendered layout (doesn't preserve state) | No | | `default.tsx` | Fallback UI for parallel routes when no match | No | #### Route Segment Structure ``` app/ ├── layout.tsx # Root layout (required) ├── page.tsx # Home page (/) ├── loading.tsx # Loading state for / ├── error.tsx # Error boundary for / ├── not-found.tsx # 404 page ├── dashboard/ │ ├── layout.tsx # Dashboard layout (nested) │ ├── page.tsx # /dashboard │ ├── loading.tsx # Loading state for /dashboard │ ├── settings/ │ │ └── page.tsx # /dashboard/settings │ └── [id]/ │ └── page.tsx # /dashboard/:id (dynamic) └── (marketing)/ # Route group (no URL impact) ├── about/ │ └── page.tsx # /about └── blog/ └── page.tsx # /blog ``` **Why this works:** File conventions eliminate boilerplate routing configuration, layouts automatically nest, and special files provide consistent behavior patterns across the app. --- ### Pattern 2: Server Components vs Client Components Server Components are the default in the App Router. Use `"use client"` directive only when necessary. #### When to Use Server Components (Default) - Fetching data from databases or APIs - Accessing backend resources (file system, environment variables) - Keeping sensitive information on the server (API keys, tokens) - Reducing client-side JavaScript bundle - Rendering static content #### When to Use Client Components (`"use client"`) - Adding interactivity with event handlers (`onClick`, `onChange`) - Using React state (`useState`, `useReducer`) - Using lifecycle effects (`useEffect`, `useLayoutEffect`) - Using browser-only APIs (`localStorage`, `window`, `navigator`) - Using custom hooks that depend on state or effects #### Composition Pattern: Server Wrapping Client ```tsx // app/dashboard/page.tsx (Server Component - default) import { getUser } from "@/lib/data"; import { UserProfile } from "./user-profile"; export default async function DashboardPage() { const user = await getUser(); // Server-side data fetch return (

Dashboard

{/* Pass data as props to Client Component */}
); } ``` ```tsx // app/dashboard/user-profile.tsx (Client Component) "use client"; import { useState } from "react"; import type { User } from "@/lib/types"; interface UserProfileProps { user: User; } export function UserProfile({ user }: UserProfileProps) { const [isEditing, setIsEditing] = useState(false); return (

{user.name}

); } ``` **Why good:** Server Component fetches data without client-side JavaScript, Client Component handles only the interactive parts, minimal JavaScript shipped to browser --- ### Pattern 3: Streaming with Suspense and loading.tsx Streaming allows progressive rendering by sending HTML chunks as they become available. #### Route-Level Loading with loading.tsx ```tsx // app/dashboard/loading.tsx export default function DashboardLoading() { return (
); } ``` **Why good:** Automatically wraps page in Suspense boundary, shows loading state immediately while data fetches, no manual Suspense setup needed #### Granular Streaming with Suspense ```tsx // app/dashboard/page.tsx import { Suspense } from "react"; import { RevenueChart, RevenueChartSkeleton } from "./revenue-chart"; import { LatestInvoices, InvoicesSkeleton } from "./latest-invoices"; export default function DashboardPage() { return (

Dashboard

{/* Each section streams independently */} }> }>
); } ``` **Why good:** Slow data fetches don't block fast ones, users see content progressively, each section loads independently improving perceived performance --- ### Pattern 4: Layouts and Nested Layouts Layouts wrap page content and persist across navigations within their segment. #### Root Layout (Required) ```tsx // app/layout.tsx import type { Metadata } from "next"; import "./globals.css"; export const metadata: Metadata = { title: { template: "%s | Acme", default: "Acme", }, description: "The React Framework for the Web", }; export default function RootLayout({ children, }: { children: React.ReactNode; }) { return ( {children} ); } ``` #### Nested Layout with Navigation ```tsx // app/dashboard/layout.tsx import { DashboardNav } from "./dashboard-nav"; export default function DashboardLayout({ children, }: { children: React.ReactNode; }) { return (
{children}
); } ``` **Why good:** Navigation state persists when switching between dashboard pages, layout doesn't re-render on navigation, shared UI defined once --- ### Pattern 5: Error Handling with error.tsx Error boundaries catch runtime errors and display fallback UI. #### Error Boundary Component ```tsx // app/dashboard/error.tsx "use client"; // Error components must be Client Components import { useEffect } from "react"; interface ErrorProps { error: Error & { digest?: string }; reset: () => void; } export default function DashboardError({ error, reset }: ErrorProps) { useEffect(() => { // Log error to reporting service console.error("Dashboard error:", error); }, [error]); return (

Something went wrong!

{error.message}

); } ``` **Why good:** Errors are contained to the segment (rest of app remains functional), reset function allows retry without full page reload, digest provides server-side error reference #### Global Error Handler ```tsx // app/global-error.tsx "use client"; export default function GlobalError({ error, reset, }: { error: Error & { digest?: string }; reset: () => void; }) { return (

Something went wrong!

); } ``` **Note:** global-error.tsx must define its own `` and `` tags as it replaces the root layout when triggered. --- ### Pattern 6: Metadata API for SEO Use static `metadata` object or dynamic `generateMetadata` function for SEO. #### Static Metadata ```tsx // app/about/page.tsx import type { Metadata } from "next"; export const metadata: Metadata = { title: "About Us", description: "Learn more about our company", openGraph: { title: "About Us | Acme", description: "Learn more about our company", images: ["/og-about.png"], }, }; export default function AboutPage() { return

About Us

; } ``` #### Dynamic Metadata with generateMetadata ```tsx // app/blog/[slug]/page.tsx import type { Metadata } from "next"; import { getPost } from "@/lib/data"; interface PageProps { params: Promise<{ slug: string }>; } export async function generateMetadata({ params, }: PageProps): Promise { const { slug } = await params; const post = await getPost(slug); if (!post) { return { title: "Post Not Found" }; } return { title: post.title, description: post.excerpt, openGraph: { title: post.title, description: post.excerpt, images: [post.coverImage], type: "article", publishedTime: post.publishedAt, }, }; } export default async function BlogPostPage({ params }: PageProps) { const { slug } = await params; const post = await getPost(slug); // ... } ``` **Why good:** Type-safe metadata, automatic deduplication, fetch requests memoized across generateMetadata and page component --- ### Pattern 7: Static Generation with generateStaticParams Pre-render dynamic routes at build time for performance. ```tsx // app/blog/[slug]/page.tsx import { getAllPosts, getPost } from "@/lib/data"; // Generate static params at build time export async function generateStaticParams() { const posts = await getAllPosts(); return posts.map((post) => ({ slug: post.slug, })); } interface PageProps { params: Promise<{ slug: string }>; } export default async function BlogPostPage({ params }: PageProps) { const { slug } = await params; const post = await getPost(slug); return (

{post.title}

); } ``` **Why good:** Pages pre-rendered at build time for instant loading, combined with generateMetadata for complete static optimization, new posts added via ISR --- ### Pattern 8: Dynamic Routes Use folder naming conventions for dynamic segments. #### Single Dynamic Segment ```tsx // app/users/[id]/page.tsx interface PageProps { params: Promise<{ id: string }>; } export default async function UserPage({ params }: PageProps) { const { id } = await params; return

User: {id}

; } ``` #### Catch-All Segments ```tsx // app/docs/[...slug]/page.tsx // Matches /docs/a, /docs/a/b, /docs/a/b/c, etc. interface PageProps { params: Promise<{ slug: string[] }>; } export default async function DocsPage({ params }: PageProps) { const { slug } = await params; // slug is an array: ["a", "b", "c"] return

Docs: {slug.join("/")}

; } ``` #### Optional Catch-All Segments ```tsx // app/shop/[[...slug]]/page.tsx // Matches /shop, /shop/a, /shop/a/b, etc. interface PageProps { params: Promise<{ slug?: string[] }>; } export default async function ShopPage({ params }: PageProps) { const { slug } = await params; // slug is undefined for /shop, or an array for nested paths return

Shop: {slug?.join("/") ?? "All Products"}

; } ``` --- ### Pattern 9: Route Groups Organize routes without affecting URL structure using `(groupName)` folders. ``` app/ ├── (marketing)/ │ ├── layout.tsx # Marketing-specific layout │ ├── about/ │ │ └── page.tsx # /about (not /marketing/about) │ └── blog/ │ └── page.tsx # /blog ├── (shop)/ │ ├── layout.tsx # Shop-specific layout │ └── products/ │ └── page.tsx # /products └── layout.tsx # Root layout ``` **Why good:** Different layouts for different sections without URL nesting, logical grouping of related routes, multiple root layouts possible --- ### Pattern 10: Parallel Routes and Slots Render multiple pages simultaneously in the same layout using `@slot` folders. #### Dashboard with Multiple Slots ``` app/ └── dashboard/ ├── @analytics/ │ ├── page.tsx # Analytics slot content │ └── default.tsx # Fallback when no match ├── @team/ │ ├── page.tsx # Team slot content │ └── default.tsx ├── layout.tsx # Receives slots as props └── page.tsx # Main dashboard content ``` ```tsx // app/dashboard/layout.tsx export default function DashboardLayout({ children, analytics, team, }: { children: React.ReactNode; analytics: React.ReactNode; team: React.ReactNode; }) { return (
{children}
{analytics}
{team}
); } ``` **Why good:** Independent loading states per slot, parallel data fetching, conditional rendering based on user role --- ### Pattern 11: Intercepting Routes for Modals Intercept navigation to show content in a modal while preserving the original route. #### Modal Pattern Structure ``` app/ ├── @modal/ │ ├── (.)photo/[id]/ │ │ └── page.tsx # Intercepted route (modal) │ └── default.tsx # Returns null when no modal ├── photo/[id]/ │ └── page.tsx # Full page (direct navigation) └── layout.tsx ``` #### Intercepting Convention | Convention | Description | | ---------- | ------------------- | | `(.)` | Match same level | | `(..)` | Match one level up | | `(..)(..)` | Match two levels up | | `(...)` | Match from root | ```tsx // app/@modal/(.)photo/[id]/page.tsx import { Modal } from "@/components/modal"; import { getPhoto } from "@/lib/data"; interface PageProps { params: Promise<{ id: string }>; } export default async function PhotoModal({ params }: PageProps) { const { id } = await params; const photo = await getPhoto(id); return ( {photo.title}

{photo.title}

 ); } ``` ```tsx // app/@modal/default.tsx export default function Default() { return null; } ``` ```tsx // app/layout.tsx export default function RootLayout({ children, modal, }: { children: React.ReactNode; modal: React.ReactNode; }) { return ( {children} {modal} ); } ``` **Why good:** Modal shows on soft navigation with shareable URL, full page renders on hard refresh or direct link, back button closes modal --- ### Pattern 12: Defining Server Actions Define Server Actions using the `'use server'` directive. Place it at the file level (recommended for Client Component imports) or function level (for Server Components). #### File-Level Directive (Recommended) ```typescript // app/actions.ts "use server"; import { revalidatePath } from "next/cache"; export async function createPost(formData: FormData) { const title = formData.get("title") as string; const content = formData.get("content") as string; // Mutation logic here (defer to your database solution) // ... revalidatePath("/posts"); } ``` **Why good:** File-level directive marks all exports as Server Actions, clear separation of server code, can be imported into Client Components #### Function-Level Directive (Server Components Only) ```typescript // app/page.tsx - Server Component export default function Page() { async function createPost(formData: FormData) { 'use server' // Server Action logic } return
...
} ``` **Why good:** Inline definition when action is only used in one place, directive at function level keeps action close to usage --- ### Pattern 13: Form Actions with Progressive Enhancement Invoke Server Actions via the `action` attribute on forms. This enables progressive enhancement - forms work even without JavaScript. ```typescript // app/posts/new/page.tsx import { createPost } from '@/app/actions' export default function NewPostPage() { return (