Imported from Desperado911/FRsite (.agents/skills/nextjs/AGENTS.md). Install upstream with npx skills add Desperado911/FRsite --skill nextjs. Copyright stays with the author.

Next.js 16 App Router

Version 0.1.0
Next.js Community
August 2026

Note:
This document is mainly for agents and LLMs to follow when maintaining,
generating, or refactoring codebases. Humans may also find it useful,
but guidance here is optimized for automation and consistency by AI-assisted workflows.

Abstract

Comprehensive performance optimization guide for Next.js 16 App Router applications, designed for AI agents and LLMs. Contains 40+ rules across 8 categories, prioritized by impact from critical (build optimization, caching strategy) to incremental (client components). Each rule includes detailed explanations, real-world examples comparing incorrect vs. correct implementations, and specific impact metrics to guide automated refactoring and code generation.

Table of Contents

1. Build & Bundle Optimization — CRITICAL
   • 1.1 Avoid Barrel File Imports in App Router — CRITICAL (faster dev startup)
   • 1.2 Configure optimizePackageImports for Icon Libraries — CRITICAL (faster imports, smaller bundles)
   • 1.3 Configure Server External Packages for Node Dependencies — HIGH (prevents bundling issues, faster builds)
   • 1.4 Configure Turbopack at the Top Level — CRITICAL (faster cold starts on large apps)
   • 1.5 Use Dynamic Imports for Heavy Components — CRITICAL (smaller initial bundle)
2. Caching Strategy — CRITICAL
   • 2.1 Configure Fetch Cache Options Explicitly — HIGH (controls data freshness per request)
   • 2.2 Match Route Configuration to the Active Cache Model — MEDIUM-HIGH
   • 2.3 Use React cache() for Request Deduplication — HIGH (eliminates duplicate fetches per request)
   • 2.4 Use revalidatePath for Route-Level Cache Invalidation — HIGH (invalidates all cached data for a route)
   • 2.5 Use revalidateTag with cacheLife Profiles — CRITICAL (stale-while-revalidate behavior, instant updates)
   • 2.6 Use 'use cache' with Cache Components — CRITICAL (eliminates implicit caching confusion, explicit control)
3. Server Components & Data Fetching — HIGH
   • 3.1 Avoid Client-Side Data Fetching for Initial Data — MEDIUM-HIGH
   • 3.2 Colocate Data Fetching with Components — HIGH (eliminates prop drilling, enables streaming)
   • 3.3 Fetch Data in Parallel in Server Components — HIGH (eliminates server-side waterfalls, faster)
   • 3.4 Handle Server Component Errors Gracefully — MEDIUM (prevents full page crashes, better UX)
   • 3.5 Stream Server Components for Progressive Loading — HIGH (faster Time to First Byte, progressive rendering)
   • 3.6 Use Preload Pattern for Critical Data — MEDIUM-HIGH
4. Routing & Navigation — HIGH
   • 4.1 Configure Link Prefetching Appropriately — MEDIUM-HIGH
   • 4.2 Use Intercepting Routes for Modal Patterns — HIGH (enables shareable modal URLs, better UX)
   • 4.3 Use notFound() for Missing Resources — MEDIUM (proper 404 handling, better SEO)
   • 4.4 Use Parallel Routes for Independent Content — HIGH (independent loading, streaming, error handling)
   • 4.5 Use proxy.ts for Network Boundary Logic — MEDIUM-HIGH
5. Server Actions & Mutations — MEDIUM-HIGH
   • 5.1 Handle Server Action Errors Gracefully — MEDIUM-HIGH
   • 5.2 Revalidate Cache After Mutations — MEDIUM (ensures fresh data after changes)
   • 5.3 Show Pending States with useFormStatus — MEDIUM-HIGH
   • 5.4 Use Optimistic Updates for Instant Feedback — MEDIUM (instant UI response, better perceived performance)
   • 5.5 Use Server Actions for Form Submissions — MEDIUM-HIGH
6. Streaming & Loading States — MEDIUM
   • 6.1 Match Skeleton Dimensions to Actual Content — MEDIUM (prevents layout shift, better CLS score)
   • 6.2 Nest Suspense for Progressive Disclosure — LOW-MEDIUM
   • 6.3 Place Suspense Boundaries Strategically — MEDIUM (faster perceived performance, progressive loading)
   • 6.4 Use error.tsx for Route-Level Error Boundaries — MEDIUM (graceful error recovery, prevents full page crashes)
   • 6.5 Use loading.tsx for Route-Level Loading States — MEDIUM (automatic loading UI, instant navigation feedback)
7. Metadata & SEO — MEDIUM
   • 7.1 Configure Robots for Crawl Control — MEDIUM (prevents indexing of private pages)
   • 7.2 Generate Dynamic OpenGraph Images — LOW-MEDIUM
   • 7.3 Generate Sitemaps Dynamically — MEDIUM (improved crawlability, faster indexing)
   • 7.4 Use generateMetadata for Dynamic Metadata — MEDIUM (dynamic SEO, social sharing optimization)
8. Client Components — LOW-MEDIUM
   • 8.1 Avoid Hydration Mismatches — LOW-MEDIUM
   • 8.2 Load Third-Party Scripts Efficiently — LOW-MEDIUM
   • 8.3 Minimize 'use client' Boundary Scope — LOW-MEDIUM
   • 8.4 Pass Server Components as Children to Client Components — LOW-MEDIUM

References

1. https://nextjs.org/docs
2. https://nextjs.org/blog/next-16
3. https://react.dev
4. https://vercel.com/blog

Source Files

This document was compiled from individual reference files. For detailed editing or extension: