Next.js 16 Applications
Build Next.js 16 applications correctly with distinctive design.
Critical Breaking Changes (Next.js 16)
1. params and searchParams are Now Promises
THIS IS THE MOST COMMON MISTAKE.
typescript1// WRONG - Next.js 15 pattern (WILL FAIL) 2export default function Page({ params }: { params: { id: string } }) { 3 return <div>ID: {params.id}</div> 4} 5 6// CORRECT - Next.js 16 pattern 7export default async function Page({ 8 params, 9}: { 10 params: Promise<{ id: string }> 11}) { 12 const { id } = await params 13 return <div>ID: {id}</div> 14}
2. Client Components Need use() Hook
typescript1"use client" 2import { use } from "react" 3 4export default function ClientPage({ 5 params, 6}: { 7 params: Promise<{ id: string }> 8}) { 9 const { id } = use(params) 10 return <div>ID: {id}</div> 11}
3. searchParams Also Async
typescript1export default async function Page({ 2 searchParams, 3}: { 4 searchParams: Promise<{ page?: string }> 5}) { 6 const { page } = await searchParams 7 return <div>Page: {page ?? "1"}</div> 8}
Core Patterns
Project Setup
bash1npx create-next-app@latest my-app --typescript --tailwind --eslint 2cd my-app 3 4# Add shadcn/ui 5npx shadcn@latest init 6npx shadcn@latest add button form dialog table sidebar
App Router Layout
typescript1// app/layout.tsx 2export default function RootLayout({ 3 children, 4}: { 5 children: React.ReactNode 6}) { 7 return ( 8 <html lang="en"> 9 <body className="min-h-screen"> 10 {children} 11 </body> 12 </html> 13 ) 14}
Dynamic Routes
typescript1// app/tasks/[id]/page.tsx 2export default async function TaskPage({ 3 params, 4}: { 5 params: Promise<{ id: string }> 6}) { 7 const { id } = await params 8 const task = await getTask(id) 9 10 return ( 11 <main> 12 <h1>{task.title}</h1> 13 </main> 14 ) 15}
Server Actions
typescript1// app/actions.ts 2"use server" 3 4import { revalidatePath } from "next/cache" 5 6export async function createTask(formData: FormData) { 7 const title = formData.get("title") as string 8 9 await db.insert(tasks).values({ title }) 10 11 revalidatePath("/tasks") 12} 13 14// Usage in component 15<form action={createTask}> 16 <input name="title" /> 17 <button type="submit">Create</button> 18</form>
API Routes
typescript1// app/api/tasks/route.ts 2import { NextResponse } from "next/server" 3 4export async function GET() { 5 const tasks = await db.select().from(tasksTable) 6 return NextResponse.json(tasks) 7} 8 9export async function POST(request: Request) { 10 const body = await request.json() 11 const task = await db.insert(tasksTable).values(body).returning() 12 return NextResponse.json(task, { status: 201 }) 13}
Middleware → proxy.ts
typescript1// proxy.ts (replaces middleware.ts in Next.js 16) 2import { NextRequest } from "next/server" 3 4export function proxy(request: NextRequest) { 5 // Authentication check 6 const token = request.cookies.get("token") 7 if (!token && request.nextUrl.pathname.startsWith("/dashboard")) { 8 return Response.redirect(new URL("/login", request.url)) 9 } 10} 11 12export const config = { 13 matcher: ["/dashboard/:path*"], 14}
Data Fetching
Server Component (Default)
typescript1// This runs on the server - can use async/await directly 2async function TaskList() { 3 const tasks = await fetch("https://api.example.com/tasks", { 4 cache: "no-store", // SSR, or 5 // next: { revalidate: 60 } // ISR 6 }).then(r => r.json()) 7 8 return ( 9 <ul> 10 {tasks.map(task => <li key={task.id}>{task.title}</li>)} 11 </ul> 12 ) 13}
Client Component
typescript1"use client" 2 3import useSWR from "swr" 4 5const fetcher = (url: string) => fetch(url).then(r => r.json()) 6 7export function ClientTaskList() { 8 const { data, error, isLoading } = useSWR("/api/tasks", fetcher) 9 10 if (isLoading) return <div>Loading...</div> 11 if (error) return <div>Error loading tasks</div> 12 13 return ( 14 <ul> 15 {data.map(task => <li key={task.id}>{task.title}</li>)} 16 </ul> 17 ) 18}
Project Structure
app/
├── layout.tsx # Root layout
├── page.tsx # Home page
├── globals.css # Global styles
├── api/ # API routes
│ └── tasks/route.ts
├── tasks/
│ ├── page.tsx # /tasks
│ └── [id]/page.tsx # /tasks/:id
├── actions.ts # Server actions
└── proxy.ts # Request proxy (middleware)
components/
├── ui/ # shadcn/ui components
└── task-list.tsx # App components
lib/
├── db.ts # Database connection
└── utils.ts # Utilities
Next.js DevTools MCP
Use the next-devtools-mcp server for runtime diagnostics and development automation.
Setup
bash1claude mcp add next-devtools npx next-devtools-mcp@latest
Or in settings.json:
json1{ 2 "mcpServers": { 3 "next-devtools": { 4 "type": "stdio", 5 "command": "npx", 6 "args": ["next-devtools-mcp@latest"] 7 } 8 } 9}
Available Tools
| Tool | Purpose |
|---|---|
init | Establish context with available tools and best practices |
nextjs_docs | Search and fetch official Next.js documentation |
browser_eval | Automate browser testing with Playwright |
nextjs_index | Discover running Next.js dev servers |
nextjs_call | Execute MCP tools on running dev servers |
upgrade_nextjs_16 | Automated upgrade with codemods |
enable_cache_components | Configure Cache Components for Next.js 16 |
Key Use Cases
1. Get Real-time Errors
"What build errors are there in my Next.js app?"
"Show me TypeScript errors in the current project"
2. Debug Runtime Issues
"Check the dev server logs for errors"
"What runtime errors are happening on the dashboard page?"
3. Upgrade Assistance
"Upgrade this project to Next.js 16"
"Enable cache components for this app"
4. Documentation Lookup
"How do I use the Image component in Next.js 16?"
"What's the correct way to handle dynamic routes?"
Next.js 16 MCP Endpoint
Next.js 16+ exposes a built-in MCP endpoint at http://localhost:3000/_next/mcp (or your dev server port). The devtools MCP automatically discovers and connects to running servers.
Verification
Run: python3 scripts/verify.py
Expected: ✓ building-nextjs-apps skill ready
If Verification Fails
- Check: references/ folder has nextjs-16-patterns.md
- Stop and report if still failing
Related Skills
- styling-with-shadcn - UI components for Next.js apps
- fetching-library-docs - Latest Next.js docs:
--library-id /vercel/next.js --topic routing - configuring-better-auth - OAuth/SSO for Next.js apps
References
- references/nextjs-16-patterns.md - Complete Next.js 16 patterns
- references/frontend-design.md - Aesthetic guidelines for distinctive UI
- references/datetime-patterns.md - UTC/timezone handling for datetime-local inputs
