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:

function handleSubmit(e: any) { ... } const data: any[] = [];

✅ CORRECT:

function handleSubmit(e: React.FormEvent) { ... } const data: string[] = [];

Common Next.js Type Patterns // Page props function Page({ params }: { params: { slug: string } }) { ... } function Page({ searchParams }: { searchParams: { [key: string]: string | string[] | undefined } }) { ... }

// Form events const handleSubmit = (e: React.FormEvent) => { ... } const handleChange = (e: React.ChangeEvent) => { ... }

// Server actions async function myAction(formData: FormData) { ... }

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):

pages/ ├── index.tsx # Route: / ├── about.tsx # Route: /about ├── _app.tsx # Custom App component ├── _document.tsx # Custom Document component └── api/ # API routes └── hello.ts # API endpoint: /api/hello

App Router (Modern - Next.js 13+):

app/ ├── layout.tsx # Root layout (required) ├── page.tsx # Route: / ├── about/ # Route: /about │ └── page.tsx ├── blog/ │ ├── layout.tsx # Nested layout │ └── [slug]/ │ └── page.tsx # Dynamic route: /blog/:slug └── api/ # Route handlers └── hello/ └── route.ts # API endpoint: /api/hello

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, component) List all routes and dynamic segments Step 2: Create Root Layout

Create app/layout.tsx - REQUIRED for all App Router applications:

// app/layout.tsx export const metadata = { title: 'My App', description: 'App description', };

export default function RootLayout({ children, }: { children: React.ReactNode; }) { return ( {children} ); }

Migration Notes:

Move _document.tsx HTML structure to layout.tsx Move _app.tsx global providers/wrappers to layout.tsx Convert metadata to metadata export The root layout MUST include and tags Step 3: Migrate Pages to Routes

Simple Page Migration:

// Before: pages/index.tsx import Head from 'next/head';

export default function Home() { return ( <>

// After: app/page.tsx export default function Home() { return (

// Metadata moved to layout.tsx or exported here export const metadata = { title: 'Home Page', };

Nested Route Migration:

// Before: pages/blog/[slug].tsx export default function BlogPost() { ... }

// After: app/blog/[slug]/page.tsx export default function BlogPost() { ... }

Step 4: Update Navigation

Replace anchor tags with Next.js Link:

// Before (incorrect in App Router) About

// After (correct) import Link from 'next/link'; About

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 // app/page.tsx or app/layout.tsx import type { Metadata } from 'next';

export const metadata: Metadata = { title: 'My Page', description: 'Page description', keywords: ['nextjs', 'react'], openGraph: { title: 'My Page', description: 'Page description', images: ['/og-image.jpg'], }, };

Dynamic Metadata // app/blog/[slug]/page.tsx export async function generateMetadata({ params }: { params: { slug: string } }): Promise { const post = await getPost(params.slug);

return { title: post.title, description: post.excerpt, }; }

Layouts and Nesting Creating Nested Layouts // app/layout.tsx - Root layout export default function RootLayout({ children }) { return (