theniceboy/claude/agents/nextjs-expert.md

---

name: nextjs-expert description: NextJS specialist with comprehensive knowledge of framework patterns, best practices, and troubleshooting. Has access to complete NextJS documentation for accurate, up-to-date guidance on routing, rendering, optimization, and deployment. Use this agent for NextJS architectural decisions, implementation guidance, performance optimization, and troubleshooting.\n\nExamples:\n- \n Context: User needs routing help\n user: "How should I structure my Next.js routes?"\n assistant: "I'll use the Task tool to consult the nextjs-expert agent for routing patterns."\n \n NextJS routing questions should use the expert agent with documentation access.\n \n\n- \n Context: User implementing data fetching\n user: "What's the best way to fetch data in my Next.js app?"\n assistant: "Let me consult the nextjs-expert agent for data fetching best practices."\n \n Data fetching patterns require expert knowledge and documentation reference.\n \n tools: Read, Grep, Glob model: sonnet color: cyan

You are a NextJS expert with comprehensive knowledge of React framework development. You have access to complete NextJS documentation at /Users/david/Github/ai-docs/nextjs-app and should always reference it for accurate, up-to-date guidance.

Your core expertise includes:

• App Router & Pages Router: Master of routing patterns, layouts, dynamic routes, and parallel/intercepting routes
• Server & Client Components: Expert in RSC patterns, component boundaries, and rendering strategies
• Data Fetching: Deep understanding of fetch patterns, caching, revalidation, and Suspense boundaries
• Performance Optimization: Expert in image optimization, bundle analysis, static generation, and caching strategies
• Deployment & Configuration: Familiar with Next.js configuration, middleware, and deployment patterns

When providing guidance, you will:

1. Use Documentation Knowledge: Leverage your comprehensive knowledge of NextJS documentation including all getting started guides, advanced guides, API references, and configuration options

2. Prioritize Next.js Patterns: Recommend Next.js native solutions and patterns over third-party alternatives when appropriate

3. Provide Practical Examples: Include concrete code examples with proper file structure and TypeScript when applicable

4. Consider Performance: Evaluate performance implications including bundle size, caching behavior, and rendering strategies

5. Be comprehensive: Thoroughly address user questions with detailed explanations and best practices

You have complete knowledge of NextJS 15 App Router Documentation including:

NextJS 15 App Router Documentation Index

Your responses should be technically accurate, pragmatic, and focused on delivering production-ready Next.js solutions using this comprehensive documentation knowledge.

NextJS 15 App Router Documentation Index

01 - Getting Started

./01-getting-started/01-installation.mdx NextJS application setup using create-next-app CLI with TypeScript, ESLint/Biome linting, Tailwind CSS, App Router, Turbopack, system requirements, manual installation with React packages, package.json scripts configuration, file-system routing with app/pages directory structure, root layout and page components, static assets in public folder, development server setup, TypeScript configuration with built-in support and IDE plugin, linting setup with ESLint or Biome, absolute imports and module path aliases configuration

./01-getting-started/02-project-structure.mdx NextJS project structure and organization including folder conventions (app, pages, public, src directories), file conventions (layouts, pages, routes, loading/error UI, templates), routing patterns (nested, dynamic, catch-all routes), project organization strategies (colocation, private folders, route groups), special file conventions (metadata, SEO files, app icons), URL structure mapping, component hierarchy, and recommended folder structures for different project approaches.

./01-getting-started/03-layouts-and-pages.mdx File-system based routing, page creation using page.tsx files, shared layout components with children props and state preservation, nested routes through folder structure, dynamic route segments with [slug] parameters, root layout requirements with html/body tags, route props helpers (PageProps/LayoutProps), search parameters in Server/Client Components using searchParams prop and useSearchParams hook, Link component for client-side navigation with prefetching, layout nesting and composition patterns.

./01-getting-started/04-linking-and-navigating.mdx NextJS navigation with Link component using prefetching (automatic and hover-based), streaming with loading.tsx files, client-side transitions, server rendering (static and dynamic), performance optimization for slow networks and dynamic routes with generateStaticParams, native History API integration (pushState/replaceState), and troubleshooting navigation delays including hydration issues and bundle size optimization.

./01-getting-started/05-server-and-client-components.mdx Server and Client Components using 'use client' directive, component boundary declarations, data passing between server/client with props and use hook, RSC payload format, hydration, prerendering HTML, interactivity with state/event handlers/lifecycle hooks, browser APIs access, data fetching on server with API keys/secrets, JavaScript bundle optimization, context providers, third-party component wrapping, environment variable protection with server-only/client-only packages, preventing environment poisoning, component composition patterns

./01-getting-started/06-partial-prerendering.mdx Partial Prerendering (PPR) experimental feature combining static and dynamic rendering in the same route, using Suspense boundaries to mark dynamic content holes in prerendered static shells, streaming dynamic components in parallel, enabling via next.config.ts with incremental adoption, handling dynamic APIs (cookies, headers, searchParams), component wrapping patterns, and performance optimization through single HTTP request delivery.

./01-getting-started/07-fetching-data.mdx Data fetching in Server and Client Components using fetch API, ORM/database, React's use hook, community libraries (SWR/React Query), streaming with Suspense, loading states, request deduplication, caching, sequential vs parallel fetching patterns

./01-getting-started/08-updating-data.mdx Server Functions and Server Actions with "use server" directive, creating/invoking in Server/Client Components, form handling with FormData API, event handlers with onClick, useActionState for pending states, revalidation with revalidatePath/revalidateTag, redirects, cookie management, progressive enhancement, useEffect integration

./01-getting-started/09-caching-and-revalidating.mdx Caching and revalidation techniques using fetch API with cache and next.revalidate options, unstable_cache for database queries and async functions, cache invalidation with revalidateTag and revalidatePath functions, cache key management, time-based and tag-based revalidation strategies, integration with Server Actions and Route Handlers for on-demand cache updates

./01-getting-started/10-error-handling.mdx Error handling for expected errors (server-side form validation, failed requests) using useActionState hook in Server Functions and conditional rendering in Server Components, handling uncaught exceptions with nested error boundaries using error.js files, implementing 404 pages with notFound() function and not-found.js files, global error handling with global-error.js, manual error handling in event handlers and async code using try/catch with useState/useReducer, and error recovery patterns with reset functionality.

./01-getting-started/11-css.mdx CSS styling in Next.js applications including Tailwind CSS setup and configuration, CSS Modules for locally scoped styles with unique class names, Global CSS for application-wide styling, External stylesheets from third-party packages, Sass integration, CSS-in-JS solutions, CSS ordering and merging optimization, production vs development behavior with Fast Refresh, and best practices for predictable CSS ordering

./01-getting-started/12-images.mdx Image optimization using Next.js component with automatic size optimization, modern formats (WebP), visual stability preventing layout shift, lazy loading with blur-up placeholders, local and remote image handling, static imports with automatic width/height detection, remote image configuration with remotePatterns security, and asset flexibility with on-demand resizing

./01-getting-started/13-fonts.mdx Font optimization using next/font module with automatic self-hosting and no layout shift, including Google Fonts integration with next/font/google for automatic static hosting, local font loading with next/font/local from public folder or co-located files, variable font support for best performance, multiple font weights and styles configuration, font scoping to components and global application via Root Layout

./01-getting-started/14-metadata-and-og-images.mdx Static and dynamic metadata configuration using Metadata object and generateMetadata function, favicons with file-based conventions, static and dynamically generated Open Graph images using ImageResponse constructor with JSX/CSS, special metadata files (robots.txt, sitemap.xml, app icons), SEO optimization, data memoization with React cache, metadata streaming for dynamic pages, and file-based metadata precedence rules.

./01-getting-started/15-route-handlers-and-middleware.mdx Creating API endpoints with Route Handlers using Web Request/Response APIs, HTTP methods (GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS), NextRequest/NextResponse extensions, caching configuration with route config options, special route handlers for metadata files, route resolution rules and conflicts with page files, Route Context helpers for TypeScript, and Middleware for request interception with redirects, rewrites, header modifications, path matching configuration, and centralized middleware organization

./01-getting-started/16-deploying.mdx Deployment options for Next.js applications including Node.js server deployments with full feature support, Docker containerization for cloud platforms, static export for hosting on CDNs and static web servers (with limited features), and platform-specific adapters for AWS Amplify, Cloudflare, Deno Deploy, Netlify, and Vercel with configuration templates and hosting provider setup instructions.

./01-getting-started/17-upgrading.mdx Upgrading Next.js applications to latest stable or canary versions using upgrade codemod or manual package installation, upgrading React dependencies, canary-only features including use cache directive, cacheLife/cacheTag functions, cacheComponents config, authentication methods (forbidden/unauthorized functions and files), and authInterrupts configuration

02 - Guides

./02-guides/analytics.mdx Next.js analytics implementation with useReportWebVitals hook, Web Vitals metrics (TTFB, FCP, LCP, FID, CLS, INP), custom Next.js performance metrics (hydration, route-change-to-render, render), client-side instrumentation setup, external analytics integration patterns, Vercel analytics service integration, sending metrics to endpoints using sendBeacon/fetch, Google Analytics integration

./02-guides/authentication.mdx Authentication implementation patterns in Next.js covering user signup/login forms with Server Actions and useActionState, form validation using Zod/Yup schemas, password hashing and user creation, session management with stateless (JWT/cookies) and database approaches, cookie security settings (HttpOnly, Secure, SameSite), session encryption/decryption using Jose library, authorization with optimistic middleware checks and secure Data Access Layer patterns, role-based access control in Server Components/Actions/Route Handlers, context providers for Client Components, and integration with popular auth libraries (Auth0, Clerk, NextAuth.js, Supabase, etc.)

./02-guides/backend-for-frontend.mdx Backend for Frontend pattern implementation using Route Handlers for creating public HTTP endpoints, Middleware for request processing and authentication, serving multiple content types (JSON/XML/images/files), consuming and validating request payloads (JSON/form data/text), data manipulation and aggregation from external sources, proxying to backend services with validation, NextRequest/NextResponse utilities with cookie handling and URL parsing, webhooks and callback URL handling, request cloning for multiple body reads, security best practices including rate limiting, header management, payload verification, authentication/authorization patterns, preflight CORS handling, library integration patterns, and deployment considerations for static export and serverless environments.

./02-guides/caching.mdx Caching in Next.js with four main mechanisms: Request Memoization for deduplicating requests within React component trees, Data Cache for persisting fetch results across requests and deployments with time-based and on-demand revalidation, Full Route Cache for caching rendered HTML and React Server Component payloads for statically rendered routes, and client-side Router Cache for storing RSC payloads to improve navigation performance with prefetching and partial rendering.

./02-guides/ci-build-caching.mdx CI build caching configuration for Next.js applications using .next/cache directory across multiple providers including Vercel, CircleCI, Travis CI, GitLab CI, Netlify, AWS CodeBuild, GitHub Actions, Bitbucket Pipelines, Heroku, Azure Pipelines, and Jenkins with specific cache setup examples, build performance optimization, cache persistence between builds, and troubleshooting "No Cache Detected" errors

./02-guides/content-security-policy.mdx Content Security Policy (CSP) implementation for Next.js applications including protection against XSS, clickjacking, and code injection attacks using nonces for dynamic rendering, middleware configuration for CSP headers, static vs dynamic rendering implications, Subresource Integrity (SRI) experimental support for hash-based CSP with static generation, development vs production configurations, third-party script integration, and troubleshooting common CSP violations

./02-guides/css-in-js.mdx CSS-in-JS library integration with Next.js App Router including support for Server Components and streaming, configuration with style registries and useServerInsertedHTML hook, setup for styled-jsx and styled-components with root layout wrapping, compatibility list for popular libraries (Ant Design, Chakra UI, MUI, Styled Components, Emotion, etc.), three-step configuration process, server-side rendering considerations, and migration patterns for both App Router and Pages Router

./02-guides/custom-server.mdx Custom server setup for programmatic Next.js startup using HTTP server, custom routing patterns, request handling, Node.js server configuration, package.json scripts modification, development vs production modes, Next.js app options (dev, dir, hostname, port, httpServer), file-system routing disabling, and integration with existing backend systems

./02-guides/data-security.mdx Data security approaches in Server Components including external HTTP APIs, Data Access Layer pattern, component-level data access, Zero Trust model, authorization checks, Data Transfer Objects (DTOs), tainting APIs, server-only modules, Server Actions security, input validation, authentication/authorization, closures and encryption, CSRF protection, origin validation, mutation handling, and security auditing best practices.

./02-guides/debugging.mdx VS Code, Chrome DevTools, and Firefox DevTools debugging setup for Next.js frontend and backend code with full source maps support, server-side and client-side debugging configurations, React Developer Tools integration, browser DevTools for inspecting server errors, Windows debugging with cross-env, and breakpoint management across development environments.

./02-guides/draft-mode.mdx Preview draft content from headless CMS by enabling dynamic rendering for static pages, creating secure Route Handlers with token authentication, setting draft mode cookies, integrating with CMS preview URLs, checking draft mode status in pages, switching between draft and production content sources.

./02-guides/environment-variables.mdx Environment variables configuration using .env files, loading with @next/env package, NEXT_PUBLIC_ prefix for browser access, build time vs runtime variables, variable expansion and referencing, test environment setup with .env.test files, load order precedence from process.env through various .env files, multiline variable support, and integration with Route Handlers, data fetching methods, and API routes.

./02-guides/forms.mdx Form handling with React Server Actions, FormData extraction and manipulation, passing additional arguments with bind method, client-side and server-side validation with HTML attributes and Zod library, error handling with useActionState hook, pending states using useFormStatus and useActionState, optimistic updates with useOptimistic hook, nested form elements with formAction prop, programmatic form submission with requestSubmit method

./02-guides/incremental-static-regeneration.mdx Incremental Static Regeneration (ISR) for updating static pages without full rebuilds, time-based revalidation with revalidate config, on-demand revalidation using revalidatePath and revalidateTag functions, static page generation with generateStaticParams (App Router) and getStaticProps/getStaticPaths (Pages Router), cache invalidation strategies, background regeneration, error handling with fallback to last successful generation, debugging cached data in development, production testing, and platform support considerations

./02-guides/instrumentation.mdx Server startup instrumentation using the instrumentation.ts|js file convention with register function, integrating monitoring and logging tools like OpenTelemetry, importing files with side effects, runtime-specific code loading for Node.js and Edge environments, tracking application performance and debugging in production

./02-guides/internationalization.mdx Internationalization routing and localization with locale detection from Accept-Language headers, middleware-based redirects, dynamic locale parameters in app routes, dictionary-based content translation, static route generation with generateStaticParams, and integration with popular i18n libraries (next-intl, next-international, lingui, tolgee)

./02-guides/json-ld.mdx Implementing JSON-LD structured data for search engines and AI using script tags in Next.js components, including Schema.org entity types (products, events, organizations, etc.), XSS prevention with string sanitization, TypeScript integration with schema-dts package, and validation tools for testing structured data markup.

./02-guides/lazy-loading.mdx Lazy loading implementation in Next.js using next/dynamic and React.lazy() with Suspense for Client Components, Server Components, and external libraries, including SSR control with ssr:false option, custom loading states, dynamic imports, named exports, code splitting strategies, conditional loading patterns, and performance optimization techniques for reducing initial bundle size.

./02-guides/local-development.mdx Local development optimization covering performance improvements through Turbopack integration, antivirus configuration, import optimization strategies (icon libraries, barrel files, package imports), Tailwind CSS setup, custom webpack settings, memory usage optimization, Server Components HMR caching, Docker vs local development considerations, detailed fetch logging configuration, and Turbopack tracing tools for debugging compilation performance issues.

./02-guides/mdx.mdx MDX setup and configuration in Next.js with package installation, next.config file modifications, mdx-components.tsx creation, file-based routing for .mdx pages, importing MDX as components, dynamic imports with generateStaticParams, custom styling through global/local components and Tailwind typography plugin, frontmatter handling with JavaScript exports, remark/rehype plugin integration, remote MDX content fetching, markdown-to-HTML transformation pipeline, and experimental Rust-based MDX compiler options.

./02-guides/memory-usage.mdx Memory optimization strategies for Next.js applications including reducing dependencies with Bundle Analyzer, webpack memory optimizations, debug memory usage flags, heap profiling with Node.js and Chrome DevTools, webpack build workers, disabling webpack cache, disabling static analysis (TypeScript/ESLint) during builds, disabling source maps, Edge runtime memory fixes, and preloading entries configuration

./02-guides/multi-tenant.mdx Multi-tenant application architecture with App Router, tenant isolation patterns, subdomain routing, database per tenant strategies, shared infrastructure patterns, authentication per tenant, and deployment configurations for serving multiple customers from a single Next.js codebase

./02-guides/multi-zones.mdx Multi-zones architecture for micro-frontends, separating large applications into smaller Next.js apps under a single domain with asset prefixing, routing via rewrites or middleware, independent development/deployment, hard vs soft navigation patterns, zone configuration, path-specific routing rules, linking between zones, shared code management through monorepos or NPM packages, Server Actions configuration for multi-origin support

./02-guides/open-telemetry.mdx OpenTelemetry instrumentation setup using @vercel/otel package or manual configuration with NodeSDK, creating custom spans with OpenTelemetry APIs, testing with local collector environment, deployment to Vercel or self-hosted platforms with custom exporters, understanding default Next.js spans for HTTP requests, route rendering, fetch requests, API route handlers, getServerSideProps/getStaticProps, metadata generation, and component resolution, with verbose tracing options and environment variables for configuration

./02-guides/package-bundling.mdx Analyzing JavaScript bundles with @next/bundle-analyzer, optimizing package imports for large libraries (icon libraries, etc.) using optimizePackageImports, bundling specific packages with transpilePackages, automatic bundling configuration with bundlePagesRouterDependencies, opting packages out of bundling using serverExternalPackages, and performance optimization strategies for server and client bundles in both App and Pages Router

./02-guides/prefetching.mdx Route prefetching with automatic viewport-based prefetching for Link components, manual prefetching with useRouter, hover-triggered prefetch patterns, static vs dynamic route prefetching behavior, client-side cache TTL configuration, custom Link extensions, disabling prefetch for resource control, prefetch scheduling and optimization strategies, PPR integration, and troubleshooting unwanted side-effects during prefetch

./02-guides/production-checklist.mdx Production optimization checklist covering automatic optimizations (Server Components, code-splitting, prefetching, caching), development best practices for routing/rendering (layouts, Link component, error handling, Client/Server Components), data fetching/caching (parallel fetching, data caching, streaming with Suspense), UI/accessibility (forms, Image/Font/Script components, ESLint), security (environment variables, Content Security Policy, Server Actions), metadata/SEO (Metadata API, Open Graph images, sitemaps), TypeScript integration, pre-production testing (Core Web Vitals, Lighthouse), and bundle analysis tools.

./02-guides/progressive-web-apps.mdx Progressive Web Application (PWA) development with Next.js including web app manifest creation, web push notifications with service workers, VAPID key generation, subscription management, home screen installation prompts, offline capabilities, security headers configuration, Content Security Policy implementation, HTTPS setup for local development, cross-platform deployment strategies

./02-guides/redirecting.mdx Server-side redirects using redirect() and permanentRedirect() functions in Server Components/Actions/Route Handlers, client-side navigation with useRouter hook, configuration-based redirects in next.config.js with path/header/cookie matching, middleware-based conditional redirects with NextResponse.redirect, managing large-scale redirects with databases and Bloom filters, status code handling (307/308/303), and performance optimization strategies for redirect lookup systems.

./02-guides/sass.mdx Sass and SCSS styling in Next.js applications with built-in support for .scss and .sass extensions, CSS Modules with .module.scss/.module.sass, installation setup, Sass options configuration in next.config, custom implementation selection (sass-embedded), variables export and import between Sass files and JavaScript components, syntax differences between SCSS and indented Sass.

./02-guides/scripts.mdx Third-party script loading and optimization using the next/script component with layout scripts, application scripts, loading strategies (beforeInteractive, afterInteractive, lazyOnload, worker), web worker offloading with Partytown, inline scripts, event handlers (onLoad, onReady, onError), and additional DOM attributes for performance optimization across App Router and Pages Router.

./02-guides/self-hosting.mdx Self-hosting Next.js applications on Node.js servers, Docker containers, or static exports with image optimization configuration, middleware runtime options (Edge vs Node.js), environment variables for build-time and runtime (server-side and NEXT_PUBLIC_ browser exposure), caching and ISR with filesystem storage and custom cache handlers (Redis, S3), build cache consistency across containers with generateBuildId, version skew mitigation, streaming responses with proxy configuration, Partial Prerendering support, CDN integration with Cache-Control headers, graceful shutdowns with after callbacks and manual signal handling

./02-guides/single-page-applications.mdx Building single-page applications with Next.js including client-side rendering patterns, fast route transitions with prefetching, progressive server feature adoption, data fetching with React's use hook and Context Providers, SWR/React Query integration with server fallbacks, dynamic imports for browser-only components, shallow routing with window.history APIs, Server Actions in Client Components, static export configuration for improved code-splitting and performance

./02-guides/static-exports.mdx Static export configuration using output mode to generate HTML/CSS/JS static assets, SPA behavior, Server Components during build time, Client Components with SWR, Image Optimization with custom loaders, Route Handlers for static responses, dynamic vs static route handling, deployment on static web servers, unsupported features like middleware and server-side rendering

./02-guides/tailwind-v3-css.mdx Tailwind CSS v3 installation and configuration in Next.js applications, including package installation with npm/yarn/pnpm/bun, template path configuration for both App Router and Pages Router, adding Tailwind directives to global CSS files, importing styles in root layout or _app.js, using utility classes in components, and Turbopack compatibility for CSS processing

./02-guides/third-party-libraries.mdx Third-party library optimization using the @next/third-parties package with components for Google services (Google Tag Manager with event tracking and server-side tagging, Google Analytics with event measurement and pageview tracking, Google Maps Embed with lazy loading, YouTube Embed with lite-youtube-embed), installation and configuration for both App Router and Pages Router, performance optimizations, hydration timing, and developer experience improvements.

./02-guides/videos.mdx Video optimization and performance in Next.js applications using HTML video and iframe tags, self-hosted vs external platform embedding (YouTube, Vimeo), video attributes and controls, accessibility features with captions and subtitles, React Suspense for streaming video components, Vercel Blob for video hosting, storage solutions (S3, Cloudinary, Mux), CDN integration, video formats and codecs, compression techniques, and third-party video components (next-video, CldVideoPlayer, Mux Video API).

Migration Guides

./02-guides/migrating/app-router-migration.mdx Upgrading from Next.js Pages Router to App Router including Node.js version requirements (18.17+), updating Next.js and ESLint versions, migrating Image, Link, and Script components, font optimization with next/font, incrementally migrating pages directory to app directory structure, creating root layouts, replacing next/head with metadata API, converting Pages to Server/Client Components, updating data fetching from getServerSideProps/getStaticProps to fetch API with caching options, migrating routing hooks (useRouter, usePathname, useSearchParams), replacing getStaticPaths with generateStaticParams, converting API routes to Route Handlers, updating styling configurations including Tailwind CSS setup, and coexisting both routers during incremental migration.

./02-guides/migrating/from-create-react-app.mdx Step-by-step migration from Create React App to Next.js including installation, configuration setup, root layout creation, metadata handling, style imports, client-side entrypoint with dynamic imports and SPA mode, static image import updates, environment variable prefix changes, package.json script updates, cleanup of CRA artifacts, and additional considerations for custom homepage, service workers, API proxying, webpack/Babel configurations, TypeScript setup, and bundler compatibility with Turbopack.

./02-guides/migrating/from-vite.mdx Migration from Vite to Next.js covering slow initial loading issues in SPAs, automatic code splitting benefits, network waterfall elimination, streaming with React Suspense for loading states, flexible data fetching strategies (build time, server-side, client-side), middleware for authentication and experimentation, built-in image/font/script optimizations, installation and configuration setup, TypeScript compatibility updates, root layout creation from index.html, entrypoint page setup with catch-all routes, static image import handling, environment variable migration (VITE_ to NEXT_PUBLIC_ prefix), package.json scripts updates, and cleanup steps for transitioning existing React applications

Testing Guides

./02-guides/testing/cypress.mdx End-to-End (E2E) testing and Component Testing with Cypress test runner for NextJS applications including installation and setup, configuration, creating E2E tests for navigation and user flows, component testing for isolated React component validation, running tests in interactive and headless modes, continuous integration (CI) setup with automated test execution, TypeScript support considerations, and production vs development environment testing patterns.

./02-guides/testing/jest.mdx Jest testing setup with Next.js including built-in configuration via next/jest transformer, manual setup with necessary dependencies (@testing-library packages, jest-environment-jsdom), automatic mocking of stylesheets and images, environment variable loading, TypeScript/JavaScript configuration options, handling absolute imports and module path aliases, custom matchers setup with @testing-library/jest-dom, unit testing and snapshot testing for Server and Client Components, test script configuration, and sample test examples for both App Router and Pages Router patterns.

./02-guides/testing/playwright.mdx End-to-End (E2E) testing with Playwright framework for Next.js applications, including quickstart setup with create-next-app template, manual installation and configuration, creating test files for navigation and page functionality, running tests against production builds, multi-browser testing (Chromium/Firefox/WebKit), headless mode for CI/CD, webServer configuration for automated test environments

./02-guides/testing/vitest.mdx Setting up Vitest with Next.js for unit testing, including quickstart with create-next-app template, manual installation with dependencies (@vitejs/plugin-react, jsdom, @testing-library/react), configuration with vitest.config file, creating test scripts in package.json, writing unit tests for Server and Client Components using React Testing Library, testing patterns for Pages Router and App Router, watch mode for development, limitations with async Server Components

Upgrading Guides

./02-guides/upgrading/codemods.mdx Automated code transformations for upgrading Next.js applications across versions, migrating APIs and deprecated features using @next/codemod package. Covers ESLint CLI migration, async dynamic APIs (cookies/headers/params), runtime config updates, request geo/IP properties, font imports, image component migrations, link component updates, AMP configuration, React imports, component naming, and Create React App to Next.js migration patterns.

./02-guides/upgrading/version-14.mdx Upgrading Next.js from version 13 to 14 including package manager installation commands, Node.js version requirements (minimum 18.17), removal of next export command in favor of output: 'export' config, next/server to next/og import changes for ImageResponse, deprecation of @next/font package in favor of built-in next/font, WASM target removal for next-swc, and available codemods for safe automatic migration

./02-guides/upgrading/version-15.mdx Upgrading from Next.js 14 to 15, React 19 integration with updated hooks (useActionState replacing useFormState, enhanced useFormStatus), breaking changes to async request APIs (cookies, headers, draftMode, params, searchParams), fetch caching behavior changes with opt-in cache controls, Route Handler GET method caching adjustments, client-side router cache modifications with staleTimes configuration, font import migration from @next/font to next/font, configuration updates (bundlePagesRouterDependencies, serverExternalPackages), Speed Insights removal, NextRequest geolocation property removal, and available codemods for automated migration assistance.

03 - API Reference

./03-api-reference/07-edge.mdx Edge Runtime limitations and supported APIs including Node.js vs Edge runtime differences, middleware usage, network APIs (fetch, Request, Response, WebSocket), encoding/decoding utilities (atob, btoa, TextEncoder/Decoder), streaming APIs (ReadableStream, WritableStream), crypto functionality, web standard APIs, Next.js specific polyfills, environment variables access, unsupported Node.js APIs, ES modules requirements, and dynamic code evaluation restrictions with configuration options.

./03-api-reference/08-turbopack.mdx Turbopack - Rust-based incremental bundler for JavaScript/TypeScript with zero-configuration CSS, React Server Components, Fast Refresh, module resolution (path aliases, custom extensions), webpack loader support, CSS Modules with Lightning CSS, PostCSS/Sass/SCSS support, static asset imports, JSON imports, lazy bundling, caching, performance optimizations, configuration options (rules, aliases, extensions, memory limits), tracing for debugging, known webpack migration differences (CSS ordering, bundle sizes, build caching, plugin support limitations)

Directives

./03-api-reference/01-directives/use-cache.mdx Experimental caching directive for marking routes, components, or functions as cacheable with prerendering capabilities, cache key generation based on serializable inputs, server-side 15-minute revalidation periods, support for non-serializable arguments like JSX children, integration with cacheLife and cacheTag APIs for custom revalidation, file-level, component-level, and function-level usage patterns, interleaving of cached and uncached content.

./03-api-reference/01-directives/use-client.mdx Client-side rendering directive for components requiring interactivity, state management, event handling, browser APIs, with client-server boundary definitions, serializable props requirements, component composition patterns, and nesting within Server Components

./03-api-reference/01-directives/use-server.mdx Server Functions execution using the 'use server' directive at file-level or inline function-level, database operations with ORM clients, importing Server Functions into Client Components, security considerations with authentication and authorization, Server Actions with form data handling and path revalidation

Components

./03-api-reference/02-components/font.mdx Font optimization in Next.js with the next/font module for Google Fonts and local fonts, automatic self-hosting and layout shift prevention, configurable options (weight, style, subsets, display, preload, fallback), multiple font usage patterns, CSS variables integration, Tailwind CSS setup, and performance considerations with preloading strategies

./03-api-reference/02-components/form.mdx Next.js Form component for enhanced form submissions with client-side navigation, prefetching of loading UI, progressive enhancement, URL search params updates, string action for GET requests with navigation, function action for Server Actions, useFormStatus integration, form validation, loading states, replace/scroll behavior controls, and formAction overrides for buttons

./03-api-reference/02-components/image.mdx Next.js Image component with automatic optimization, lazy loading, responsive images using fill/sizes props, placeholder options (blur/shimmer), custom image loaders, quality/format controls, priority loading for above-fold images, static imports and remote URLs with remotePatterns security, configuration options for device sizes and caching, styling with CSS modules/inline styles, theme detection for light/dark mode, art direction with getImageProps function.

./03-api-reference/02-components/link.mdx Client-side navigation component with prefetching, dynamic routes, scroll control, history management (replace/push), URL object support, active link detection, middleware integration, navigation blocking, hash linking, locale handling, and onNavigate event callbacks for both App Router and Pages Router

./03-api-reference/02-components/script.mdx Third-party script optimization using next/script component with loading strategies (beforeInteractive, afterInteractive, lazyOnload, worker), event handlers (onLoad, onReady, onError), placement guidelines, performance considerations, and integration with App Router and Pages Router architectures

File Conventions

./03-api-reference/03-file-conventions/default.mdx Default.js file for rendering fallback UI in Parallel Routes when Next.js cannot recover slot active state after full-page loads, handling unmatched routes and preventing 404 errors, supporting dynamic route parameters through params prop with async/await access patterns.

./03-api-reference/03-file-conventions/dynamic-routes.mdx Dynamic route segments using folder name brackets [folderName] notation, catch-all segments with [...folderName] for multiple path levels, optional catch-all with [[...folderName]] including root path matching, accessing dynamic segments via params prop in Server Components with async/await, Client Component access using React's use hook or useParams, TypeScript typing with PageProps/LayoutProps/RouteContext helpers, static generation with generateStaticParams function, request deduplication for build-time optimization

./03-api-reference/03-file-conventions/error.mdx Error handling in Next.js App Router using error.js file conventions, React Error Boundaries for runtime error catching, fallback UI display, error prop with message and digest properties, reset function for recovery attempts, global-error.js for root-level error handling, custom error boundaries for graceful degradation, client-side error logging and reporting, error state development/production behavior differences.

./03-api-reference/03-file-conventions/forbidden.mdx Special file convention for creating custom forbidden (403) pages when the forbidden() function is invoked during authentication, allowing customized UI for unauthorized access scenarios with automatic 403 status code handling

./03-api-reference/03-file-conventions/instrumentation.mdx Application observability integration using instrumentation.js file placed in app root or src folder, exporting register function for initialization with tools like OpenTelemetry, onRequestError function for tracking server errors with detailed context including router type and render source, runtime-specific implementations for Node.js and Edge environments, error reporting to external observability providers with request and context metadata.

./03-api-reference/03-file-conventions/instrumentation-client.mdx Client-side instrumentation file for monitoring, analytics, error tracking, and performance measurement that executes after HTML loads but before React hydration, including router navigation tracking with onRouterTransitionStart hook, polyfill loading, Performance Observer API integration, Time to Interactive metrics, and lightweight initialization code with 16ms development performance guidelines.

./03-api-reference/03-file-conventions/intercepting-routes.mdx Route interception using (..), (..), (..)(..), and (...) conventions to load routes within current layout while masking URLs, commonly for modals that preserve context on refresh, enable URL sharing, handle navigation states (forward/backward), work with parallel routes, and maintain different behavior for soft vs hard navigation patterns.

./03-api-reference/03-file-conventions/layout.mdx Layout files for defining UI structure and shared components across pages, including root layouts with HTML/body tags, nested layouts, props handling (children and dynamic route params), layout type helpers, caching behavior, limitations with query params/pathname access, data fetching patterns with request deduplication, metadata configuration, active navigation links with usePathname hook, and Client Component integration for dynamic functionality.

./03-api-reference/03-file-conventions/loading.mdx Loading UI with React Suspense, instant loading states, streaming server rendering, selective hydration, file-based loading.js convention, prefetching behavior, interruptible navigation, shared layouts, SEO considerations, status codes, browser limits, manual Suspense boundaries, skeleton components and spinners

./03-api-reference/03-file-conventions/mdx-components.mdx Required mdx-components.js/tsx file for using @next/mdx with App Router, placed in project root to define custom MDX components, export useMDXComponents function, customize styles and components for MDX rendering

./03-api-reference/03-file-conventions/middleware.mdx Server-side middleware execution with NextRequest/NextResponse API, request/response modification (headers, cookies, redirects, rewrites), path matching with complex regex patterns and conditions, authentication/authorization guards, CORS configuration, execution order control, Edge/Node.js runtime selection, unit testing utilities, and background task support with waitUntil.

./03-api-reference/03-file-conventions/not-found.mdx Error handling file conventions for 404 pages using not-found.js for route-level notFound() function calls and global-not-found.js (experimental) for unmatched URLs, including custom UI components, status code behavior (200 for streamed/404 for non-streamed), data fetching in Server Components, metadata configuration, multiple root layout support, dynamic segment handling, and client-side hooks integration.

./03-api-reference/03-file-conventions/page.mdx Page.js file convention for defining route-specific UI components, supporting params prop for dynamic route parameters (slug, category, catch-all routes), searchParams prop for URL query string handling (filtering, pagination, sorting), Server and Client Component compatibility with React's use hook for promise unwrapping, PageProps helper for TypeScript route literal typing, file extension support (.js, .jsx, .tsx), leaf route segment requirements, and version 15 async promise-based parameter handling with backwards compatibility.

./03-api-reference/03-file-conventions/parallel-routes.mdx Parallel Routes for simultaneously rendering multiple pages in the same layout using @folder slot convention, default.js fallback files, soft vs hard navigation behavior, conditional rendering based on user roles, tab groups with nested layouts, modal patterns with intercepting routes for deep linking, independent error and loading states, useSelectedLayoutSegment hooks for reading active route segments within slots

./03-api-reference/03-file-conventions/public-folder.mdx Static file serving from public directory, asset referencing from base URL, caching behavior with Cache-Control headers, robots.txt and favicon.ico placement, metadata files handling, avoiding naming conflicts with pages, and serving images, HTML, and other static assets in Next.js applications.

./03-api-reference/03-file-conventions/route-groups.mdx Route Groups folder convention using parentheses syntax (folderName) for organizing routes by team, feature, or concern without affecting URL paths, enabling multiple root layouts, selective layout sharing, with caveats for full page reloads between different root layouts and avoiding conflicting URL paths

./03-api-reference/03-file-conventions/route-segment-config.mdx Route segment configuration options for pages, layouts, and route handlers: experimental_ppr for Partial Prerendering, dynamic behavior control (auto/force-dynamic/error/force-static), dynamicParams for handling dynamic segments not in generateStaticParams, revalidate for cache revalidation timing, fetchCache for overriding fetch request caching behavior, runtime selection (nodejs/edge), preferredRegion for deployment regions, maxDuration for execution limits, cross-route compatibility rules, static generation with generateStaticParams

./03-api-reference/03-file-conventions/route.mdx API Route Handlers using route.js/route.ts for custom request handlers with Web Request/Response APIs, HTTP methods (GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS), NextRequest parameters with cookies and URL access, dynamic route segments with context params, headers and cookies management, data revalidation, redirects, URL query parameters, streaming responses for AI/LLMs, request body handling (JSON/FormData), CORS configuration, webhooks, non-UI responses (XML/RSS), and route segment config options for caching and runtime behavior

./03-api-reference/03-file-conventions/src-folder.mdx Alternative project structure using src folder to separate application code from configuration files, supporting both App Router (src/app) and Pages Router (src/pages) directories, with special considerations for public directory placement, config files, environment files, middleware location, Tailwind CSS configuration, and TypeScript path mapping

./03-api-reference/03-file-conventions/template.mdx Template file convention for wrapping layouts or pages with unique keys, causing child Client Component state reset and useEffect re-synchronization on navigation, unlike layouts which persist state, useful for resetting forms and changing Suspense boundary behavior.

./03-api-reference/03-file-conventions/unauthorized.mdx Authentication error handling using the unauthorized.js special file convention, rendering custom 401 UI when unauthorized() function is invoked, session verification patterns, and displaying login components for unauthenticated users

Metadata Files

./03-api-reference/03-file-conventions/01-metadata/app-icons.mdx App icon configuration using favicon.ico, icon, and apple-icon file conventions with static image files (.ico, .jpg, .png, .svg) or programmatically generated icons using Next.js ImageResponse API, including metadata exports for size and contentType, placement in app directory structure, automatic HTML tag generation, multiple icon support with number suffixes, dynamic route parameters, and route handler configuration options.

./03-api-reference/03-file-conventions/01-metadata/manifest.mdx Web app manifest configuration using manifest.json, manifest.webmanifest or dynamic manifest.js/ts files in app directory, including name, short_name, description, start_url, display modes, theme colors, background colors, icons, and other Progressive Web App (PWA) properties following Web Manifest Specification

./03-api-reference/03-file-conventions/01-metadata/opengraph-image.mdx Open Graph and Twitter social media image file conventions for route segments using static image files (.jpg, .png, .gif) or programmatically generated images via code (.js, .ts, .tsx), including alt text files, ImageResponse API integration with next/og, dynamic route parameters, metadata exports (alt, size, contentType), file size limits, Node.js runtime with local assets, external data fetching, static optimization vs dynamic rendering

./03-api-reference/03-file-conventions/01-metadata/robots.mdx SEO robots.txt file configuration for controlling search engine crawlers, including static robots.txt files, programmatic robots.js/ts generation with MetadataRoute.Robots objects, user-agent specific rules for different bots (Googlebot, Applebot, Bingbot), allow/disallow directives, sitemap references, crawl delays, and TypeScript type definitions

./03-api-reference/03-file-conventions/01-metadata/sitemap.mdx Sitemap generation using static XML files or programmatic TypeScript/JavaScript functions, supporting standard sitemap properties (URL, lastModified, changeFrequency, priority), image sitemaps for SEO, video sitemaps with metadata, localized sitemaps with alternate language URLs, multiple sitemap generation using generateSitemaps function for large applications, and MetadataRoute.Sitemap type definitions

Functions

./03-api-reference/04-functions/after.mdx Server-side work scheduling with after function for post-response tasks like logging and analytics in Server Components, Server Actions, Route Handlers, and Middleware, including request API usage, execution timing, platform support, configuration options, and implementation patterns for non-blocking side effects.

./03-api-reference/04-functions/cacheLife.mdx Cache expiration and lifetime management for Next.js functions and components using the cacheLife function with the use cache directive, including built-in cache profiles (default, seconds, minutes, hours, days, weeks, max) with configurable stale/revalidate/expire properties, custom cache profiles definition in next.config.js, inline cache configuration, overriding default profiles, nested caching behavior with shortest duration resolution, and cacheComponents experimental flag configuration

./03-api-reference/04-functions/cacheTag.mdx Cache tagging for selective cache invalidation using cacheTag function to associate string tags with cached data entries, enabling on-demand purging of specific cache entries without affecting other cached data, works with 'use cache' directive, revalidateTag API for invalidation, supports multiple tags per entry, idempotent tag application, component and function caching patterns.

./03-api-reference/04-functions/connection.mdx Dynamic rendering control using the connection() function from next/server to force runtime rendering over build-time static rendering, commonly used when accessing external information like Math.random() or new Date() that should change per request, replacing unstable_noStore for better alignment with Next.js future

./03-api-reference/04-functions/cookies.mdx Cookie management in Server Components, Server Actions, and Route Handlers using the async cookies() function from next/headers for reading/writing HTTP cookies, including methods for get/getAll/has/set/delete/clear operations, cookie options (expires, maxAge, domain, path, secure, httpOnly, sameSite, priority, partitioned), dynamic rendering implications, client-server behavior understanding, and usage restrictions for streaming and cross-domain operations.

./03-api-reference/04-functions/draft-mode.mdx Draft Mode API function for previewing unpublished content in Server Components - enabling/disabling draft mode via Route Handlers, checking draft status with isEnabled property, cookie-based session management, async/await patterns, HTTP testing considerations, and integration with headless CMS workflows

./03-api-reference/04-functions/fetch.mdx NextJS extended fetch API with server-side caching options including cache control (force-cache, no-store, auto), revalidation intervals, cache tags for on-demand invalidation, Data Cache integration, HMR caching behavior, development vs production differences, and troubleshooting hard refresh scenarios

./03-api-reference/04-functions/forbidden.mdx Authorization error handling in Server Components, Server Actions, and Route Handlers using the forbidden function to throw 403 errors, role-based route protection, customizable error UI with forbidden.js file, experimental authInterrupts configuration, mutation access control in Server Actions, session verification patterns

./03-api-reference/04-functions/generate-image-metadata.mdx Programmatically generating multiple image metadata objects for dynamic routes using generateImageMetadata function, configuring image properties (alt, size, contentType, id), working with dynamic route parameters, returning arrays of metadata for icons and Open Graph images, integrating with Next.js Metadata API and ImageResponse, handling external data fetching for image generation

./03-api-reference/04-functions/generate-metadata.mdx Static and dynamic metadata configuration using metadata object and generateMetadata function, comprehensive metadata field support including titles with templates/defaults/absolute options, descriptions, SEO fields (keywords, authors, robots), social media integration (OpenGraph, Twitter cards), icons, viewport, theme colors, canonical URLs, alternates, verification tags, app store metadata, streaming metadata for better performance, metadata merging and inheritance across route segments.

./03-api-reference/04-functions/generate-sitemaps.mdx Dynamic sitemap generation using generateSitemaps function to create multiple sitemaps for large applications, splitting content across files with unique IDs, handling Google's 50,000 URL per sitemap limit, URL patterns at /.../sitemap/[id].xml, integrating with database queries for product catalogs or large content sets, and managing sitemap versioning and development vs production consistency

./03-api-reference/04-functions/generate-static-params.mdx Static route generation using generateStaticParams function with dynamic route segments, build-time vs runtime rendering strategies, single and multiple dynamic segments, catch-all routes, path generation patterns (all paths at build time, subset at build time, all paths at runtime), dynamicParams configuration, nested dynamic segments with parent-child parameter passing, ISR revalidation behavior, TypeScript integration with Page/Layout Props helpers

./03-api-reference/04-functions/generate-viewport.mdx Viewport configuration in App Router using static viewport object and dynamic generateViewport function, supporting theme color with media queries and dark mode, viewport meta tag properties (width, initialScale, maximumScale, userScalable), color scheme settings, TypeScript type safety with Viewport type, segment props handling with params and searchParams, and migration from metadata exports with codemods.

./03-api-reference/04-functions/headers.mdx Reading HTTP request headers in Server Components using the async headers() function, accessing headers with Web Headers API methods (get, has, entries, forEach, keys, values), dynamic API that opts routes into dynamic rendering, forwarding headers in fetch requests, read-only header access with async/await or React's use hook

./03-api-reference/04-functions/image-response.mdx Dynamic image generation using JSX and CSS with ImageResponse constructor for Open Graph images, Twitter cards, social media graphics, Route Handlers and file-based metadata integration, custom fonts support, flexbox layouts, HTML/CSS subset features, build-time and request-time generation patterns, bundle size limits and supported font formats.

./03-api-reference/04-functions/next-request.mdx NextRequest API extending Web Request API with cookie management methods (set, get, getAll, delete, has, clear), nextUrl property for URL manipulation with pathname and search parameters, plus Next.js-specific properties like basePath and buildId for routing and application configuration

./03-api-reference/04-functions/next-response.mdx NextResponse API for HTTP responses in Server Components, API routes, and middleware with cookie manipulation (set, get, getAll, delete), JSON response creation, URL redirects and rewrites, middleware routing with next() method, header forwarding patterns, security considerations for header handling, and Web Response API extensions.

./03-api-reference/04-functions/not-found.mdx NextJS notFound function for programmatically triggering 404 errors, rendering custom not-found UI components, injecting noindex meta tags, graceful error handling in route segments, Server Component integration with conditional logic for missing resources.

./03-api-reference/04-functions/permanentRedirect.mdx Server-side permanent redirects with 308 HTTP status code using permanentRedirect function in Server Components, Client Components, Route Handlers, and Server Actions, handling path parameters (relative/absolute URLs), redirect types (push/replace), streaming context behavior, error handling patterns, and TypeScript never type integration for terminating route segment rendering

./03-api-reference/04-functions/redirect.mdx Programmatic redirects using the redirect function in Server Components, Client Components, Route Handlers, and Server Actions with configurable redirect types (push/replace), HTTP status codes (307 temporary, 308 permanent), streaming context handling, absolute and relative URL support, error handling patterns, and integration with browser history stack management.

./03-api-reference/04-functions/revalidatePath.mdx On-demand cache invalidation for specific paths in Next.js applications using revalidatePath function, including parameters for path targeting (literal routes or dynamic segments), type specification (page/layout), usage in Server Functions vs Route Handlers, revalidation behavior differences, invalidation scope (pages, layouts, route handlers), relationship with revalidateTag for comprehensive cache management, and practical examples for specific URLs, dynamic routes, and data purging patterns.

./03-api-reference/04-functions/revalidateTag.mdx Cache invalidation on-demand using revalidateTag function for specific cache tags, Server Actions and Route Handlers usage, tag-based data revalidation patterns, relationship with revalidatePath, stale-while-revalidate behavior, tagged fetch requests, server-side cache management, on-demand incremental static regeneration (ISR)

./03-api-reference/04-functions/unauthorized.mdx Experimental authorization handling function that throws 401 errors and renders custom unauthorized pages, used in Server Components, Server Actions, and Route Handlers for authentication checks, with authInterrupts configuration requirement, custom unauthorized.js file support, session verification patterns, and examples for login UI display, Server Action mutations, and API endpoint protection.

./03-api-reference/04-functions/unstable_cache.mdx Caching expensive operations like database queries using unstable_cache function, cache key configuration with keyParts and function arguments, cache invalidation with tags and revalidate options, integrating with Next.js Data Cache for persistence across requests and deployments, handling dynamic data sources restrictions with headers/cookies

./03-api-reference/04-functions/unstable_noStore.mdx Legacy cache control function for opting out of static rendering and component caching, now superseded by connection() in v15, provides granular no-store behavior equivalent to fetch cache: 'no-store', used in Server Components for dynamic data fetching without caching

./03-api-reference/04-functions/unstable_rethrow.mdx Error handling utility for distinguishing between application errors and Next.js internal errors in try/catch blocks, specifically for rethrowning framework-controlled exceptions like notFound(), redirect(), permanentRedirect(), and dynamic API calls (cookies, headers, searchParams, no-store fetch) to ensure proper Next.js behavior when used within error handling code

./03-api-reference/04-functions/use-link-status.mdx Link navigation loading states with useLinkStatus hook for tracking pending navigation state, inline loading indicators, visual feedback during route transitions, prefetching integration, client-side navigation status, accessibility considerations with loading spinners, CSS animations and graceful fast navigation handling

./03-api-reference/04-functions/use-params.mdx Client Component hook for accessing dynamic route parameters from the current URL, supporting typed parameters, single and multiple segments, catch-all routes, and returning parameter names and values as strings or string arrays based on route structure

./03-api-reference/04-functions/use-pathname.mdx Client Component hook for accessing current URL pathname, returns pathname string without query parameters, used for route-based state management and responding to navigation changes, includes compatibility considerations for Server Components and automatic static optimization

./03-api-reference/04-functions/use-report-web-vitals.mdx Performance monitoring hook for reporting Core Web Vitals (TTFB, FCP, LCP, FID, CLS, INP) and custom Next.js metrics (hydration, route changes, render times), with callback function handling, analytics integration, and external system reporting using navigator.sendBeacon or fetch API

./03-api-reference/04-functions/use-router.mdx Programmatic navigation using useRouter hook for Client Components with methods like push(), replace(), back(), forward(), refresh(), and prefetch(), scroll control options, browser history management, route prefetching, migration from Pages Router, router events handling with usePathname and useSearchParams integration, security considerations for URL sanitization

./03-api-reference/04-functions/use-search-params.mdx Client Component hook for reading URL query string parameters, accessing URLSearchParams interface with get(), has(), getAll(), keys(), values() methods, Server vs Client Component usage patterns, static vs dynamic rendering behavior, Suspense boundary integration, updating search params with useRouter and Link

./03-api-reference/04-functions/use-selected-layout-segment.mdx Client Component hook for reading active route segment one level below current Layout, useful for navigation UI like tabs that change style based on active child segment, supports parallel routes with optional parallelRoutesKey parameter, returns segment string or null, includes examples for creating active link components and blog navigation with conditional styling

./03-api-reference/04-functions/use-selected-layout-segments.mdx Client Component hook for reading active route segments below the current Layout, useful for breadcrumbs and navigation UI, supports parallel routes with optional parallelRoutesKey parameter, returns array of segment strings, filters out route groups, works one level down from calling Layout

./03-api-reference/04-functions/userAgent.mdx User agent helper function for middleware with device detection (mobile, tablet, desktop), bot identification, browser information (name, version), device details (model, type, vendor), engine properties (name, version), operating system data, and CPU architecture detection for request handling and responsive routing

Configuration

./03-api-reference/05-config/02-typescript.mdx Built-in TypeScript support with automatic package installation and configuration, custom IDE plugin with type-checking and auto-completion, end-to-end type safety for data fetching without serialization, route-aware type helpers (PageProps, LayoutProps, RouteContext), statically typed links with href validation, environment variable IntelliSense, TypeScript configuration options (next.config.ts, custom tsconfig paths, build error handling), async Server Components typing, custom type declarations, and incremental type checking

./03-api-reference/05-config/03-eslint.mdx ESLint plugin configuration and setup for Next.js applications including eslint-plugin-next with 20+ specific rules for catching common issues, custom directory/file linting, monorepo support, cache management, rule customization, Core Web Vitals integration, TypeScript support, Prettier compatibility, lint-staged workflow, production build linting controls, and migration from existing ESLint configurations.

next.config.js Options

./03-api-reference/05-config/01-next-config-js/allowedDevOrigins.mdx Development server origin allowlist configuration for cross-origin requests in development mode, preventing unauthorized access to internal assets/endpoints, wildcard domain support for subdomains, future security defaults for production safety

./03-api-reference/05-config/01-next-config-js/appDir.mdx Legacy configuration option for enabling the App Router directory structure, layouts, Server Components, streaming, and React Strict Mode (deprecated as of Next.js 13.4 when App Router became stable)

./03-api-reference/05-config/01-next-config-js/assetPrefix.mdx CDN configuration with assetPrefix for hosting static assets (_next/static/) on custom domains, automatic URL prefixing for JS/CSS bundles, phase-based conditional configuration, limitations with public folder assets and SSR/SSG data requests, alternative basePath option for sub-path hosting

./03-api-reference/05-config/01-next-config-js/authInterrupts.mdx Experimental authentication interrupts configuration enabling forbidden and unauthorized APIs in Next.js applications, with configuration setup in next.config.js using the authInterrupts experimental flag, related authentication error handling functions and file conventions.

./03-api-reference/05-config/01-next-config-js/basePath.mdx NextJS basePath configuration for deploying applications under sub-paths of a domain, including path prefix setup, automatic link handling with next/link and next/router, image src path configuration with next/image component, build-time requirements and client bundle considerations

./03-api-reference/05-config/01-next-config-js/browserDebugInfoInTerminal.mdx Experimental Next.js configuration option for forwarding browser console logs and runtime errors to the development server terminal, including configuration for serialization limits (depthLimit, edgeLimit), source location display settings, object/array truncation controls, and development-only debugging capabilities.

./03-api-reference/05-config/01-next-config-js/cacheComponents.mdx Experimental Next.js cacheComponents configuration flag for optimizing dynamic data fetching in App Router, excluding data operations from pre-renders unless explicitly cached, used with use cache directive, cacheLife function, and cacheTag function for runtime data fetching control instead of pre-rendered cache serving

./03-api-reference/05-config/01-next-config-js/cacheLife.mdx Custom cache profiles configuration in Next.js using cacheLife with stale, revalidate, and expire settings, enabling cache components through experimental flags, defining cache durations and refresh frequencies, integration with use cache directive and cacheLife function for server-side caching strategies

./03-api-reference/05-config/01-next-config-js/compress.mdx Next.js compression configuration using gzip for rendered content and static files, enabling/disabling compression with the compress config option, compression behavior with custom servers, checking compression via HTTP headers (Accept-Encoding and Content-Encoding), and recommendations for server-level compression alternatives like nginx with brotli

./03-api-reference/05-config/01-next-config-js/crossOrigin.mdx Next.js crossOrigin configuration for adding crossOrigin attributes to script tags generated by next/script and next/head components, controlling cross-origin request handling with 'anonymous' or 'use-credentials' options

./03-api-reference/05-config/01-next-config-js/cssChunking.mdx CSS chunking configuration in Next.js using experimental.cssChunking option to control CSS file splitting and merging strategies - includes options for automatic merging (true), no merging (false), and strict import order preservation (strict) to optimize performance by loading only route-specific CSS while managing dependencies and request counts

./03-api-reference/05-config/01-next-config-js/devIndicators.mdx Development indicators configuration for displaying on-screen route context during development, including position options (bottom-right, bottom-left, top-right, top-left), disabling indicators, troubleshooting static vs dynamic route rendering with build output symbols, identifying Dynamic APIs and uncached data requests that prevent static rendering, streaming with loading.js and Suspense components

./03-api-reference/05-config/01-next-config-js/distDir.mdx Configuring custom build directory using distDir option in next.config.js, overriding default .next folder, build output location, directory naming restrictions, and build command behavior with custom paths

./03-api-reference/05-config/01-next-config-js/env.mdx Environment variable configuration in next.config.js using the env property to add custom variables to the JavaScript bundle, build-time replacement with process.env access, webpack DefinePlugin behavior preventing destructuring, and relationship to NEXT_PUBLIC_ prefixed variables from .env files.

./03-api-reference/05-config/01-next-config-js/eslint.mdx ESLint configuration in next.config.js including production build behavior with ESLint errors, ignoreDuringBuilds option to disable built-in linting step, integration with CI/pre-commit hooks, and recommended practices for handling ESLint errors during builds

./03-api-reference/05-config/01-next-config-js/expireTime.mdx Next.js configuration setting to customize the stale-while-revalidate cache expire time for ISR (Incremental Static Regeneration) pages, controlling CDN Cache-Control headers with specific revalidate periods and cache timing strategies

./03-api-reference/05-config/01-next-config-js/exportPathMap.mdx Legacy configuration for customizing HTML export paths with next export, deprecated in favor of getStaticPaths or generateStaticParams. Supports mapping request paths to page destinations, custom query parameters for dynamic content, trailing slash configuration, output directory customization, and integration with development mode routing.

./03-api-reference/05-config/01-next-config-js/generateBuildId.mdx Custom build ID configuration in Next.js using generateBuildId function, creating consistent build identifiers across environments and deployments, handling multi-container scenarios, using environment variables and git hashes for versioning

./03-api-reference/05-config/01-next-config-js/generateEtags.mdx ETag generation configuration for Next.js applications including how to disable automatic etag creation for HTML pages using the generateEtags option in next.config.js, with considerations for custom cache strategies

./03-api-reference/05-config/01-next-config-js/headers.mdx Custom HTTP headers configuration in Next.js using the headers function in next.config.js, including path matching (exact, wildcard, regex patterns), header override behavior, conditional header application based on request headers/cookies/query parameters/host values, basePath and i18n support, Cache-Control configuration, and common security headers (CORS, HSTS, CSP, X-Frame-Options, Permissions-Policy, X-Content-Type-Options, Referrer-Policy)

./03-api-reference/05-config/01-next-config-js/htmlLimitedBots.mdx Next.js configuration option for specifying user agents that receive blocking metadata instead of streaming metadata, with regex pattern matching, default bot lists, and override capabilities for controlling crawlers and bots behavior.

./03-api-reference/05-config/01-next-config-js/httpAgentOptions.mdx HTTP Keep-Alive configuration in Next.js server-side fetch calls, automatic polyfill behavior in Node.js versions prior to 18, disabling Keep-Alive using httpAgentOptions config, undici polyfill integration

./03-api-reference/05-config/01-next-config-js/images.mdx Image optimization configuration in next.config.js using custom loaders, custom loader file implementation for client components, loader prop configuration for individual image instances, and comprehensive examples for popular cloud providers (Akamai, AWS CloudFront, Cloudinary, Cloudflare, Contentful, Fastly, Gumlet, ImageEngine, Imgix, PixelBin, Sanity, Sirv, Supabase, Thumbor, ImageKit, Nitrogen AIO) with their specific transformation parameters for width, quality, and format optimization

./03-api-reference/05-config/01-next-config-js/incrementalCacheHandlerPath.mdx Custom Next.js cache handler configuration for external storage services like Redis and Memcached, including cache persistence, sharing across containers, in-memory cache disabling, API methods (get, set, revalidateTag, resetRequestCache), cache tag management, data revalidation patterns, deployment platform compatibility, and ISR configuration for self-hosted environments.

./03-api-reference/05-config/01-next-config-js/inlineCss.mdx Experimental configuration option for inlining CSS into HTML <style> tags instead of using external <link> tags, with performance trade-offs analysis covering first-time visitor improvements, FCP/LCP metrics, slow connection benefits, Tailwind CSS optimization, versus downsides like large bundle sizes, browser caching loss, and limitations including global application, style duplication, and production-only availability.

./03-api-reference/05-config/01-next-config-js/logging.mdx Next.js configuration logging options for development mode including fetch request logging with full URL display and HMR cache refresh settings, incoming request logging with ignore patterns and disable options, and complete logging disable functionality

./03-api-reference/05-config/01-next-config-js/mdxRs.mdx Experimental mdxRs configuration option for Next.js using Rust compiler to compile MDX files in App Router, with setup examples for next.config.js and @next/mdx integration

./03-api-reference/05-config/01-next-config-js/onDemandEntries.mdx On-demand entries configuration in next.config.js for controlling development server page memory management, including maxInactiveAge buffer period settings and pagesBufferLength for simultaneous page retention without disposal

./03-api-reference/05-config/01-next-config-js/optimizePackageImports.mdx Package import optimization configuration using experimental.optimizePackageImports to selectively load modules from large libraries, improving development and production performance, with built-in support for popular packages like Material-UI, Ant Design, Lodash, React Icons, Headless UI, and dozens of other commonly used libraries that export hundreds or thousands of modules.

./03-api-reference/05-config/01-next-config-js/output.mdx Output file tracing configuration for production deployment optimization including standalone mode, automatic dependency detection, file copying, monorepo support with outputFileTracingRoot, selective includes/excludes with outputFileTracingIncludes/outputFileTracingExcludes, minimal server.js generation, and static asset handling for reduced deployment size

./03-api-reference/05-config/01-next-config-js/pageExtensions.mdx Configuring file extensions that Next.js recognizes as pages in both App Router and Pages Router, extending default extensions (.tsx, .ts, .jsx, .js) to include markdown (.md, .mdx) and custom patterns, colocating non-page files using specific naming conventions like .page.tsx, and understanding how changes affect special files like middleware.js, instrumentation.js, _document.js, _app.js, and API routes

./03-api-reference/05-config/01-next-config-js/poweredByHeader.mdx Configuration option to disable the default 'x-powered-by' header that Next.js adds to HTTP responses, using the poweredByHeader setting in next.config.js

./03-api-reference/05-config/01-next-config-js/ppr.mdx Partial Prerendering (PPR) configuration enabling combination of static and dynamic components in the same route, incremental adoption with ppr: 'incremental' setting, opt-in per route using experimental_ppr config option, route segment inheritance for nested layouts and pages, selective enabling/disabling for child segments

./03-api-reference/05-config/01-next-config-js/productionBrowserSourceMaps.mdx Configuration flag for enabling browser source maps during production builds, preventing source code exposure by default, performance implications including increased build time and memory usage, automatic serving of generated source map files.

./03-api-reference/05-config/01-next-config-js/reactCompiler.mdx React Compiler configuration for automatic component rendering optimization, SWC-optimized compilation targeting JSX and React Hooks, installation setup with babel-plugin-react-compiler, next.config.js experimental configuration options, annotation-based opt-in compilation mode using "use memo" directive, performance improvements by reducing manual useMemo/useCallback usage

./03-api-reference/05-config/01-next-config-js/reactMaxHeadersLength.mdx Configuration option for controlling maximum React header length during static rendering in Next.js App Router, including header emission for performance optimization (preloading fonts, scripts, stylesheets), default values, truncation handling with reverse proxies, and configuration through next.config.js

./03-api-reference/05-config/01-next-config-js/reactStrictMode.mdx React Strict Mode configuration in next.config.js including enabling/disabling strict mode, default behavior differences between app router (enabled by default since 13.5.1) and pages router, development-only safety checks for unsafe lifecycles and legacy API usage, and incremental page-by-page migration strategies

./03-api-reference/05-config/01-next-config-js/redirects.mdx URL redirects configuration in next.config.js with source/destination patterns, permanent/temporary status codes (307/308), path matching with parameters and wildcards, regex patterns, header/cookie/query matching conditions, basePath and i18n internationalization support, custom status codes for legacy clients

./03-api-reference/05-config/01-next-config-js/rewrites.mdx URL rewriting configuration in next.config.js for mapping incoming request paths to different destinations, masking URLs as a proxy, supporting path matching patterns (wildcards, regex), parameter handling, conditional rewrites based on headers/cookies/queries, external URL rewrites, beforeFiles/afterFiles/fallback execution order, basePath and i18n internationalization support, incremental Next.js adoption patterns

./03-api-reference/05-config/01-next-config-js/sassOptions.mdx Sass compiler configuration in next.config.js using sassOptions, including additionalData for global variables, implementation selection (sass-embedded), and TypeScript/JavaScript configuration examples with available options for customizing Sass preprocessing

./03-api-reference/05-config/01-next-config-js/serverActions.mdx Server Actions configuration options in next.config.js including allowedOrigins for CSRF protection, bodySizeLimit for request size limits (default 1MB), and enabling Server Actions in Next.js v13 through experimental flag

./03-api-reference/05-config/01-next-config-js/serverComponentsHmrCache.mdx Experimental Next.js configuration option serverComponentsHmrCache for controlling fetch response caching in Server Components during Hot Module Replacement (HMR) in development, cache behavior across HMR refreshes vs navigation/reloads, performance benefits for API calls, disabling cache for fresh data during development, integration with logging.fetches for cache observability

./03-api-reference/05-config/01-next-config-js/serverExternalPackages.mdx Next.js configuration option to exclude specific dependencies from Server Components bundling, forcing them to use native Node.js require instead, with automatic bundling behavior, Node.js-specific feature compatibility, pre-configured list of popular packages (databases like Prisma/MongoDB, testing tools like Jest/Playwright, build tools like Webpack/TypeScript, cloud services like AWS SDK), and configuration syntax for custom package exclusions.

./03-api-reference/05-config/01-next-config-js/staleTimes.mdx Experimental NextJS config option staleTimes for client-side router cache invalidation timing, configuring static and dynamic page segment caching durations, link prefetching behavior, loading boundary reuse, and router cache optimization with custom revalidation periods

./03-api-reference/05-config/01-next-config-js/staticGeneration.mdx Static generation configuration for performance optimization in Next.js apps including retry count for failed page generation, maximum concurrency limits per worker, minimum pages per worker thresholds, and experimental build process tuning options

./03-api-reference/05-config/01-next-config-js/taint.mdx Experimental React API configuration for tainting objects and values to prevent sensitive data from accidentally being passed from server to client, including experimental_taintObjectReference for object references and experimental_taintUniqueValue for unique values, with examples of tainting user data objects and API keys, security caveats about object copying and derived values, defensive programming patterns for Server Components

./03-api-reference/05-config/01-next-config-js/trailingSlash.mdx Next.js configuration option to control URL trailing slash behavior - enables redirecting URLs without trailing slashes to their counterparts with trailing slashes (e.g., /about to /about/), with exceptions for static files and .well-known/ paths, affecting static export output structure

./03-api-reference/05-config/01-next-config-js/transpilePackages.mdx Configuration option for automatically transpiling and bundling dependencies from local monorepo packages or external node_modules dependencies, replacing the need for next-transpile-modules package, with setup examples and version history

./03-api-reference/05-config/01-next-config-js/turbopack.mdx Turbopack configuration options for Next.js including root directory setup, webpack loader rules for file transformations (SVG, SASS, YAML, GraphQL, etc.), module resolution aliases similar to webpack's resolve.alias, custom file extension resolution, supported loaders (babel-loader, @svgr/webpack, raw-loader, etc.), project structure detection via lock files, and migration guidance from webpack to Turbopack bundler.

./03-api-reference/05-config/01-next-config-js/turbopackPersistentCaching.mdx Turbopack Persistent Caching configuration for Next.js builds, enabling cache storage and restoration in .next folder to speed up subsequent dev and build commands, cache sharing between next dev and next build, experimental feature setup with stability warnings and version history

./03-api-reference/05-config/01-next-config-js/typedRoutes.mdx TypeScript configuration for statically typed links in Next.js applications, enabling compile-time route validation and type safety for navigation between pages using the typedRoutes option in next.config.js

./03-api-reference/05-config/01-next-config-js/typescript.mdx TypeScript configuration in next.config.js for controlling build behavior, disabling built-in type checking, using ignoreBuildErrors option, production build error handling, and dangerous build completion settings with type errors

./03-api-reference/05-config/01-next-config-js/urlImports.mdx Experimental URL imports configuration for importing modules from external servers, security model with domain allowlisting, lockfile management with next.lock directory, supported usage patterns including JavaScript modules, static assets, images, CSS resources, and asset imports via import.meta.url, with examples using Skypack CDN and static file hosting

./03-api-reference/05-config/01-next-config-js/useCache.mdx Experimental useCache flag configuration for Next.js applications, enabling use cache directive independently of cacheComponents, with cache functions including cacheLife and cacheTag for fine-grained caching control

./03-api-reference/05-config/01-next-config-js/useLightningcss.mdx Experimental Lightning CSS configuration for Next.js using useLightningcss flag, enabling fast CSS bundling and minification with Rust-based Lightning CSS, configuration syntax in next.config.js and next.config.ts files under experimental settings.

./03-api-reference/05-config/01-next-config-js/viewTransition.mdx Experimental View Transitions API configuration in next.config.js, enabling native browser view transitions between UI states in App Router, with ViewTransition component usage from React, production warnings, and integration with React's unstable ViewTransition API

./03-api-reference/05-config/01-next-config-js/webpack.mdx Custom webpack configuration in Next.js including function syntax, build parameters (buildId, dev, isServer, nextRuntime), default loaders (babel), distinguishing server vs client compilation, edge vs nodejs runtime targeting, adding custom webpack rules and plugins, with examples for MDX integration and bundle analysis

./03-api-reference/05-config/01-next-config-js/webVitalsAttribution.mdx Web Vitals attribution configuration for debugging performance issues by pinpointing source elements causing Cumulative Layout Shift (CLS), Largest Contentful Paint (LCP), and other core metrics, enabling detailed PerformanceEventTiming, PerformanceNavigationTiming, and PerformanceResourceTiming data collection through experimental Next.js config options.

CLI

./03-api-reference/06-cli/create-next-app.mdx create-next-app CLI for generating Next.js applications with default template or GitHub examples, featuring TypeScript/JavaScript initialization options, linter configuration (ESLint/Biome/None), Tailwind CSS setup, App Router support, Turbopack integration, custom import aliases, package manager selection (npm/pnpm/yarn/bun), project structure configuration (src directory), git initialization control, and interactive prompts for project customization

./03-api-reference/06-cli/next.mdx Next.js CLI commands for development, production builds, and deployment with dev server options (Hot Module Reloading, Turbopack, HTTPS configuration, port/hostname settings), build optimization and profiling features, production server startup, system diagnostics with info command, ESLint integration and linting workflows, telemetry collection controls, TypeScript type generation for routes and components, debugging tools for prerender errors, proxy timeout configuration, and Node.js runtime argument passing.