Building Nextjs Apps

Name: Building Nextjs Apps
Author: bilalmk

bilalmk/todo_correct

17 installs
1 repo stars
Updated January 27, 2026
bilalmk/todo_correct

building-nextjs-apps is a skill for building Next.js 16 applications with correct App Router patterns, covering async params, server actions, and proxy.ts.

About

building-nextjs-apps is a skill for building Next.js 16 applications with correct patterns and distinctive design. It highlights breaking changes such as params and searchParams now being Promises, the use() hook for client components, and proxy.ts replacing middleware. It covers project setup with shadcn/ui, App Router layouts, dynamic routes, server actions, API routes, and server/client data fetching. A developer uses it when creating pages or upgrading from Next.js 15, and not for non-React or backend-only apps.

Builds Next.js 16 apps with correct App Router patterns
Covers breaking changes: async params/searchParams, Turbopack, proxy.ts
Includes server actions, API routes, and data-fetching patterns

Building Nextjs Apps by the numbers

17 all-time installs (skills.sh)
Ranked #1,582 of 2,245 Frontend Development skills by installs in the Skillselion catalog
Data as of Jul 28, 2026 (Skillselion catalog sync)

At a glance

building-nextjs-apps capabilities & compatibility

free

Capabilities: nextjs scaffolding · app router patterns · server actions
Use cases: frontend · web design · api development
IDEs: vscode · cursor ide
Pricing: Free

From the docs

What building-nextjs-apps says it does

Build Next.js 16 applications with correct patterns and distinctive design.

SKILL.md

params and searchParams are Now Promises

SKILL.md

// proxy.ts (replaces middleware.ts in Next.js 16)

SKILL.md

npx skills add https://github.com/bilalmk/todo_correct --skill building-nextjs-apps

Add your badge

Show developers this skill is listed on Skillselion. Paste this into your README.

[![Listed on Skillselion](https://skillselion.com/badge/skills/bilalmk/todo_correct/building-nextjs-apps.svg)](https://skillselion.com/skills/bilalmk/todo_correct/building-nextjs-apps)

Installs	17
repo stars	★ 1
Last updated	January 27, 2026
Repository	bilalmk/todo_correct ↗

What it does

Build Next.js 16 apps with correct App Router patterns, handling async params, server actions, and proxy.ts.

Who is it for?

Building or upgrading Next.js 16 App Router apps

Skip if: Non-React or backend-only applications

When should I use this skill?

Creating pages, layouts, dynamic routes, upgrading from Next.js 15, or implementing proxy.ts

What you get

A Next.js 16 app with correct async params, server actions, routing, and proxy.ts.

Next.js 16 pages, layouts, and routes
Server actions and API routes
proxy.ts configuration

By the numbers

Targets Next.js 16 breaking changes (async params, Turbopack, cacheComponents)

Files

SKILL.mdMarkdownGitHub ↗

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.

// WRONG - Next.js 15 pattern (WILL FAIL)
export default function Page({ params }: { params: { id: string } }) {
  return <div>ID: {params.id}</div>
}

// CORRECT - Next.js 16 pattern
export default async function Page({
  params,
}: {
  params: Promise<{ id: string }>
}) {
  const { id } = await params
  return <div>ID: {id}</div>
}

2. Client Components Need use() Hook

"use client"
import { use } from "react"

export default function ClientPage({
  params,
}: {
  params: Promise<{ id: string }>
}) {
  const { id } = use(params)
  return <div>ID: {id}</div>
}

3. searchParams Also Async

export default async function Page({
  searchParams,
}: {
  searchParams: Promise<{ page?: string }>
}) {
  const { page } = await searchParams
  return <div>Page: {page ?? "1"}</div>
}

---

Core Patterns

Project Setup

npx create-next-app@latest my-app --typescript --tailwind --eslint
cd my-app

# Add shadcn/ui
npx shadcn@latest init
npx shadcn@latest add button form dialog table sidebar

App Router Layout

// app/layout.tsx
export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body className="min-h-screen">
        {children}
      </body>
    </html>
  )
}

Dynamic Routes

// app/tasks/[id]/page.tsx
export default async function TaskPage({
  params,
}: {
  params: Promise<{ id: string }>
}) {
  const { id } = await params
  const task = await getTask(id)

  return (
    <main>
      <h1>{task.title}</h1>
    </main>
  )
}

Server Actions

// app/actions.ts
"use server"

import { revalidatePath } from "next/cache"

export async function createTask(formData: FormData) {
  const title = formData.get("title") as string

  await db.insert(tasks).values({ title })

  revalidatePath("/tasks")
}

// Usage in component
<form action={createTask}>
  <input name="title" />
  <button type="submit">Create</button>
</form>

API Routes

// app/api/tasks/route.ts
import { NextResponse } from "next/server"

export async function GET() {
  const tasks = await db.select().from(tasksTable)
  return NextResponse.json(tasks)
}

export async function POST(request: Request) {
  const body = await request.json()
  const task = await db.insert(tasksTable).values(body).returning()
  return NextResponse.json(task, { status: 201 })
}

Middleware → proxy.ts

// proxy.ts (replaces middleware.ts in Next.js 16)
import { NextRequest } from "next/server"

export function proxy(request: NextRequest) {
  // Authentication check
  const token = request.cookies.get("token")
  if (!token && request.nextUrl.pathname.startsWith("/dashboard")) {
    return Response.redirect(new URL("/login", request.url))
  }
}

export const config = {
  matcher: ["/dashboard/:path*"],
}

---

Data Fetching

Server Component (Default)

// This runs on the server - can use async/await directly
async function TaskList() {
  const tasks = await fetch("https://api.example.com/tasks", {
    cache: "no-store", // SSR, or
    // next: { revalidate: 60 } // ISR
  }).then(r => r.json())

  return (
    <ul>
      {tasks.map(task => <li key={task.id}>{task.title}</li>)}
    </ul>
  )
}

Client Component

"use client"

import useSWR from "swr"

const fetcher = (url: string) => fetch(url).then(r => r.json())

export function ClientTaskList() {
  const { data, error, isLoading } = useSWR("/api/tasks", fetcher)

  if (isLoading) return <div>Loading...</div>
  if (error) return <div>Error loading tasks</div>

  return (
    <ul>
      {data.map(task => <li key={task.id}>{task.title}</li>)}
    </ul>
  )
}

---

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

claude mcp add next-devtools npx next-devtools-mcp@latest

Or in settings.json:

{
  "mcpServers": {
    "next-devtools": {
      "type": "stdio",
      "command": "npx",
      "args": ["next-devtools-mcp@latest"]
    }
  }
}

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

1. Check: references/ folder has nextjs-16-patterns.md 2. 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

DateTime and Timezone Patterns

Handle datetime values correctly across the full stack: browser → API → database → browser.

The Golden Rule

Store UTC, Display Local

Browser (local) → Convert to UTC → API → Store UTC → Database
Database → Return UTC → API → Browser → Display in local

Critical Pitfall: datetime-local Input

The HTML <input type="datetime-local"> returns a string WITHOUT timezone info:

<input type="datetime-local" value="2025-12-15T23:13">

This gives "2025-12-15T23:13" - but is this UTC? Local time? The browser doesn't tell you.

The Bug

// WRONG - Backend interprets as UTC, but user entered local time!
const dueDate = "2025-12-15T23:13"  // User in PKT (UTC+5)
await api.createTask({ due_date: dueDate })
// Backend stores as 23:13 UTC
// But user meant 23:13 PKT = 18:13 UTC
// Task is now 5 hours late!

The Fix

// CORRECT - Convert local datetime to UTC ISO string
function handleSubmit() {
  let dueDateUTC: string | undefined = undefined

  if (dueDate) {
    // datetime-local gives "2025-12-15T23:13" (local time, no TZ)
    // new Date() interprets it in browser's local timezone
    // toISOString() converts to UTC: "2025-12-15T18:13:00.000Z"
    const localDate = new Date(dueDate)
    dueDateUTC = localDate.toISOString()
  }

  await api.createTask({ due_date: dueDateUTC })
}

Frontend Patterns (TypeScript/React)

Converting datetime-local to UTC

// Input: "2025-12-15T23:13" (from datetime-local)
// Output: "2025-12-15T18:13:00.000Z" (UTC ISO string)

function localToUTC(localDatetime: string): string {
  const date = new Date(localDatetime)
  return date.toISOString()
}

Converting UTC to datetime-local (for editing)

// Input: "2025-12-15T18:13:00Z" (UTC from API)
// Output: "2025-12-15T23:13" (local, for datetime-local input)

function utcToLocal(utcDatetime: string): string {
  const date = new Date(utcDatetime)
  const year = date.getFullYear()
  const month = String(date.getMonth() + 1).padStart(2, '0')
  const day = String(date.getDate()).padStart(2, '0')
  const hours = String(date.getHours()).padStart(2, '0')
  const minutes = String(date.getMinutes()).padStart(2, '0')
  return `${year}-${month}-${day}T${hours}:${minutes}`
}

Full Form Example

"use client"
import { useState } from "react"

export function TaskForm() {
  const [dueDate, setDueDate] = useState("")

  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault()

    // Convert local to UTC for API
    let dueDateUTC: string | undefined
    if (dueDate) {
      dueDateUTC = new Date(dueDate).toISOString()
    }

    await api.createTask({
      title: "My Task",
      due_date: dueDateUTC,
    })
  }

  return (
    <form onSubmit={handleSubmit}>
      <input
        type="datetime-local"
        value={dueDate}
        onChange={(e) => setDueDate(e.target.value)}
      />
      <button type="submit">Create</button>
    </form>
  )
}

Backend Patterns (Python/FastAPI)

Pydantic Validator

from datetime import UTC, datetime
from pydantic import field_validator
from sqlmodel import SQLModel

class TaskCreate(SQLModel):
    title: str
    due_date: datetime | None = None

    @field_validator("due_date", mode="after")
    @classmethod
    def normalize_datetime(cls, v: datetime | None) -> datetime | None:
        """Convert timezone-aware to naive UTC for storage."""
        if v is None:
            return None
        if v.tzinfo is not None:
            v = v.astimezone(UTC).replace(tzinfo=None)
        return v

Database Storage

Always store as naive UTC:

-- PostgreSQL
due_date TIMESTAMP  -- NOT TIMESTAMP WITH TIME ZONE

# SQLModel
class Task(SQLModel, table=True):
    due_date: datetime | None = Field(default=None)

Displaying Times

import { formatDistanceToNow, format } from 'date-fns'

// Relative: "in 2 hours", "3 days ago"
formatDistanceToNow(new Date(utcDatetime), { addSuffix: true })

// Absolute local: "Dec 15, 2025 11:13 PM"
format(new Date(utcDatetime), 'MMM d, yyyy h:mm a')

Common Pitfalls

Pitfall	Wrong	Right
Sending datetime-local directly	`api.post({ due_date: "2025-12-15T23:13" })`	`api.post({ due_date: new Date("2025-12-15T23:13").toISOString() })`
Displaying UTC to user	`<span>{task.due_date}</span>`	`<span>{new Date(task.due_date).toLocaleString()}</span>`
Comparing dates	`task.due_date < datetime.now(UTC)`	`task.due_date < datetime.utcnow()`

Summary

Location	Format	Example
`datetime-local` input	Local, no TZ	`2025-12-15T23:13`
API request/response	UTC ISO 8601	`2025-12-15T18:13:00.000Z`
Database	Naive UTC	`2025-12-15 18:13:00`
Display to user	Local formatted	`Dec 15, 2025 11:13 PM`

Next.js 16

Build Next.js 16 applications correctly. This skill prevents common mistakes when working with Next.js 16's breaking changes.

When to Use

Creating new Next.js 16 projects
Upgrading from Next.js 15 to 16
Working with dynamic routes and params
Implementing request proxying (formerly middleware)
Configuring Turbopack builds
Using cacheComponents (formerly dynamicIO)

Critical Breaking Changes

1. params and searchParams are Now Promises

THIS IS THE MOST COMMON MISTAKE. In Next.js 16, params and searchParams are asynchronous.

// WRONG - Next.js 15 pattern (WILL FAIL)
export default function Page({ params }: { params: { id: string } }) {
  return <div>ID: {params.id}</div>
}

// CORRECT - Next.js 16 pattern
export default async function Page({
  params,
}: {
  params: Promise<{ id: string }>
}) {
  const { id } = await params
  return <div>ID: {id}</div>
}

For searchParams:

// WRONG - Next.js 15 pattern
export default function Page({
  searchParams
}: {
  searchParams: { query: string }
}) {
  return <div>Query: {searchParams.query}</div>
}

// CORRECT - Next.js 16 pattern
export default async function Page({
  searchParams,
}: {
  searchParams: Promise<{ query?: string }>
}) {
  const { query } = await searchParams
  return <div>Query: {query}</div>
}

In layouts:

// CORRECT - Layout with async params
export default async function Layout({
  children,
  params,
}: {
  children: React.ReactNode
  params: Promise<{ slug: string }>
}) {
  const { slug } = await params
  return (
    <div>
      <nav>Current: {slug}</nav>
      {children}
    </div>
  )
}

In generateMetadata:

// CORRECT - Async params in metadata
export async function generateMetadata({
  params,
}: {
  params: Promise<{ id: string }>
}): Promise<Metadata> {
  const { id } = await params
  const product = await getProduct(id)
  return { title: product.name }
}

2. middleware.ts is Now proxy.ts

DO NOT CREATE `middleware.ts` in Next.js 16. Use proxy.ts instead.

// File: proxy.ts (NOT middleware.ts)
// Location: project root (same level as app/)

import type { NextRequest } from 'next/server'
import { NextResponse } from 'next/server'

// WRONG: export function middleware() {}
// CORRECT:
export function proxy(request: NextRequest) {
  // Check auth
  const token = request.cookies.get('token')

  if (!token && request.nextUrl.pathname.startsWith('/dashboard')) {
    return NextResponse.redirect(new URL('/login', request.url))
  }

  return NextResponse.next()
}

// Matcher config remains the same
export const config = {
  matcher: ['/dashboard/:path*', '/api/:path*'],
}

Key differences from middleware:

File renamed: middleware.ts → proxy.ts
Function renamed: middleware() → proxy()
Location: Still at project root
Matcher config: Same syntax

3. Turbopack is Now Default

Turbopack is the default bundler. The --turbopack flag is no longer needed.

# Next.js 15
next dev --turbopack

# Next.js 16 (Turbopack is default)
next dev

Configuration moved to top-level:

// next.config.ts

// WRONG - Next.js 15 pattern
const config = {
  experimental: {
    turbo: {
      rules: { /* ... */ }
    }
  }
}

// CORRECT - Next.js 16 pattern
const config = {
  turbopack: {
    rules: {
      '*.svg': {
        loaders: ['@svgr/webpack'],
        as: '*.js',
      },
    },
  },
}

4. cacheComponents Replaces dynamicIO

The dynamicIO experimental flag is now cacheComponents:

// next.config.ts

// WRONG - Next.js 15 pattern
const config = {
  experimental: {
    dynamicIO: true,
  }
}

// CORRECT - Next.js 16 pattern
const config = {
  cacheComponents: true,
}

5. Parallel Routes Require default.js

Parallel routes MUST have a `default.js` file or you'll get 404 errors during soft navigation.

app/
├── @modal/
│   ├── default.tsx    ← REQUIRED
│   └── login/
│       └── page.tsx
├── layout.tsx
└── page.tsx

// app/@modal/default.tsx
export default function Default() {
  return null
}

6. Image Component Changes

Several next/image props have changed:

// WRONG - Next.js 15 patterns
<Image
  src="/photo.jpg"
  layout="fill"           // Removed
  objectFit="cover"       // Removed
  objectPosition="center" // Removed
  lazyBoundary="200px"    // Removed
  lazyRoot={ref}          // Removed
/>

// CORRECT - Next.js 16 patterns
<Image
  src="/photo.jpg"
  fill                    // Use fill prop
  style={{
    objectFit: 'cover',
    objectPosition: 'center'
  }}
/>

7. Route Handlers Async Context

Route handlers also need async params:

// WRONG
export async function GET(
  request: Request,
  { params }: { params: { id: string } }
) {
  return Response.json({ id: params.id })
}

// CORRECT
export async function GET(
  request: Request,
  { params }: { params: Promise<{ id: string }> }
) {
  const { id } = await params
  return Response.json({ id })
}

Quick Start

# Create new Next.js 16 project
npx create-next-app@latest my-app

# Or upgrade existing project
npm install next@16 react@latest react-dom@latest

Project Structure (Next.js 16)

my-app/
├── app/
│   ├── layout.tsx           # Root layout
│   ├── page.tsx             # Home page
│   ├── globals.css
│   ├── @modal/              # Parallel route
│   │   ├── default.tsx      # REQUIRED default
│   │   └── login/
│   │       └── page.tsx
│   ├── dashboard/
│   │   ├── layout.tsx
│   │   └── [id]/            # Dynamic route
│   │       └── page.tsx     # Uses async params
│   └── api/
│       └── tasks/
│           └── [id]/
│               └── route.ts # Uses async params
├── proxy.ts                 # NOT middleware.ts
├── next.config.ts           # Turbopack at top-level
├── package.json
└── tsconfig.json

Common Patterns

httpOnly Cookie Proxy (Auth Token Forwarding)

When using Better Auth or similar with httpOnly cookies, JavaScript cannot access the token. Create a server-side API route to forward requests with the token:

// app/api/proxy/[...path]/route.ts
import { NextRequest, NextResponse } from "next/server";
import { cookies } from "next/headers";

const BACKEND_URL = process.env.BACKEND_URL || "http://localhost:8000";

export async function POST(
  request: NextRequest,
  { params }: { params: Promise<{ path: string[] }> }
) {
  const { path } = await params;
  const cookieStore = await cookies();

  // Read httpOnly cookie (only accessible server-side)
  const idToken = cookieStore.get("auth_token")?.value;

  if (!idToken) {
    return NextResponse.json({ error: "Not authenticated" }, { status: 401 });
  }

  // Build target URL
  const targetPath = "/" + path.join("/");
  const url = new URL(targetPath, BACKEND_URL);

  // Forward query params
  request.nextUrl.searchParams.forEach((value, key) => {
    url.searchParams.set(key, value);
  });

  try {
    const body = await request.text();

    const response = await fetch(url.toString(), {
      method: "POST",
      headers: {
        Authorization: `Bearer ${idToken}`,
        "Content-Type": "application/json",
      },
      body: body || undefined,
    });

    // Handle SSE streaming responses
    if (response.headers.get("content-type")?.includes("text/event-stream")) {
      return new Response(response.body, {
        status: response.status,
        headers: {
          "Content-Type": "text/event-stream",
          "Cache-Control": "no-cache",
          "Connection": "keep-alive",
        },
      });
    }

    const data = await response.json().catch(() => null);
    return NextResponse.json(data, { status: response.status });
  } catch (error) {
    console.error("[Proxy] Error:", error);
    return NextResponse.json({ error: "Proxy request failed" }, { status: 500 });
  }
}

// Add GET, PUT, DELETE as needed with same pattern

Key points:

httpOnly cookies are a security feature - JavaScript cannot read them
Server-side API routes CAN read all cookies via cookies() from next/headers
Always handle SSE streaming by passing through response.body
Use credentials: "include" on client fetch to send cookies to the proxy

Evidence: web-dashboard/src/app/api/chatkit/route.ts

Script Loading for Web Components (beforeInteractive)

External web component scripts must load before React hydration. Use beforeInteractive in root layout:

// app/layout.tsx
import Script from "next/script";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <head>
        {/* MUST be in <head> with beforeInteractive for web components */}
        <Script
          src="https://cdn.example.com/web-component.js"
          strategy="beforeInteractive"
        />
      </head>
      <body>{children}</body>
    </html>
  );
}

Script strategies:

Strategy	When It Loads	Use Case
`beforeInteractive`	Before hydration, in `<head>`	Web components, critical JS
`afterInteractive`	After page interactive	Analytics, non-critical
`lazyOnload`	During idle time	Low priority

Evidence: web-dashboard/src/app/layout.tsx

Dynamic Route with Data Fetching

// app/tasks/[id]/page.tsx
import { notFound } from 'next/navigation'

interface Props {
  params: Promise<{ id: string }>
}

async function getTask(id: string) {
  const res = await fetch(`${process.env.API_URL}/api/tasks/${id}`)
  if (!res.ok) return null
  return res.json()
}

export async function generateMetadata({ params }: Props) {
  const { id } = await params
  const task = await getTask(id)
  return { title: task?.title ?? 'Task Not Found' }
}

export default async function TaskPage({ params }: Props) {
  const { id } = await params
  const task = await getTask(id)

  if (!task) notFound()

  return (
    <div>
      <h1>{task.title}</h1>
      <p>Status: {task.status}</p>
    </div>
  )
}

Search Page with Filters

// app/search/page.tsx
interface Props {
  searchParams: Promise<{
    query?: string
    status?: string
    page?: string
  }>
}

export default async function SearchPage({ searchParams }: Props) {
  const { query, status, page = '1' } = await searchParams

  const results = await fetch(
    `${process.env.API_URL}/api/search?` +
    new URLSearchParams({
      ...(query && { query }),
      ...(status && { status }),
      page,
    })
  ).then(r => r.json())

  return (
    <div>
      <h1>Search Results for: {query}</h1>
      {results.map(r => <div key={r.id}>{r.title}</div>)}
    </div>
  )
}

Proxy with Auth Check

// proxy.ts
import { NextRequest, NextResponse } from 'next/server'

const publicPaths = ['/', '/login', '/register', '/api/auth']

export function proxy(request: NextRequest) {
  const { pathname } = request.nextUrl

  // Allow public paths
  if (publicPaths.some(p => pathname.startsWith(p))) {
    return NextResponse.next()
  }

  // Check for auth token
  const token = request.cookies.get('session')?.value

  if (!token) {
    const loginUrl = new URL('/login', request.url)
    loginUrl.searchParams.set('callbackUrl', pathname)
    return NextResponse.redirect(loginUrl)
  }

  // Add user header for API routes
  const response = NextResponse.next()
  response.headers.set('x-user-token', token)
  return response
}

export const config = {
  matcher: [
    '/((?!_next/static|_next/image|favicon.ico).*)',
  ],
}

API Route with Validation

// app/api/tasks/[id]/route.ts
import { NextRequest, NextResponse } from 'next/server'

interface Props {
  params: Promise<{ id: string }>
}

export async function GET(request: NextRequest, { params }: Props) {
  const { id } = await params

  // Fetch from backend
  const res = await fetch(`${process.env.BACKEND_URL}/api/tasks/${id}`, {
    headers: {
      Authorization: request.headers.get('Authorization') ?? '',
    },
  })

  if (!res.ok) {
    return NextResponse.json(
      { error: 'Task not found' },
      { status: 404 }
    )
  }

  return NextResponse.json(await res.json())
}

export async function PATCH(request: NextRequest, { params }: Props) {
  const { id } = await params
  const body = await request.json()

  const res = await fetch(`${process.env.BACKEND_URL}/api/tasks/${id}`, {
    method: 'PATCH',
    headers: {
      'Content-Type': 'application/json',
      Authorization: request.headers.get('Authorization') ?? '',
    },
    body: JSON.stringify(body),
  })

  return NextResponse.json(await res.json(), { status: res.status })
}

next.config.ts Template

import type { NextConfig } from 'next'

const config: NextConfig = {
  // Turbopack config (was experimental.turbo)
  turbopack: {
    rules: {
      '*.svg': {
        loaders: ['@svgr/webpack'],
        as: '*.js',
      },
    },
  },

  // Cache components (was experimental.dynamicIO)
  cacheComponents: true,

  // Environment variables (public)
  env: {
    NEXT_PUBLIC_API_URL: process.env.NEXT_PUBLIC_API_URL,
  },

  // Images
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: '**.example.com',
      },
    ],
  },

  // Rewrites for API proxy
  async rewrites() {
    return [
      {
        source: '/api/:path*',
        destination: `${process.env.BACKEND_URL}/api/:path*`,
      },
    ]
  },
}

export default config

Migration Checklist

When upgrading from Next.js 15:

[ ] Rename middleware.ts to proxy.ts
[ ] Rename middleware() function to proxy()
[ ] Update all page components with async params
[ ] Update all page components with async searchParams
[ ] Update all route handlers with async params
[ ] Update generateMetadata with async params
[ ] Move turbo config from experimental.turbo to turbopack
[ ] Replace dynamicIO with cacheComponents
[ ] Add default.tsx to all parallel routes
[ ] Update next/image usage (remove layout, objectFit props)
[ ] Remove --turbopack flag from dev scripts

Common Pitfalls

1. Forgetting to await params

// WRONG - Results in Promise object, not value
export default async function Page({ params }) {
  return <div>ID: {params.id}</div>  // Shows [object Promise]
}

// CORRECT
export default async function Page({ params }) {
  const { id } = await params
  return <div>ID: {id}</div>
}

2. Using middleware.ts

// WRONG - File will be ignored
// middleware.ts

// CORRECT - Use proxy.ts
// proxy.ts
export function proxy(request) { ... }

3. Missing default.tsx in parallel routes

// WRONG - 404 during soft navigation
app/@sidebar/page.tsx

// CORRECT - Include default
app/@sidebar/default.tsx
app/@sidebar/page.tsx

4. Old turbo config location

// WRONG
experimental: { turbo: {} }

// CORRECT
turbopack: {}

5. Reading httpOnly cookies from JavaScript

// WRONG - httpOnly cookies cannot be read from JavaScript
const token = document.cookie.split('; ')
  .find(row => row.startsWith('auth_token='));
// Returns undefined even if cookie exists

// CORRECT - Use server-side API route proxy
// app/api/proxy/route.ts reads cookies via next/headers
const cookieStore = await cookies();
const token = cookieStore.get("auth_token")?.value;

6. Script afterInteractive for web components

// WRONG - Web component not defined when React renders
<Script src="https://cdn.example.com/component.js" strategy="afterInteractive" />

// CORRECT - Load before React hydration
<head>
  <Script src="https://cdn.example.com/component.js" strategy="beforeInteractive" />
</head>

References

For additional documentation, use Next.js DevTools MCP:

mcp__next-devtools__nextjs_docs with action="get" and path="/docs/app/guides/upgrading/version-16"

Or Context7:

mcp__context7__get-library-docs with context7CompatibleLibraryID="/vercel/next.js" and topic="app router"

#!/usr/bin/env python3
"""Verify building-nextjs-apps skill has required references."""
import os
import sys

def main():
    skill_dir = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
    refs_dir = os.path.join(skill_dir, "references")

    required = ["nextjs-16-patterns.md"]
    missing = [r for r in required if not os.path.isfile(os.path.join(refs_dir, r))]

    if not missing:
        print("✓ building-nextjs-apps skill ready")
        sys.exit(0)
    else:
        print(f"✗ Missing: {', '.join(missing)}")
        sys.exit(1)

if __name__ == "__main__":
    main()

Related skills

Vercel React Best PracticesAutomatically apply Vercel’s official React and Next.js performance rules during code generation and review.587k29.6k

Vercel Composition PatternsGenerate and refactor React components that stay maintainable as complexity grows without boolean prop explosion.267k29.6k

ShadcnAdd, compose, search, fix, and style production-grade React components directly from source without leaving their editor.257k120k

Develop UserscriptsCorrectly write, debug, and package userscripts for Tampermonkey and ScriptCat with proper metadata, GM APIs, and runtime decisions.224k72

Minimalist UiGenerate clean, editorial-style web interfaces with warm monochrome palettes, typographic hierarchy, bento grids and flat components that feel premium and utilita212k69.4k

Image To CodeConvert high-fidelity design images into production-ready, visually accurate frontend code that avoids generic AI design pitfalls.177k69.4k

FAQ

What is the most common Next.js 16 mistake?

Treating params and searchParams as plain objects; in Next.js 16 they are Promises and must be awaited.

What replaces middleware.ts?

proxy.ts replaces middleware.ts in Next.js 16.

Frontend Developmentfrontend

About

Building Nextjs Apps by the numbers

building-nextjs-apps capabilities & compatibility

What building-nextjs-apps says it does

Add your badge

What it does

Who is it for?

When should I use this skill?

What you get

By the numbers

Files

Next.js 16 Applications

Critical Breaking Changes (Next.js 16)

1. params and searchParams are Now Promises

2. Client Components Need use() Hook

3. searchParams Also Async

Core Patterns

Project Setup

App Router Layout

Dynamic Routes

Server Actions

API Routes

Middleware → proxy.ts

Data Fetching

Server Component (Default)

Client Component

Project Structure

Next.js DevTools MCP

Setup

Available Tools

Key Use Cases

Next.js 16 MCP Endpoint

Verification

If Verification Fails

Related Skills

References

DateTime and Timezone Patterns

The Golden Rule

Critical Pitfall: datetime-local Input

The Bug

The Fix

Frontend Patterns (TypeScript/React)

Converting datetime-local to UTC

Converting UTC to datetime-local (for editing)

Full Form Example

Backend Patterns (Python/FastAPI)

Pydantic Validator

Database Storage

Displaying Times

Common Pitfalls

Summary

Frontend Aesthetics Guidelines

Design Thinking

Key Focus Areas

Typography

Color & Theme

Motion

Spatial Composition

Backgrounds & Visual Details

NEVER Use

Next.js 16

When to Use

Critical Breaking Changes

1. params and searchParams are Now Promises

2. middleware.ts is Now proxy.ts

3. Turbopack is Now Default

4. cacheComponents Replaces dynamicIO

5. Parallel Routes Require default.js

6. Image Component Changes

7. Route Handlers Async Context

Quick Start

Project Structure (Next.js 16)

Common Patterns

httpOnly Cookie Proxy (Auth Token Forwarding)

Script Loading for Web Components (beforeInteractive)

Dynamic Route with Data Fetching

Search Page with Filters

Proxy with Auth Check

API Route with Validation

next.config.ts Template