Next.js Upgrade Workflow

When to Apply

• Upgrading Next.js to a new major version (13, 14, 15, 16)
• Running codemods to automate breaking change migrations
• Resolving deprecation warnings in an existing Next.js project
• Planning an incremental migration path for large codebases
• Validating that an upgrade did not introduce regressions

9-Step Upgrade Workflow

Step 1: Detect Current Version

# Check current version
cat package.json | grep '"next"'

# Check Node.js version (Next.js 15+ requires Node 18.18+, Next.js 16 requires Node 20+)
node --version

Step 2: Create Upgrade Branch

git checkout -b upgrade/nextjs-{target-version}

Step 3: Run Codemods

# Interactive mode (recommended) -- selects applicable codemods
npx @next/codemod@latest upgrade latest

# Or target a specific version
npx @next/codemod@latest upgrade 15
npx @next/codemod@latest upgrade 16

Next.js 13 to 14

• next-image-to-legacy-image

  -- Renames

  next/image

  imports to

  next/legacy/image

• next-image-experimental

  -- Migrates from

  next/legacy/image

  to new

  next/image

• metadata

  -- Moves Head metadata to Metadata API exports

Next.js 14 to 15

• next-async-request-apis

  -- Converts synchronous dynamic APIs (

  cookies()

  ,

  headers()

  ,

  params

  ,

  searchParams

  ) to async

• next-dynamic-ssr-false

  -- Replaces

  ssr: false

  with

  { loading }

  pattern for

  next/dynamic

• next-og-import

  -- Moves OG image generation imports to

  next/og

Next.js 15 to 16

• next-use-cache

  -- Converts

  unstable_cache

  to

  'use cache'

  directive

• next-cache-life

  -- Migrates cache revalidation to

  cacheLife()

  API

• next-form

  -- Wraps

  <form>

  elements with

  next/form

  where applicable

Step 4: Update Dependencies

# Update Next.js and React together
npm install next@latest react@latest react-dom@latest

# For Next.js 15+, also update React types
npm install -D @types/react@latest @types/react-dom@latest

# Update eslint config
npm install -D eslint-config-next@latest

1. Check which packages require older React/Next versions
2. Update those packages first, or check for newer versions
3. Use

   --legacy-peer-deps

   only as a last resort (document why)

Step 5: Update Configuration

next.config.js

next.config.ts

// next.config.ts (Next.js 15+ recommends TypeScript config)
import type { NextConfig } from 'next';

const nextConfig: NextConfig = {
  // Next.js 15+: experimental features that graduated
  // Remove these from experimental:
  // - serverActions (now stable in 14+)
  // - appDir (now stable in 14+)
  // - ppr (now stable in 16+)

  // Next.js 16+: new cache configuration
  cacheComponents: true,  // Enable component-level caching
};

export default nextConfig;

appDir

serverActions

bundlePagesRouterDependencies

swcMinify

dynamicIO

cacheComponents: true

Step 6: Resolve Breaking Changes

1. Async Request APIs:

   cookies()

   ,

   headers()

   ,

   params

   ,

   searchParams

   are now async
   typescript

   // Before (Next.js 14)
   export default function Page({ params }: { params: { id: string } }) {
     const { id } = params;
   }
   
   // After (Next.js 15+)
   export default async function Page({ params }: { params: Promise<{ id: string }> }) {
     const { id } = await params;
   }

2. Caching Default Changed:

   fetch()

   requests are no longer cached by default in Next.js 15+
   typescript

   // Before: cached by default
   fetch('https://api.example.com/data');
   
   // After: explicitly opt-in to caching
   fetch('https://api.example.com/data', { cache: 'force-cache' });
   // Or use 'use cache' directive in Next.js 16

3. Route Handlers: GET route handlers are no longer cached by default
   typescript

   // Next.js 15+: explicitly set caching
   export const dynamic = 'force-static';

Step 7: Run Tests

# Run existing test suite
npm test

# Run build to catch compile-time errors
npm run build

# Run dev server and check key pages manually
npm run dev

• Build completes without errors
• All existing tests pass
• Key user flows work in dev mode
• No console warnings about deprecated APIs
• Server-side rendering works correctly
• Client-side navigation works correctly
• API routes return expected responses
• Middleware functions correctly
• Static generation (SSG) pages build correctly

Step 8: Update TypeScript Types

# Regenerate TypeScript declarations
npm run build

# Fix any new type errors
npx tsc --noEmit

• PageProps

  type changes (params/searchParams become Promise in 15+)

• Metadata

  type updates (new fields added)

• NextRequest

  /

  NextResponse

  API changes
• Route handler parameter types

Step 9: Document and Commit

# Create detailed commit
git add -A
git commit -m "chore: upgrade Next.js from {old} to {new}

Breaking changes resolved:
- [list specific changes]

Codemods applied:
- [list codemods run]

Manual fixes:
- [list manual changes]"

Incremental Upgrade Path

Next.js 13 -> 14 -> 15 -> 16

• Codemods are version-specific and may not compose correctly across multiple versions
• Easier to debug issues when changes are smaller
• Each version has its own set of breaking changes to resolve
• Tests can validate each intermediate step

1. Run codemods for that version
2. Update deps
3. Fix breaking changes
4. Run tests
5. Commit checkpoint
6. Proceed to next version

Troubleshooting

Build fails after upgrade

1. Clear

   .next

   directory:

   rm -rf .next

2. Clear node_modules:

   rm -rf node_modules && npm install

3. Clear Next.js cache:

   rm -rf .next/cache

Module not found errors

1. Check if package was renamed or merged
2. Update imports per migration guide
3. Check if package needs separate update

Hydration mismatches after upgrade

1. Check for server/client rendering differences
2. Ensure dynamic imports use correct options
3. Verify date/locale handling is consistent

Middleware issues

1. Middleware API changed in Next.js 13 (moved to root)

2. NextResponse.rewrite()

   behavior changed in 15
3. Check matcher configuration syntax

Iron Laws

1. ALWAYS upgrade on a dedicated branch, never on main directly — upgrade branches can be rebased or reverted without disrupting production; direct main upgrades risk deploying half-migrated code.
2. NEVER skip intermediate versions in a multi-version jump — Next.js codemods are version-specific and do not compose correctly across major versions; skipping steps leaves un-migrated breaking changes.
3. ALWAYS run official codemods before making manual changes — codemods handle the bulk of mechanical migrations; manual-first approaches miss patterns and create divergence from the reference migration path.
4. NEVER use

   --legacy-peer-deps

   without documenting the specific conflict and resolution plan — suppressing peer errors hides version conflicts that will cause runtime failures.
5. ALWAYS validate with a full build plus test suite before merging — the dev server does not exercise SSG, edge runtime, or build optimizations that can fail silently post-upgrade.

Anti-Patterns

upgrade/nextjs-{version}

--legacy-peer-deps

npm run build

References

• Next.js Upgrade Guide
• Next.js Codemods
• Next.js Changelog