Next.js 16 Expert
Production-ready React framework with Server Components, streaming, and Turbopack.
Agent Workflow (MANDATORY)
Before ANY implementation, use TeamCreate to spawn 3 agents:
- fuse-ai-pilot:explore-codebase - Analyze existing routes, components, and patterns
- fuse-ai-pilot:research-expert - Verify latest Next.js 16 docs via Context7/Exa
- mcp__context7__query-docs - Check breaking changes v15→v16
After implementation, run fuse-ai-pilot:sniper for validation.
Overview
When to Use
- Building new React applications with server-first architecture
- Need Server Components for optimal performance and SEO
- Implementing streaming and progressive rendering
- Migrating from Next.js 14/15 to version 16
- Using proxy.ts for route protection (replaces middleware)
- Leveraging Turbopack for faster development builds
Why Next.js 16
| Feature |
Benefit |
| Turbopack default |
2-5x faster builds, 10x faster HMR, Webpack deprecated |
| Cache Components |
Explicit caching with use cache directive |
| proxy.ts |
Full Node.js runtime, replaces Edge middleware |
| React Compiler |
Automatic memoization, no manual useMemo/useCallback |
| React 19 |
View Transitions, useEffectEvent, Activity component |
| App Router |
Nested layouts, parallel routes, intercepting routes |
Breaking Changes from v15
Critical Migration Points
- proxy.ts replaces middleware.ts - Full Node.js runtime, not Edge
- Turbopack ONLY - Webpack completely deprecated and removed
use cache directive - Replaces Partial Prerendering (PPR)- React 19 required - New hooks and View Transitions API
- Async params/searchParams - Must await dynamic route params
SOLID Architecture
Module-Based Structure
Pages are thin entry points importing from feature modules:
app/page.tsx → imports from modules/public/home/app/dashboard/page.tsx → imports from modules/auth/dashboard/modules/cores/ → Shared services, utilities, configurations
File Conventions
- page.tsx - Route UI component
- layout.tsx - Shared UI wrapper
- loading.tsx - Suspense loading state
- error.tsx - Error boundary
- not-found.tsx - 404 handling
Core Concepts
Server Components (Default)
All components are Server Components by default. Use 'use client' directive only when needed for interactivity, hooks, or browser APIs.
Caching Strategy
use cache - Mark async functions for cachingcacheTag() - Tag cached data for targeted revalidationcacheLife() - Control cache duration (stale, revalidate, expire)revalidateTag() - Invalidate cached data on-demand
Data Fetching
Server Components fetch data directly. Use fetch() with native caching or database queries. No need for getServerSideProps or getStaticProps.
Reference Guide
| Need |
Reference |
| Initial setup |
installation.md, project-structure.md |
| Migration v15→v16 |
upgrade.md, middleware-migration.md |
| Routing |
app-router.md, routing-advanced.md |
| Caching |
caching.md, cache-components.md |
| Server Components |
server-components.md, directives.md |
| React 19 features |
react-19.md, react-compiler.md |
| Route protection |
proxy.md, security.md |
| SEO/Metadata |
metadata.md, metadata-files.md |
| Forms/Actions |
forms.md, data-fetching.md |
| Deployment |
deployment.md, environment.md |
Best Practices
- Server Components first - Only add
'use client' when necessary
- Colocate data fetching - Fetch data where it's used
- Streaming with Suspense - Wrap slow components in Suspense
- proxy.ts over middleware - Full Node.js runtime for auth
- Cache explicitly - Use
use cache for expensive operations
- Parallel routes - Load independent UI sections simultaneously
Performance
Build Optimization
- Turbopack - Incremental compilation, instant HMR
- React Compiler - Automatic memoization
- Tree shaking - Unused code elimination
- Code splitting - Automatic route-based splitting
Runtime Optimization
- Streaming - Progressive HTML rendering
- Partial hydration - Only hydrate interactive components
- Image optimization - Automatic WebP/AVIF conversion
- Font optimization - Zero layout shift with next/font
1---2name: nextjs-16-33description: Expert Next.js 16 with Turbopack, App Router, Cache Components, proxy.ts, React 19. Use when building Next.js apps, routing, caching, server components, or migrating from v15.4---5
6# Next.js 16 Expert
7
8Production-ready React framework with Server Components, streaming, and Turbopack.
9
10## Agent Workflow (MANDATORY)
11
12Before ANY implementation, use `TeamCreate` to spawn 3 agents:
13
141. **fuse-ai-pilot:explore-codebase** - Analyze existing routes, components, and patterns
152. **fuse-ai-pilot:research-expert** - Verify latest Next.js 16 docs via Context7/Exa
163. **mcp__context7__query-docs** - Check breaking changes v15→v16
17
18After implementation, run **fuse-ai-pilot:sniper** for validation.
19
20---
21
22## Overview
23
24### When to Use
25
26- Building new React applications with server-first architecture
27- Need Server Components for optimal performance and SEO
28- Implementing streaming and progressive rendering
29- Migrating from Next.js 14/15 to version 16
30- Using proxy.ts for route protection (replaces middleware)
31- Leveraging Turbopack for faster development builds
32
33### Why Next.js 16
34
35| Feature | Benefit |
36|---------|---------|
37| Turbopack default | 2-5x faster builds, 10x faster HMR, Webpack deprecated |
38| Cache Components | Explicit caching with `use cache` directive |
39| proxy.ts | Full Node.js runtime, replaces Edge middleware |
40| React Compiler | Automatic memoization, no manual useMemo/useCallback |
41| React 19 | View Transitions, useEffectEvent, Activity component |
42| App Router | Nested layouts, parallel routes, intercepting routes |
43
44---
45
46## Breaking Changes from v15
47
48### Critical Migration Points
49
501. **proxy.ts replaces middleware.ts** - Full Node.js runtime, not Edge
512. **Turbopack ONLY** - Webpack completely deprecated and removed
523. **`use cache` directive** - Replaces Partial Prerendering (PPR)
534. **React 19 required** - New hooks and View Transitions API
545. **Async params/searchParams** - Must await dynamic route params
55
56---
57
58## SOLID Architecture
59
60### Module-Based Structure
61
62Pages are thin entry points importing from feature modules:
63
64- `app/page.tsx` → imports from `modules/public/home/`
65- `app/dashboard/page.tsx` → imports from `modules/auth/dashboard/`
66- `modules/cores/` → Shared services, utilities, configurations
67
68### File Conventions
69
70- **page.tsx** - Route UI component
71- **layout.tsx** - Shared UI wrapper
72- **loading.tsx** - Suspense loading state
73- **error.tsx** - Error boundary
74- **not-found.tsx** - 404 handling
75
76---
77
78## Core Concepts
79
80### Server Components (Default)
81
82All components are Server Components by default. Use `'use client'` directive only when needed for interactivity, hooks, or browser APIs.
83
84### Caching Strategy
85
86- **`use cache`** - Mark async functions for caching
87- **`cacheTag()`** - Tag cached data for targeted revalidation
88- **`cacheLife()`** - Control cache duration (stale, revalidate, expire)
89- **`revalidateTag()`** - Invalidate cached data on-demand
90
91### Data Fetching
92
93Server Components fetch data directly. Use `fetch()` with native caching or database queries. No need for `getServerSideProps` or `getStaticProps`.
94
95---
96
97## Reference Guide
98
99| Need | Reference |
100|------|-----------|
101| Initial setup | [installation.md](references/installation.md), [project-structure.md](references/project-structure.md) |
102| Migration v15→v16 | [upgrade.md](references/upgrade.md), [middleware-migration.md](references/middleware-migration.md) |
103| Routing | [app-router.md](references/app-router.md), [routing-advanced.md](references/routing-advanced.md) |
104| Caching | [caching.md](references/caching.md), [cache-components.md](references/cache-components.md) |
105| Server Components | [server-components.md](references/server-components.md), [directives.md](references/directives.md) |
106| React 19 features | [react-19.md](references/react-19.md), [react-compiler.md](references/react-compiler.md) |
107| Route protection | [proxy.md](references/proxy.md), [security.md](references/security.md) |
108| SEO/Metadata | [metadata.md](references/metadata.md), [metadata-files.md](references/metadata-files.md) |
109| Forms/Actions | [forms.md](references/forms.md), [data-fetching.md](references/data-fetching.md) |
110| Deployment | [deployment.md](references/deployment.md), [environment.md](references/environment.md) |
111
112---
113
114## Best Practices
115
1161. **Server Components first** - Only add `'use client'` when necessary
1172. **Colocate data fetching** - Fetch data where it's used
1183. **Streaming with Suspense** - Wrap slow components in Suspense
1194. **proxy.ts over middleware** - Full Node.js runtime for auth
1205. **Cache explicitly** - Use `use cache` for expensive operations
1216. **Parallel routes** - Load independent UI sections simultaneously
122
123---
124
125## Performance
126
127### Build Optimization
128
129- **Turbopack** - Incremental compilation, instant HMR
130- **React Compiler** - Automatic memoization
131- **Tree shaking** - Unused code elimination
132- **Code splitting** - Automatic route-based splitting
133
134### Runtime Optimization
135
136- **Streaming** - Progressive HTML rendering
137- **Partial hydration** - Only hydrate interactive components
138- **Image optimization** - Automatic WebP/AVIF conversion
139- **Font optimization** - Zero layout shift with next/font
majiayu000