How to upgrade to version 15

Upgrading from 14 to 15

To update to Next.js version 15, you can use the upgrade codemod:

pnpm dlx @next/codemod@canary upgrade latest

npx @next/codemod@canary upgrade latest

yarn dlx @next/codemod@canary upgrade latest

bunx @next/codemod@canary upgrade latest

If you prefer to do it manually, ensure that you're installing the latest Next & React versions:

pnpm add next@latest react@latest react-dom@latest eslint-config-next@latest

npm install next@latest react@latest react-dom@latest eslint-config-next@latest

yarn add next@latest react@latest react-dom@latest eslint-config-next@latest

bun add next@latest react@latest react-dom@latest eslint-config-next@latest

React 19

• The Pages Router supports both React 18 and React 19, so upgrading react and react-dom to 19 is optional.

• useFormState has been replaced by useActionState. The useFormState hook is still available in React 19, but it is deprecated and will be removed in a future release. useActionState is recommended and includes additional properties like reading the pending state directly. Learn more.
• useFormStatus now includes additional keys like data, method, and action. If you are not using React 19, only the pending key is available. Learn more.
• Read more in the React 19 upgrade guide.

next/font

The @next/font package has been removed in favor of the built-in next/font. A codemod is available to safely and automatically rename your imports.

// Before
import { Inter } from '@next/font/google'
 
// After
import { Inter } from 'next/font/google'

bundlePagesRouterDependencies

experimental.bundlePagesExternals is now stable and renamed to bundlePagesRouterDependencies.

/** @type {import('next').NextConfig} */
const nextConfig = {
  // Before
  experimental: {
    bundlePagesExternals: true,
  },
 
  // After
  bundlePagesRouterDependencies: true,
}
 
module.exports = nextConfig

serverExternalPackages

experimental.serverComponentsExternalPackages is now stable and renamed to serverExternalPackages.

/** @type {import('next').NextConfig} */
const nextConfig = {
  // Before
  experimental: {
    serverComponentsExternalPackages: ['package-name'],
  },
 
  // After
  serverExternalPackages: ['package-name'],
}
 
module.exports = nextConfig

Speed Insights

Auto instrumentation for Speed Insights was removed in Next.js 15.

To continue using Speed Insights, follow the Vercel Speed Insights Quickstart guide.

NextRequest Geolocation

The geo and ip properties on NextRequest have been removed as these values are provided by your hosting provider. A codemod is available to automate this migration.

If you are using Vercel, you can alternatively use the geolocation and ipAddress functions from @vercel/functions instead:

import { geolocation } from '@vercel/functions'
import type { NextRequest } from 'next/server'
 
export function middleware(request: NextRequest) {
  const { city } = geolocation(request)
 
  // ...
}

import { ipAddress } from '@vercel/functions'
import type { NextRequest } from 'next/server'
 
export function middleware(request: NextRequest) {
  const ip = ipAddress(request)
 
  // ...
}

Troubleshooting

Installation fails after upgrading to React 19

• If another package's peer dependencies reject React 19, revert react, react-dom, their types, and react-is (if present) to the previous versions, provided the target Next.js version and router support them.
• Restore or remove React type overrides or resolutions added by the upgrade in package.json or pnpm-workspace.yaml.
• If installation interrupted the upgrade command, retry the same exact target with --skip-react-upgrade to preserve the repaired dependencies. If Next.js already matches the target, install dependencies and run any skipped codemods individually. Run the app's checks.

Installation fails after upgrading to ESLint 9

• If another package's peer dependencies reject ESLint 9, restore the previous compatible versions of eslint, eslint-config-next, and @next/eslint-plugin-next (if present), along with the previous lint configuration.
• If installation interrupted the upgrade command, retry the same exact target with --skip-eslint-upgrade to preserve the repaired dependency. If Next.js already matches the target, install dependencies and run any skipped codemods individually. Complete any required lint migration manually, then run the app's lint checks.

Review migration checklist

After applying the changes relevant to your app, review these action items before you consider the migration complete:

• React dependencies and types meet the React 19 requirements for the app's router.
• Font imports use next/font instead of @next/font.
• Existing bundlePagesExternals and serverComponentsExternalPackages settings use their documented stable names while preserving package configuration.
• NextRequest geo and ip consumers use an appropriate source for the actual hosting provider.
• Apps that relied on automatic Speed Insights instrumentation have an explicit integration if they still need it.
• The app's supported checks and affected runtime behavior pass. Remaining required failures keep the migration incomplete.