next-best-practices git:20261007.04729edA

Immutable. This exact content never changes and is served at /api/v1/blob/9e17e3e4a9df592a.

---
name: next-best-practices
description: "Next.js best-practice rules for writing or reviewing Next.js code. Use when working on a Next.js app: file conventions and route segments, RSC boundaries (invalid async client components, non-serializable props), async API patterns (Next 15+), runtime selection, directives, error handling, and the v16 middleware→proxy rename. Topic detail files load on demand."
paths: ["next.config.*", "app/**"]
---

# 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

---

**Source:** https://officialskills.sh/vercel-labs/skills/next-best-practices