Next.js App Router: Coding Standards & Best Practices

Comprehensive reference for building Next.js applications with the App Router. Apply these standards whenever writing or reviewing Next.js code. Security-specific patterns are in the nextjs-security skill; testing in nextjs-testing; debugging in nextjs-troubleshooting.

Core Philosophy

Server First: Default every component to a React Server Component. Only opt into 'use client' at leaf components that strictly require state, effects, or browser APIs. This minimizes the JavaScript shipped to the browser.

1. Project Structure

app/
  layout.tsx              # Root layout (replaces _app and _document)
  page.tsx                # Home route
  error.tsx               # Error boundary for this segment
  not-found.tsx           # 404 handling
  (marketing)/            # Route Group — no URL impact
    about/page.tsx
  (shop)/
    products/page.tsx
  api/                    # Route Handlers
lib/
  dal.ts                  # Data Access Layer (server-only)
  auth.ts                 # Authentication utilities
components/
  ui/                     # Client Components (interactive leaf nodes)
  server/                 # Server Components (data-fetching wrappers)

Rules

• Use Route Groups (name) to organize routes without affecting URLs. Effective for separate layouts or logical grouping (e.g., (auth), (dashboard)).
• For large apps, adopt a monorepo strategy (Turborepo) for shared components.
• Place all database queries and external API calls in a dedicated Data Access Layer (lib/dal.ts) marked with import 'server-only'.

2. Server vs. Client Component Boundaries

Server Components (default) — execute on the server, ship zero JS to the browser. Use for data fetching, backend logic, and static UI.

Client Components ('use client') — required only for useState, useEffect, event handlers, or browser APIs (localStorage, window).

The Composition Pattern

A Server Component cannot be imported into a Client Component. Instead, pass it as a children prop from a parent Server Component. React resolves the server code first, then passes the serialized RSC Payload to the client. See references/server-client-patterns.md for complete code examples.

Boundary Rules

• Mark modules with sensitive logic using import 'server-only' — build fails if accidentally imported client-side.
• Props crossing the boundary must be serializable (no Date, Map, Set, or functions).
• Push 'use client' to the deepest leaf possible to minimize the client bundle.

3. Data Fetching Patterns

Server Components

Fetch data directly with async/await in Server Components — no useEffect or client-side libraries needed. See references/server-client-patterns.md for complete data fetching and streaming examples.

Critical Patterns

• Data Access Layer (DAL): Centralize all queries in a server-only module. Perform authorization checks and return minimal DTOs, never raw database records.
• Parallel Fetching: Use Promise.all() or Promise.allSettled() for independent requests. Sequential await statements create waterfalls.
• Request Deduplication: Wrap DAL functions with React.cache() so multiple components requesting the same data in one render only trigger one query.
• Streaming with Suspense: Wrap async components in <Suspense fallback={<Skeleton />}> to stream content progressively.

Server Actions

Server Actions are public POST endpoints — always treat input as hostile:

• Validate all input with Zod or Valibot using safeParse().
• Re-verify authentication and authorization inside every action (never rely solely on middleware).
• Use revalidatePath() or revalidateTag() after successful mutations.
• Native <form action={serverAction}> works even before client JS loads.

See references/server-client-patterns.md for complete Server Action patterns with form submission and streaming examples.

Anti-Patterns

• Avoid placing sequential await calls that don't depend on each other — use Promise.all() instead.
• Avoid accessing cookies(), headers(), or searchParams outside a <Suspense> boundary — doing so forces the entire route dynamic.
• Never perform mutations (database writes, cookie setting) during component rendering — use Server Actions or Route Handlers.

4. Caching & Revalidation

Next.js 15+ Defaults

fetch requests, GET Route Handlers, and the Client Router Cache are uncached by default. Opt into caching explicitly.

Caching Patterns

• `"use cache"` directive (Next.js 16): Apply at the function, component, or page level for explicit caching. The compiler generates cache keys automatically.
• On-demand revalidation: After mutations, call revalidatePath('/path') or revalidateTag('tag') inside Server Actions.
• ISR (time-based): Configure expiration for content that changes periodically (product catalogs, blog posts). Serves cached content while regenerating in the background.
• Streaming Promises to Client: Pass an unresolved Promise as a prop and unwrap with React use() inside a <Suspense> boundary.

5. Performance Optimization

See references/performance-checklist.md for the complete CWV optimization reference.

Key rules:

• LCP: priority prop on above-the-fold next/image. Never lazy-load the LCP image.
• CLS: Always set width/height on images. Use transform for animations, not top/margin.
• INP: Break long tasks with scheduler.yield(). Move logic to Server Components.
• Assets: next/image for all images, next/font for self-hosted fonts, next/script with lazyOnload, next/dynamic for heavy below-fold components.
• PPR: Wrap dynamic components in <Suspense> to serve static shell instantly while streaming dynamic content.

6. Layout & Error Handling Patterns

Layouts

• layout.tsx shares UI across sibling routes and preserves state on navigation (does not re-render).
• Root layout replaces legacy _app and _document — customize <html> and <body> here.
• Do not place auth checks in layouts — they won't re-run on sibling navigation. Put auth in page.tsx or the DAL.

Error Handling

• error.tsx creates an isolated React Error Boundary for its child segment.
• error.tsx does not catch errors in its sibling layout.tsx — only in the layout's children.
• Use not-found.tsx for graceful 404 handling.

7. Middleware & Deployment

Middleware (proxy.ts in Next.js 16)

Use for edge-level routing: redirects, header injection (CSP, HSTS), A/B testing, geo-routing. Never rely on middleware as the sole security boundary — always re-verify auth in Route Handlers and Server Actions.

Production Checklist

1. Run npm run build && npm run start locally before deploying.
2. Audit bundle sizes with @next/bundle-analyzer.
3. Verify all images use next/image, fonts use next/font, scripts use next/script.
4. Confirm security headers are applied (see nextjs-security skill).
5. Set up monitoring with instrumentation.ts (OpenTelemetry, Sentry, Datadog).
6. Track Core Web Vitals with Real User Monitoring (Vercel Analytics or equivalent).

Turbopack

The Rust-based Turbopack compiler is stable in Next.js 15+ for dev and production. Delivers up to 10x faster HMR and 2-5x faster builds.

Additional Resources

Reference Files

For detailed patterns and code examples, consult:

• `references/server-client-patterns.md` — Server/Client component boundary patterns, composition examples, and data fetching code
• `references/performance-checklist.md` — Complete Core Web Vitals optimization reference with specific metrics and techniques

Related Skills

• `nextjs-security` — Authentication, API protection, CSP, CSRF, XSS, environment variables
• `nextjs-testing` — Vitest, Cypress, Playwright setup and patterns
• `nextjs-troubleshooting` — Common bugs, error diagnosis, debugging patterns