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
| Priority | Category | Impact | Prefix |
|---|---|---|---|
| 1 | Build & Bundle Optimization | CRITICAL | build- |
| 2 | Caching Strategy | CRITICAL | cache- |
| 3 | Server Components & Data Fetching | HIGH | server- |
| 4 | Routing & Navigation | HIGH | route- |
| 5 | Server Actions & Mutations | MEDIUM-HIGH | action- |
| 6 | Streaming & Loading States | MEDIUM | stream- |
| 7 | Metadata & SEO | MEDIUM | meta- |
| 8 | Client Components | LOW-MEDIUM | client- |
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-19skill - •For data fetching patterns, see
tanstack-queryskill - •For client-side forms, see
react-hook-formskill
Full Compiled Document
For the complete guide with all rules expanded: AGENTS.md