next-best-practices

Enforce Next.js App Router architecture and async API conventions during code review.

885|108|Updated Apr 30, 2025
One-click install
npx skills add https://github.com/legions-developer/invoicely --skill next-best-practices-legions-developer
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: next-best-practices
Source: https://github.com/legions-developer/invoicely/tree/main/.agents/skills/next-best-practices
Command: npx skills add https://github.com/legions-developer/invoicely --skill next-best-practices-legions-developer

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This Skill helps prevent common Next.js App Router mistakes that cause incorrect rendering, performance regressions, hydration bugs, and SEO issues.

Core Features & Use Cases

  • File conventions & routing sanity: Guides correct use of App Router special files, route segment patterns, parallel/intercepting routes, and middleware/proxy naming so hard navigations don’t break.
  • Server/Client correctness & async safety: Detects invalid React Server Components boundary patterns, ensures Next.js 15+ async APIs like params/searchParams/cookies/headers are handled properly, and recommends safe patterns for metadata.
  • Performance & quality guardrails: Covers runtime selection, bundling pitfalls, suspense boundaries for CSR bailout hooks, image/font optimization, script loading, and structured error handling to keep apps stable and fast.
  • Operational recipes: Includes practical guidance for route handlers vs server actions, OG image generation, self-hosting considerations, and debugging workflows (including MCP endpoint usage).

Quick Start

Apply the guidance from the next-best-practices Skill to your Next.js codebase by reviewing your affected route files for the listed conventions and updating them until they follow the documented RSC boundaries, async patterns, and metadata/image rules.

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 App Router?

Async params in Next.js 15+ App Router require awaiting dynamic APIs like params, searchParams, cookies, and headers. You must handle these asynchronous request APIs safely to prevent rendering and hydration bugs.

What are the correct React Server Components boundaries in Next.js?

Correct RSC boundaries in Next.js isolate server-only logic from client interactivity. You must enforce valid React Server Components boundary patterns and wrap CSR bailout hooks in safe Suspense boundaries to prevent hydration errors.

How do I optimize images and fonts in Next.js for performance?

Optimize images and fonts in Next.js by applying performance guardrails for runtime selection, bundling, and script loading. Proper metadata configuration and OG image generation ensure apps remain stable and fast.

Does this Next.js guidance cover route handlers and server actions?

Yes, this Next.js guidance includes operational recipes for choosing between route handlers and server actions. It enforces correct file naming, route segment patterns, and middleware proxy conventions so hard navigations don't break.

What is the best way to structure error handling in Next.js App Router?

The best way to structure error handling in Next.js App Router is implementing structured error boundaries. This prevents common App Router mistakes, maintains correct rendering, and keeps applications stable during runtime exceptions.

Why does my Next.js metadata configuration cause SEO issues?

Next.js metadata causes SEO issues when async request APIs are mishandled or RSC boundaries are invalid. Applying safe patterns for metadata and OG image generation prevents these performance regressions and SEO problems.