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.