vercel-labs/next-skills

Overview

This skill provides a concise, opinionated set of Next.js best practices covering file conventions, RSC boundaries, data patterns, runtime selection, metadata, error handling, route handlers, image/font optimization, and bundling. It is designed to be a single reference when writing or reviewing Next.js apps and when making architecture or migration decisions. The guidance targets Next.js 15+ async APIs and modern React Server Component patterns. It focuses on practical rules that reduce bugs, improve performance, and simplify maintenance.

How this skill works

The skill inspects code and architecture choices against a curated checklist: file and routing conventions, RSC/client boundaries, async usage, runtime choices, metadata generation, and common pitfalls like hydration errors and bundle incompatibilities. It flags invalid patterns (e.g., async client components, non-serializable props to RSCs), suggests alternatives (e.g., route handlers vs server actions), and recommends optimizations for images, fonts, and bundles. It also captures migration patterns and codemods related to async APIs and runtime changes. Outputs are prescriptive, actionable, and tied to concrete file-level or API-level fixes.

When to use it

• During code reviews to enforce consistent Next.js patterns and catch anti-patterns early.
• When designing new pages, routes, or data-fetching flows for Next.js 15+ apps.
• Before migrating to a newer Next.js version or switching runtimes (Node.js ↔ Edge).
• When diagnosing hydration errors, slow LCP, or unexpected bundle size increases.
• While implementing metadata, OG image generation, or static/dynamic metadata strategies.

Best practices

• Follow explicit file conventions: use route segments, groups, parallel routes, and reserved filenames predictably.
• Respect RSC boundaries: keep server-only APIs and non-serializable values out of client components.
• Prefer async patterns supported by the runtime: async params, cookies(), and headers() in Server Components.
• Default to Node.js runtime; choose Edge only for low-latency, globally distributed needs.
• Use next/image and next/font for optimization; preload critical subsets and set responsive sizes.
• Avoid server-side data waterfalls—use Promise.all, Suspense, or preload to parallelize fetching.

Example use cases

• Linting a pull request to find a client component incorrectly marked async or receiving non-serializable props.
• Choosing between a route.ts handler and a server action for an API endpoint with file-based routing.
• Optimizing page load by converting a large hero image to next/image with responsive sizes and blur placeholder.
• Fixing a hydration error caused by direct use of browser APIs inside a Server Component.
• Analyzing bundle output to replace server-incompatible packages and reduce CJS/ESM friction.