Next.js Best Practices

# 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`