next-best-practices

vercel-labs/openreview

Next.js best practices reference for file conventions, RSC boundaries, data patterns, and optimization.

What is next-best-practices?

A comprehensive guide to Next.js development patterns covering file structure, React Server Components, async APIs, error handling, and performance optimization. Use this when writing or reviewing Next.js code to ensure compliance with framework conventions and best practices.

Enforces file conventions and route segment patterns including dynamic, catch-all, and parallel routes
Detects invalid React Server Component patterns and non-serializable props
Guides async API usage for params, searchParams, cookies, and headers in Next.js 15+
Provides error handling strategies with error.tsx, not-found.tsx, and redirect functions
Optimizes images and fonts using next/image and next/font with responsive sizing and preloading
Covers data fetching patterns, route handlers, metadata generation, and bundling best practices

How to install next-best-practices

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

Claude Code

Cursor

Windsurf

Cline

How to use next-best-practices

1.Reference the appropriate guide (file-conventions.md, rsc-boundaries.md, etc.) based on the code pattern you're reviewing
2.Check file structure against file-conventions.md for correct naming and organization
3.Validate React Server Component usage and async patterns against rsc-boundaries.md and async-patterns.md
4.Apply error handling patterns from error-handling.md for custom error pages and redirects
5.Implement image and font optimization using guidelines from image.md and font.md
6.Use the MCP endpoint or debug-build-paths flag for AI-assisted debugging when needed

Use cases

Good for

Reviewing Next.js code to catch RSC boundary violations and async pattern misuse
Setting up project structure with correct file conventions and route organization
Optimizing Core Web Vitals through image priority, font preloading, and script loading strategies
Implementing error boundaries and custom error pages for production applications
Migrating to Next.js 15+ async APIs and updating deprecated patterns

Who it's for

Next.js developers building full-stack applications
Code reviewers ensuring Next.js best practices compliance
Teams migrating to Next.js 15+ async patterns
Developers optimizing performance and Core Web Vitals
AI coding agents assisting with Next.js code generation and review

next-best-practices FAQ

When should I use Server Actions vs Route Handlers?

Use Server Actions for mutations and client-to-server communication from components; use Route Handlers for building APIs, webhooks, or when you need full HTTP method control.

What causes hydration errors and how do I fix them?

Hydration errors occur when server and client render different content, commonly from browser APIs, date/time differences, or invalid HTML. The error overlay provides specific fixes for each cause.

How do I optimize images in Next.js?

Always use next/image instead of img tags, configure remote image domains, set responsive sizes attributes, add blur placeholders, and mark LCP images with priority={true}.

What is the difference between 'use client' and 'use server'?

'use client' marks a component boundary for client-side rendering; 'use server' marks individual functions as Server Actions callable from clients. 'use cache' is a Next.js directive for caching.

How do I handle async params and searchParams in Next.js 15+?

In Next.js 15+, params and searchParams are async and must be awaited. Use the migration codemod to update existing code, and always await these values before accessing their properties.

Full instructions (SKILL.md)

Source of truth, from vercel-labs/openreview.