Node.js 18.17 or newer is required
Action requiredOlder Node.js runtimes are unsupported.
Migration
Update local, CI and hosting runtimes before building.
Official sources
Next.js Upgrade Guide
Compare Next.js versions and see exactly what changes, what requires action, and what you can start using.
→
9Changes
5Breaking
9Actions
0Features
1Migration tools
Analyze your project
Local only Check your package.json
UpgradePath detects relevant tools and selects them automatically.
Analyzed locally in your browser. Nothing is uploaded.
Project setup
What does your project use?
Select the tools in your project to include relevant dependency updates in this guide.
Breaking Changes
next export is removed
Action requiredStatic export is configured through output.
// build: next build && next export
module.exports = {};// build: next build
module.exports = {
output: 'export',
}; Migration
Set output: 'export' in next.config.js and run next build. Check dynamic routes and server-only features.
Official sources
@next/font is removed
Action requiredUse the built-in font module.
import { Roboto } from '@next/font/google';
const font = Roboto({ weight: '400', subsets: ['latin'] });import { Roboto } from 'next/font/google';
const font = Roboto({ weight: '400', subsets: ['latin'] }); Migration
Replace @next/font imports with next/font; run npx @next/codemod@latest built-in-next-font .
Official sources
ImageResponse moves to next/og
Action requiredThe next/server import is replaced.
import { ImageResponse } from 'next/server';
export async function GET() {
return new ImageResponse(<div>UpgradePath</div>);
}import { ImageResponse } from 'next/og';
export async function GET() {
return new ImageResponse(<div>UpgradePath</div>);
} Migration
Import ImageResponse from next/og and verify generated social images.
Official sources
Request APIs become asynchronous
Action requiredcookies, headers, draftMode, params and searchParams require migration.
import { cookies } from 'next/headers';
type Props = { params: { slug: string } };
export default function Page({ params }: Props) {
const theme = cookies().get('theme')?.value;
return <main data-theme={theme}>{params.slug}</main>;
}import { cookies } from 'next/headers';
type Props = { params: Promise<{ slug: string }> };
export default async function Page({ params }: Props) {
const { slug } = await params;
const store = await cookies();
const theme = store.get('theme')?.value;
return <main data-theme={theme}>{slug}</main>;
} Migration
Await request APIs and route props in App Router code. Run npx @next/codemod@latest next-async-request-api . and review its output.
Official sources
Migration Tools
App Router adopts React 19
Action requiredReact dependencies and types need coordinated updates.
{
"dependencies": {
"next": "^14.0.0",
"react": "^18.2.0",
"react-dom": "^18.2.0"
}
}{
"dependencies": {
"next": "^15.0.0",
"react": "^19.0.0",
"react-dom": "^19.0.0"
}
} Migration
Upgrade react and react-dom together. For TypeScript, update their types and check third-party peer dependencies.
Official sources
Behavior Changes
fetch is uncached by default
Action requiredServer fetch calls no longer opt into caching automatically.
// Next.js 14: cache-eligible server request
const response = await fetch('https://example.com/api/catalog');// Next.js 15: opt in if this catalog should remain cached
const response = await fetch('https://example.com/api/catalog', {
cache: 'force-cache',
}); Migration
Use cache: 'force-cache' explicitly where caching is intended; check freshness and SSR performance.
Official sources
GET Route Handlers are uncached by default
Action requiredGET responses no longer default to cached output.
// app/api/catalog/route.ts
export async function GET() {
return Response.json({ categories: ['books', 'music'] });
}// Only for public data intended to be statically cached.
export const dynamic = 'force-static';
export async function GET() {
return Response.json({ categories: ['books', 'music'] });
} Migration
Opt eligible handlers into static caching with export const dynamic = 'force-static'.
Official sources
Page segments are not cached by default
Action requiredClient navigation changes page cache reuse.
// next.config.mjs
// Next.js 14 page cache defaults
export default {};// Optional: reuse dynamic page segments for 30 seconds.
export default {
experimental: {
staleTimes: { dynamic: 30 },
},
}; Migration
Review navigation and staleTimes configuration; test back/forward behavior.
Official sources