home / skills / bobmatnyc / claude-mpm-skills / v16

v16 skill

safe

This skill guides migrating to Next.js 16 by outlining async request patterns, opt-in caching, and Turbopack usage to improve performance.

npx playbooks add skill bobmatnyc/claude-mpm-skills --skill v16

Review the files below or copy the command above to add this skill to your agents.

Files (5)

SKILL.md

759 B

---
name: nextjs-v16
description: Next.js 16 migration guide (async request APIs, "use cache", Turbopack)
version: 1.1.0
category: toolchain
progressive_disclosure:
  entry_point:
    summary: "Next.js 16 migration: async request APIs + opt-in caching"
tags: [nextjs, nextjs-16]
---

# Next.js 16

- Async `params`/`cookies`/`headers`; opt-in caching via `"use cache"`; Turbopack default.

Anti-patterns:

- ❌ Sync request APIs; ✅ `await` `params`, `cookies()`, and `headers()`.
- ❌ Keep `middleware.ts`; ✅ use `proxy.ts` and `export function proxy`.
- ❌ `revalidateTag("posts")`; ✅ `revalidateTag("posts", "max")` or `{ expire: ... }`.

References: `references/migration-checklist.md`, `references/cache-components.md`, `references/turbopack.md`

Overview

This skill is a concise migration guide for upgrading projects to Next.js 16, focusing on async request APIs, opt-in caching with "use cache", and the new Turbopack default. It distills key anti-patterns, recommended replacements, and pragmatic examples so teams can adopt Next.js 16 with minimal regressions. The guidance is implementation-focused, helping maintainers update middleware, caching calls, and build tooling quickly.

How this skill works

The skill inspects common migration touchpoints and explains the required code changes and API behaviors. It highlights synchronous-to-async transitions for request data, shows how to opt into component caching, and describes swapping Webpack for Turbopack as the default bundler. Each recommendation lists the anti-pattern, the correct pattern, and a short rationale to reduce trial-and-error during migration.

When to use it

When upgrading an existing Next.js project from a pre-16 release to Next.js 16.
When server components or request APIs still use synchronous access patterns.
When you want predictable component caching and must opt into cache semantics.
When diagnosing build-time or runtime issues after enabling Turbopack.
When refactoring middleware to avoid deprecated middleware.ts usage.

Best practices

Make params(), cookies(), and headers() calls with await and treat them as async APIs.
Replace legacy middleware.ts with proxy.ts and export function proxy to handle edge routing.
Use explicit cache control: annotate components with "use cache" or pass expire options to revalidateTag.
Prefer revalidateTag('name', 'max') or revalidateTag('name', { expire: ... }) over the old single-arg call.
Test builds under Turbopack early in feature branches to surface compatibility issues quickly.

Example use cases

Converting server components that synchronously read cookies to await cookies() and adjust logic accordingly.
Replacing middleware.ts logic with an exported proxy function to keep routing behavior under Next.js 16.
Adding "use cache" to layout or component files to opt into automatic caching where appropriate.
Changing revalidation calls to include an expiration option to avoid stale tag behavior.
Switching CI pipelines to run a Turbopack build step and validating output parity with Webpack.

FAQ

Do I have to change every header/cookie access to await?

Yes. Next.js 16 exposes params, cookies, and headers as async providers; update accesses to use await to avoid runtime errors.

What if Turbopack breaks my build?

Run a parallel Webpack build in CI while you fix incompatibilities. Enable Turbopack progressively and test increments to isolate breaking changes.