Next Best Practices
Give your coding agent authoritative Next.js rules for file layout, RSC boundaries, async App Router APIs, metadata, errors, and performance while you ship App Router apps.
Overview
Next Best Practices is an agent skill most often used in Build (also Ship → review) that applies Vercel’s Next.js conventions for RSC, async App Router APIs, metadata, errors, and performance when writing or reviewing co
Install
npx skills add https://github.com/vercel-labs/next-skills --skill next-best-practicesWhat is this skill?
- Covers file conventions, dynamic segments, parallel/intercepting routes, and middleware→proxy rename in v16
- Flags invalid RSC patterns: async client components, non-serializable props, and Server Action exceptions
- Documents Next.js 15+ async params, searchParams, cookies(), headers(), plus migration codemods
- Guides runtime selection (Node vs Edge), directives (use client/server/cache), and navigation/generate helpers
- Includes metadata, error handling, route handlers, and image/font optimization plus bundling guidance
- Covers dedicated reference areas including file conventions, RSC boundaries, async patterns, runtime selection, directiv
Adoption & trust: 102k installs on skills.sh; 919 GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You are building on the App Router but generic React guidance lets your agent mix invalid RSC patterns, sync-only APIs, and outdated file conventions into your repo.
Who is it for?
Solo builders actively coding or reviewing Next.js 15+ App Router projects who want checklist-driven guardrails rather than one-off Stack Overflow answers.
Skip if: Teams not using Next.js, backend-only services with no Next app, or operators looking for Vercel deploy/CI configuration instead of in-repo coding rules.
When should I use this skill?
Apply when writing or reviewing Next.js code (file conventions, RSC, data patterns, async APIs, metadata, errors, route handlers, images, fonts, bundling).
What do I get? / Deliverables
Your agent follows documented Next.js patterns for routing, server/client boundaries, async APIs, and optimization so implementation and code review stay framework-correct before you ship.
- Code and reviews aligned to Next.js file conventions and RSC rules
- Migration-friendly use of async route and cookie/header APIs
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Next.js conventions and RSC patterns are applied whenever you write or review app code, so the canonical shelf is Build → frontend even though the same rules matter during pre-release review. The skill is entirely about App Router UI, routing, and client/server boundaries—not backend-only APIs or infra.
Where it fits
Scaffold a marketing site with correct route groups and generateStaticParams without breaking RSC props.
Refactor pages to async params and searchParams after upgrading to Next.js 15.
Review a PR for invalid async client components and missing error.tsx boundaries before release.
Tune image/font loaders and bundling choices called out in the optimization sections.
How it compares
Use as a structured Next.js rule pack during implementation and review, not as a separate MCP server or generic frontend linter.
Common Questions / FAQ
Who is next-best-practices for?
Indie and solo developers shipping Next.js sites or SaaS dashboards with Claude Code, Cursor, or Codex who need the agent to respect App Router file conventions, RSC limits, and Next 15+ async APIs.
When should I use next-best-practices?
During Build when adding routes, server actions, or metadata; during Ship → review when auditing RSC boundaries and async params/searchParams; and anytime you migrate middleware or caching directives to match current Next docs.
Is next-best-practices safe to install?
It is documentation-style procedural knowledge with no built-in shell or network calls in the skill itself; review the Security Audits panel on this Prism page before trusting any third-party skill in your agent environment.
SKILL.md
READMESKILL.md - Next Best Practices
# Next.js Best Practices Apply these rules when writing or reviewing Next.js code. ## File Conventions See [file-conventions.md](./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](./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](./async-patterns.md) for: - Async `params` and `searchParams` - Async `cookies()` and `headers()` - Migration codemod ## Runtime Selection See [runtime-selection.md](./runtime-selection.md) for: - Default to Node.js runtime - When Edge runtime is appropriate ## Directives See [directives.md](./directives.md) for: - `'use client'`, `'use server'` (React) - `'use cache'` (Next.js) ## Functions See [functions.md](./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](./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](./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](./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](./metadata.md) for: - Static and dynamic metadata - `generateMetadata` function - OG image generation with `next/og` - File-based metadata conventions ## Image Optimization See [image.md](./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](./font.md) for: - `next/font` setup - Google Fonts, local fonts - Tailwind CSS integration - Preloading subsets ## Bundling See [bundling.md](./bundling.md) for: - Server-incompatible packages - CSS imports (not link tags) - Polyfills (already included) - ESM/CommonJS issues - Bundle analysis ## Scripts See [scripts.md](./scripts.md) for: - `next/script` vs native script tags - Inline scripts need `id` - Loading strategies - Google Analytics with `@next/third-parties` ## Hydration Errors See [hydration-error.md](./hydration-error.md) for: - Common causes (browser APIs, dates, invalid HTML) - Debugging with error overlay - Fixes for each cause ## Suspense Boundaries See [suspense-boundaries.md](./suspense-boundaries.md) for: - CSR bailout with `useSearchParams` and `usePathname` - Which hooks require Suspense boundaries ## Parallel & Intercepting Routes See [parallel-routes.md](./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](./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](./debug-tricks.md) for: - MCP endpoint for AI-assisted debugging - Rebuild specific routes with `--debug-build-paths`