nextjs-16
Use when building Next.js 16 apps — Turbopack, App Router, Cache Components, proxy.ts, v15 migration. Not for stack scaffolding (nextjs-stack) or React SPA (react-expert).
How do I install this agent skill?
npx skills add https://github.com/fusengine/claude-plugins --skill nextjs-16Is this agent skill safe to install?
- Gen Agent Trust Hubpass
This skill provides documentation for a fictional version of Next.js (version 16) and enforces a specific, non-standard workflow for the AI agent. It also encourages the use of an unverified third-party tool (next-devtools-mcp). While not explicitly malicious, the deceptive versioning and meta-instructions could lead the agent to generate incorrect code or install unnecessary software.
- Socketpass
No alerts
- Snykfail
Risk: CRITICAL · 2 issues
What does this agent skill do?
Documents the critical v15→v16 breaking changes: proxy.ts replacing middleware.ts, Turbopack as the default for next dev/next build, cacheComponents replacing the removed experimental.ppr flag, required React 19, and async params/searchParams. This skill covers core framework APIs only — for assembling a full production stack (Prisma, Better Auth, shadcn/ui, Zustand together) use nextjs-stack instead; for a pure React SPA without next.config.* use the react-expert skills instead.
</objective>
Next.js 16 Expert
Production-ready React framework with Server Components, streaming, and Turbopack.
Agent Workflow (MANDATORY)
Before ANY implementation, spawn 3 agents in parallel, one Agent call each with a name:
- 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 only via --webpack opt-out |
| 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 by default -
next dev/next builduse Turbopack; a customwebpackconfig fails the build unless you migrate it or opt out with--webpack cacheComponents+use cache- Replacesexperimental.ppr/experimental_ppr(removed); PPR is the default behavior undercacheComponents- React 19 required - New hooks and View Transitions API
- Async params/searchParams - Must await dynamic route params
Cache Components: the recommended model (16.4+)
Since 16.4 Cache Components is recommended for every Next.js app, create-next-app enables it by default, and it becomes the default in Next.js 17. Data fetching is dynamic by default; opt in to caching per component/function with 'use cache'. Use the two-flag setup (cacheComponents: true + partialPrefetching: true, set partialPrefetching explicitly) for new code and when touching caching/data fetching; see cache-components.md. Existing apps: npx next@canary upgrade --agent=latest (see upgrade.md).
New in 16.1 – 16.4 (see upgrade.md)
- 16.1 - Turbopack filesystem cache on by default for
next dev;next dev --inspect - 16.2 -
transitionTypesprop on<Link>,next start --inspect, Adapters API stable - 16.3 -
catchError+retry()error recovery (stable),next/root-params,import.meta.glob, Turbopack build cache on by default, opt-in Instant Navigations (partialPrefetchingwithcacheComponents) - 16.4 - Cache Components recommended for all apps (on by default in
create-next-app, default in Next.js 17);ensureStaticroute segment config;navigation()/prefetch()fromnext/cache;next upgrade --agent+experimental.agentUpgrade; React 19.3 (stable View Transitions, Fragment Refs,browser()); lazy server HMR, smaller Turbopack disk cache and production bundles
SOLID Architecture
Module-Based Structure
Pages are thin entry points importing from feature modules:
app/page.tsx→ imports frommodules/public/home/app/dashboard/page.tsx→ imports frommodules/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
- Default - With
cacheComponentson (recommended, 16.4+) data fetching is dynamic; wrap uncached runtime access in<Suspense>and cache explicitly 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 cachefor 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
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/fusengine/claude-plugins/nextjs-16">View nextjs-16 on skillZs</a>