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.tsxredirect, permanentRedirect, notFoundforbidden, 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
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