upgrade 16 beta to stable

Author: huozhi

README.md

@@ -113,9 +113,9 @@ startup_timeout_ms = 20_000
 
 </details>
 
-### Next.js Runtime Integration (Recommended for Next.js >= 16 beta)
+### Next.js Runtime Integration (Recommended for Next.js >= 16)
 
-For Next.js 16 beta or later, enable the MCP server in your Next.js application to unlock powerful runtime diagnostics and integration with Claude Code:
+For Next.js 16 or later, enable the MCP server in your Next.js application to unlock powerful runtime diagnostics and integration with Claude Code:
 
 **Update `next.config.ts` or `next.config.js`:**
 
@@ -153,7 +153,7 @@ Help me upgrade my Next.js app to version 16
 
 Your MCP client should provide guidance and tools for upgrading your Next.js application.
 
-If you're on **Next.js 16 beta or later** with `experimental.mcpServer` enabled, you can also try:
+If you're on **Next.js 16 or later** with `experimental.mcpServer` enabled, you can also try:
 
 ```
 What's the structure of my Next.js routes?
@@ -194,7 +194,7 @@ Callable tools for automating Next.js development workflows:
 
 ### `upgrade_nextjs_16` Tool
 
-Guides through upgrading Next.js to version 16 beta with automated codemod execution.
+Guides through upgrading Next.js to version 16 with automated codemod execution.
 
 **Capabilities:**
 - Runs official Next.js codemod automatically (requires clean git state)

src/index.ts

@@ -27,6 +27,11 @@ import {
   readFundamentalsSection,
   isNextjsFundamentalsUri,
 } from "./mcp-resources/nextjs-fundamentals-knowledge.js"
+import {
+  getBetaToStableResource,
+  readBetaToStableGuide,
+  isBetaToStableUri,
+} from "./mcp-resources/nextjs-16-beta-to-stable.js"
 
 async function main() {
   // Create MCP server instance
@@ -130,7 +135,8 @@ async function main() {
   server.setRequestHandler(ListResourcesRequestSchema, async () => {
     const nextjs16Resources = getNextjs16KnowledgeResources()
     const fundamentalsResources = getNextjsFundamentalsResources()
-    const resources = [...nextjs16Resources, ...fundamentalsResources]
+    const betaToStableResource = getBetaToStableResource()
+    const resources = [...nextjs16Resources, ...fundamentalsResources, betaToStableResource]
 
     return { resources }
   })
@@ -146,6 +152,8 @@ async function main() {
         content = readKnowledgeSection(uri)
       } else if (isNextjsFundamentalsUri(uri)) {
         content = readFundamentalsSection(uri)
+      } else if (isBetaToStableUri(uri)) {
+        content = readBetaToStableGuide()
       } else {
         throw new Error(`Unknown resource URI: ${uri}`)
       }

src/mcp-prompts/upgrade-nextjs-16-prompt.md

@@ -112,7 +112,7 @@ Run the official codemod to handle most changes automatically:
 # - Convert async params/searchParams automatically
 # - Update experimental config locations
 # - Fix other breaking changes
-<pkg-exec> @next/codemod@canary upgrade beta
+<pkg-exec> @next/codemod@canary upgrade latest
 ```
 
 **Note:** When prompted for options during codemod execution, select "yes" for all selections to apply all recommended changes.
@@ -147,7 +147,7 @@ If your project already uses `'use cache'` directives from Next.js 15 canary, yo
 <pkg-manager> add -D eslint-config-next@canary
 ```
 
-Otherwise, the beta version is recommended for most projects.
+Otherwise, the stable version is recommended for most projects.
 {{/IF_REQUIRES_CANARY}}
 
 ## PHASE 3: Analyze Remaining Issues
@@ -255,7 +255,15 @@ After the codemod runs, check for any remaining issues it might have missed:
    }
    ```
 
-**I. Edge Cases the Codemod May Miss**
+**I. Beta to Stable Migration (REQUIRED if upgrading from v16 beta)**
+
+   If you're upgrading from Next.js 16 **beta** to 16 **stable**, there are additional config migrations required:
+
+   {{BETA_TO_STABLE_GUIDE}}
+
+   **Key migration**: `experimental.cacheLife` must be moved to top-level `cacheLife`
+
+**J. Edge Cases the Codemod May Miss**
    Review these manually:
 
    - Complex async destructuring patterns
@@ -296,7 +304,7 @@ After the codemod runs, check for any remaining issues it might have missed:
    }
    ```
 
-**J. ViewTransition API Renamed (NOT handled by codemod)**
+**K. ViewTransition API Renamed (NOT handled by codemod)**
    Files: Search for imports of `unstable_ViewTransition` from React
    Action: Rename to `ViewTransition` (now stable in v16)
 
@@ -305,7 +313,7 @@ After the codemod runs, check for any remaining issues it might have missed:
    + import { ViewTransition } from 'react'
    ```
 
-**K. revalidateTag API Changes (Deprecation - NOT handled by codemod)**
+**L. revalidateTag API Changes (Deprecation - NOT handled by codemod)**
    Files: Search for `revalidateTag(` calls
    Check: All revalidateTag calls now require a profile parameter
 
@@ -419,7 +427,7 @@ Report findings in this format:
 [ ] Git working directory is clean (no uncommitted changes)
 
 ## Phase 2: Codemod Execution
-- [ ] Ran codemod: `<pkg-exec> @next/codemod@canary upgrade beta`
+- [ ] Ran codemod: `<pkg-exec> @next/codemod@canary upgrade latest`
 - [ ] Selected "yes" for all codemod prompts
 - [ ] Codemod upgraded Next.js, React, and React DOM to latest
 - [ ] Codemod upgraded React type definitions to latest
@@ -439,6 +447,7 @@ Issues the codemod couldn't handle:
 [ ] next.config.js: turbopackPersistentCachingForDev → turbopackFileSystemCacheForDev
 [ ] next.config.js: Remove eslint config object
 [ ] next.config.js: Move serverComponentsExternalPackages out of experimental
+[ ] next.config.js: Move cacheLife out of experimental (beta → stable migration)
 [ ] revalidateTag API changes
 [ ] Edge cases in async APIs
 [ ] Deprecated features to update

src/mcp-prompts/upgrade-nextjs-16.ts

@@ -1,11 +1,12 @@
 import type { GetPromptResult, Prompt } from "@modelcontextprotocol/sdk/types.js"
 import { readFileSync } from "fs"
 import { join } from "path"
+import { readBetaToStableGuide } from "../mcp-resources/nextjs-16-beta-to-stable.js"
 
 export const upgradeNextjs16Prompt: Prompt = {
   name: "upgrade-nextjs-16",
   description:
-    "Guide through upgrading Next.js to version 16 beta. CRITICAL: Runs the official codemod FIRST (requires clean git state) for automatic upgrades and fixes, then handles remaining issues manually. The codemod upgrades Next.js, React, and React DOM automatically. Covers async API changes, config moves, image defaults, parallel routes, and deprecations.",
+    "Guide through upgrading Next.js to version 16. CRITICAL: Runs the official codemod FIRST (requires clean git state) for automatic upgrades and fixes, then handles remaining issues manually. The codemod upgrades Next.js, React, and React DOM automatically. Covers async API changes, config moves, image defaults, parallel routes, and deprecations.",
   arguments: [
     {
       name: "project_path",
@@ -18,18 +19,22 @@ export const upgradeNextjs16Prompt: Prompt = {
 export function getUpgradeNextjs16Prompt(args?: Record<string, string>): GetPromptResult {
   const projectPath = args?.project_path || process.cwd()
 
-  // TEMPORARY: Set to false once Next.js 16 beta supports experimental.cacheComponents
-  const REQUIRES_CANARY_FOR_CACHE_COMPONENTS = true
+  // TEMPORARY: Set to false once Next.js 16 supports experimental.cacheComponents
+  const REQUIRES_CANARY_FOR_CACHE_COMPONENTS = false
 
   // Load critical rules (always embedded)
   const criticalRules = readFileSync(join(__dirname, "nextjs-16-critical-rules.md"), "utf-8")
 
+  // Load beta-to-stable migration guide (always embedded)
+  const betaToStableGuide = readBetaToStableGuide()
+
   // Load prompt template
   let promptTemplate = readFileSync(join(__dirname, "upgrade-nextjs-16-prompt.md"), "utf-8")
 
   // Replace sentinel values
   promptTemplate = promptTemplate.replace(/{{PROJECT_PATH}}/g, projectPath)
   promptTemplate = promptTemplate.replace(/{{CRITICAL_RULES}}/g, criticalRules)
+  promptTemplate = promptTemplate.replace(/{{BETA_TO_STABLE_GUIDE}}/g, betaToStableGuide)
 
   // Handle conditional blocks
   if (REQUIRES_CANARY_FOR_CACHE_COMPONENTS) {

src/mcp-resources/nextjs-16-beta-to-stable.md

@@ -0,0 +1,138 @@
+# Next.js 16 Beta to Stable Migration Guide
+
+## Overview
+
+This guide covers the specific breaking changes when migrating from **Next.js 16.0.0-beta** to **Next.js 16.0.0 stable**.
+
+If you're already on Next.js 16 beta and upgrading to stable, you need to apply these additional config migrations that were stabilized between beta and stable releases.
+
+## Required Config Migrations
+
+### 1. experimental.cacheLife → cacheLife
+
+**Status**: BREAKING - Required for beta → stable migration
+
+The `cacheLife` configuration has been moved out of the `experimental` object and is now a top-level config option.
+
+**File**: `next.config.js` or `next.config.ts`
+
+**Migration**:
+
+```diff
+// next.config.js
+export default {
+-   experimental: {
+-     cacheLife: {
+-       default: { stale: 3600, revalidate: 900, expire: 86400 },
+-       custom: { stale: 1800, revalidate: 450, expire: 43200 },
+-     },
+-   },
++   cacheLife: {
++     default: { stale: 3600, revalidate: 900, expire: 86400 },
++     custom: { stale: 1800, revalidate: 450, expire: 43200 },
++   },
+}
+```
+
+**Why this matters**:
+- Projects using Cache Components with custom `cacheLife` profiles will fail to recognize the config if it's still under `experimental`
+- The stable release expects `cacheLife` at the top level
+
+**How to find**:
+```bash
+# Search for experimental.cacheLife in your config
+grep -r "experimental.*cacheLife" .
+# or
+rg "experimental.*cacheLife"
+```
+
+### 2. experimental.cacheComponents remains experimental
+
+**Status**: Still experimental in stable
+
+The `experimental.cacheComponents` flag itself **remains experimental** and should stay under the `experimental` object.
+
+```js
+// next.config.js
+export default {
+  experimental: {
+    cacheComponents: true, // ✅ Keep this in experimental
+  },
+  cacheLife: {
+    // ✅ Move this to top-level
+    default: { stale: 3600, revalidate: 900, expire: 86400 },
+  },
+}
+```
+
+## Detection Checklist
+
+Run this checklist to verify your migration:
+
+- [ ] Searched for `experimental.cacheLife` in `next.config.js`/`next.config.ts`
+- [ ] Moved `cacheLife` object to top-level if found
+- [ ] Verified `experimental.cacheComponents` remains in experimental (don't move this)
+- [ ] Tested dev server starts without config errors
+- [ ] Verified custom cacheLife profiles are recognized
+
+## Complete Example
+
+**Before (Next.js 16 beta)**:
+```js
+// next.config.js
+export default {
+  experimental: {
+    cacheComponents: true,
+    cacheLife: {
+      default: {
+        stale: 3600,
+        revalidate: 900,
+        expire: 86400,
+      },
+      blog: {
+        stale: 1800,
+        revalidate: 600,
+        expire: 43200,
+      },
+    },
+  },
+}
+```
+
+**After (Next.js 16 stable)**:
+```js
+// next.config.js
+export default {
+  experimental: {
+    cacheComponents: true, // Stays here
+  },
+  cacheLife: {
+    // Moved to top-level
+    default: {
+      stale: 3600,
+      revalidate: 900,
+      expire: 86400,
+    },
+    blog: {
+      stale: 1800,
+      revalidate: 600,
+      expire: 43200,
+    },
+  },
+}
+```
+
+## Additional Notes
+
+- This migration is **only required** if you're upgrading from Next.js 16 beta to stable
+- If you're upgrading from Next.js 15 or earlier directly to 16 stable, this doesn't apply (since you wouldn't have `experimental.cacheLife` yet)
+- The codemod `@next/codemod@canary upgrade latest` does NOT handle this migration automatically
+- Error you might see if not migrated: Custom cacheLife profiles not being applied, or config validation warnings
+
+## Related Changes
+
+For other Next.js 16 upgrade requirements, see:
+- `experimental.serverComponentsExternalPackages` → `serverComponentsExternalPackages` (top-level)
+- Async params/searchParams
+- Config location migrations
+- Image defaults changes

src/mcp-resources/nextjs-16-beta-to-stable.ts

@@ -0,0 +1,41 @@
+import type { Resource } from "@modelcontextprotocol/sdk/types.js"
+import { readFileSync } from "node:fs"
+import { join } from "node:path"
+
+/**
+ * Next.js 16 Beta to Stable Migration Resource
+ *
+ * This resource provides specific guidance for upgrading from Next.js 16 beta
+ * to Next.js 16 stable, covering config migrations and breaking changes that
+ * happened between beta and stable releases.
+ */
+
+const BETA_TO_STABLE_RESOURCE: Resource = {
+  uri: "nextjs16://migration/beta-to-stable",
+  name: "Next.js 16 Beta to Stable Migration",
+  description:
+    "Specific breaking changes and config migrations required when upgrading from Next.js 16 beta to stable (experimental.cacheLife → cacheLife, etc.)",
+  mimeType: "text/markdown",
+}
+
+/**
+ * Get the beta-to-stable migration resource
+ */
+export function getBetaToStableResource(): Resource {
+  return BETA_TO_STABLE_RESOURCE
+}
+
+/**
+ * Read the beta-to-stable migration guide content
+ */
+export function readBetaToStableGuide(): string {
+  const filePath = join(__dirname, "nextjs-16-beta-to-stable.md")
+  return readFileSync(filePath, "utf-8")
+}
+
+/**
+ * Check if a URI is the beta-to-stable migration resource
+ */
+export function isBetaToStableUri(uri: string): boolean {
+  return uri === BETA_TO_STABLE_RESOURCE.uri
+}

src/mcp-tools/upgrade-nextjs-16.ts

@@ -16,7 +16,7 @@ const upgradeNextjs16InputSchema = z.object({
 })
 
 export const upgradeNextjs16Tool = tool({
-  description: `Guide through upgrading Next.js to version 16 beta.
+  description: `Guide through upgrading Next.js to version 16.
 
 CRITICAL: Runs the official codemod FIRST (requires clean git state) for automatic upgrades and fixes, then handles remaining issues manually. The codemod upgrades Next.js, React, and React DOM automatically.