nextjs-16_skill

Overview

This skill teaches correct patterns for building and upgrading Next.js 16 applications, focusing on breaking changes and new defaults. It prevents common mistakes around async params/searchParams, proxy-based request handling, Turbopack configuration, and cacheComponents. Use it to enforce reliable routes, layouts, proxies, and image/route-handler updates for Next.js 16.

How this skill works

The skill inspects component and route patterns and provides concrete replacements for Next.js 15 idioms that would fail in Next.js 16. It highlights where params and searchParams must be awaited, enforces proxy.ts usage over middleware.ts, and guides top-level Turbopack and cacheComponents configuration. It also offers patterns for parallel routes, image usage, server-side proxying with httpOnly cookies, and route handler updates.

When to use it

• Starting a new Next.js 16 project
• Upgrading an app from Next.js 15 to 16
• Implementing dynamic routes, generateMetadata, or route handlers
• Replacing middleware with server-side request proxying (proxy.ts)
• Configuring Turbopack rules at top-level and enabling cacheComponents
• Fixing image props and parallel route default components

Best practices

• Always declare page/layout/route handler params and searchParams as Promise types and await them before use
• Place proxy.ts at project root and export proxy(request) with matcher config — do not use middleware.ts
• Move Turbopack config to next.config.ts top-level turbopack section; remove --turbopack flags
• Enable cacheComponents instead of experimental.dynamicIO in next.config.ts
• Provide default.tsx for every parallel route folder to avoid 404s on soft navigation
• Use server-side API proxies to read httpOnly cookies and forward auth tokens; handle SSE by streaming response.body

Example use cases

• Dynamic product page using async params in page, layout, and generateMetadata
• Global auth proxy in proxy.ts that redirects unauthenticated requests and forwards token headers
• API proxy route that reads httpOnly cookie and forwards requests to backend, including SSE streaming support
• Turbopack rule to handle SVGs with @svgr/webpack configured at top-level
• Search page that awaits searchParams and builds server-side fetch queries