Next.js Best Practices

Apply these rules when writing or reviewing Next.js code.

File Conventions

See file-conventions.md for:

• Project structure and special files

• Route segments (dynamic, catch-all, groups)

• Parallel and intercepting routes

• Middleware rename in v16 (middleware → proxy)

RSC Boundaries

Detect invalid React Server Component patterns.

See rsc-boundaries.md for:

• Async client component detection (invalid)

• Non-serializable props detection

• Server Action exceptions

Async Patterns

Next.js 15+ async API changes.

See async-patterns.md for:

• Async params and searchParams

• Async cookies() and headers()

• Migration codemod

Runtime Selection

See runtime-selection.md for:

• Default to Node.js runtime

• When Edge runtime is appropriate

Directives

See directives.md for:

• 'use client', 'use server' (React)

• 'use cache' (Next.js)

Functions

See functions.md for:

• Navigation hooks: useRouter, usePathname, useSearchParams, useParams

• Server functions: cookies, headers, draftMode, after

• Generate functions: generateStaticParams, generateMetadata

Error Handling

See error-handling.md for:

• error.tsx, global-error.tsx, not-found.tsx

• redirect, permanentRedirect, notFound

• forbidden, unauthorized (auth errors)

• unstable_rethrow for catch blocks

Data Patterns

See data-patterns.md for:

• Server Components vs Server Actions vs Route Handlers

• Avoiding data waterfalls (Promise.all, Suspense, preload)

• Client component data fetching

Route Handlers

See route-handlers.md for:

• route.ts basics

• GET handler conflicts with page.tsx

• Environment behavior (no React DOM)

• When to use vs Server Actions

Metadata & OG Images

See metadata.md for:

• Static and dynamic metadata

• generateMetadata function

• OG image generation with next/og

• File-based metadata conventions

Image Optimization

See image.md for:

• Always use next/image over <img>

• Remote images configuration

• Responsive sizes attribute

• Blur placeholders

• Priority loading for LCP

Font Optimization

See font.md for:

• next/font setup

• Google Fonts, local fonts

• Tailwind CSS integration

• Preloading subsets

Bundling

See bundling.md for:

• Server-incompatible packages

• CSS imports (not link tags)

• Polyfills (already included)

• ESM/CommonJS issues

• Bundle analysis

Scripts

See scripts.md for:

• next/script vs native script tags

• Inline scripts need id

• Loading strategies

• Google Analytics with @next/third-parties

Hydration Errors

See hydration-error.md for:

• Common causes (browser APIs, dates, invalid HTML)

• Debugging with error overlay

• Fixes for each cause

Suspense Boundaries

See suspense-boundaries.md for:

• CSR bailout with useSearchParams and usePathname

• Which hooks require Suspense boundaries

Parallel & Intercepting Routes

See parallel-routes.md for:

• Modal patterns with @slot and (.) interceptors

• default.tsx for fallbacks

• Closing modals correctly with router.back()

Self-Hosting

See self-hosting.md for:

• output: 'standalone' for Docker

• Cache handlers for multi-instance ISR

• What works vs needs extra setup

Debug Tricks

See debug-tricks.md for:

• MCP endpoint for AI-assisted debugging

• Rebuild specific routes with --debug-build-paths