git:20260508.65c1b0b to git:20261007.04729ed

6 added, 0 removed. Audit C to A.

+ ---

+ 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