Nextjs Best Practices

Next.js Best Practices

Practical, production-ready Next.js patterns for the App Router. Apply these when building or reviewing Next.js applications.

App Router Architecture

File Conventions

The App Router uses special filenames to define behavior for each route segment. Every folder in `app/` can contain these files, and they compose automatically across nested folders:

`layout.tsx` and `template.tsx` differ in lifecycle — layouts persist across navigations (the sidebar does not remount when navigating between dashboard pages), templates remount every time. Prefer `layout.tsx` unless you need effect re-runs or animation reset on every navigation.

Root Layout

The root `app/layout.tsx` is required and wraps every page. It defines the HTML shell, font loading, global styles, and shared metadata defaults. Every provider (auth, theme, query client) in the root layout affects the entire application — keep this tree narrow. Providers that only apply to a subset of routes belong in a route group layout.

Route Groups

Use `(folder)` parentheses to organize routes without affecting URL structure. Route groups create separate layout trees under the same URL namespace:

Marketing pages get a minimal layout with nav and footer. Dashboard pages get auth middleware plus sidebar. No URL segments distinguish them — the difference is purely organizational. This is the standard pattern for apps with public pages and authenticated sections.

Route Handlers

With Server Actions handling mutations and Server Components handling reads, the `app/api/` directory shrinks to a few specialized cases. Route handlers (`route.ts`) are needed only for:

All standard CRUD operations, form submissions, and data mutations go through Server Actions. All reads go through Server Components.

Server vs Client Components

The Decision Rule

Default to Server Component. Add `"use client"` only when the component needs one of these:

A Server Component runs exclusively on the server: it sends zero JavaScript to the browser, can directly access databases and filesystems with no API route wrapper, and can `await` data fetches inline without a loading state variable. Environment variables and API keys referenced in Server Components never reach the client bundle.

The Composition Pattern

Keep pages as Server Components. Extract only the interactive parts as leaf Client Components. Pass data as props from server to client. A Client Component can receive Server Components as `children` — this embeds server-rendered content inside interactive shells without pushing JavaScript to the browser for the inner content. This is the standard pattern for pages that are mostly static but have one or two interactive widgets.

The Cost of Overuse

Adding `"use client"` to a file makes every import in that file's tree part of the client bundle. A single broad `"use client"` on a layout or page can pull server-only dependencies into the browser bundle, negating the bundle-size benefit of Server Components. Push `"use client"` as far down the tree as possible — to the leaf components that genuinely need interactivity.

Data Fetching and Caching

Server Component Fetching

Server Components fetch data directly at render time — no API route wrapper, no `useEffect`, no client-side loading state, no state variable for the result:

The `fetch` API is also available directly in Server Components. React automatically deduplicates `fetch` calls with the same URL and options within a single render pass. You can call the same data function in `generateMetadata` and the page component — it resolves once.

Caching Strategy

Next.js 15 changed the caching defaults. Previously, `fetch` responses were cached indefinitely by default. Now the defaults are more conservative, and every data fetch should carry an explicit strategy:

Cache Layers

Next.js has four cache layers. Request Memoization lasts one render pass. Data Cache persists across HTTP requests (`revalidate`/`cache`). Full Route Cache stores rendered HTML (skipped for dynamic routes). Router Cache lives in the browser (hard refresh clears it). Data-staleness bugs most often stem from layer interactions — the Router Cache may serve stale data while the Data Cache is fresh. Debug from client to origin: hard refresh first, then verify each layer.

Dynamic rendering is triggered by any dynamic API (`cookies()`, `headers()`, `searchParams` access), uncached `fetch`, or `export const dynamic = "force-dynamic"`. In Next.js 15, `fetch` defaults to `no-store`, so most routes using `fetch` render dynamically without explicit cache: "no-store".

Parallel Data Fetching

Never waterfall independent data fetches inside a single component. Start all independent fetches simultaneously and await them together with `Promise.all`. Sequential fetches add latency equal to the sum of each fetch's duration. Parallel fetches complete in the duration of the slowest fetch:

Streaming and Suspense

Suspense Boundaries at Data Boundaries

Every async data dependency should be wrapped in its own `` boundary with a dimensionally accurate skeleton. This lets each section of the page stream independently — a slow analytics chart does not block the fast user list, and a failed data fetch in one section does not hold up the rest of the page. The page shell renders immediately, and each data-dependent section replaces its skeleton when ready.

loading.tsx vs Explicit Suspense

`loading.tsx` wraps the entire page in a single Suspense boundary automatically. Use it as a coarse initial fallback for the page shell. Inside the page, use explicit `` boundaries around individual data-dependent sections for granular streaming. This way, sections whose data resolves quickly render immediately while slow sections show their own individual skeletons.

Partial Prerendering (PPR): Enable `experimental.ppr = true` in `next.config` to pre-render static shells at build time while streaming dynamic content. Static Suspense boundaries render immediately (CDN-cacheable), dynamic ones hydrate per-request. This combines static speed with dynamic freshness.

Skeleton Design

A good skeleton matches the exact dimensions and layout of the content it replaces — border radius, line heights, and approximate block sizes should mirror the final content. This prevents cumulative layout shift and gives users an accurate mental model of what is loading. Avoid generic spinner-centered animations for layout-heavy sections; they cause layout shift when the content finally renders.

Server Actions

Server Actions replace API routes for mutations. They are async functions annotated with `"use server"` that run on the server and can be called directly from Client Components or used as HTML form `action` attributes.

Progressive Enhancement

Server Actions work without JavaScript. When used as a form `action`, the form submits as a standard HTML form post. When JavaScript loads, the submission becomes seamless with pending states, error handling, and client-side validation. Every form works on first render and gets progressively better — this is the defining advantage over traditional API routes.

Input Validation

Every Server Action must validate its inputs at the top of the function body. Untrusted data from the client must never reach the database or business logic without passing through a validation schema. Return typed error objects to the client rather than throwing exceptions — this keeps error handling predictable and type-safe at the call site.

When Server Actions Are Not the Right Tool

Routing Patterns

Parallel Routes (`@folder`)

Use parallel routes for dashboards with independent sections. Each slot (`@analytics`, `@notifications`) loads independently with its own `loading.tsx`, `error.tsx`, and data dependencies. A crash in one slot cannot take down the others. Each slot also gets its own `layout.tsx` if needed, providing independent layout trees alongside each other.

Every parallel slot must include a `default.tsx` file. Without it, navigating to a route that does not match the slot causes a 404 error — Next.js cannot determine what to render in the unmatched slot and defaults to an error state.

Intercepting Routes

Use intercepting routes for modals and overlays that display content from another route while preserving the underlying page. The syntax mirrors relative path traversal:

The same URL renders inline in a modal when navigated from within the app, or as a full page when accessed directly or refreshed. The same data function powers both views — no duplicate data fetching or state synchronization.

Dynamic Routes

In Next.js 15, `params` and `searchParams` are Promises and must be awaited before accessing:

Use `generateStaticParams` for routes with a known set of values (blog posts, products, documentation pages) to pre-render them at build time. This eliminates per-request computation and allows static delivery via CDN.

Metadata and SEO

Use `generateMetadata` for dynamic metadata that depends on route params or fetched data. It runs on the server and is deduplicated with the page component's data fetch — if both call `getPost(id)`, the call is made once.

Site-wide defaults go in the root layout's `metadata` export. Page-specific overrides go in each page's `generateMetadata`. Values merge down the route hierarchy — more specific segments override their parents. Configure a title template in the root layout (e.g., `"%s | My App"`) so every page's title is consistently branded without repeating the suffix.

Middleware

Middleware runs on the Edge Runtime before every matched request, before the route renders. Use it for operations that must happen early in the request lifecycle:

Keep middleware fast, stateless, and side-effect-free. It runs on every matched request — any heavy computation or database access belongs in the page or route handler. Use `config.matcher` to limit middleware execution to paths that genuinely need it.

Performance

Dynamic Imports

Use `next/dynamic` for heavy client components not needed on initial render. The `ssr: false` option skips server-side rendering for components that depend on browser APIs:

Image Optimization

Use `next/image` for automatic image optimization: responsive sizes, WebP and AVIF format negotiation, lazy loading, and explicit dimension requirements that prevent layout shift. Above-the-fold images should set `priority` to skip lazy loading. Always provide the `sizes` attribute for responsive images so the browser selects the correct source.

Font Optimization

Use `next/font` to load fonts at build time with automatic self-hosting. This eliminates external font requests, reduces layout shift from font swap, and inlines font CSS declarations for critical path rendering.

Bundle Analysis

Run bundle analysis regularly. A charting library, markdown renderer, or date utility imported at the top of a route component contributes to every visitor's critical path JavaScript. Dynamic imports and route-level code splitting keep the initial bundle lean.

Error Handling

Granular Error Boundaries

Place `error.tsx` at the most specific route segment possible. A dashboard with three parallel slots should have an error boundary in each slot rather than a single boundary at the layout level. A failing notifications panel should not blank the entire dashboard.

`error.tsx` must be a Client Component. It receives `error` (the thrown value) and `reset` (a function that retries rendering the segment). Use `reset()` for transient errors like network timeouts — it re-renders the failed segment without a full page reload.

For errors thrown in the root layout itself, create `app/global-error.tsx`. This file must include its own `` and `` tags because the root layout has already failed and cannot provide them.

Production Checklist

Before shipping, verify each of the following:

Common Mistakes