next-best-practices

Enforce Next.js best practices for file conventions, RSC boundaries, and async APIs.

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

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Consolidates Next.js conventions and checks to prevent common routing, rendering, and performance mistakes that cause runtime errors, hydration mismatches, and poor SEO.

Core Features & Use Cases

  • File Conventions & Routing: Guidance for project structure, dynamic/catch-all segments, route groups, and parallel/intercepting routes.
  • RSC Boundaries & Async Patterns: Detect invalid async client components, non-serializable props, and correct usage of async params, cookies, and headers.
  • Metadata, Images & Bundling: Best practices for the Metadata API, OG image generation, next/image usage, font optimization, and avoiding server-incompatible packages.
  • Error Handling & Debugging: Patterns for error.tsx/global-error, navigation gotchas, hydration fixes, and MCP-assisted debug tips.
  • Use Case: Run during PR reviews, migrations, or architecture audits to flag RSC violations, route handler conflicts, and bundling/runtime issues and get actionable remediation steps.

Quick Start

Run a targeted Next.js code review against the next-best-practices checklist to flag RSC boundary issues, async API misuse, routing conflicts, metadata problems, and bundling pitfalls.

Frequently Asked Questions about next-best-practices

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

FAQPage Schema
How do I fix async client component misuse and non-serializable props in Next.js?

To fix async client component misuse and non-serializable props in Next.js, enforce React Server Component boundaries by ensuring async APIs like cookies and headers run only on the server, passing serializable data to client components.

What are the Next.js best practices for the Metadata API and OG image generation?

Next.js best practices for the Metadata API and OG image generation involve using the App Router Metadata API for static and dynamic metadata, and leveraging route handlers to dynamically generate optimized OG images efficiently.

Why does my Next.js route handler conflict with file conventions during architecture audits?

Next.js route handler conflicts occur when file conventions are violated, such as mismatched dynamic segments or improper route group usage. Auditing project structure and aligning route handlers with App Router conventions provides concrete remediation.

How do I resolve bundling and runtime incompatibilities with server-incompatible packages in Next.js?

Resolve bundling and runtime incompatibilities in Next.js by identifying server-incompatible packages during code reviews and configuring bundling settings or dynamic imports to prevent runtime errors and hydration mismatches in server components.

Can I use error.tsx and global-error patterns for Next.js error handling and debugging?

Yes, you can use error.tsx and global-error patterns for Next.js error handling to gracefully catch runtime errors. Implementing these boundaries alongside proper navigation gotchas ensures robust debugging and hydration fixes.