next-best-practices

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

2|1|Updated Jun 9, 2026
One-click install
npx skills add https://github.com/zester4/zilmate --skill next-best-practices-zester4
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: next-best-practices
Source: https://github.com/zester4/zilmate/tree/main/.agents/skills/next-best-practices
Command: npx skills add https://github.com/zester4/zilmate --skill next-best-practices-zester4

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 consolidates these rules so code follows current Next.js standards and avoids common pitfalls like hydration errors, data waterfalls, and invalid RSC patterns. ## Core Features & Use Cases - RSC Boundary Validation: Detects invalid patterns such as async Client Components and non-serializable props (Date objects, Maps, class instances) passed across the Server/Client boundary. - Modern API Guidance: Covers Next.js 15+ async params, searchParams, cookies(), and headers(), plus the v16 middleware-to-proxy rename. - Performance & Optimization: Rules for next/image, next/font, next/script, bundle analysis, and avoiding data waterfalls with Promise.all and Suspense. - Use Case: When reviewing a pull request that adds a new dynamic route, use this Skill to verify async params handling, metadata generation, error boundaries, and image optimization all follow current Next.js conventions. ## Quick Start Review my Next.js page component and check it against current best practices for async params, metadata, and image optimization.

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 in Next.js 15?

In Next.js 15+, params and searchParams are Promises that must be awaited. Type them as Promise<{ slug: string }> and await them in pages, layouts, route handlers, and generateMetadata. A codemod (npx @next/codemod@latest next-async-request-api) automates migration.

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

Use Server Actions for mutations triggered from your UI, such as form submissions, 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 lose their methods during serialization. Convert dates with .toISOString() on the server, then reconstruct with new Date() inside the Client Component.

Does useSearchParams require a Suspense boundary?

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 <Suspense> with a fallback UI.

How do I fix hydration errors in Next.js?

Hydration errors come from browser-only APIs, timezone-dependent dates, random values, or invalid HTML nesting. Fix them by rendering browser-dependent content only after mount, using useId for IDs, and correcting invalid nesting like div inside p.

What changed with middleware in Next.js 16?

Next.js 16 renames middleware.ts to proxy.ts with a proxy() export, keeping the same capabilities and config matcher. Run npx @next/codemod@latest upgrade to auto-rename existing files.