/app-router

Overview

The App Router is Next.js's file-system based router built on React Server Components. It uses a app/ directory structure where folders define routes and special files control UI behavior.

Core File Conventions

Route Files

Each route segment is defined by a folder. Special files within folders control behavior:

File	Purpose
page.tsx	Unique UI for a route, makes route publicly accessible
layout.tsx	Shared UI wrapper, preserves state across navigations
loading.tsx	Loading UI using React Suspense
error.tsx	Error boundary for route segment
not-found.tsx	UI for 404 responses
template.tsx	Like layout but re-renders on navigation
default.tsx	Fallback for parallel routes

Folder Conventions

Pattern	Purpose	Example
folder/	Route segment	app/blog/ → /blog
[folder]/	Dynamic segment	app/blog/[slug]/ → /blog/:slug
[...folder]/	Catch-all segment	app/docs/[...slug]/ → /docs/*
[[...folder]]/	Optional catch-all	app/shop/[[...slug]]/ → /shop or /shop/*
(folder)/	Route group (no URL)	app/(marketing)/about/ → /about
@folder/	Named slot (parallel routes)	app/@modal/login/
_folder/	Private folder (excluded)	app/_components/

Creating Routes

Basic Route Structure

To create a new route, add a folder with page.tsx:

app/
├── page.tsx              # / (home)
├── about/
│   └── page.tsx          # /about
└── blog/
    ├── page.tsx          # /blog
    └── [slug]/
        └── page.tsx      # /blog/:slug

Page Component

A page is a Server Component by default:

// app/about/page.tsx
export default function AboutPage() {
  return (
    <main>
      <h1>About Us</h1>
      <p>Welcome to our company.</p>
    </main>
  )
}

Dynamic Routes

Access route parameters via the params prop:

// app/blog/[slug]/page.tsx
interface PageProps {
  params: Promise<{ slug: string }>
}

export default async function BlogPost({ params }: PageProps) {
  const { slug } = await params
  const post = await getPost(slug)

  return <article>{post.content}</article>
}

Layouts

Root Layout (Required)

Every app needs a root layout with <html> and <body>:

// app/layout.tsx
export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  )
}

Nested Layouts

Layouts wrap their children and preserve state:

// app/dashboard/layout.tsx
export default function DashboardLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <div className="flex">
      <Sidebar />
      <main className="flex-1">{children}</main>
    </div>
  )
}

Loading and Error States

Loading UI

Create instant loading states with Suspense:

// app/dashboard/loading.tsx
export default function Loading() {
  return <div className="animate-pulse">Loading...</div>
}

Error Boundaries

Handle errors gracefully:

// app/dashboard/error.tsx
'use client'

export default function Error({
  error,
  reset,
}: {
  error: Error
  reset: () => void
}) {
  return (
    <div>
      <h2>Something went wrong!</h2>
      <button onClick={reset}>Try again</button>
    </div>
  )
}

Route Groups

Organize routes without affecting URL structure:

app/
├── (marketing)/
│   ├── layout.tsx        # Marketing layout
│   ├── about/page.tsx    # /about
│   └── contact/page.tsx  # /contact
└── (shop)/
    ├── layout.tsx        # Shop layout
    └── products/page.tsx # /products

Metadata

Static Metadata

// app/about/page.tsx
import { Metadata } from 'next'

export const metadata: Metadata = {
  title: 'About Us',
  description: 'Learn more about our company',
}

Dynamic Metadata

// app/blog/[slug]/page.tsx
export async function generateMetadata({ params }: PageProps): Promise<Metadata> {
  const { slug } = await params
  const post = await getPost(slug)
  return { title: post.title }
}

Key Patterns

1. Colocation: Keep components, tests, and styles near routes
2. Private folders: Use _folder for non-route files
3. Route groups: Use (folder) to organize without URL impact
4. Parallel routes: Use @slot for complex layouts
5. Intercepting routes: Use (.) patterns for modals

Resources

For detailed patterns, see:

• references/routing-conventions.md - Complete file conventions
• references/layouts-templates.md - Layout composition patterns
• references/loading-error-states.md - Suspense and error handling
• examples/dynamic-routes.md - Dynamic routing examples
• examples/parallel-routes.md - Parallel and intercepting routes