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