playbooks

home / skills / hoangnguyen0403 / agent-skills-standard / app-router

app-router skill

/skills/nextjs/app-router

This skill helps you implement Next.js App Router patterns, ensuring proper routing, layouts, and server/client boundaries with best practices.

npx playbooks add skill hoangnguyen0403/agent-skills-standard --skill app-router

Review the files below or copy the command above to add this skill to your agents.

Files (2)
SKILL.md
2.0 KB
---
name: Next.js App Router
description: File-system routing, Layouts, and Route Groups.
metadata:
  labels: [nextjs, routing, app-router]
  triggers:
    files: ['app/**/page.tsx', 'app/**/layout.tsx', 'app/**/loading.tsx']
    keywords: [App Router, Layout, Route Group, parallel routes]
---

# Next.js App Router

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

Use the App Router (`app/` directory) for all new projects.

## **Next.js 15+ Async APIs**

> [!IMPORTANT]
> `params`, `searchParams`, `cookies()`, and `headers()` are now **Promises**. You MUST await them.

### Pages & Layouts

```tsx
type Props = { params: Promise<{ slug: string }> };
export default async function Page({ params }: Props) {
  const { slug } = await params;
}
```

### Server Functions (Cookies/Headers)

```tsx
import { cookies } from 'next/headers';
const cookieStore = await cookies();
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)

Overview

This skill documents Next.js App Router patterns for file-system routing, layouts, and route groups. It highlights critical behaviors in Next.js 15+ (async APIs) and prescribes file conventions, folder patterns, and best practices for reliable app structure. Use it to standardize new projects and avoid common pitfalls.

How this skill works

The skill inspects routing and layout conventions inside the app/ directory and enforces patterns that do not change URL behavior (route groups, private folders, dynamic routes). It emphasizes that route-related APIs (params, searchParams, cookies(), headers()) are Promises and must be awaited, and it maps common filenames to their intended roles (page.tsx, layout.tsx, route.ts, etc.). It also guides component colocation, RSC serialization boundaries, and advanced routing features like parallel and intercepting routes.

When to use it

  • Starting any new Next.js project — use the App Router by default.
  • Refactoring older pages/ directory projects to the app/ router model.
  • Designing layouts that must persist across client navigation.
  • Creating private/internal code folders that should not generate routes.
  • Implementing server endpoints with route.ts and handling cookies/headers on the server.

Best practices

  • Always use the App Router (app/ directory) for new projects.
  • Await params, searchParams, cookies(), and headers() since they are Promises in Next.js 15+.
  • Keep page.tsx for route UI, layout.tsx for shared wrappers, loading.tsx for suspense, error.tsx as a Client Component, and route.ts for server endpoints.
  • Use route groups (parentheses) to organize without changing the URL and underscore-prefixed folders for private code.
  • Ensure props passed to Client Components are serializable to respect RSC boundaries.
  • Colocate components, styles, and tests inside each route folder for maintainability.

Example use cases

  • Protected auth flow organized with (auth) route group while keeping clean URLs.
  • Persistent navigation layout defined in app/layout.tsx that wraps all nested pages.
  • Server-side API route implemented in route.ts alongside page.tsx for tight cohesion.
  • Parallel UI states using @folder parallel routes with default.tsx fallbacks.
  • Internal library code placed in _lib to prevent accidental routing and public exposure.

FAQ

Why must I await params and cookies() now?

In Next.js 15+ these route-related helpers return Promises to support async resolution on the server. Not awaiting them can cause undefined or incorrect values.

When should error.tsx be a Client Component?

error.tsx must be a Client Component because it may need to handle client-only state, effects, or error UI behavior that requires browser APIs.