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