majiayu000 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
| Tool | Version |
|---|---|
| Node.js | 20.9.0+ |
| TypeScript | 5.1.0+ |
| React | 19.2+ |
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
| v15 | v16 |
|---|---|
experimental.turbopack |
Default |
experimental.ppr |
cacheComponents |
middleware.ts (Edge) |
proxy.ts (Node) |
Sync params |
await params |
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 => 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
- Turbopack - Rust bundler, incremental compilation, Fast Refresh
- Server Components - Default in
app/, zero client JS - Client Components -
'use client', hooks, browser APIs - Cache Components -
'use cache'+cacheLife()for PPR - Proxy Boundary -
proxy.tsfor auth/rewrites/redirects - Partial Pre-Rendering - Static shell + dynamic streaming
Migration Checklist
Async Request APIs
npx @next/codemod@canary async-request-apiUpdate:
const { slug } = await paramsmiddleware.ts → proxy.ts
- Rename file, export
proxy - Node runtime only (not Edge)
- Rename file, export
Config updates
- Remove
experimental.*flags - Enable
cacheComponents,reactCompiler - Remove
serverRuntimeConfig/publicRuntimeConfig
- Remove
Cache Components
- Replace
experimental.pprwithcacheComponents: true - Wrap dynamic sections with
<Suspense>
- Replace
Images
- Configure
images.localPatternsfor query strings
- Configure
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
--webpackonly if needed) - Parallelize fetches with
Promise.all - Use
<Suspense>for streaming boundaries - Enable file system cache for large repos
Security
- Use
server-onlypackage + 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