Agent-Skills.md

Agent Skills: nextjs-app-router

Configure file-system routing with nested layouts, route groups, parallel routes, and error boundaries in Next.js App Router. Use when creating page routes, adding loading/error states, or organizing routes with groups and dynamic segments. (triggers: app/**/page.tsx, app/**/layout.tsx, app/**/loading.tsx, App Router, Layout, Route Group, parallel routes)

UncategorizedID: hoangnguyen0403/agent-skills-standard/nextjs-app-router

Repository

hoangnguyen0403/agent-skills-standard
HoangNguyen0403License: Apache-2.0
362103

Install this agent skill to your local

pnpm dlx add-skill https://github.com/HoangNguyen0403/agent-skills-standard/tree/HEAD/skills/nextjs/nextjs-app-router

Skill Files

Browse the full folder contents for nextjs-app-router.

Download Skill

Loading file tree…

skills/nextjs/nextjs-app-router/SKILL.md

Skill Metadata

Name
nextjs-app-router
Description
"Configure file-system routing with nested layouts, route groups, parallel routes, and error boundaries in Next.js App Router. Use when creating page routes, adding loading/error states, or organizing routes with groups and dynamic segments. (triggers: app/**/page.tsx, app/**/layout.tsx, app/**/loading.tsx, App Router, Layout, Route Group, parallel routes)"

Priority: P0 (CRITICAL)

Workflow: Add a New Route

  1. Create page — Add app/dashboard/page.tsx as a Server Component.
  2. Add layout — Create app/dashboard/layout.tsx returning {children}.
  3. Add loading state — Create app/dashboard/loading.tsx for Suspense boundary.
  4. Add error boundary — Create app/dashboard/error.tsx with 'use client' and reset prop.
  5. Await async APIs — In Next.js 15+, await params, cookies(), headers().

Route Group Example

See implementation examples

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.

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.
  • 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

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.