cover more breaking changes in upgrade flow (#13)

Author: huozhi

src/mcp-prompts/nextjs-16-critical-rules.md

@@ -44,6 +44,33 @@ export async function GET(request: Request, props) {
 }
 ```
 
+**Metadata Image Routes (opengraph-image, twitter-image, icon, apple-icon):**
+```typescript
+// ❌ BEFORE (Next.js 15)
+export default function Image({ params, id }) {
+  const slug = params.slug
+  const imageId = id  // string
+  // ...
+}
+
+export async function generateImageMetadata({ params }) {
+  return [{ id: '1' }, { id: '2' }]
+}
+
+// ✅ AFTER (Next.js 16)
+export default async function Image(props, id) {
+  const params = await props.params  // params now async
+  const imageId = await id  // id is now Promise<string> when using generateImageMetadata
+  const slug = params.slug
+  // ...
+}
+
+export async function generateImageMetadata(props) {
+  const params = await props.params
+  return [{ id: '1' }, { id: '2' }]
+}
+```
+
 ### 2. Async Dynamic Functions
 **cookies(), headers(), draftMode()**
 
@@ -96,7 +123,51 @@ revalidateTag('posts', 'max')  // For background invalidation
 
 ## ⚙️ Config Migrations
 
-### Image Defaults Changed (No Action Needed)
+### 1. Turbopack Config Rename (REQUIRED for canary users)
+```typescript
+// ❌ BEFORE
+// next.config.js
+export default {
+  turbopackPersistentCachingForDev: true,
+}
+
+// ✅ AFTER
+// next.config.js
+export default {
+  turbopackFileSystemCacheForDev: true,
+}
+```
+
+### 2. ESLint Config Removal (REQUIRED)
+```typescript
+// ❌ BEFORE - Remove this from next.config.js
+export default {
+  eslint: {
+    ignoreDuringBuilds: true,
+    dirs: ['app', 'src'],
+  },
+}
+
+// ✅ AFTER - Move to .eslintrc.json or eslint.config.js
+// ESLint configuration should now be in dedicated ESLint config files
+```
+
+### 3. serverComponentsExternalPackages (BREAKING)
+```typescript
+// ❌ BEFORE - In experimental
+export default {
+  experimental: {
+    serverComponentsExternalPackages: ['package-name'],
+  },
+}
+
+// ✅ AFTER - Top-level config
+export default {
+  serverComponentsExternalPackages: ['package-name'],
+}
+```
+
+### 4. Image Defaults Changed (No Action Needed)
 These changed automatically - override if needed:
 - `minimumCacheTTL`: 60s → 14400s (4 hours)
 - `qualities`: [1..100] → [75]
@@ -136,7 +207,7 @@ import { ViewTransition } from 'react'
 
 ## 📁 Parallel Routes Requirement
 
-If you have `@modal`, `@auth`, etc. folders:
+If you have `@modal`, `@auth`, etc. folders (any `@` folder except `@children`):
 
 ```typescript
 // MUST create: app/@modal/default.tsx
@@ -145,6 +216,8 @@ export default function Default() {
 }
 ```
 
+**Note:** `@children` is a special implicit slot and does NOT require a `default.js` file.
+
 ## 🛡️ Image Security
 
 If using local images with query strings:
@@ -206,12 +279,17 @@ export default async function Page(props) {
 - [ ] `function Layout({ params })` → `async function Layout(props)` + `await props.params`
 - [ ] `generateMetadata({ params })` → `async generateMetadata(props)` + `await props.params`
 - [ ] `generateViewport({ params })` → `async generateViewport(props)` + `await props.params`
+- [ ] Metadata image routes: `function Image({ params, id })` → `async function Image(props, id)` + `await props.params` + `await id`
+- [ ] `generateImageMetadata({ params })` → `async generateImageMetadata(props)` + `await props.params`
 - [ ] `cookies().get()` → `(await cookies()).get()`
 - [ ] `headers().get()` → `(await headers()).get()`
 - [ ] `draftMode().isEnabled` → `(await draftMode()).isEnabled`
 - [ ] `revalidateTag(tag)` → `updateTag(tag, 'max')` or `revalidateTag(tag, 'max')`
 
-**Config changes:**
+**Config changes in next.config.js:**
+- [ ] Rename `turbopackPersistentCachingForDev` → `turbopackFileSystemCacheForDev`
+- [ ] Remove `eslint` config object (move to .eslintrc.json or eslint.config.js)
+- [ ] Move `serverComponentsExternalPackages` out of `experimental` to top-level
 - [ ] Add `default.tsx` for all parallel route `@` folders
 - [ ] Update `unstable_ViewTransition` → `ViewTransition`
 - [ ] Review image config defaults (if using local images with query strings)

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

@@ -103,13 +103,15 @@ After the codemod runs, check for any remaining issues it might have missed:
 ### Manual Check Checklist:
 
 **A. Parallel Routes (NOT handled by codemod)**
-   Files: Check for @ folders
+   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.
+
    Fix if missing:
    ```typescript
-   // Create: app/@modal/default.js
+   // Create: app/@modal/default.js (for @modal, @auth, etc.)
    export default function Default() {
      return null
    }
@@ -145,19 +147,68 @@ After the codemod runs, check for any remaining issues it might have missed:
    1. Use Biome: `biome check .`
    2. Use ESLint directly: `<pkg-exec> @next/codemod@canary next-lint-to-eslint-cli .`
 
-**E. --turbopack Flags (No Longer Needed)**
+**E. next.config.js Turbopack Config Updates (REQUIRED for canary users)**
+   File: next.config.js
+   Check: `turbopackPersistentCachingForDev` config option
+   Action: Rename to `turbopackFileSystemCacheForDev`
+
+   ```diff
+   // next.config.js
+   export default {
+   -   turbopackPersistentCachingForDev: true,
+   +   turbopackFileSystemCacheForDev: true,
+   }
+   ```
+
+   Note: This was a temporary change on canary - not everyone has this config
+
+**F. --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
 
-**F. Edge Cases the Codemod May Miss**
+**G. ESLint Config Removal (REQUIRED)**
+   File: next.config.js
+   Check: `eslint` configuration object
+   Action: Remove eslint config from next.config.js
+
+   ```diff
+   // next.config.js
+   export default {
+   -   eslint: {
+   -     ignoreDuringBuilds: true,
+   -     dirs: ['app', 'src'],
+   -   },
+   }
+   ```
+
+   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
+
+**H. 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
+
+   ```diff
+   // next.config.js
+   export default {
+   -   experimental: {
+   -     serverComponentsExternalPackages: ['package-name'],
+   -   },
+   +   serverComponentsExternalPackages: ['package-name'],
+   }
+   ```
+
+**I. 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)
 
    **CRITICAL: Only change if function actually uses these 5 APIs:**
    1. `params` from props
@@ -171,7 +222,26 @@ After the codemod runs, check for any remaining issues it might have missed:
    - `generateStaticParams()`
    - Any function that doesn't use the 5 APIs above
 
-**G. ViewTransition API Renamed (NOT handled by codemod)**
+   **METADATA IMAGE ROUTES - Important Changes:**
+   For metadata image route files (opengraph-image, twitter-image, icon, apple-icon):
+   - The first argument changes from `{ params }` to `params` (aligned with other App Router routes)
+   - `params` is now async: `await props.params`
+   - The second argument `id` becomes `Promise<string>` when using `generateImageMetadata`
+
+   ```typescript
+   // ❌ BEFORE
+   export default function Image({ params, id }) {
+     const slug = params.slug
+   }
+
+   // ✅ AFTER
+   export default async function Image(props, id) {
+     const params = await props.params
+     const imageId = await id  // if using generateImageMetadata
+   }
+   ```
+
+**J. ViewTransition API Renamed (NOT handled by codemod)**
    Files: Search for imports of `unstable_ViewTransition` from React
    Action: Rename to `ViewTransition` (now stable in v16)
 
@@ -180,7 +250,7 @@ After the codemod runs, check for any remaining issues it might have missed:
    + import { ViewTransition } from 'react'
    ```
 
-**H. revalidateTag API Changes (Deprecation - NOT handled by codemod)**
+**K. revalidateTag API Changes (Deprecation - NOT handled by codemod)**
    Files: Search for `revalidateTag(` calls
    Check: All revalidateTag calls now require a profile parameter
 
@@ -210,7 +280,7 @@ After the codemod runs, check for any remaining issues it might have missed:
 
    Load `nextjs16://knowledge/cache-invalidation` for detailed API semantics and migration patterns.
 
-**I. Deprecated Features (WARNINGS - Optional)**
+**L. Deprecated Features (WARNINGS - Optional)**
    - `middleware.ts` → consider renaming to `proxy.ts`
    - `next/legacy/image` → use `next/image`
    - `images.domains` → use `images.remotePatterns`
@@ -304,6 +374,9 @@ Issues the codemod couldn't handle:
 [ ] Parallel routes missing default.js
 [ ] Image security config needed
 [ ] Lint commands to update
+[ ] next.config.js: turbopackPersistentCachingForDev → turbopackFileSystemCacheForDev
+[ ] next.config.js: Remove eslint config object
+[ ] next.config.js: Move serverComponentsExternalPackages out of experimental
 [ ] revalidateTag API changes
 [ ] Edge cases in async APIs
 [ ] Deprecated features to update