Next.js Best Practices

Next.js

Comprehensive Next.js best practices — always-on, non-invocable guidance for every Next.js project.

Overview

Next.js Best Practices is a passive, always-on skill that injects framework-specific knowledge into the agent's context whenever it works on a Next.js codebase. It covers file conventions, React Server Component boundaries, async patterns, runtime selection, data fetching, metadata, error handling, and more.

Unlike invocable skills, this one is loaded automatically and provides continuous guardrails. It includes 20 deep-dive reference files for the agent to consult on specific topics.

When to Use

This skill is non-invocable — it activates automatically when the agent detects a Next.js project. It guides the agent on:

• Structuring app/ directory with correct file conventions (page.tsx, layout.tsx, loading.tsx, etc.)
• Drawing the right boundary between Server and Client Components
• Using async/await patterns correctly in server contexts
• Choosing between Edge and Node.js runtimes
• Implementing data fetching and caching strategies
• Setting up metadata and Open Graph tags
• Building error boundaries and error.tsx / not-found.tsx handlers
• Writing route handlers (route.ts) properly
• Optimizing images with next/image and fonts with next/font
• Configuring bundling and tree-shaking
• Using Suspense boundaries effectively
• Debugging and preventing hydration errors

Key Features

• Always-on — no explicit prompt needed; active in any Next.js project
• File conventions — enforces correct app/ directory structure
• RSC boundaries — prevents common Server/Client Component mistakes
• Async patterns — correct async usage in server components and route handlers
• Runtime selection — guidance on Edge vs. Node.js runtime trade-offs
• Data patterns — fetch, cache, revalidate, and mutate best practices
• Metadata — static and dynamic metadata, Open Graph, JSON-LD
• Error handling — error boundaries, not-found pages, global error handlers
• Image & font optimization — next/image sizing, next/font self-hosting
• Suspense & streaming — correct Suspense boundary placement for PPR
• Hydration error prevention — common causes and fixes
• 20 reference files — deep-dive documents the agent can consult as needed

Example Prompts

"Set up a new Next.js app with proper file conventions and metadata"
"Fix the hydration error in my product page component"
"Add streaming with Suspense boundaries to my dashboard route"

Source

• Skill folder: skills/next-best-practices/
• Standard: agentskills.io