Next.js Upgrade Guide

// build: next build && next export
module.exports = {};

// build: next build
module.exports = {
  output: 'export',
};

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'] });

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>);
}

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>;
}

// Next.js 15 temporary synchronous compatibility
import { cookies, type UnsafeUnwrappedCookies } from 'next/headers';
export function readTheme() {
  const store = cookies() as unknown as UnsafeUnwrappedCookies;
  return store.get('theme')?.value;
}

// Next.js 16: remove synchronous access
import { cookies } from 'next/headers';
export async function readTheme() {
  const store = await cookies();
  return store.get('theme')?.value;
}

{
  "scripts": {
    "lint": "next lint",
    "build": "next build"
  }
}

{
  "scripts": {
    "lint": "eslint .",
    "build": "next build",
    "check": "npm run lint && npm run build"
  }
}

import type { MetadataRoute } from 'next';
export async function generateSitemaps() {
  return [{ id: 0 }, { id: 1 }];
}
export default async function sitemap(
  { id }: { id: number },
): Promise<MetadataRoute.Sitemap> {
  return [{ url: 'https://example.com/catalog/' + id }];
}

import type { MetadataRoute } from 'next';
export async function generateSitemaps() {
  return [{ id: 0 }, { id: 1 }];
}
export default async function sitemap(
  { id }: { id: Promise<string> },
): Promise<MetadataRoute.Sitemap> {
  const shard = Number(await id);
  return [{ url: 'https://example.com/catalog/' + shard }];
}

// next.config.mjs: local /assets/photo.jpg?v=2
export default {};

export default {
  images: {
    localPatterns: [{ pathname: '/assets/**', search: '?v=2' }],
  },
};

// next.config.mjs: relying on Next.js 15 image defaults
export default {};

// Configure only the old behavior your application needs.
export default {
  images: {
    minimumCacheTTL: 60,
    imageSizes: [16, 32, 48, 64, 96, 128, 256, 384],
    qualities: [60, 75, 90],
  },
};

import Image from 'next/image';
// Private-IP source that may now be rejected.
export default function Photo() {
  return <Image src='http://10.0.0.5/photo.jpg' width={640} height={480} alt='Catalog' />;
}

import Image from 'next/image';
// Prefer a trusted public origin, allowlisted with images.remotePatterns.
export default function Photo() {
  return <Image src='https://assets.example.com/photo.jpg' width={640} height={480} alt='Catalog' />;
}
// Do not enable dangerouslyAllowLocalIP as a blanket migration fix.

// next.config.mjs: image redirects were previously unlimited
export default {};

// Prefer final asset URLs. If a longer chain is required:
export default {
  images: { maximumRedirects: 5 },
};

// pages/article.tsx
import { useAmp } from 'next/amp';
export const config = { amp: 'hybrid' };
export default function Article() {
  const isAmp = useAmp();
  return <main><h1>Article</h1><p>{isAmp ? 'AMP edition' : 'Web edition'}</p></main>;
}

// pages/article.tsx: standard page, no AMP APIs/configuration
export default function Article() {
  return <main><h1>Article</h1><p>Web edition</p></main>;
}
// Replace AMP-specific elements and review former AMP URLs/canonicals.

// app/@modal/page.tsx exists, but @modal has no default.tsx.
export default function ModalPage() {
  return null;
}

// Add app/@modal/default.tsx for unmatched direct navigation.
export default function ModalDefault() {
  return null;
}
// Add an appropriate default for each parallel slot;
// use notFound() if unmatched routes should return 404.

// Experimental PPR on Next.js 15 canaries
export default { experimental: { ppr: true } };
// Routes may also export experimental_ppr.

// Only when intentionally migrating to Cache Components:
export default { cacheComponents: true };
// Remove experimental_ppr and migrate affected routes.
// Review Suspense boundaries and caching; this is not just a flag rename.
// If not adopting this model, remove old flags instead of enabling it.

import 'server-only';
import getConfig from 'next/config';
export function readApiToken() {
  return getConfig().serverRuntimeConfig.apiToken;
}

import 'server-only';
import { connection } from 'next/server';
export async function readApiToken() {
  await connection(); // read this value at request time
  return process.env.API_TOKEN;
}
// Never prefix secrets with NEXT_PUBLIC_.

import { ImageResponse } from 'next/og';
type Props = { params: { slug: string }; id: string };
export default function Image({ params, id }: Props) {
  return new ImageResponse(<div>{params.slug}: {id}</div>);
}

import { ImageResponse } from 'next/og';
type Props = { params: Promise<{ slug: string }>; id: Promise<string> };
export default async function Image({ params, id }: Props) {
  const { slug } = await params;
  const imageId = await id;
  return new ImageResponse(<div>{slug}: {imageId}</div>);
}
// This is the image function, not generateImageMetadata.

// next.config.mjs: projects already using React Compiler
export default { experimental: { reactCompiler: true } };

// next.config.mjs: optional, not required for the upgrade
export default { reactCompiler: true };
// Keep babel-plugin-react-compiler installed if opting in.

{
  "scripts": {
    "dev": "next dev",
    "build": "next build"
  }
}

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

{"extends":["next/core-web-vitals","next/typescript"]}

// eslint.config.mjs (JavaScript, not JSON)
import { defineConfig } from "eslint/config";
import nextVitals from "eslint-config-next/core-web-vitals";
import nextTypes from "eslint-config-next/typescript";
export default defineConfig([...nextVitals, ...nextTypes]);

{
  "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"
  }
}

{
  "dependencies": {
    "next": "^15.0.0",
    "react": "^19.0.0",
    "react-dom": "^19.0.0"
  }
}

{
  "dependencies": {
    "next": "^16.0.0",
    "react": "^19.2.0",
    "react-dom": "^19.2.0"
  }
}

import { unstable_cacheLife as cacheLife, unstable_cacheTag as cacheTag } from 'next/cache';

import { cacheLife, cacheTag } from 'next/cache';

// 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',
});

// 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'] });
}

// 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 },
  },
};

// middleware.ts
import { NextResponse, type NextRequest } from 'next/server';
export function middleware(request: NextRequest) {
  if (request.nextUrl.pathname === '/old-guide') {
    return NextResponse.redirect(new URL('/guides', request.url));
  }
  return NextResponse.next();
}

// proxy.ts: verify Node.js runtime compatibility
import { NextResponse, type NextRequest } from 'next/server';
export function proxy(request: NextRequest) {
  if (request.nextUrl.pathname === '/old-guide') {
    return NextResponse.redirect(new URL('/guides', request.url));
  }
  return NextResponse.next();
}

'use server';
import { revalidateTag } from 'next/cache';
export async function invalidateCatalog() {
  revalidateTag('catalog');
}

'use server';
import { revalidateTag, updateTag } from 'next/cache';
export async function invalidateInBackground() {
  revalidateTag('catalog', 'max');
}
// Immediate read-your-writes in a Server Action:
export async function invalidateImmediately() {
  updateTag('catalog');
}

import Image from 'next/legacy/image';
export default function Photo() {
  return <Image src='/photo.jpg' width={640} height={480} alt='Catalog' />;
}

import Image from 'next/image';
export default function Photo() {
  return <Image src='/photo.jpg' width={640} height={480} alt='Catalog' />;
}
// Recheck layout/styling; the new component's behavior differs.