FilippoDeSilva Priority: P0 (CRITICAL)
Workflow: Add New Route
- Create page — Add
app/dashboard/page.tsxas Server Component. - Add layout — Create
app/dashboard/layout.tsxreturning{children}. - Add loading state — Create
app/dashboard/loading.tsxfor Suspense boundary. - Add error boundary — Create
app/dashboard/error.tsxwith'use client'andresetprop. - Await async APIs — In Next.js 15+,
await params,cookies(),headers().
Route Group Example
See implementation examples
Implementation Guidelines
Routing Architecture
- Structure: Use
app/directory. Define routes withapp/dashboard/layout.tsxreturning{children}; shared UI nests insideapp/layout.tsxautomatically. Handle states withloading.tsx,error.tsx, andnot-found.tsx. - Segments: Organize features with Route Groups (brackets
(auth)) to excluded from URL path. Use Dynamic Routes (brackets[slug]) and define static paths viagenerateStaticParams. - Specialized: Use Parallel Routes (
@modal) by adding slot to parent layout and providingdefault.tsxfallback. Use Intercepting Routes ((.)route) for advanced layouts like dashboards.
Data & Functions
- Next.js 15+ Async: Always
awaitparams: Promise,searchParams,cookies(), andheaders(). - Security: Use
middleware.tsfor edge-side authentication and redirection. Ensure all Route Handlers (route.ts) 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.tsxto auto-wrap routes in Suspense boundary. Inerror.tsx, use'use client'and providereset: () => voidfunction.
File Conventions
- page.tsx: UI for route.
- layout.tsx: Shared UI wrapping children. Persists across navigation.
- loading.tsx: Suspense boundary for loading states.
- error.tsx: Error boundary (Must 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
_libto exclude from routing. - Dynamic Routes: Use brackets
[slug]or[...slug](catch-all).
Best Practices
- RSC Boundaries: Ensure props passed to Client Components serializable. See RSC Boundaries & Serialization.
- Parallel Routes (
@folder): Render multiple pages in same layout. Usedefault.tsxfor fallback. - Intercepting Routes (
(..)folder): Load routes within current layout context. - Colocation: Keep component files, styles, and tests inside route folder.
- Layouts: Use Root Layout (
app/layout.tsx) for<html>and<body>tags. - Self-Hosting Standard
Anti-Patterns
- No unawaited async APIs:
params,cookies(),headers()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: Onlyapp/layout.tsx(root layout) should include them. - No missing
error.tsx: Every route segment needs Client Component error boundary.