git:20260323.4e4393e to git:20260324.a02e282

---

name: nextjs-app-router

description: Provides patterns and code examples for building Next.js 16+ applications with App Router architecture. Use when creating projects with App Router, implementing Server Components and Client Components ("use client"), creating Server Actions for forms, building Route Handlers (route.ts), configuring caching with "use cache" directive (cacheLife, cacheTag), setting up parallel routes (`@slot`) or intercepting routes, migrating to proxy.ts, or working with App Router file conventions (layout.tsx, page.tsx, loading.tsx, error.tsx).

allowed-tools: Read, Write, Edit, Bash

---

# Next.js App Router (Next.js 16+)

Build modern React applications using Next.js 16+ with App Router architecture.

## Overview

## When to Use

Activate when user requests involve:

- "Create a Next.js 16 project", "Set up App Router"

- "Server Component", "Client Component", "use client"

- "Server Action", "form submission", "mutation"

- "Route Handler", "API endpoint", "route.ts"

- "use cache", "cacheLife", "cacheTag", "revalidation"

- "parallel routes", "`@`slot", "intercepting routes"

- "proxy.ts", "migrate from middleware.ts"

- "layout.tsx", "page.tsx", "loading.tsx", "error.tsx", "not-found.tsx"

- "generateMetadata", "next/image", "next/font"

## Quick Reference

## Instructions

### Create New Project

```bash

npx create-next-app@latest my-app --typescript --tailwind --app --turbopack

```

```tsx

// app/users/page.tsx

async function getUsers() {

const apiUrl = process.env.API_URL;

const res = await fetch(`${apiUrl}/users`);

return res.json();

}

export default async function UsersPage() {

const users = await getUsers();

}

```

Add `"use client"` when using hooks, browser APIs, or event handlers.

```tsx

"use client";

import { useState } from "react";

export default function Counter() {

const [count, setCount] = useState(0);

}

```

```tsx

// app/actions.ts

"use server";

import { revalidatePath } from "next/cache";

export async function createUser(formData: FormData) {

const name = formData.get("name") as string;

const email = formData.get("email") as string;

await db.user.create({ data: { name, email } });

revalidatePath("/users");

}

```

Use with forms in Client Components:

```tsx

"use client";

import { useActionState } from "react";

import { createUser } from "./actions";

export default function UserForm() {

const [state, formAction, pending] = useActionState(createUser, {});

return (

<form action={formAction}>

<input name="name" />

<input name="email" type="email" />

</form>

);

}

```

### Configure Caching

```tsx

"use cache";

import { cacheLife, cacheTag } from "next/cache";

const { id } = await params;

cacheTag(`product-${id}`);

cacheLife("hours");

const product = await fetchProduct(id);

return <ProductDetail product={product} />;

}

```

```ts

// app/api/users/route.ts

import { NextRequest, NextResponse } from "next/server";

export async function GET(request: NextRequest) {

}

export async function POST(request: NextRequest) {

const body = await request.json();

}

```

Dynamic segments use `[param]`:

```ts

// app/api/users/[id]/route.ts

const { id } = await params;

const user = await db.user.findUnique({ where: { id } });

return NextResponse.json(user);

}

```

All Next.js APIs are async in version 16.

```tsx

export default async function Page() {

const cookieStore = await cookies();

const headersList = await headers();

const session = cookieStore.get("session")?.value;

const userAgent = headersList.get("user-agent");

return <div>...</div>;

}

```

```tsx

export default async function Page({

params,

searchParams,

}: {

params: Promise<{ slug: string }>;

searchParams: Promise<{ sort?: string }>;

}) {

const { slug } = await params;

const { sort } = await searchParams;

// ...

}

```

See [references/nextjs16-migration.md](references/nextjs16-migration.md) for migration guide and proxy.ts configuration.

Use `@folder` convention for parallel route slots.

```tsx

// app/dashboard/layout.tsx

return (

<div>

{children}

</div>

);

}

```

```tsx

// app/dashboard/@team/page.tsx

// app/dashboard/@analytics/page.tsx

```

See [references/routing-patterns.md](references/routing-patterns.md) for intercepting routes, route groups, and dynamic routes.

## Best Practices

- Fetch in Server Components when possible

- Use React's `cache()` for deduplication

- Parallelize independent fetches

- Add Suspense boundaries with `loading.tsx`

- Use `loading.tsx` for Suspense boundaries

- Use `next/image` for optimized images

- Use `next/font` for font optimization

## Examples

**Output:**

```tsx

// app/blog/actions.ts

"use server";

import { z } from "zod";

import { revalidatePath } from "next/cache";

export async function createPost(formData: FormData) {

await db.post.create({ data: parsed.data });

revalidatePath("/blog");

return { success: true };

}

```

```tsx

// app/blog/new/page.tsx

"use client";

import { useActionState } from "react";

import { createPost } from "../actions";

export default function NewPostPage() {

const [state, formAction, pending] = useActionState(createPost, {});

return (

<form action={formAction}>

<input name="title" placeholder="Title" />

{state.errors?.title && <span>{state.errors.title[0]}</span>}

<textarea name="content" placeholder="Content" />

{state.errors?.content && <span>{state.errors.content[0]}</span>}

</form>

);

}

```

**Output:**

```tsx

// app/products/[id]/page.tsx

"use cache";

import { cacheLife, cacheTag } from "next/cache";

const { id } = await params;

cacheTag(`product-${id}`, "products");

cacheLife("hours");

const product = await db.product.findUnique({ where: { id } });

}

```

// app/api/revalidate/route.ts

import { revalidateTag } from "next/cache";

import { NextResponse } from "next/server";

export async function POST(request: Request) {

const { tag } = await request.json();

revalidateTag(tag);

return NextResponse.json({ revalidated: true });

}

```

### Example 3: Dashboard with Parallel Routes

**Output:**

```tsx

// app/dashboard/layout.tsx

return (

<div className="flex">

<aside className="w-64">{sidebar}</aside>

</div>

);

}

```

```tsx

// app/dashboard/@sidebar/page.tsx

// app/dashboard/@stats/page.tsx

export default async function Stats() {

const stats = await fetchStats();

}

```

## Constraints and Warnings

- Server Components cannot use browser APIs or React hooks

- Client Components cannot be async (no direct data fetching)

- `cookies()`, `headers()`, `draftMode()` are async in Next.js 16

- `params` and `searchParams` are Promise-based in Next.js 16

## References