Next.js 16 Launchpad

Next.js 16 Launchpad

Next.js 16: Turbopack default (2-5× faster builds), Cache Components ('use cache'), and proxy.ts for explicit control.

When to Use

✅ Next.js 16, Turbopack, Cache Components, proxy migration, App Router, React 19.2

❌ Pages Router, Next.js ≤15, generic React questions

Requirements

Quick Start

# New project
npx create-next-app@latest my-app

# Upgrade existing
npx @next/​codemod@canary upgrade latest
npm install next@latest react@latest react-dom@latest

Recommended: TypeScript, ESLint, Tailwind, App Router, Turbopack, @/​* alias.

Minimal Setup

// app/​layout.tsx
export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>{children}</​body>
    </​html>
  )
}

// app/​page.tsx
export default function Page() {
  return <h1>Hello, Next.js 16!</​h1>
}

Configuration

// next.config.ts
import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  cacheComponents: true,
  reactCompiler: true,
}

export default nextConfig

v15 → v16 Changes

Core Patterns

1. Server Components (Default)

export default async function BlogPage() {
  const res = await fetch('https://api.example.com/​posts')
  const posts = await res.json()
  return <PostList posts={posts} />
}

2. Cache Components

import { cacheLife } from 'next/​cache'

export default async function BlogPage() {
  'use cache'
  cacheLife('hours')
  const posts = await fetch('https://api.example.com/​posts').then(r => r.json())
  return <PostList posts={posts} />
}

3. Client Components

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

export default function Counter() {
  const [count, setCount] = useState(0)
  return (
    <div>
      <p>Count: {count}</​p>
      <button onClick={() => setCount(count + 1)}>+</​button>
    </​div>
  )
}

4. Proxy Boundary

// app/​proxy.ts
export function proxy(request: NextRequest) {
  if (!request.cookies.get('auth') && request.nextUrl.pathname.startsWith('/​dashboard')) {
    return NextResponse.redirect(new URL('/​login', request.url))
  }
  return NextResponse.next()
}

5. Cache Tags + Server Actions

// app/​blog/​page.tsx
'use cache'
cacheLife('hours')
cacheTag('blog-posts')

export default async function BlogList() {
  const posts = await db.posts.findMany()
  return <PostList posts={posts} />
}

// app/​actions.ts
'use server'
import { updateTag } from 'next/​cache'

export async function createPost(data: PostData) {
  await db.posts.create(data)
  updateTag('blog-posts')
}

6. Streaming with Suspense

export default function Dashboard() {
  return (
    <div>
      <Suspense fallback={<Skeleton />}>
        <RevenueCard />
      </​Suspense>
      <Suspense fallback={<Skeleton />}>
        <UsersCard />
      </​Suspense>
    </​div>
  )
}

async function RevenueCard() {
  const data = await db.analytics.revenue()
  return <div>{data}</​div>
}

Key Concepts

1. Turbopack - Rust bundler, incremental compilation, Fast Refresh
2. Server Components - Default in app/, zero client JS
3. Client Components - 'use client', hooks, browser APIs
4. Cache Components - 'use cache' + cacheLife() for PPR
5. Proxy Boundary - proxy.ts for auth/​rewrites/​redirects
6. Partial Pre-Rendering - Static shell + dynamic streaming

Migration Checklist

1. Async Request APIs

   npx @next/​codemod@canary async-request-api
   

   Update: const { slug } = await params

2. middleware.ts → proxy.ts

   • Rename file, export proxy
   • Node runtime only (not Edge)

3. Config updates

   • Remove experimental.* flags
   • Enable cacheComponents, reactCompiler
   • Remove serverRuntimeConfig/publicRuntimeConfig

4. Cache Components

   • Replace experimental.ppr with cacheComponents: true
   • Wrap dynamic sections with <Suspense>

5. Images

   • Configure images.localPatterns for query strings

See references/​nextjs16-migration-playbook.md for complete guide.

Common Pitfalls

❌ Mixing 'use cache' with runtime APIs (cookies(), headers()) ❌ Missing <Suspense> when Cache Components enabled ❌ Tilde Sass imports under Turbopack ❌ Running proxy.ts on Edge runtime

✅ Read cookies/​headers first, pass as props to cached components ✅ Wrap dynamic children in <Suspense> ✅ Use standard Sass imports ✅ Use Node runtime for proxy

Decision Guide

Enable Cache Components? → Yes for static/​semi-static content → No for fully dynamic dashboards

Where does auth live? → proxy.ts for cross-route checks → Route handlers for API-specific logic

When to use 'use client'? → Only when you need hooks, state, or browser APIs → Keep presentational components server-side

Production Patterns

E-commerce

// Product page with streaming
export default async function Product({ params }) {
  const { id } = await params
  const product = await db.products.findById(id)
  
  return (
    <>
      <ProductInfo product={product} />
      <Suspense fallback={<ReviewsSkeleton />}>
        <Reviews productId={id} />
      </​Suspense>
    </>
  )
}

Authenticated Dashboard

// proxy.ts
export function proxy(request: NextRequest) {
  const session = request.cookies.get('session')
  if (!session && request.nextUrl.pathname.startsWith('/​dashboard')) {
    return NextResponse.redirect(new URL('/​login', request.url))
  }
}

See references/​nextjs16-advanced-patterns.md for more blueprints.

Performance

• Keep Turbopack enabled (opt-out with --webpack only if needed)
• Parallelize fetches with Promise.all
• Use <Suspense> for streaming boundaries
• Enable file system cache for large repos

Security

• Use server-only package + React Taint API
• Keep auth in proxy.ts
• Validate inputs in Server Actions
• Gate env vars with NEXT_PUBLIC_ prefix
• Extract cookies/​headers before cached scopes

Deployment

• Vercel: Zero-config
• Docker/​Node: output: 'standalone'
• Monitor build times (2-5× speedup expected)
• Configure cache lifecycles to match CDN

Reference Files

• references/​nextjs16-reference.md - Install/​config/​checklists
• references/​nextjs16-migration-playbook.md - Migration guide with codemods
• references/​nextjs16-advanced-patterns.md - Streaming, caching, auth patterns
• references/​NEXTJS_16_COMPLETE_GUIDE.md - Complete documentation
• scripts/​bootstrap-nextjs16.ps1 - Automated setup script
• assets/​app-router-starter/​ - Reference implementation

Resources

• Docs: https://nextjs.org/docs
• GitHub: https://github.com/vercel/next.js

Version: 1.1.0 | Updated: 2025-12-27