Skip to content

davepoon/buildwithclaude / plugins/nextjs-expert/skills/app-router

app-router

Verified

This skill should be used when the user asks to "create a Next.js route", "add a page", "set up layouts", "implement loading states", "add error boundaries", "organize routes", "create dynamic routes", or needs guidance on Next.js App Router file conventions and routing patterns.

references/routing-conventions.md

View on GitHub
# Next.js App Router File Conventions

## Route Segment Files

### page.tsx

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

```tsx
// 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:

```tsx
// 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:

```tsx
// 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:

```tsx
// 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:

```tsx
// 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:

```tsx
// 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:**
```tsx
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:

```tsx
// 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:

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

## Route Segment Options

### Route Segment Config

```tsx
// 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`
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall