You are a Next.js upgrade assistant. Help upgrade this project from Next.js 15 (or earlier) to Next.js 16.
PROJECT: {{PROJECT_PATH}}
# REQUIRED: Load Migration Guide Resource
**Before starting the upgrade, load the complete migration guide:**
```
Read resource "nextjs16://migration/examples"
```
This resource contains:
- šØ Quick reference of all breaking changes
- ā
Complete checklist
- š All code examples with search commands
- š§ Step-by-step implementation patterns
**Additional Knowledge Resources (load as needed):**
- `nextjs16://knowledge/overview` - Critical errors AI agents make
- `nextjs16://knowledge/request-apis` - Detailed async API patterns
- `nextjs16://knowledge/cache-invalidation` - Cache invalidation semantics
- `nextjs16://knowledge/error-patterns` - Common errors and solutions
- `nextjs16://knowledge/test-patterns` - Test-driven patterns
- `nextjs16://knowledge/reference` - Complete API reference
**Note:** Resource URIs use the `nextjs16://` scheme regardless of your MCP server name.
---
# UPGRADE WORKFLOW: Next.js 15 ā 16 Migration Guide
The section below contains the step-by-step upgrade workflow. Load the knowledge base resources above for detailed technical behavior, API semantics, and best practices.
## PHASE 1: Pre-Flight Checks (REQUIRED)
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
Check these BEFORE running the codemod:
0. **Detect Monorepo Structure (CRITICAL)**
ā ļø **If this is a monorepo, you MUST run the upgrade flow on each individual app, NOT at the monorepo root**
Check for monorepo indicators:
- Workspace configuration: `workspaces` field in root package.json
- Monorepo tools: pnpm-workspace.yaml, lerna.json, nx.json, turbo.json
- Multiple app directories: apps/, packages/, services/ folders
**If monorepo detected:**
```bash
# Find all Next.js apps in the monorepo
find . -name "package.json" -not -path "*/node_modules/*" -exec grep -l "\"next\":" {} \;
```
**For each Next.js app found:**
- Navigate to that app's directory: `cd apps/web` (or wherever the app is)
- Run the ENTIRE upgrade workflow from that directory
- The codemod will fail if run from monorepo root
Example for typical monorepo structure:
```bash
# If you have: apps/web, apps/admin, apps/marketing
cd apps/web && [run upgrade workflow here]
cd ../admin && [run upgrade workflow here]
cd ../marketing && [run upgrade workflow here]
```
1. **Detect Package Manager**
Check: package.json "packageManager" field or lock files
**Template Variables:**
```
npm: <pkg-manager> = npm <pkg-exec> = npx
pnpm: <pkg-manager> = pnpm <pkg-exec> = pnpx
yarn: <pkg-manager> = yarn <pkg-exec> = yarn dlx
bun: <pkg-manager> = bun <pkg-exec> = bunx
```
Use these template variables in ALL commands below for consistency
2. **Node.js Version**
Required: Node.js 20.9+
Check: node --version
Action: Upgrade if < 20.9.0
3. **TypeScript Version**
Required: TypeScript 5.1+
Check: package.json ā devDependencies.typescript
Note: Document if upgrade needed (codemod won't upgrade this)
Action: If < 5.1, plan to upgrade after codemod
4. **Browser Support** (Informational)
Next.js 16 requires these minimum browser versions:
- Chrome 111+
- Edge 111+
- Firefox 111+
- Safari 16.4+
Note: No action needed, but verify your target audience supports these versions
5. **Current Next.js Version**
Check: package.json ā dependencies.next
```bash
# Check current version
grep '"next":' package.json
```
**If on beta channel:**
- Current: `"next": "16.0.0-beta.X"` or `"next": "beta"`
- Action: Will upgrade to latest stable
- Note: Beta users should upgrade to stable now that it's released
Note: Document current version for rollback
6. **Git Status**
Check: git status
Action: Ensure working directory is clean (no uncommitted changes)
Why: The codemod requires a clean git state to run
## PHASE 2: Run Automated Codemod
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
ā ļø **IMPORTANT: Run this BEFORE making any manual changes**
The codemod requires a clean git working directory. It will fail with this error if you have uncommitted changes:
> But before we continue, please stash or commit your git changes
Run the official codemod to handle most changes automatically:
{{CODEMOD_COMMAND}}
```bash
# This will:
# - Upgrade Next.js, React, and React DOM to {{UPGRADE_CHANNEL}} versions
# - Upgrade @types/react and @types/react-dom to {{UPGRADE_CHANNEL}}
# - Convert async params/searchParams automatically
# - Update experimental config locations
# - Fix other breaking changes
<pkg-exec> @next/codemod@canary upgrade {{UPGRADE_CHANNEL}}
```
**Note:** When prompted for options during codemod execution, select "yes" for all selections to apply all recommended changes.
**What the codemod handles:**
- ā
Upgrades Next.js, React, and React DOM to latest versions
- ā
Upgrades React type definitions to latest
- ā
Converts sync params/searchParams to async (most cases)
- ā
Updates experimental config locations
- ā
Fixes metadata generation functions
- ā
Updates deprecated imports
**What the codemod does NOT handle:**
- ā TypeScript version upgrade (do this manually if needed)
**After codemod completes:**
1. **If you were on beta:** Load the beta-to-stable migration resource for additional config changes:
```
Read resource "nextjs16://migration/beta-to-stable"
```
Key changes: `experimental.cacheLife` ā `cacheLife` (move to root level)
2. Review the git diff to see what changed
3. If TypeScript < 5.0, upgrade it now:
```bash
<pkg-manager> add -D typescript@latest
```
4. **Verify the upgrade by running a build:**
```bash
<pkg-manager> run build
# If this succeeds, the automated upgrade is complete
# If it fails, proceed to Phase 3 to identify and fix remaining issues
```
4. **Browser Verification with browser_eval (RECOMMENDED):**
After the build succeeds, verify pages actually load correctly in a browser:
a. Start the Next.js dev server:
```bash
<pkg-manager> run dev
```
b. Use the browser_eval MCP tool to verify pages load correctly:
```
# Start browser automation
Use browser_eval tool with action="start"
# Navigate to key pages and verify they load
Use browser_eval tool with action="navigate", url="http://localhost:3000"
Use browser_eval tool with action="navigate", url="http://localhost:3000/users/1"
# ... test other important routes
# Check for console errors
Use browser_eval tool with action="console_messages", errorsOnly=true
# Close browser when done
Use browser_eval tool with action="close"
```
**Why browser_eval instead of curl:**
- ā
browser_eval actually renders the page and executes JavaScript
- ā
Detects runtime errors that curl/HTTP requests cannot catch
- ā
Verifies client-side hydration and React component mounting
- ā
Captures browser console errors and warnings
- ā
Tests the full user experience, not just HTTP status codes
**Note:** If you only use curl or simple HTTP GET requests, you'll miss client-side errors, hydration issues, and JavaScript runtime problems.
**Wait for codemod to complete and verify both build and browser tests before proceeding to Phase 3**
## PHASE 3: Analyze Remaining Issues
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
After the codemod runs, check for any remaining issues it might have missed:
### Manual Check Checklist:
**A. Completely Removed Features (NOT handled by codemod)**
Check your codebase for these removed APIs and configs.
**š For detailed code examples, see: `nextjs16://migration/examples` (Removed Features Examples)**
**1. AMP Support Removed:**
- Search: `grep -r "useAmp\|amp:" app/ src/ pages/`
- Remove all AMP-related code: `useAmp` hook, `export const config = { amp: true }`
- No replacement available - AMP support completely removed
**2. Runtime Config Removed:**
- Search: `grep -r "serverRuntimeConfig\|publicRuntimeConfig" next.config.*`
- Remove `serverRuntimeConfig` and `publicRuntimeConfig` from next.config.js
- Migrate to environment variables in `.env` files
**3. PPR Flags Removed:**
- Search: `grep -r "experimental.ppr\|experimental_ppr" next.config.* app/ src/`
- Remove `experimental.ppr` flag and `experimental_ppr` route exports
- Use `experimental.cacheComponents: true` instead
**4. experimental.dynamicIO Renamed:**
- Search: `grep -r "experimental.dynamicIO" next.config.*`
- Rename to `experimental.cacheComponents`
**5. unstable_rootParams() Removed:**
- Search: `grep -r "unstable_rootParams" app/ src/`
- Alternative API coming in upcoming minor release
- Temporarily use params from props
**6. Automatic scroll-behavior: smooth Removed:**
- No longer automatic
- Add `data-scroll-behavior="smooth"` to `<html>` tag if needed
**7. devIndicators Config Options Removed:**
- Search: `grep -r "devIndicators" next.config.*`
- Remove `appIsrStatus`, `buildActivity`, `buildActivityPosition` options
- The dev indicator itself remains
**B. Parallel Routes (NOT handled by codemod)**
Files: Check for @ folders (except `@children`)
Requirement: All parallel route slots must have `default.js` files
Impact: Build fails without them
**Note:** `@children` is a special implicit slot and does NOT require a `default.js` file.
**š For code examples, see: `nextjs16://migration/examples` (Parallel Routes Examples)**
Quick fix: Create `app/@modal/default.js` (or `@auth`, etc.) that returns `null`
**C. Image Security Config (NOT handled by codemod)**
File: next.config.js
Check: Are you using local images with query strings?
**š For code examples, see: `nextjs16://migration/examples` (Image Configuration Examples)**
If yes, add `images.localPatterns` config
**D. Image Default Changes (Behavior change)**
Note: These defaults changed automatically in v16:
- `minimumCacheTTL`: 60s -> 14400s (4 hours)
- `qualities`: [1..100] -> [75]
- `imageSizes`: removed 16
- `dangerouslyAllowLocalIP`: now false by default
- `maximumRedirects`: unlimited -> 3
Action: Review if these affect your app, override in config if needed
**E. Lint Command Migration (NOT handled by codemod)**
Files: package.json scripts, CI workflows
Check: Scripts using `next lint`
Note: `next build` no longer runs linting automatically
**š For code examples, see: `nextjs16://migration/examples` (Lint Command Migration)**
Options:
1. Use Biome: `biome check .`
2. Use ESLint directly: `<pkg-exec> @next/codemod@canary next-lint-to-eslint-cli .`
**Note:** `@next/eslint-plugin-next` now defaults to ESLint Flat Config format, aligning with ESLint v10
**F. next.config.js Turbopack Config Updates (REQUIRED for canary users)**
File: next.config.js
Check: `turbopackPersistentCachingForDev` config option
Action: Rename to `turbopackFileSystemCacheForDev`
**š For code examples, see: `nextjs16://migration/examples` (Config Migration Examples)**
Note: This was a temporary change on canary - not everyone has this config
**Additional Turbopack Enhancement:**
- Turbopack now automatically enables Babel if a babel config is found
- Previously exited with hard error
- No action needed - automatic behavior
**G. --turbopack Flags (No Longer Needed)**
Files: package.json scripts
Check: `next dev --turbopack`, `next build --turbopack`
Action: Remove `--turbopack` flags (Turbopack is default in v16)
Note: Use `--webpack` flag if you want webpack instead
**š For code examples, see: `nextjs16://migration/examples` (Config Migration Examples)**
**H. ESLint Config Removal (REQUIRED)**
File: next.config.js
Check: `eslint` configuration object
Action: Remove eslint config from next.config.js
**š For code examples, see: `nextjs16://migration/examples` (Config Migration Examples)**
Note: ESLint configuration should now be in .eslintrc.json or eslint.config.js
Migration: Use `<pkg-exec> @next/codemod@canary next-lint-to-eslint-cli .` if needed
**I. serverComponentsExternalPackages Deprecation (BREAKING)**
File: next.config.js
Check: `serverComponentsExternalPackages` in experimental config
Action: Move out of experimental - this is now a top-level config option
**š For code examples, see: `nextjs16://migration/examples` (Config Migration Examples)**
{{IF_BETA_CHANNEL}}**J. Beta to Stable Migration (REQUIRED for beta channel users)**
You are currently upgrading to Next.js 16 **beta** channel. When Next.js 16 **stable** is released, you will need to apply additional config migrations:
{{BETA_TO_STABLE_GUIDE}}
**Key migration when stable is released**: `experimental.cacheLife` must be moved to top-level `cacheLife`{{/IF_BETA_CHANNEL}}
**K. Edge Cases the Codemod May Miss**
Review these manually:
- Complex async destructuring patterns
- Dynamic params in nested layouts
- Route handlers with cookies()/headers() in conditionals
- Custom metadata generation with complex logic
- Metadata image routes (opengraph-image, twitter-image, icon, apple-icon)
**š For detailed code examples, see: `nextjs16://migration/examples` (Async API Migration Examples)**
**CRITICAL: Only change if function actually uses these 5 APIs:**
1. `params` from props
2. `searchParams` from props
3. `cookies()` in body
4. `headers()` in body
5. `draftMode()` in body
**Do NOT change:**
- `robots()`, `sitemap()`, `manifest()` without these APIs
- `generateStaticParams()`
- Any function that doesn't use the 5 APIs above
**METADATA IMAGE ROUTES - Important Changes:**
For metadata image route files (opengraph-image, twitter-image, icon, apple-icon):
- The function signature remains `{ params, id }` but `params` becomes a Promise
- `params` is now async: `await params`
- The `id` parameter remains a string (not a Promise)
See migration examples resource for complete before/after code
**L. ViewTransition API Renamed (NOT handled by codemod)**
Files: Search for imports of `unstable_ViewTransition` from React
Action: Rename to `ViewTransition` (now stable in v16)
**š For code examples, see: `nextjs16://migration/examples` (ViewTransition API Migration)**
- Rename `unstable_ViewTransition` ā `ViewTransition`
- Remove `experimental.viewTransition` flag from next.config.js
**M. revalidateTag API Changes (Deprecation - NOT handled by codemod)**
Files: Search for `revalidateTag(` calls
Check: All revalidateTag calls now require a profile parameter
**š For code examples, see: `nextjs16://migration/examples` (Cache Invalidation Examples)**
Search: `grep -r "revalidateTag(" app/ src/`
**When to use which:**
- Use `updateTag('tag')` in Server Actions when you need immediate consistency (read-your-own-writes, no profile parameter)
- Use `revalidateTag('tag', 'max')` in Route Handlers or when background invalidation is acceptable (requires profile parameter)
Load `nextjs16://knowledge/cache-invalidation` for detailed API semantics and migration patterns.
**N. Middleware to Proxy Migration (NOT handled by codemod)**
Files: middleware.ts, next.config.js
Check: Middleware-related files and config properties
**š For code examples, see: `nextjs16://migration/examples` (Middleware to Proxy Examples)**
The `middleware` concept is being renamed to `proxy` in Next.js 16:
**File renames:**
- Rename `middleware.ts` ā `proxy.ts`
- Rename named export `middleware` ā `proxy` in the file
**Config property renames:**
- `experimental.middlewarePrefetch` ā `experimental.proxyPrefetch`
- `experimental.middlewareClientMaxBodySize` ā `experimental.proxyClientMaxBodySize`
- `experimental.externalMiddlewareRewritesResolve` ā `experimental.externalProxyRewritesResolve`
- `skipMiddlewareUrlNormalize` ā `skipProxyUrlNormalize`
Search: `grep -r "middlewarePrefetch\|middlewareClientMaxBodySize\|externalMiddlewareRewritesResolve\|skipMiddlewareUrlNormalize" .`
**O. Build and Dev Improvements (Informational - No action needed)**
These improvements are automatic in Next.js 16:
- **Terminal Output Redesign:**
- Clearer formatting
- Better error messages
- Improved performance metrics
- **Separate Output Directories:**
- `next dev` and `next build` now use separate output directories
- Enables concurrent execution of both commands
- **Lockfile Mechanism:**
- Prevents multiple `next dev` or `next build` instances on same project
- Prevents conflicts from concurrent builds
- **Modern Sass Support:**
- `sass-loader` bumped to v16
- Supports modern Sass syntax and new features
- Automatic - no action needed if using Sass
- **Native TypeScript Config (Optional):**
- Run with `--experimental-next-config-strip-types` flag to enable native TS for `next.config.ts`
- Example: `next dev --experimental-next-config-strip-types`
**P. unstable_noStore Migration (If using Cache Components)**
- Search: `grep -r "unstable_noStore" app/ src/`
- Context: If you plan to enable Cache Components (experimental.cacheComponents)
- Action: Remove all `unstable_noStore()` calls - dynamic is the default with Cache Components
- Migration: No replacement needed - everything is dynamic by default
- Alternative: If content should be cached, use `"use cache"` instead
**š For code examples, see: `nextjs16://migration/examples` (unstable_noStore Examples)**
**Note:** `unstable_noStore()` is only incompatible when Cache Components are enabled. If you're not using Cache Components, you can keep using it.
**Q. Other Deprecated Features (WARNINGS - Optional)**
- `next/legacy/image` ā use `next/image`
- `images.domains` ā use `images.remotePatterns`
- `unstable_rootParams()` ā being replaced
## PHASE 4: Apply Manual Fixes
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
Only fix issues the codemod missed:
**š For all code examples, see: `nextjs16://migration/examples`**
Based on Phase 3 analysis, apply only the necessary manual fixes:
**1. Remove completely removed features (if found in Phase 3 section A)**
- Remove AMP-related code
- Migrate runtime configs to environment variables
- Remove PPR flags
- Rename experimental.dynamicIO to cacheComponents
- Remove unstable_rootParams() usage
- Add data-scroll-behavior attribute if needed
- Remove devIndicators config options
See: `nextjs16://migration/examples` ā Removed Features Examples
**2. Add missing default.js files (if you have @ folders)**
See: `nextjs16://migration/examples` ā Parallel Routes Examples
**3. Add image security config (if using local images with query strings)**
See: `nextjs16://migration/examples` ā Image Configuration Examples
**4. Update lint commands (if using next lint in scripts/CI)**
See: `nextjs16://migration/examples` ā Lint Command Migration
**5. Fix revalidateTag calls (see section M in Phase 3)**
- Update all `revalidateTag(tag)` calls to include profile parameter
- Use `updateTag(tag)` for Server Actions (read-your-own-writes, no profile parameter)
- Use `revalidateTag(tag, 'max')` for Route Handlers (background invalidation, requires profile parameter)
See: `nextjs16://migration/examples` ā Cache Invalidation Examples
**6. Migrate middleware to proxy (see section N in Phase 3)**
- Rename middleware.ts to proxy.ts
- Update config properties
See: `nextjs16://migration/examples` ā Middleware to Proxy Examples
**7. Remove unstable_noStore (see section P in Phase 3 - if using Cache Components)**
- Remove all `unstable_noStore()` calls
- Remove imports: `import { unstable_noStore } from 'next/cache'`
- No replacement needed - dynamic by default with Cache Components
- Add migration comments explaining removal
See: `nextjs16://migration/examples` ā unstable_noStore Examples
**8. Fix edge cases the codemod missed (RARE - only if found in Phase 3 section K)**
See: `nextjs16://migration/examples` ā Async API Migration Examples
## OUTPUT FORMAT
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
Report findings in this format:
```
# Next.js 16 Upgrade Report
## Summary
- Current Version: [version]
- On Beta: [Yes/No] - If yes, will upgrade to stable
- Target Version: 16 (stable channel)
- Package Manager: [npm/pnpm/yarn/bun]
- Monorepo: [Yes/No]
- If Monorepo, Apps to Upgrade: [list of app directories]
## Phase 1: Pre-Flight Checks
[ ] Monorepo structure detected (if applicable, list all Next.js apps)
[ ] Working directory: [current app directory path]
[ ] Node.js version (20.9+)
[ ] TypeScript version checked (5.1+)
[ ] Browser support requirements reviewed (Chrome 111+, Edge 111+, Firefox 111+, Safari 16.4+)
[ ] Current Next.js version documented
[ ] Git working directory is clean (no uncommitted changes)
## Phase 2: Codemod Execution
- [ ] Checked current version: On beta? [Yes/No]
- [ ] If on beta: Noted to review beta-to-stable guide after upgrade
- [ ] If already on stable: Skipped codemod (no reinstall needed)
- [ ] If NOT on stable: Ran codemod: `<pkg-exec> @next/codemod@canary upgrade {{UPGRADE_CHANNEL}}`
- [ ] Selected "yes" for all codemod prompts
- [ ] Codemod upgraded Next.js, React, and React DOM to stable
- [ ] Codemod upgraded React type definitions to stable
- [ ] Codemod applied automatic fixes
- [ ] TypeScript upgraded if needed: `<pkg-manager> add -D typescript@latest`
- [ ] Reviewed git diff for codemod changes
- [ ] **Verified build: `<pkg-manager> run build` (if this passes, upgrade is complete!)**
- [ ] **Browser verification with browser_eval (RECOMMENDED):**
- [ ] Started dev server: `<pkg-manager> run dev`
- [ ] Started browser automation with action="start"
- [ ] Navigated to key routes and verified pages load
- [ ] Checked for console errors with action="console_messages"
- [ ] Closed browser with action="close"
- [ ] No client-side errors or hydration issues detected
## Phase 3: Issues Requiring Manual Fixes
Issues the codemod couldn't handle:
[ ] A. Removed features check:
[ ] AMP support removal
[ ] Runtime config removal (serverRuntimeConfig, publicRuntimeConfig)
[ ] PPR flags removal (experimental.ppr, experimental_ppr)
[ ] experimental.dynamicIO ā cacheComponents rename
[ ] unstable_rootParams() removal
[ ] Automatic scroll-behavior: smooth removal
[ ] devIndicators config options removal
[ ] B. Parallel routes missing default.js
[ ] C. Image security config needed
[ ] D. Image default changes reviewed
[ ] E. Lint commands to update (ESLint flat config default noted)
[ ] F. next.config.js: turbopackPersistentCachingForDev ā turbopackFileSystemCacheForDev (Babel auto-enabled noted)
[ ] G. Remove --turbopack flags from scripts
[ ] H. next.config.js: Remove eslint config object
[ ] I. next.config.js: Move serverComponentsExternalPackages out of experimental
{{IF_BETA_CHANNEL}}[ ] J. next.config.js: Move cacheLife out of experimental (required when stable is released)
{{/IF_BETA_CHANNEL}}[ ] K. Edge cases in async APIs
[ ] L. ViewTransition API renamed (unstable_ViewTransition ā ViewTransition, remove experimental.viewTransition flag)
[ ] M. revalidateTag API changes
[ ] N. Middleware to Proxy migration (rename middleware.ts ā proxy.ts and config properties)
[ ] O. Build and dev improvements reviewed (informational)
[ ] P. unstable_noStore removal (if using Cache Components)
[ ] Q. Deprecated features to update
## Files Requiring Manual Changes
- path/to/file1.ts (reason - not handled by codemod)
- path/to/file2.tsx (reason - not handled by codemod)
...
## Phase 4: Manual Changes Applied
- [List of manual fixes made]
- [ ] **Final build verification: `<pkg-manager> run build` (must succeed)**
- [ ] **Final browser verification with browser_eval:**
- [ ] All key routes load successfully in browser
- [ ] No console errors or warnings
- [ ] Client-side hydration works correctly
## Completion Status
- [ ] Upgrade complete - build succeeds without errors
- [ ] Browser verification passed (using browser_eval, not curl)
- [ ] All manual fixes applied (if any were needed)
## Next Steps
- [What to do next, e.g., commit changes, test in staging, etc.]
```
# START HERE
Begin migration:
1. **FIRST: Check if this is a monorepo** - If yes, navigate to each Next.js app directory and run the workflow there (NOT at monorepo root)
2. Start with Phase 1 pre-flight checks (ensure clean git state)
3. Run the codemod in Phase 2 (this handles most changes automatically)
4. **Verify with build** - If `<pkg-manager> run build` succeeds, continue to browser verification
5. **Verify with browser_eval** - Use the browser_eval MCP tool to load pages in a real browser (NOT curl). This catches client-side errors that build verification misses
6. Only if build or browser verification fails, proceed to Phase 3 and Phase 4 to fix remaining issues
**ā ļø CRITICAL: Always use browser_eval for page verification, never curl or simple HTTP requests. browser_eval actually renders the page and detects runtime errors, hydration issues, and JavaScript problems that curl cannot catch.**
**ā ļø MONOREPO USERS:** If you're in a monorepo, you MUST be in the specific Next.js app directory (e.g., `apps/web/`) before starting. The codemod will fail if run from the monorepo root.
