App Router

Name: App Router
Author: davepoon

davepoon/buildwithclaude

133 installs
3.2k repo stars
Updated August 2, 2026
davepoon/buildwithclaude

Implement Next.js App Router layouts, nested routes, server components, loading states, and data-fetching patterns for modern React apps.

About

Provides Next.js App Router guidance for Claude-assisted builds: file-based routing, layout.tsx conventions, server versus client components, streaming and suspense, metadata, and recommended patterns for SaaS and content sites on Next 13+.

Next.js App Router
Server and client components
Nested layouts and routes
Loading and error boundaries
Modern React data fetching

App Router by the numbers

133 all-time installs (skills.sh)
Ranked #977 of 2,244 Frontend Development skills by installs in the Skillselion catalog
Data as of Aug 3, 2026 (Skillselion catalog sync)

npx skills add https://github.com/davepoon/buildwithclaude --skill app-router

Add your badge

Show developers this skill is listed on Skillselion. Paste this into your README.

[![Listed on Skillselion](https://skillselion.com/badge/skills/davepoon/buildwithclaude/app-router.svg)](https://skillselion.com/skills/davepoon/buildwithclaude/app-router)

Installs	133
repo stars	★ 3.2k
Last updated	August 2, 2026
Repository	davepoon/buildwithclaude ↗

What it does

Implement Next.js App Router layouts, nested routes, server components, loading states, and data-fetching patterns for modern React apps.

Files

SKILL.mdMarkdownGitHub ↗

Next.js App Router Patterns

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

Dynamic Routes Examples

Single Dynamic Segment

Basic Dynamic Route

app/
└── blog/
    └── [slug]/
        └── page.tsx

// 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 fetch(`https://api.example.com/posts/${slug}`)
    .then(res => res.json())

  return (
    <article>
      <h1>{post.title}</h1>
      <div>{post.content}</div>
    </article>
  )
}

// Generate static pages at build time
export async function generateStaticParams() {
  const posts = await fetch('https://api.example.com/posts')
    .then(res => res.json())

  return posts.map((post) => ({
    slug: post.slug,
  }))
}

Multiple Dynamic Segments

app/
└── shop/
    └── [category]/
        └── [productId]/
            └── page.tsx

// app/shop/[category]/[productId]/page.tsx
interface PageProps {
  params: Promise<{
    category: string
    productId: string
  }>
}

export default async function ProductPage({ params }: PageProps) {
  const { category, productId } = await params

  return (
    <div>
      <nav>Category: {category}</nav>
      <h1>Product: {productId}</h1>
    </div>
  )
}

export async function generateStaticParams() {
  const products = await getProducts()

  return products.map((product) => ({
    category: product.category,
    productId: product.id,
  }))
}

Catch-All Segments

Basic Catch-All

app/
└── docs/
    └── [...slug]/
        └── page.tsx

Matches: /docs/a, /docs/a/b, /docs/a/b/c

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

export default async function DocsPage({ params }: PageProps) {
  const { slug } = await params
  // slug = ['a', 'b', 'c'] for /docs/a/b/c

  const path = slug.join('/')
  const doc = await getDoc(path)

  return (
    <div>
      <nav>
        {slug.map((segment, index) => (
          <span key={index}>
            {index > 0 && ' / '}
            {segment}
          </span>
        ))}
      </nav>
      <article>{doc.content}</article>
    </div>
  )
}

Optional Catch-All

app/
└── shop/
    └── [[...slug]]/
        └── page.tsx

Matches: /shop, /shop/category, /shop/category/product

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

export default async function ShopPage({ params }: PageProps) {
  const { slug } = await params

  // /shop -> slug is undefined
  // /shop/electronics -> slug = ['electronics']
  // /shop/electronics/phones -> slug = ['electronics', 'phones']

  if (!slug) {
    return <AllProducts />
  }

  if (slug.length === 1) {
    return <CategoryPage category={slug[0]} />
  }

  return <ProductPage category={slug[0]} product={slug[1]} />
}

Dynamic Metadata

Based on Route Params

// app/blog/[slug]/page.tsx
import { Metadata } from 'next'

interface PageProps {
  params: Promise<{ slug: string }>
}

export async function generateMetadata({
  params,
}: PageProps): Promise<Metadata> {
  const { slug } = await params
  const post = await getPost(slug)

  return {
    title: post.title,
    description: post.excerpt,
    openGraph: {
      title: post.title,
      description: post.excerpt,
      images: [post.coverImage],
    },
  }
}

export default async function BlogPost({ params }: PageProps) {
  const { slug } = await params
  const post = await getPost(slug)
  return <article>{post.content}</article>
}

Search Params

Accessing Query Params

// app/search/page.tsx
interface PageProps {
  searchParams: Promise<{ q?: string; page?: string }>
}

export default async function SearchPage({ searchParams }: PageProps) {
  const { q, page } = await searchParams
  const currentPage = parseInt(page || '1')

  const results = await search(q, currentPage)

  return (
    <div>
      <h1>Search results for: {q}</h1>
      <ul>
        {results.map(result => (
          <li key={result.id}>{result.title}</li>
        ))}
      </ul>
      <Pagination current={currentPage} />
    </div>
  )
}

Combined with Dynamic Segments

// app/products/[category]/page.tsx
interface PageProps {
  params: Promise<{ category: string }>
  searchParams: Promise<{ sort?: string; filter?: string }>
}

export default async function CategoryPage({
  params,
  searchParams,
}: PageProps) {
  const { category } = await params
  const { sort, filter } = await searchParams

  const products = await getProducts({
    category,
    sort: sort || 'newest',
    filter,
  })

  return (
    <div>
      <h1>{category}</h1>
      <ProductGrid products={products} />
    </div>
  )
}

Static Generation Patterns

Generate All Pages

// app/blog/[slug]/page.tsx
export async function generateStaticParams() {
  const posts = await getAllPosts()

  return posts.map((post) => ({
    slug: post.slug,
  }))
}

Generate on Demand (ISR)

// app/blog/[slug]/page.tsx
export const dynamicParams = true // Allow dynamic params not in generateStaticParams

export async function generateStaticParams() {
  // Only pre-render popular posts
  const popularPosts = await getPopularPosts(10)

  return popularPosts.map((post) => ({
    slug: post.slug,
  }))
}

Block Unknown Params

// app/blog/[slug]/page.tsx
export const dynamicParams = false // Return 404 for unknown slugs

export async function generateStaticParams() {
  const posts = await getAllPosts()
  return posts.map((post) => ({ slug: post.slug }))
}

Real-World Example: E-commerce

app/
└── shop/
    ├── page.tsx                           # /shop
    ├── [category]/
    │   ├── page.tsx                       # /shop/electronics
    │   └── [productId]/
    │       ├── page.tsx                   # /shop/electronics/123
    │       └── reviews/
    │           └── page.tsx               # /shop/electronics/123/reviews
    └── cart/
        └── page.tsx                       # /shop/cart

// app/shop/[category]/[productId]/page.tsx
interface PageProps {
  params: Promise<{
    category: string
    productId: string
  }>
}

export async function generateMetadata({ params }: PageProps): Promise<Metadata> {
  const { category, productId } = await params
  const product = await getProduct(productId)

  return {
    title: `${product.name} | ${category}`,
    description: product.description,
  }
}

export default async function ProductPage({ params }: PageProps) {
  const { category, productId } = await params
  const product = await getProduct(productId)

  return (
    <div>
      <Breadcrumbs category={category} product={product.name} />
      <ProductDetails product={product} />
      <RelatedProducts category={category} />
    </div>
  )
}

export async function generateStaticParams() {
  const products = await getAllProducts()

  return products.map((product) => ({
    category: product.category,
    productId: product.id,
  }))
}

Parallel Routes and Intercepting Routes

Parallel Routes Basics

Parallel routes allow rendering multiple pages in the same layout simultaneously using named slots.

Slot Convention

Slots are defined with @folder naming:

app/
├── @dashboard/
│   └── page.tsx
├── @analytics/
│   └── page.tsx
├── layout.tsx
└── page.tsx

Layout with Slots

// app/layout.tsx
export default function Layout({
  children,
  dashboard,
  analytics,
}: {
  children: React.ReactNode
  dashboard: React.ReactNode
  analytics: React.ReactNode
}) {
  return (
    <div className="grid grid-cols-3 gap-4">
      <main className="col-span-2">{children}</main>
      <aside className="space-y-4">
        {dashboard}
        {analytics}
      </aside>
    </div>
  )
}

Dashboard Layout Example

app/
├── @team/
│   ├── page.tsx
│   └── loading.tsx
├── @notifications/
│   ├── page.tsx
│   └── loading.tsx
├── @metrics/
│   └── page.tsx
├── layout.tsx
└── page.tsx

// app/layout.tsx
export default function DashboardLayout({
  children,
  team,
  notifications,
  metrics,
}: {
  children: React.ReactNode
  team: React.ReactNode
  notifications: React.ReactNode
  metrics: React.ReactNode
}) {
  return (
    <div className="min-h-screen">
      <header className="h-16 border-b">
        <h1>Dashboard</h1>
      </header>

      <div className="grid grid-cols-4 gap-4 p-4">
        <main className="col-span-3">{children}</main>
        <aside className="space-y-4">
          {team}
          {notifications}
          {metrics}
        </aside>
      </div>
    </div>
  )
}

// app/@team/page.tsx
export default async function TeamSlot() {
  const team = await getTeamMembers()
  return (
    <div className="bg-white p-4 rounded shadow">
      <h2>Team</h2>
      <ul>
        {team.map(member => (
          <li key={member.id}>{member.name}</li>
        ))}
      </ul>
    </div>
  )
}

Default Fallback

When navigating to a route without a matching slot, use default.tsx:

// app/@notifications/default.tsx
export default function NotificationsDefault() {
  return null // or a placeholder
}

Conditional Slots

// app/layout.tsx
import { auth } from '@/auth'

export default async function Layout({
  children,
  admin,
  user,
}: {
  children: React.ReactNode
  admin: React.ReactNode
  user: React.ReactNode
}) {
  const session = await auth()

  return (
    <div>
      {session?.user?.role === 'admin' ? admin : user}
      {children}
    </div>
  )
}

Intercepting Routes

Intercept a route to show it in the current layout (e.g., modals).

Convention

Pattern	Intercepts
`(.)folder`	Same level
`(..)folder`	One level up
`(..)(..)folder`	Two levels up
`(...)folder`	From root

Modal Example

app/
├── @modal/
│   ├── (.)photo/
│   │   └── [id]/
│   │       └── page.tsx    # Intercepted route (modal)
│   └── default.tsx
├── photo/
│   └── [id]/
│       └── page.tsx        # Full page route
├── layout.tsx
└── page.tsx

// app/layout.tsx
export default function Layout({
  children,
  modal,
}: {
  children: React.ReactNode
  modal: React.ReactNode
}) {
  return (
    <>
      {children}
      {modal}
    </>
  )
}

// app/@modal/default.tsx
export default function Default() {
  return null
}

// app/@modal/(.)photo/[id]/page.tsx (Modal version)
import { Modal } from '@/components/modal'

export default async function PhotoModal({
  params,
}: {
  params: Promise<{ id: string }>
}) {
  const { id } = await params
  const photo = await getPhoto(id)

  return (
    <Modal>
      <img src={photo.url} alt={photo.title} />
    </Modal>
  )
}

// app/photo/[id]/page.tsx (Full page version)
export default async function PhotoPage({
  params,
}: {
  params: Promise<{ id: string }>
}) {
  const { id } = await params
  const photo = await getPhoto(id)

  return (
    <div className="container mx-auto">
      <img src={photo.url} alt={photo.title} />
      <h1>{photo.title}</h1>
    </div>
  )
}

Modal Component

// components/modal.tsx
'use client'

import { useRouter } from 'next/navigation'
import { useCallback, useEffect } from 'react'

export function Modal({ children }: { children: React.ReactNode }) {
  const router = useRouter()

  const onDismiss = useCallback(() => {
    router.back()
  }, [router])

  const onKeyDown = useCallback(
    (e: KeyboardEvent) => {
      if (e.key === 'Escape') onDismiss()
    },
    [onDismiss]
  )

  useEffect(() => {
    document.addEventListener('keydown', onKeyDown)
    return () => document.removeEventListener('keydown', onKeyDown)
  }, [onKeyDown])

  return (
    <div
      className="fixed inset-0 bg-black/50 flex items-center justify-center"
      onClick={onDismiss}
    >
      <div
        className="bg-white rounded-lg p-6 max-w-2xl w-full mx-4"
        onClick={(e) => e.stopPropagation()}
      >
        {children}
        <button
          onClick={onDismiss}
          className="absolute top-4 right-4"
        >
          Close
        </button>
      </div>
    </div>
  )
}

Gallery with Modal

// app/page.tsx (Gallery)
import Link from 'next/link'

export default async function GalleryPage() {
  const photos = await getPhotos()

  return (
    <div className="grid grid-cols-4 gap-4">
      {photos.map((photo) => (
        <Link key={photo.id} href={`/photo/${photo.id}`}>
          <img
            src={photo.thumbnail}
            alt={photo.title}
            className="rounded cursor-pointer hover:opacity-80"
          />
        </Link>
      ))}
    </div>
  )
}

Login Modal Pattern

app/
├── @auth/
│   ├── (.)login/
│   │   └── page.tsx        # Login modal
│   └── default.tsx
├── login/
│   └── page.tsx            # Full login page
└── layout.tsx

// app/@auth/(.)login/page.tsx
import { Modal } from '@/components/modal'
import { LoginForm } from '@/components/login-form'

export default function LoginModal() {
  return (
    <Modal>
      <h1 className="text-2xl font-bold mb-4">Sign In</h1>
      <LoginForm />
    </Modal>
  )
}

// app/login/page.tsx
import { LoginForm } from '@/components/login-form'

export default function LoginPage() {
  return (
    <div className="min-h-screen flex items-center justify-center">
      <div className="w-full max-w-md">
        <h1 className="text-2xl font-bold mb-4">Sign In</h1>
        <LoginForm />
      </div>
    </div>
  )
}

Tab Navigation with Parallel Routes

app/dashboard/
├── @tabs/
│   ├── overview/
│   │   └── page.tsx
│   ├── analytics/
│   │   └── page.tsx
│   └── settings/
│       └── page.tsx
├── layout.tsx
└── page.tsx

// app/dashboard/layout.tsx
import Link from 'next/link'

export default function DashboardLayout({
  children,
  tabs,
}: {
  children: React.ReactNode
  tabs: React.ReactNode
}) {
  return (
    <div>
      <nav className="flex gap-4 border-b pb-4">
        <Link href="/dashboard/overview">Overview</Link>
        <Link href="/dashboard/analytics">Analytics</Link>
        <Link href="/dashboard/settings">Settings</Link>
      </nav>
      <div className="mt-4">
        {tabs}
      </div>
    </div>
  )
}

Next.js Layouts and Templates

Root Layout

Every Next.js app requires a root layout at app/layout.tsx:

// app/layout.tsx
import { Inter } from 'next/font/google'
import './globals.css'

const inter = Inter({ subsets: ['latin'] })

export const metadata = {
  title: 'My App',
  description: 'Description of my app',
}

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

Requirements:

Must define <html> and <body> tags
Must accept and render children
Server Component (cannot use 'use client')

Nested Layouts

Create layouts for route segments:

app/
├── layout.tsx              # Root layout
├── page.tsx                # Home page
└── dashboard/
    ├── layout.tsx          # Dashboard layout
    ├── page.tsx            # /dashboard
    └── settings/
        ├── layout.tsx      # Settings layout
        └── page.tsx        # /dashboard/settings

// app/dashboard/layout.tsx
export default function DashboardLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <div className="flex">
      <aside className="w-64 bg-gray-100 p-4">
        <DashboardNav />
      </aside>
      <main className="flex-1 p-6">{children}</main>
    </div>
  )
}

Layout Composition

Layouts nest automatically:

Root Layout
└── Dashboard Layout
    └── Settings Layout
        └── Page

The final output:

<RootLayout>
  <DashboardLayout>
    <SettingsLayout>
      <SettingsPage />
    </SettingsLayout>
  </DashboardLayout>
</RootLayout>

Sharing UI Across Routes

Common Header/Footer

// app/layout.tsx
import { Header } from '@/components/header'
import { Footer } from '@/components/footer'

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

Conditional Layouts with Route Groups

app/
├── (with-header)/
│   ├── layout.tsx          # Layout with header
│   ├── about/page.tsx
│   └── contact/page.tsx
└── (no-header)/
    ├── layout.tsx          # Layout without header
    └── login/page.tsx

Templates vs Layouts

Layout Behavior

Persists across navigations
Maintains state
Does not re-render

Template Behavior

Creates new instance on navigation
Re-renders on every navigation
State is reset

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

import { useEffect } from 'react'

export default function Template({ children }: { children: React.ReactNode }) {
  useEffect(() => {
    // Runs on every navigation
    console.log('Template mounted')
    return () => console.log('Template unmounted')
  }, [])

  return <div>{children}</div>
}

When to Use Templates

1. Page transitions/animations:

// app/template.tsx
'use client'

import { motion } from 'framer-motion'

export default function Template({ children }: { children: React.ReactNode }) {
  return (
    <motion.div
      initial={{ opacity: 0, y: 20 }}
      animate={{ opacity: 1, y: 0 }}
      exit={{ opacity: 0, y: -20 }}
    >
      {children}
    </motion.div>
  )
}

2. Analytics on route change:

'use client'

import { useEffect } from 'react'
import { usePathname } from 'next/navigation'

export default function Template({ children }) {
  const pathname = usePathname()

  useEffect(() => {
    trackPageView(pathname)
  }, [pathname])

  return <>{children}</>
}

Layout Data Fetching

Layouts can fetch data:

// app/dashboard/layout.tsx
import { getUser } from '@/lib/auth'

export default async function DashboardLayout({
  children,
}: {
  children: React.ReactNode
}) {
  const user = await getUser()

  return (
    <div>
      <header>
        <span>Welcome, {user.name}</span>
      </header>
      {children}
    </div>
  )
}

Note: You cannot pass data from layout to page via props. Use:

Shared fetch with cache()
React Context
Parallel data fetching

Shared Fetching Pattern

// lib/get-user.ts
import { cache } from 'react'

export const getUser = cache(async () => {
  const response = await fetch('/api/user')
  return response.json()
})

// app/dashboard/layout.tsx
import { getUser } from '@/lib/get-user'

export default async function Layout({ children }) {
  const user = await getUser() // Cached
  return <div><UserNav user={user} />{children}</div>
}

// app/dashboard/page.tsx
import { getUser } from '@/lib/get-user'

export default async function Page() {
  const user = await getUser() // Returns cached result
  return <h1>Hello {user.name}</h1>
}

Multiple Root Layouts

Use route groups for different root layouts:

app/
├── (marketing)/
│   ├── layout.tsx          # Marketing root layout
│   ├── page.tsx            # / (home)
│   └── about/page.tsx      # /about
└── (app)/
    ├── layout.tsx          # App root layout
    └── dashboard/page.tsx  # /dashboard

// app/(marketing)/layout.tsx
export default function MarketingLayout({ children }) {
  return (
    <html lang="en">
      <body className="marketing-theme">{children}</body>
    </html>
  )
}

// app/(app)/layout.tsx
export default function AppLayout({ children }) {
  return (
    <html lang="en">
      <body className="app-theme">{children}</body>
    </html>
  )
}

Layout Metadata

// app/dashboard/layout.tsx
import { Metadata } from 'next'

export const metadata: Metadata = {
  title: {
    template: '%s | Dashboard',
    default: 'Dashboard',
  },
}

// app/dashboard/settings/page.tsx
export const metadata = {
  title: 'Settings', // Results in: "Settings | Dashboard"
}

Loading and Error States in Next.js

Loading UI with loading.tsx

Basic Loading State

// app/dashboard/loading.tsx
export default function Loading() {
  return <div>Loading...</div>
}

Skeleton Loading

// app/dashboard/loading.tsx
export default function Loading() {
  return (
    <div className="animate-pulse">
      <div className="h-8 bg-gray-200 rounded w-1/4 mb-4" />
      <div className="space-y-3">
        <div className="h-4 bg-gray-200 rounded w-full" />
        <div className="h-4 bg-gray-200 rounded w-5/6" />
        <div className="h-4 bg-gray-200 rounded w-4/6" />
      </div>
    </div>
  )
}

How loading.tsx Works

Next.js automatically wraps page.tsx in a Suspense boundary:

// What Next.js creates internally
<Suspense fallback={<Loading />}>
  <Page />
</Suspense>

Manual Suspense Boundaries

Streaming Components

// app/dashboard/page.tsx
import { Suspense } from 'react'
import { SlowComponent } from './slow-component'
import { FastComponent } from './fast-component'

export default function DashboardPage() {
  return (
    <div>
      <FastComponent /> {/* Renders immediately */}

      <Suspense fallback={<p>Loading analytics...</p>}>
        <SlowAnalytics /> {/* Streams when ready */}
      </Suspense>

      <Suspense fallback={<p>Loading feed...</p>}>
        <SlowFeed /> {/* Streams when ready */}
      </Suspense>
    </div>
  )
}

Nested Suspense

export default function Page() {
  return (
    <Suspense fallback={<PageSkeleton />}>
      <Header />
      <main>
        <Suspense fallback={<SidebarSkeleton />}>
          <Sidebar />
        </Suspense>
        <Suspense fallback={<ContentSkeleton />}>
          <Content />
        </Suspense>
      </main>
    </Suspense>
  )
}

Error Handling with error.tsx

Basic Error Boundary

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

export default function Error({
  error,
  reset,
}: {
  error: Error & { digest?: string }
  reset: () => void
}) {
  return (
    <div className="p-4 bg-red-50 border border-red-200 rounded">
      <h2 className="text-red-800 font-bold">Something went wrong!</h2>
      <p className="text-red-600">{error.message}</p>
      <button
        onClick={() => reset()}
        className="mt-2 px-4 py-2 bg-red-600 text-white rounded"
      >
        Try again
      </button>
    </div>
  )
}

Error Boundary Scope

Error boundaries catch errors in:

Child components
The page.tsx in the same segment
Nested routes

app/
├── layout.tsx          # ❌ Errors here not caught
├── error.tsx           # ✅ Catches errors below
├── page.tsx            # ✅ Errors caught by error.tsx
└── dashboard/
    ├── layout.tsx      # ✅ Errors caught by parent error.tsx
    ├── error.tsx       # ✅ Catches dashboard errors
    └── page.tsx        # ✅ Errors caught by dashboard/error.tsx

Global Error Handler

For errors in root layout:

// app/global-error.tsx
'use client'

export default function GlobalError({
  error,
  reset,
}: {
  error: Error & { digest?: string }
  reset: () => void
}) {
  return (
    <html>
      <body>
        <h2>Something went wrong!</h2>
        <button onClick={() => reset()}>Try again</button>
      </body>
    </html>
  )
}

Error Logging

// app/error.tsx
'use client'

import { useEffect } from 'react'

export default function Error({
  error,
  reset,
}: {
  error: Error & { digest?: string }
  reset: () => void
}) {
  useEffect(() => {
    // Log to error reporting service
    console.error(error)
    reportError(error)
  }, [error])

  return (
    <div>
      <h2>Something went wrong!</h2>
      <button onClick={() => reset()}>Try again</button>
    </div>
  )
}

Not Found Handling

not-found.tsx

// app/not-found.tsx
import Link from 'next/link'

export default function NotFound() {
  return (
    <div className="flex flex-col items-center justify-center min-h-screen">
      <h2 className="text-2xl font-bold">404 - Page Not Found</h2>
      <p className="text-gray-600 mt-2">
        The page you're looking for doesn't exist.
      </p>
      <Link
        href="/"
        className="mt-4 px-4 py-2 bg-blue-600 text-white rounded"
      >
        Return Home
      </Link>
    </div>
  )
}

Triggering Not Found

// app/posts/[slug]/page.tsx
import { notFound } from 'next/navigation'

export default async function PostPage({
  params,
}: {
  params: Promise<{ slug: string }>
}) {
  const { slug } = await params
  const post = await getPost(slug)

  if (!post) {
    notFound() // Renders not-found.tsx
  }

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

Nested Not Found

// app/dashboard/not-found.tsx
export default function DashboardNotFound() {
  return (
    <div>
      <h2>Dashboard resource not found</h2>
      <p>The requested dashboard item doesn't exist.</p>
    </div>
  )
}

Combined Patterns

Loading + Error + Not Found

app/dashboard/
├── layout.tsx
├── loading.tsx       # Shows while page loads
├── error.tsx         # Shows on errors
├── not-found.tsx     # Shows for 404s
└── page.tsx

Progressive Loading

// app/dashboard/page.tsx
import { Suspense } from 'react'

export default function DashboardPage() {
  return (
    <div>
      {/* Critical content loads first */}
      <h1>Dashboard</h1>

      {/* Stats stream in */}
      <Suspense fallback={<StatsSkeleton />}>
        <Stats />
      </Suspense>

      {/* Chart streams separately */}
      <Suspense fallback={<ChartSkeleton />}>
        <Chart />
      </Suspense>

      {/* Recent activity last */}
      <Suspense fallback={<ActivitySkeleton />}>
        <RecentActivity />
      </Suspense>
    </div>
  )
}

Error Recovery with State

// app/error.tsx
'use client'

import { useState } from 'react'

export default function Error({
  error,
  reset,
}: {
  error: Error
  reset: () => void
}) {
  const [isRetrying, setIsRetrying] = useState(false)

  const handleRetry = async () => {
    setIsRetrying(true)
    // Optional: wait before retry
    await new Promise(resolve => setTimeout(resolve, 1000))
    reset()
  }

  return (
    <div>
      <h2>Error: {error.message}</h2>
      <button onClick={handleRetry} disabled={isRetrying}>
        {isRetrying ? 'Retrying...' : 'Try again'}
      </button>
    </div>
  )
}

Next.js App Router File Conventions

Route Segment Files

page.tsx

The page.tsx file makes a route segment publicly accessible:

// app/dashboard/page.tsx
export default function DashboardPage() {
  return <h1>Dashboard</h1>
}

Rules:

Required to make a route accessible
Must export a default React component
Server Component by default
Can be async for data fetching

layout.tsx

Shared UI that wraps page and nested layouts:

// app/dashboard/layout.tsx
export default function DashboardLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <div>
      <nav>Dashboard Nav</nav>
      <main>{children}</main>
    </div>
  )
}

Rules:

Must accept a children prop
Preserves state across navigations
Does not re-render when navigating between child routes
Root layout is required and must include <html> and <body>

loading.tsx

Instant loading UI using React Suspense:

// app/dashboard/loading.tsx
export default function Loading() {
  return (
    <div className="flex items-center justify-center min-h-screen">
      <div className="animate-spin rounded-full h-8 w-8 border-b-2 border-gray-900" />
    </div>
  )
}

Rules:

Automatically wraps page in Suspense boundary
Shows while page content is loading
Nested loading states are supported

error.tsx

Error boundary for route segment:

// app/dashboard/error.tsx
'use client' // Must be a Client Component

export default function Error({
  error,
  reset,
}: {
  error: Error & { digest?: string }
  reset: () => void
}) {
  return (
    <div className="flex flex-col items-center justify-center min-h-screen">
      <h2>Something went wrong!</h2>
      <p>{error.message}</p>
      <button onClick={() => reset()}>Try again</button>
    </div>
  )
}

Rules:

Must be a Client Component ('use client')
Receives error and reset props
Does not catch errors in root layout (use global-error.tsx)

global-error.tsx

Error boundary for root layout:

// app/global-error.tsx
'use client'

export default function GlobalError({
  error,
  reset,
}: {
  error: Error & { digest?: string }
  reset: () => void
}) {
  return (
    <html>
      <body>
        <h2>Something went wrong!</h2>
        <button onClick={() => reset()}>Try again</button>
      </body>
    </html>
  )
}

not-found.tsx

UI for 404 responses:

// app/not-found.tsx
import Link from 'next/link'

export default function NotFound() {
  return (
    <div>
      <h2>Not Found</h2>
      <p>Could not find requested resource</p>
      <Link href="/">Return Home</Link>
    </div>
  )
}

Triggering:

import { notFound } from 'next/navigation'

export default async function Page({ params }) {
  const { id } = await params
  const post = await getPost(id)

  if (!post) {
    notFound() // Triggers not-found.tsx
  }

  return <Post post={post} />
}

template.tsx

Like layout but re-renders on navigation:

// app/dashboard/template.tsx
export default function Template({ children }: { children: React.ReactNode }) {
  return <div>{children}</div>
}

Use cases:

Enter/exit animations
Features that rely on useEffect on each navigation
Resetting state on navigation

default.tsx

Fallback for parallel routes:

// app/@modal/default.tsx
export default function Default() {
  return null
}

Route Segment Options

Route Segment Config

// app/dashboard/page.tsx

// Force dynamic rendering
export const dynamic = 'force-dynamic'
// Options: 'auto' | 'force-dynamic' | 'error' | 'force-static'

// Set revalidation time
export const revalidate = 3600 // seconds

// Set runtime
export const runtime = 'nodejs' // or 'edge'

// Maximum execution duration
export const maxDuration = 30 // seconds

// Prefer fetching certain data
export const fetchCache = 'auto'
// Options: 'auto' | 'default-cache' | 'only-cache' | 'force-cache' | 'force-no-store' | 'default-no-store' | 'only-no-store'

Folder Naming Conventions

Dynamic Segments

Pattern	Example	Matches
`[folder]`	`[id]`	`/123`
`[...folder]`	`[...slug]`	`/a/b/c`
`[[...folder]]`	`[[...slug]]`	`/` or `/a/b/c`

Route Groups

Organize without affecting URL:

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

Private Folders

Exclude from routing:

app/
├── _components/
│   └── button.tsx         # Not a route
└── dashboard/
    └── page.tsx           # /dashboard

Parallel Routes

Named slots with @folder:

app/
├── @modal/
│   └── login/page.tsx
├── @sidebar/
│   └── page.tsx
├── layout.tsx
└── page.tsx

Intercepting Routes

Pattern	Intercepts
`(.)folder`	Same level
`(..)folder`	One level up
`(..)(..)folder`	Two levels up
`(...)folder`	From root

File Hierarchy

Rendering order in a route segment:

1. layout.tsx 2. template.tsx 3. error.tsx (boundary) 4. loading.tsx (boundary) 5. not-found.tsx (boundary) 6. page.tsx or nested layout.tsx

Related skills

Vercel React Best PracticesAutomatically apply Vercel’s official React and Next.js performance rules during code generation and review.587k29.6k

Vercel Composition PatternsGenerate and refactor React components that stay maintainable as complexity grows without boolean prop explosion.267k29.6k

ShadcnAdd, compose, search, fix, and style production-grade React components directly from source without leaving their editor.257k120k

Develop UserscriptsCorrectly write, debug, and package userscripts for Tampermonkey and ScriptCat with proper metadata, GM APIs, and runtime decisions.224k72

Minimalist UiGenerate clean, editorial-style web interfaces with warm monochrome palettes, typographic hierarchy, bento grids and flat components that feel premium and utilita212k69.4k

Image To CodeConvert high-fidelity design images into production-ready, visually accurate frontend code that avoids generic AI design pitfalls.177k69.4k

Frontend Developmentfrontend