nextjs

Next.js Community Next.js 16 App Router Best Practices

Comprehensive performance optimization guide for Next.js 16 App Router applications, maintained by the Next.js Community. Contains 40 rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.

When to Apply

Reference these guidelines when:

• Writing new Next.js 16 App Router code
• Configuring caching strategies with 'use cache' directive
• Implementing server components and data fetching
• Setting up routing with parallel and intercepting routes
• Creating server actions for form handling and mutations

Rule Categories by Priority

Quick Reference

1. Build & Bundle Optimization (CRITICAL)

• build-optimize-package-imports - Configure optimizePackageImports for Icon Libraries
• build-dynamic-imports - Use Dynamic Imports for Heavy Components
• build-barrel-files - Avoid Barrel File Imports in App Router
• build-turbopack-config - Enable Turbopack File System Caching
• build-external-packages - Configure Server External Packages for Node Dependencies

2. Caching Strategy (CRITICAL)

• cache-use-cache-directive - Use the 'use cache' Directive for Explicit Caching
• cache-revalidate-tag - Use revalidateTag with cacheLife Profiles
• cache-fetch-options - Configure Fetch Cache Options Correctly
• cache-revalidate-path - Use revalidatePath for Route-Level Cache Invalidation
• cache-react-cache - Use React cache() for Request Deduplication
• cache-segment-config - Configure Route Segment Caching with Exports

3. Server Components & Data Fetching (HIGH)

• server-parallel-fetching - Fetch Data in Parallel in Server Components
• server-component-streaming - Stream Server Components for Progressive Loading
• server-data-colocation - Colocate Data Fetching with Components
• server-preload-pattern - Use Preload Pattern for Critical Data
• server-avoid-client-fetching - Avoid Client-Side Data Fetching for Initial Data
• server-error-handling - Handle Server Component Errors Gracefully

4. Routing & Navigation (HIGH)

• route-parallel-routes - Use Parallel Routes for Independent Content
• route-intercepting-routes - Use Intercepting Routes for Modal Patterns
• route-prefetching - Configure Link Prefetching Appropriately
• route-proxy-ts - Use proxy.ts for Network Boundary Logic
• route-not-found - Use notFound() for Missing Resources

5. Server Actions & Mutations (MEDIUM-HIGH)

• action-server-action-forms - Use Server Actions for Form Submissions
• action-pending-states - Show Pending States with useFormStatus
• action-error-handling - Handle Server Action Errors Gracefully
• action-optimistic-updates - Use Optimistic Updates for Instant Feedback
• action-revalidation - Revalidate Cache After Mutations

6. Streaming & Loading States (MEDIUM)

• stream-suspense-boundaries - Place Suspense Boundaries Strategically
• stream-loading-tsx - Use loading.tsx for Route-Level Loading States
• stream-error-tsx - Use error.tsx for Route-Level Error Boundaries
• stream-skeleton-matching - Match Skeleton Dimensions to Actual Content
• stream-nested-suspense - Nest Suspense for Progressive Disclosure

7. Metadata & SEO (MEDIUM)

• meta-generate-metadata - Use generateMetadata for Dynamic Metadata
• meta-sitemap - Generate Sitemaps Dynamically
• meta-robots - Configure Robots for Crawl Control
• meta-opengraph-images - Generate Dynamic OpenGraph Images

8. Client Components (LOW-MEDIUM)

• client-use-client-boundary - Minimize 'use client' Boundary Scope
• client-children-pattern - Pass Server Components as Children to Client Components
• client-hydration-mismatch - Avoid Hydration Mismatches
• client-third-party-scripts - Load Third-Party Scripts Efficiently

How to Use

Read individual reference files for detailed explanations and code examples:

• Section definitions - Category structure and impact levels
• Rule template - Template for adding new rules
• build-dynamic-imports - Example rule file
• cache-use-cache-directive - Example rule file

Related Skills

• For React 19 fundamentals, see react-19 skill
• For data fetching patterns, see tanstack-query skill
• For client-side forms, see react-hook-form skill

Full Compiled Document

For the complete guide with all rules expanded: AGENTS.md