Next Best Practices

<!-- AUTO-GENERATED by export-skills.py — DO NOT EDIT -->
---
name: next-best-practices
description: "Vercel's authoritative Next.js 15+ patterns covering RSC boundaries, streaming, async patterns, route handlers, metadata, image/font optimization, bundling, hydration errors, parallel routes, and self-hosting. Use when: nextjs, next.js, app router, server components, RSC, next best practices."
tags: [nextjs, app-router, server-components, performance]
---

# Next.js Best Practices

Apply these rules when writing or reviewing Next.js code. Maintained by Vercel — the authoritative source for Next.js patterns.

## File Conventions

See [next-rules.md](./references/next-rules.md#file-conventions) 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 [next-rules.md](./references/next-rules.md#rsc-boundaries) for:
- Async client component detection (invalid)
- Non-serializable props detection
- Server Action exceptions

## Async Patterns

Next.js 15+ async API changes.

See [next-rules.md](./references/next-rules.md#async-patterns) for:
- Async `params` and `searchParams`
- Async `cookies()` and `headers()`
- Migration codemod

## Runtime Selection

See [next-rules.md](./references/next-rules.md#runtime-selection) for:
- Default to Node.js runtime
- When Edge runtime is appropriate

## Directives

See [next-rules.md](./references/next-rules.md#directives) for:
- `'use client'`, `'use server'` (React)
- `'use cache'` (Next.js)

## Functions

See [next-rules.md](./references/next-rules.md#functions) for:
- Navigation hooks: `useRouter`, `usePathname`, `useSearchParams`, `useParams`
- Server functions: `cookies`, `headers`, `draftMode`, `after`
- Generate functions: `generateStaticParams`, `generateMetadata`

## Error Handling

See [next-rules.md](./references/next-rules.md#error-handling) for:
- `error.tsx`, `global-error.tsx`, `not-found.tsx`
- `redirect`, `permanentRedirect`, `notFound`
- `forbidden`, `unauthorized` (auth errors)
- `unstable_rethrow` for catch blocks

## Data Patterns

See [next-rules.md](./references/next-rules.md#data-patterns) for:
- Server Components vs Server Actions vs Route Handlers
- Avoiding data waterfalls (`Promise.all`, Suspense, preload)
- Client component data fetching

## Route Handlers

See [next-rules.md](./references/next-rules.md#route-handlers) 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 [next-rules.md](./references/next-rules.md#metadata--og-images) for:
- Static and dynamic metadata
- `generateMetadata` function
- OG image generation with `next/og`
- File-based metadata conventions

## Image Optimization

See [next-rules.md](./references/next-rules.md#image-optimization) for:
- Always use `next/image` over `<img>`
- Remote images configuration
- Responsive `sizes` attribute
- Blur placeholders
- Priority loading for LCP

## Font Optimization

See [next-rules.md](./references/next-rules.md#font-optimization) for:
- `next/font` setup
- Google Fonts, local fonts
- Tailwind CSS integration
- Preloading subsets

## Bundling

See [next-rules.md](./references/next-rules.md#bundling) for:
- Server-incompatible packages
- CSS imports (not link tags)
- Polyfills (already included)
- ESM/CommonJS issues
- Bundle analysis

## Scripts

See [next-rules.md](./references/next-rules.md#scripts) for:
- `next/script` vs native script tags
- Inline scripts need `id`
- Loading strategies
- Google Analytics with `@next/third-parties`

## Hydration Errors

See [next-rules.md](./references/next-rules.md#hydration-errors) for:
- Common causes (browser APIs, dates, invalid HTML)
- Debugging with error overlay
- Fixes for each cause

## Suspense Boundaries

See [next-rules.md](./references/next-rules.md#suspense-boundaries) for:
- CSR bailout with `useSearchParams` and `usePathname`
- Which hooks require Suspense boundaries

## Parallel & Intercepting Routes

See [next-rules.md](./references/next-rules.md#parallel--intercepting-routes) for:
- Modal patterns with `@slot` and `(.)` interceptors
- `default.tsx` for fallbacks
- Closing modals correctly with `router.back()`

## Self-Hosting

See [next-rules.md](./references/next-rules.md#self-hosting) for:
- `output: 'standalone'` for Docker
- Cache handlers for multi-instance ISR
- What works vs needs extra setup

## Debug Tricks

See [next-rules.md](./references/next-rules.md#debug-tricks) for:
- MCP endpoint for AI-assisted debugging
- Rebuild specific routes with `--debug-build-paths`

<!-- Source: .faos/custom/skills/frontend/next-best-practices/SKILL.md -->