next-best-practices

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

Updated Mar 6, 2026
One-click install
npx skills add https://github.com/ebecerra-developer/ebecerra-web --skill next-best-practices-ebecerra-developer
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: next-best-practices
Source: https://github.com/ebecerra-developer/ebecerra-web/tree/main/.agents/skills/next-best-practices
Command: npx skills add https://github.com/ebecerra-developer/ebecerra-web --skill next-best-practices-ebecerra-developer

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Writing and reviewing Next.js code requires keeping track of many evolving conventions—async APIs in Next.js 15+, Server/Client Component boundaries, middleware renames in v16, and correct data fetching patterns. This Skill provides a structured rulebook so AI-assisted code generation and review follows current Next.js best practices instead of outdated or invalid patterns. ## Core Features & Use Cases - RSC Boundary Validation: Detects invalid patterns like async Client Components and non-serializable props (Date, Map, class instances) passed across the Server/Client boundary. - Async API Migration Guidance: Covers Next.js 15+ async params, searchParams, cookies(), and headers(), including the official codemod command. - Data Pattern Selection: Decision tree for choosing between Server Components, Server Actions, and Route Handlers, plus waterfall elimination with Promise.all, Suspense, and preload patterns. - Use Case: When asked to build a modal photo gallery, the Skill guides correct use of parallel routes with @slot, intercepting routes with (.), required default.tsx fallbacks, and router.back() for closing modals. ## Quick Start Review my Next.js page component and fix any violations of current Next.js best practices, including async params and RSC boundary issues.

Frequently Asked Questions about next-best-practices

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I handle async params and searchParams in Next.js 15?▼

Type params and searchParams as Promise<...> and await them inside pages, layouts, and route handlers. For synchronous components, use React's use() hook. Run npx @next/codemod@latest next-async-request-api to migrate automatically.

When should I use Server Actions vs Route Handlers in Next.js?▼

Use Server Actions for mutations and form submissions triggered from your UI, since they offer type safety and progressive enhancement. Use Route Handlers for external webhooks, public REST APIs, and GET endpoints that need HTTP caching.

Why does passing a Date object to a Client Component fail?▼

Props crossing the Server/Client boundary must be JSON-serializable, and Date objects silently become strings, causing runtime errors like getFullYear is not a function. Serialize with .toISOString() on the server and reconstruct with new Date() on the client.

Does useSearchParams require a Suspense boundary in Next.js?▼

Yes, useSearchParams requires a Suspense boundary in static routes, otherwise the entire page bails out to client-side rendering. Wrap the component using it in a Suspense fallback; usePathname also needs one in dynamic routes.

Why does my Next.js modal route 404 on page refresh?▼

Parallel route slots like @modal require a default.tsx file that returns null, otherwise hard navigation or refresh produces a 404. Also ensure modals close with router.back() rather than router.push() to correctly clear the intercepted route.

How do I self-host Next.js with ISR across multiple instances?▼

Set output: 'standalone' in next.config.js for Docker deployments, and configure a custom cacheHandler backed by Redis or S3. The default filesystem cache breaks with multiple instances because each instance only sees its own local cache.