web-meta-framework-nextjs

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, <Suspense> 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_requirements>

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 <Suspense> for granular streaming)

(You MUST use the Metadata API (metadata object or generateMetadata) for SEO - never manual <head> 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)

</critical_requirements>

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>

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

</philosophy>

<patterns>

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 segm