Next.js Best Practices
Apply these rules when writing or reviewing Next.js code.
Cache Components patterns: When the project has cacheComponents: true in next.config.ts,
use the separate cache-components skill for 'use cache', cacheLife(), cacheTag(),
updateTag(), and revalidateTag() guidance.
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 (only this hook requires a boundary)
- Forcing dynamic rendering with
connection() instead
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
1---2name: next-best-practices3description: Next.js App Router best practices covering file conventions, RSC boundaries, async APIs, data patterns, hydration errors, metadata, route handlers, image/font optimization, and bundling. Use when writing or reviewing Next.js code to prevent hydration errors, RSC violations, data waterfalls, and configuration mistakes.4argument-hint: "[question or file]"5metadata:6 source: https://skillmd.com/skills/laguagu/next-best-practices7---89# Next.js Best Practices1011Apply these rules when writing or reviewing Next.js code.1213> **Cache Components patterns**: When the project has `cacheComponents: true` in `next.config.ts`,14> use the separate `cache-components` skill for `'use cache'`, `cacheLife()`, `cacheTag()`,15> `updateTag()`, and `revalidateTag()` guidance.1617## File Conventions1819See [file-conventions.md](./file-conventions.md) for:20- Project structure and special files21- Route segments (dynamic, catch-all, groups)22- Parallel and intercepting routes23- Middleware rename in v16 (middleware → proxy)2425## RSC Boundaries2627Detect invalid React Server Component patterns.2829See [rsc-boundaries.md](./rsc-boundaries.md) for:30- Async client component detection (invalid)31- Non-serializable props detection32- Server Action exceptions3334## Async Patterns3536Next.js 15+ async API changes.3738See [async-patterns.md](./async-patterns.md) for:39- Async `params` and `searchParams`40- Async `cookies()` and `headers()`41- Migration codemod4243## Runtime Selection4445See [runtime-selection.md](./runtime-selection.md) for:46- Default to Node.js runtime47- When Edge runtime is appropriate4849## Directives5051See [directives.md](./directives.md) for:52- `'use client'`, `'use server'` (React)53- `'use cache'` (Next.js)5455## Functions5657See [functions.md](./functions.md) for:58- Navigation hooks: `useRouter`, `usePathname`, `useSearchParams`, `useParams`59- Server functions: `cookies`, `headers`, `draftMode`, `after`60- Generate functions: `generateStaticParams`, `generateMetadata`6162## Error Handling6364See [error-handling.md](./error-handling.md) for:65- `error.tsx`, `global-error.tsx`, `not-found.tsx`66- `redirect`, `permanentRedirect`, `notFound`67- `forbidden`, `unauthorized` (auth errors)68- `unstable_rethrow` for catch blocks6970## Data Patterns7172See [data-patterns.md](./data-patterns.md) for:73- Server Components vs Server Actions vs Route Handlers74- Avoiding data waterfalls (`Promise.all`, Suspense, preload)75- Client component data fetching7677## Route Handlers7879See [route-handlers.md](./route-handlers.md) for:80- `route.ts` basics81- GET handler conflicts with `page.tsx`82- Environment behavior (no React DOM)83- When to use vs Server Actions8485## Metadata & OG Images8687See [metadata.md](./metadata.md) for:88- Static and dynamic metadata89- `generateMetadata` function90- OG image generation with `next/og`91- File-based metadata conventions9293## Image Optimization9495See [image.md](./image.md) for:96- Always use `next/image` over `<img>`97- Remote images configuration98- Responsive `sizes` attribute99- Blur placeholders100- Priority loading for LCP101102## Font Optimization103104See [font.md](./font.md) for:105- `next/font` setup106- Google Fonts, local fonts107- Tailwind CSS integration108- Preloading subsets109110## Bundling111112See [bundling.md](./bundling.md) for:113- Server-incompatible packages114- CSS imports (not link tags)115- Polyfills (already included)116- ESM/CommonJS issues117- Bundle analysis118119## Scripts120121See [scripts.md](./scripts.md) for:122- `next/script` vs native script tags123- Inline scripts need `id`124- Loading strategies125- Google Analytics with `@next/third-parties`126127## Hydration Errors128129See [hydration-error.md](./hydration-error.md) for:130- Common causes (browser APIs, dates, invalid HTML)131- Debugging with error overlay132- Fixes for each cause133134## Suspense Boundaries135136See [suspense-boundaries.md](./suspense-boundaries.md) for:137- CSR bailout with `useSearchParams` (only this hook requires a boundary)138- Forcing dynamic rendering with `connection()` instead139140## Parallel & Intercepting Routes141142See [parallel-routes.md](./parallel-routes.md) for:143- Modal patterns with `@slot` and `(.)` interceptors144- `default.tsx` for fallbacks145- Closing modals correctly with `router.back()`146147## Self-Hosting148149See [self-hosting.md](./self-hosting.md) for:150- `output: 'standalone'` for Docker151- Cache handlers for multi-instance ISR152- What works vs needs extra setup153154## Debug Tricks155156See [debug-tricks.md](./debug-tricks.md) for:157- MCP endpoint for AI-assisted debugging158- Rebuild specific routes with `--debug-build-paths`159