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