vercel-labs avatar

Next Best Practices

vercel-labs/next-skills
717
vercel-labs

This Next.js best practices skill provides comprehensive guidelines for writing and reviewing Next.js code, covering topics such as project structure, React Server Components, async patterns, runtime selection, and image optimization. It also offers insights into error handling, data fetching, route handling, metadata, and performance optimization techniques, making it valuable for developers aiming to build efficient, organized, and maintainable Next.js applications. The skill is ideal for Next.js developers seeking to adhere to recommended conventions and improve their coding standards.

npx skills add https://github.com/vercel-labs/next-skills --skill next-best-practices

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

GitHub Owner

Owner: vercel-labs

GitHub Links

Files

file-conventions.md

rsc-boundaries.md

async-patterns.md

runtime-selection.md

directives.md

functions.md

error-handling.md

data-patterns.md

route-handlers.md

metadata.md

image.md

font.md

bundling.md

scripts.md

hydration-error.md

suspense-boundaries.md

parallel-routes.md

self-hosting.md

debug-tricks.md

SKILL.md

name: next-best-practices description: Next.js best practices - file conventions, RSC boundaries, data patterns, async APIs, metadata, error handling, route handlers, image/font optimization, bundling user-invocable: false

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

More skills

A
Mcp Builder

anthropics

A
Webapp Testing

anthropics

A
Swiftui Expert Skill

avdlee