Guide for working with Next.js App Router (Next.js 13+). Use when migrating from Pages Router to App Router, creating layouts, implementing routing, handling metadata, or building Next.js 13+ applications. Activates for App Router migration, layout creation, routing patterns, or Next.js 13+ developm

Next.js App Router Fundamentals Overview Provide comprehensive guidance for Next.js App Router (Next.js 13+), covering migration from Pages Router, file based routing conventions, layouts, metadata handling, and modern Next.js patterns. TypeScript: NEVER Use any Type CRITICAL RULE: This codebase has @typescript eslint/no explicit any enabled. Using any will cause build failures. ❌ WRONG: ✅ CORRECT: Common Next.js Type Patterns When to Use This Skill Use this skill when: Migrating from Pages Router ( pages/ directory) to App Router ( app/ directory) Creating Next.js 13+ applications from scratch Working with layouts, templates, and nested routing Implementing metadata and SEO optimizations Building with App Router routing conventions Handling route groups, parallel routes, or intercepting routes basics Core Concepts App Router vs Pages Router Pages Router (Legacy Next.js 12 and earlier): App Router (Modern Next.js 13+): File Conventions Special Files in App Router: layout.tsx Shared UI for a segment and its children (preserves state, doesn't re render) page.tsx Unique UI for a route, makes route publicly accessible loading.tsx Loading UI with React Suspense error.tsx Error UI with Error Boundaries not found.tsx 404 UI template.tsx Similar to layout but re renders on navigation route.ts API endpoints (Route Handlers) Colocation: Components, tests, and other files can be colocated in app/ Only page.tsx and route.ts files create public routes Other files (components, utils, tests) are NOT routable Migration Guide: Pages Router to App Router Step 1: Understand the Current Structure Examine existing Pages Router setup: Read pages/ directory structure Identify app.tsx handles global state, layouts, providers Identify document.tsx customizes HTML structure Note metadata usage ( next/head , <Head component) List all routes and dynamic segments Step 2: Create Root Layout Create app/layout.tsx REQUIRED for all App Router applications: Migration Notes: Move document.tsx HTML structure to layout.tsx Move app.tsx global providers/wrappers to layout.tsx Convert <Head metadata to metadata export The root layout MUST include <html and <body tags Step 3: Migrate Pages to Routes Simple Page Migration: Nested Route Migration: Step 4: Update Navigation Replace anchor tags with Next.js Link: Step 5: Clean Up Pages Directory After migration: Remove all page files from pages/ directory Keep pages/api/ if you're not migrating API routes yet Remove app.tsx and document.tsx (functionality moved to layout) Optionally delete empty pages/ directory Metadata Handling Static Metadata Dynamic Metadata Layouts and Nesting Creating Nested Layouts Layout Behavior: Layouts preserve state across navigation Layouts don't re render on route changes Parent layouts wrap child layouts Root layout is required and wraps entire app Routing Patterns Dynamic Routes Catch All Routes Optional Catch All Route Groups Group routes without affecting URL: Common Migration Pitfalls Pitfall 1: Forgetting Root Layout HTML Tags Wrong: Correct: Pitfall 2: Using next/head in App Router Wrong: Correct: Pitfall 3: Not Removing Pages Directory After migrating routes, remove the old pages/ directory files to avoid confusion. The build will fail if you have conflicting routes. Pitfall 4: Missing page.tsx Files Routes are NOT accessible without a page.tsx file. Layouts alone don't create routes. Pitfall 5: Incorrect Link Usage Wrong: Correct: Server Components vs Client Components Default: Server Components All components in app/ are Server Components by default: Benefits: Can use async/await directly Direct database/API access Zero client side JavaScript Automatic code splitting Client Components Use 'use client' directive when you need: Interactive elements (onClick, onChange, etc.) React hooks (useState, useEffect, useContext, etc.) Browser APIs (window, localStorage, etc.) Event listeners Data Fetching Patterns Server Component Data Fetching Parallel Data Fetching Static Site Generation with generateStaticParams Overview generateStaticParams is the App Router equivalent of getStaticPaths from the Pages Router. It generates static pages at build time for dynamic routes. Basic Usage Key Points: Returns an array of objects with route parameter keys Each object represents one page to pre render at build time Function must be exported and named generateStaticParams Works ONLY in Server Components (no 'use client' directive) Replaces Pages Router's getStaticPaths Fetching Data for Static Params Multiple Dynamic Segments Dynamic Behavior Configuration Options: dynamicParams = true (default): Non pre rendered paths generated on demand dynamicParams = false : Non pre rendered paths return 404 Common Patterns Pattern 1: Simple ID based routes Pattern 2: Fetch from API Pattern 3: Database query Migration from Pages Router Before (Pages Router): After (App Router): Common Mistakes to Avoid ❌ Wrong: Using 'use client' ❌ Wrong: Using Pages Router pattern ❌ Wrong: Missing export keyword ✅ Correct: Clean Server Component CRITICAL IMPLEMENTATION NOTE: When asked to "write" or "implement" generateStaticParams : DO use the Edit or Write tool to modify the actual file DO add the function to the existing page.tsx file DO remove any TODO comments about generateStaticParams DON'T just output code in markdown actually implement it DON'T show code without writing it to the file Testing and Validation When migrating or building with App Router, verify: 1. Structure: app/ directory exists Root layout.tsx exists with <html and <body Each route has a page.tsx file 2. Metadata: No next/head imports in App Router Metadata exported from pages or layouts Metadata properly typed with Metadata type 3. Navigation: Using Link component from next/link Not using plain <a tags for internal navigation 4. Cleanup: No remaining page files in pages/ directory app.tsx and document.tsx removed Old metadata patterns removed Quick Reference File Structure Mapping Pages Router App Router Purpose pages/index.tsx app/page.tsx Home route pages/about.tsx app/about/page.tsx About route pages/[id].tsx app/[id]/page.tsx Dynamic route pages/ app.tsx app/layout.tsx Global layout pages/ document.tsx app/layout.tsx HTML structure pages/api/hello.ts app/api/hello/route.ts API route Common Commands Additional Resources For more advanced routing patterns (parallel routes, intercepting routes, route handlers), refer to the nextjs advanced routing skill. For Server vs Client component best practices and anti patterns, refer to the nextjs server client components and nextjs anti patterns skills.

nextjs-app-router-fundamentals