# Nextjs App Router

> File-system routing, Layouts, and Route Groups. Use when implementing App Router routing, nested layouts, or route groups in Next.js. (triggers: app/**/page.tsx, app/**/layout.tsx, app/**/loading.tsx, App Router, Layout, Route Group, parallel routes)

- Skill: `comeonoliver/nextjs-app-router` (Agent Skill)
- Install (CLI): `npx skillmds@latest add comeonoliver/nextjs-app-router`
- Raw SKILL.md: https://api.skillmd.com/api/skills/comeonoliver/nextjs-app-router/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: ComeOnOliver (https://skillmd.com/u/comeonoliver)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/comeonoliver/nextjs-app-router

---


## **Priority: P0 (CRITICAL)**

## Implementation Guidelines

### Routing Architecture

- **Structure**: Use the **`app/` directory**. Define routes with **`app/dashboard/layout.tsx`** returning **`{children}`**; shared UI nests inside `app/layout.tsx` automatically. Handle states with **`loading.tsx`**, **`error.tsx`**, and **`not-found.tsx`**.
- **Segments**: Organize features with **Route Groups** (brackets **`(auth)`**) to be **excluded from URL path**. Use **Dynamic Routes** (brackets `[slug]`) and define static paths via **`generateStaticParams`**.
- **Specialized**: Use **Parallel Routes** (**`@modal`**) by adding the slot to the parent layout and providing a **`default.tsx`** fallback. Use **Intercepting Routes** (`(.)route`) for advanced layouts like dashboards.

### Data & Functions

- **Next.js 15+ Async**: Always **`await`** the **`params: Promise`**, **`searchParams`**, **`cookies()`**, and **`headers()`**.
- **Security**: Use **`middleware.ts`** for edge-side authentication and redirection. Ensure all **Route Handlers (`route.ts`)** are secured with appropriate auth checks.
- **RSC**: Default to **React Server Components (RSC)**. Only use **`'use client'`** at leaf nodes for interactivity (hooks/events).
- **Error Boundaries**: Create **`app/dashboard/loading.tsx`** to auto-wrap routes in a **Suspense boundary**. In **`error.tsx`**, use **`'use client'`** and provide a **`reset: () => void`** function.
  const theme = cookieStore.get('theme');

```

## File Conventions

- **page.tsx**: UI for a route.
- **layout.tsx**: Shared UI wrapping children. Persists across navigation.
- **loading.tsx**: Suspense boundary for loading states.
- **error.tsx**: Error boundary (Must be Client Component).
- **route.ts**: Server-side API endpoint.

## Structure Patterns

- **Route Groups**: Use parenthesis `(auth)` to organize without affecting URL path.
- **Private Folders**: Use underscore `_lib` to exclude from routing.
- **Dynamic Routes**: Use brackets `[slug]` or `[...slug]` (catch-all).

## Best Practices

- **RSC Boundaries**: Ensure props passed to Client Components are serializable. See [RSC Boundaries & Serialization](../architecture/references/RSC_BOUNDARIES.md).
- **Parallel Routes (`@folder`)**: Render multiple pages in the same layout. Use `default.tsx` for fallback.
- **Intercepting Routes (`(..)folder`)**: Load routes within current layout context.
- **Colocation**: Keep component files, styles, and tests inside the route folder.
- **Layouts**: Use Root Layout (`app/layout.tsx`) for `<html>` and `<body>` tags.
- [**Self-Hosting Standard**](references/SELF_HOSTING.md)


## Anti-Patterns

- **No unawaited async APIs**: `params`, `cookies()`, `headers()` are Promises in Next.js 15+; always await.
- **No `'use client'` at tree root**: Place at leaves; keep layouts and pages as Server Components.
- **No `<html>`/`<body>` in nested layouts**: Only `app/layout.tsx` (root layout) should include them.
- **No missing `error.tsx`**: Every route segment needs a Client Component error boundary.
```