Next.js 16 Migration Instructions for LLM

Overview

These instructions guide you through migrating an Nx workspace containing Next.js projects from Next.js 15 to Next.js 16. Work systematically through each breaking change category.

Pre-Migration Checklist

Identify all Next.js projects:

bash

nx show projects --with-target build | xargs -I {} nx show project {} --json | jq -r 'select(.targets.build.executor | contains("next")) | .name'

Or search for Next.js configuration files:

bash

find . -name "next.config.*" -not -path "*/node_modules/*"

Update packages:

bash

npm install next@latest react@latest react-dom@latest
npm install -D @types/react @types/react-dom  # if using TypeScript

Verify minimum requirements:
- Node.js 20.9+ (Node.js 18 is no longer supported)
- TypeScript 5.1.0+
- Browser support: Chrome 111+, Edge 111+, Firefox 111+, Safari 16.4+

Migration Steps by Category

1. Async Request APIs (Major Breaking Change)

This is the most impactful change in Next.js 16. All dynamic request APIs are now asynchronous.

Search Patterns:

cookies() usage in server components
headers() usage in server components
draftMode() usage
params in page, layout, route handlers, and metadata files
searchParams in page components

1.1 Page Components with params

Changes Required:

tsx

// BEFORE (Next.js 15)
export default function Page({ params }) {
  const { slug } = params;
  return <h1>{slug}</h1>;
}

// AFTER (Next.js 16)
export default async function Page(props) {
  const { slug } = await props.params;
  return <h1>{slug}</h1>;
}

Action Items:

Make all page components that use params async
Add await before accessing props.params
Update TypeScript types if applicable

1.2 Page Components with searchParams

Changes Required:

tsx

// BEFORE (Next.js 15)
export default function Page({ searchParams }) {
  const query = searchParams.q;
  return <Results query={query} />;
}

// AFTER (Next.js 16)
export default async function Page(props) {
  const searchParams = await props.searchParams;
  const query = searchParams.q;
  return <Results query={query} />;
}

Action Items:

Make all page components that use searchParams async
Add await before accessing props.searchParams

1.3 Layout Components with params

Changes Required:

tsx

// BEFORE (Next.js 15)
export default function Layout({ children, params }) {
  const { locale } = params;
  return <div data-locale={locale}>{children}</div>;
}

// AFTER (Next.js 16)
export default async function Layout(props) {
  const { locale } = await props.params;
  return <div data-locale={locale}>{props.children}</div>;
}

1.4 Route Handlers

Changes Required:

tsx

// BEFORE (Next.js 15)
export async function GET(request, { params }) {
  const { id } = params;
  return Response.json({ id });
}

// AFTER (Next.js 16)
export async function GET(request, props) {
  const { id } = await props.params;
  return Response.json({ id });
}

1.5 cookies() and headers()

Changes Required:

tsx

// BEFORE (Next.js 15)
import { cookies, headers } from 'next/headers';

export default function Page() {
  const cookieStore = cookies();
  const headersList = headers();
  const theme = cookieStore.get('theme');
  const userAgent = headersList.get('user-agent');
  return <div>...</div>;
}

// AFTER (Next.js 16)
import { cookies, headers } from 'next/headers';

export default async function Page() {
  const cookieStore = await cookies();
  const headersList = await headers();
  const theme = cookieStore.get('theme');
  const userAgent = headersList.get('user-agent');
  return <div>...</div>;
}

1.6 draftMode()

Changes Required:

tsx

// BEFORE (Next.js 15)
import { draftMode } from 'next/headers';

export default function Page() {
  const { isEnabled } = draftMode();
  return <div>{isEnabled ? 'Draft' : 'Published'}</div>;
}

// AFTER (Next.js 16)
import { draftMode } from 'next/headers';

export default async function Page() {
  const { isEnabled } = await draftMode();
  return <div>{isEnabled ? 'Draft' : 'Published'}</div>;
}

1.7 generateMetadata with params

Changes Required:

tsx

// BEFORE (Next.js 15)
export async function generateMetadata({ params }) {
  const { slug } = params;
  return { title: slug };
}

// AFTER (Next.js 16)
export async function generateMetadata(props) {
  const { slug } = await props.params;
  return { title: slug };
}

1.8 Automated Migration

Run the Next.js codemod for automated migration:

bash

npx @next/codemod@canary upgrade latest

Generate type helpers for safer migrations (Next.js 15.5+):

bash

npx next typegen

This generates PageProps, LayoutProps, and RouteContext helpers.

2. Image Generation Functions

Search Pattern: generateImageMetadata, default function Image in opengraph-image or twitter-image files

Changes Required:

tsx

// BEFORE (Next.js 15)
export function generateImageMetadata({ params }) {
  const { slug } = params;
  return [{ id: '1' }];
}

export default function Image({ params, id }) {
  const slug = params.slug;
  return new ImageResponse(/* ... */);
}

// AFTER (Next.js 16)
export async function generateImageMetadata({ params }) {
  const { slug } = await params;
  return [{ id: '1' }];
}

export default async function Image({ params, id }) {
  const { slug } = await params;
  const imageId = await id;
  return new ImageResponse(/* ... */);
}

Action Items:

Make generateImageMetadata functions async
Make Image components async
Add await for both params and id access

3. Sitemap Generation

Search Pattern: sitemap functions with id parameter

Changes Required:

tsx

// BEFORE (Next.js 15)
export default async function sitemap({ id }) {
  const start = id * 50000;
  // ...
}

// AFTER (Next.js 16)
export default async function sitemap({ id }) {
  const resolvedId = await id;
  const start = resolvedId * 50000;
  // ...
}

4. Turbopack Configuration

Turbopack is now the default bundler for development.

Search Pattern: --turbo or --turbopack flags in package.json scripts, turbopack in next.config

4.1 Remove Explicit Turbopack Flags

json

// BEFORE (Next.js 15)
{
  "scripts": {
    "dev": "next dev --turbo"
  }
}

// AFTER (Next.js 16) - Turbopack is default
{
  "scripts": {
    "dev": "next dev"
  }
}

4.2 Opt Out to Webpack (if needed)

json

{
  "scripts": {
    "build": "next build --webpack"
  }
}

4.3 Move Turbopack Config Out of Experimental

// BEFORE (Next.js 15)
const nextConfig = {
  experimental: {
    turbopack: {
      /* options */
    },
  },
};

// AFTER (Next.js 16)
const nextConfig = {
  turbopack: {
    /* options */
  },
};

4.4 Update Sass Imports (Turbopack Specific)

scss

/* BEFORE */
@import '~bootstrap/dist/css/bootstrap.min.css';

/* AFTER - Remove tilde prefix */
@import 'bootstrap/dist/css/bootstrap.min.css';

Action Items:

Remove --turbo and --turbopack flags from scripts
Move turbopack config from experimental to root level
Remove tilde (~) prefix from Sass imports
Add --webpack flag if Webpack is required

5. Middleware to Proxy Rename

Search Pattern: middleware.ts or middleware.js files

Changes Required:

bash

# Rename the file
mv middleware.ts proxy.ts

// BEFORE (middleware.ts)
export function middleware(request) {
  // ...
}

// AFTER (proxy.ts)
export function proxy(request) {
  // ...
}

Config Updates:

// BEFORE
{
  skipMiddlewareUrlNormalize: true;
}

// AFTER
{
  skipProxyUrlNormalize: true;
}

Important: The Edge runtime is no longer supported in proxy. It now uses Node.js runtime.

Action Items:

Rename middleware.ts/js to proxy.ts/js
Rename exported function from middleware to proxy
Update config option names
Remove Edge runtime usage from proxy files

6. Parallel Routes default.js Requirement

Search Pattern: Directories starting with @ in the app folder (parallel route slots)

All parallel route slots now require an explicit default.js file.

Changes Required:

tsx

// Create app/@modal/default.tsx for each parallel route slot
import { notFound } from 'next/navigation';

export default function Default() {
  notFound(); // or return null
}

Action Items:

Find all parallel route slots (app/@*/)
Create default.tsx in each slot that doesn't have one

7. Image Optimization Changes

7.1 Local Images with Query Strings

tsx

// Now requires explicit configuration
<Image src="/assets/photo?v=1" alt="Photo" width="100" height="100" />

// next.config.js
module.exports = {
  images: {
    localPatterns: [
      {
        pathname: '/assets/**',
        search: '?v=1',
      },
    ],
  },
};

7.2 Default Value Changes

Add these to next.config.js if you need the old defaults:

module.exports = {
  images: {
    // minimumCacheTTL changed from 60 to 14400 seconds
    minimumCacheTTL: 60,

    // Value 16 removed from default imageSizes
    imageSizes: [16, 32, 48, 64, 96, 128, 256, 384],

    // qualities now defaults to [75] only
    qualities: [50, 75, 100],

    // Local IP now blocked by default
    dangerouslyAllowLocalIP: true, // only for private networks

    // Maximum redirects changed from unlimited to 3
    maximumRedirects: 5,
  },
};

7.3 Deprecated images.domains

// BEFORE - Remove this
module.exports = {
  images: {
    domains: ['example.com'],
  },
};

// AFTER - Use remotePatterns instead
module.exports = {
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: 'example.com',
      },
    ],
  },
};

Action Items:

Add localPatterns for images with query strings
Migrate images.domains to images.remotePatterns
Review and update default values if needed

8. Caching API Updates

8.1 Remove unstable_ Prefix

// BEFORE (Next.js 15)
import {
  unstable_cacheLife as cacheLife,
  unstable_cacheTag as cacheTag,
} from 'next/cache';

// AFTER (Next.js 16)
import { cacheLife, cacheTag } from 'next/cache';

8.2 New Cache Functions

revalidateTag with cacheLife profile:

'use server';
import { revalidateTag } from 'next/cache';

export async function updateArticle(articleId: string) {
  revalidateTag(`article-${articleId}`, 'max');
}

updateTag (new):

'use server';
import { updateTag } from 'next/cache';

export async function updateUserProfile(userId: string, profile: Profile) {
  await db.users.update(userId, profile);
  updateTag(`user-${userId}`);
}

refresh (new):

'use server';
import { refresh } from 'next/cache';

export async function markNotificationAsRead(notificationId: string) {
  await db.notifications.markAsRead(notificationId);
  refresh();
}

Action Items:

Remove unstable_ prefix from cacheLife and cacheTag imports
Consider using new updateTag and refresh functions

9. React Compiler Support

React Compiler is now stable and supported:

// next.config.ts
const nextConfig = {
  reactCompiler: true,
};

export default nextConfig;

Install the plugin:

bash

npm install -D babel-plugin-react-compiler

Note: Expect higher compile times with React Compiler enabled.

10. Scroll Behavior Override

Next.js no longer overrides scroll-behavior: smooth during navigation.

To restore previous behavior:

tsx

// app/layout.tsx
export default function RootLayout({ children }) {
  return (
    <html lang="en" data-scroll-behavior="smooth">
      <body>{children}</body>
    </html>
  );
}

11. ESLint Migration

The next lint command has been removed. Migrate to ESLint CLI directly.

bash

# Run migration codemod
npx @next/codemod@canary next-lint-to-eslint-cli .

Remove from next.config.js:

// Remove this
{
  eslint: {
  }
}

Action Items:

Run the ESLint migration codemod
Remove eslint config from next.config.js
Update CI scripts to use eslint directly instead of next lint

12. Feature Removals

12.1 AMP Support Removed

All AMP APIs have been deleted
Remove useAmp hook usage
Remove amp config option
Delete AMP-specific pages

12.2 Runtime Configuration Removed

// BEFORE - Remove these
module.exports = {
  serverRuntimeConfig: { dbUrl: process.env.DATABASE_URL },
  publicRuntimeConfig: { apiUrl: '/api' },
};

Migration for server-side config:

tsx

// Use environment variables directly
async function fetchData() {
  const dbUrl = process.env.DATABASE_URL;
  return await db.query(dbUrl, 'SELECT * FROM users');
}

Migration for client-side config:

bash

# .env.local
NEXT_PUBLIC_API_URL="/api"

tsx

'use client';
export default function Component() {
  const apiUrl = process.env.NEXT_PUBLIC_API_URL;
  // ...
}

12.3 devIndicators Options Removed

Remove these from next.config.js:

appIsrStatus
buildActivity
buildActivityPosition

12.4 experimental.dynamicIO Renamed

// BEFORE
{
  experimental: {
    dynamicIO: true;
  }
}

// AFTER
{
  cacheComponents: true;
}

12.5 unstable_rootParams Removed

This API is removed. Await alternative API in a future minor release.

Action Items:

Remove all AMP-related code
Migrate runtime configuration to environment variables
Remove deprecated devIndicators options
Rename dynamicIO to cacheComponents

13. Development Changes

13.1 Concurrent dev and build

Development now outputs to .next/dev (separate from build).

Update Turbopack tracing command:

bash

npx next internal trace .next/dev/trace-turbopack

Post-Migration Validation

1. Run Build Per Project

bash

# Build each Next.js project individually
nx run PROJECT_NAME:build

2. Run Development Server

bash

# Start dev server to verify Turbopack works
nx run PROJECT_NAME:serve

3. Run All Affected Builds

bash

# Build all affected projects
nx affected -t build

4. Run Full Validation

bash

# Run full CI validation
nx prepush

5. Review Migration Checklist

Common Issues and Solutions

Issue: "cookies() expects to be called in a synchronous context"

Solution: Make the function async and await cookies()

Issue: "params should be awaited before accessing properties"

Solution: Add await before accessing props.params

Issue: Build fails with Turbopack

Solution: Add --webpack flag to build script, then gradually address Turbopack compatibility

Issue: Middleware not working after rename

Solution: Ensure both file and function are renamed from middleware to proxy

Issue: Parallel route not rendering

Solution: Add default.tsx file to the parallel route slot

Issue: Images with query strings not loading

Solution: Add localPatterns configuration for those images

Issue: TypeScript errors with params types

Solution: Run npx next typegen to generate type helpers, then use PageProps, LayoutProps types

Files to Review

Create a checklist of all files that need review:

bash

# Find all pages with potential params usage
find . -path "*/app/*" -name "page.tsx" -o -name "page.ts" | xargs grep -l "params\|searchParams"

# Find all layouts
find . -path "*/app/*" -name "layout.tsx" -o -name "layout.ts"

# Find all route handlers
find . -path "*/app/*" -name "route.ts" -o -name "route.tsx"

# Find middleware files
find . -name "middleware.ts" -o -name "middleware.js"

# Find files using cookies/headers
rg "from 'next/headers'" --type ts --type tsx

# Find next.config files
find . -name "next.config.*" -not -path "*/node_modules/*"

# Find parallel routes
find . -path "*/app/@*" -type d

Migration Strategy for Large Workspaces

Migrate in phases: Start with a small project, validate, then expand
Use the codemod: Run npx @next/codemod@canary upgrade latest for automated fixes
Generate types: Run npx next typegen for type-safe migrations
Run tests frequently: After each configuration change, run affected tests
Document issues: Keep track of project-specific issues and solutions

Useful Commands During Migration

bash

# Find all Next.js projects
nx show projects --with-target build

# Build specific project
nx build PROJECT_NAME

# Serve specific project
nx serve PROJECT_NAME

# Build all affected
nx affected -t build

# View project details
nx show project PROJECT_NAME --web

# Clear Nx cache if needed
nx reset

Notes for LLM Execution

When executing this migration:

Work systematically: Complete one category before moving to the next
Test after each change: Don't batch all changes without validation
Keep user informed: Report progress through each section
Handle errors promptly: If builds fail, fix immediately before proceeding
Use the codemod first: Let @next/codemod handle repetitive async/await changes
Prioritize breaking changes: Focus on async APIs first as they're most impactful
Create meaningful commits: Group related changes together with clear messages
Use TodoWrite tool: Track migration progress for visibility