AgentSkillsCN

next-best-practices

Next.js 最佳实践——文件约定、RSC 边界、数据模式、异步 API、元数据、错误处理、路由处理器、图片/字体优化、打包

SKILL.md
--- frontmatter
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
  • •ESM/CommonJS issues
  • •Bundle analysis
  • •Webpack to Turbopack migration

Hydration Errors

See hydration-error.md for:

  • •Common causes (browser APIs, dates, invalid HTML)
  • •Debugging with error overlay
  • •Fixes for each cause

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