Agent-skills-standard 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)

install

source · Clone the upstream repo

git clone https://github.com/HoangNguyen0403/agent-skills-standard

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/HoangNguyen0403/agent-skills-standard "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/nextjs/nextjs-app-router" ~/.claude/skills/hoangnguyen0403-agent-skills-standard-nextjs-app-router && rm -rf "$T"

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

source content

Priority: P0 (CRITICAL)

Workflow: Add New Route

Create page — Add
```
app/dashboard/page.tsx
```
as Server Component.
Add layout — Create
```
app/dashboard/layout.tsx
```
returning
```
{children}
```
.
Add loading state — Create
```
app/dashboard/loading.tsx
```
for Suspense boundary.

Add error boundary — Create

app/dashboard/error.tsx

with

'use client'

and

reset

prop.

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 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 excluded from URL path. Use Dynamic Routes (brackets
```
[slug]
```
) and define static paths via generateStaticParams
.
Specialized: Use Parallel Routes (@modal
) by adding slot to parent layout and providing default.tsx
fallback. Use Intercepting Routes (
```
(.)route
```
) for advanced layouts like dashboards.

Data & Functions

Next.js 15+ Async: Always await
params: Promise
, searchParams
, cookies()
, and headers()
.

Security: Use middleware.ts
for 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.tsx
to auto-wrap routes in Suspense boundary. In error.tsx
, use 'use client'
and provide reset: () => void
function.

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
```
_lib
```
to 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. Use
```
default.tsx
```
for 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: Only
```
app/layout.tsx
```
(root layout) should include them.
No missing
error.tsx
: Every route segment needs Client Component error boundary.