name: next-best-practices
description: Next.js best practices - file conventions, RSC boundaries, data patterns, async APIs, metadata, error handling, route handlers, image/font optimization, bundling
user-invocable: false

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