Upgrading your Next.js application from version 14 to 15 involves several key steps to ensure a smooth transition and to take advantage of the latest features and improvements. Here's a comprehensive guide to assist you through the process:

Automated Upgrade with Codemod CLI

Next.js provides a codemod CLI tool to automate the upgrade process:

npx @next/codemod@canary upgrade latest

This command will:

• Update Dependencies: Automatically upgrade NextJs, react, and react-dom to their latest versions.
• Apply Codemods: Transform your codebase to align with Next.js 15's new APIs and conventions.

Note: Ensure you have a clean working directory and commit all changes before running the codemod.

Manual Upgrade Steps

If you prefer or encounter issues with the automated tool, follow these manual steps:

Update Dependencies

Manually update your package.json to reflect the latest versions:

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

Then, install the updated packages:

npm install

Update Dynamic APIs to Asynchronous

In Next.js 15, certain APIs that were previously synchronous are now asynchronous. This change affects functions like cookies, header, api params and search params.

Example:
Before (Next.js 14):

Before (Next.js 14):
import { cookies } from 'next/headers';

export default function Page() {
  const cookieStore = cookies();
  const token = cookieStore.get('token');
  // ...
}

After (Next.js 15):

import { cookies } from 'next/headers';

export default async function Page() {
  const cookieStore = await cookies();
  const token = cookieStore.get('token');
  // ...
}

Update next.config.mjs for fixing possible errors or warning

⚠️ Warnings you'll see if not updated
❌ Errors that may occur

Webpack vs. Turbopack Warning

⚠️ Warning You Might See:

Webpack is configured while Turbopack is not, which may cause problems. ⚠ See instructions if you need to configure Turbopack:

If you want to use Turbopack, add this to next.config.mjs:

/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    turbo: {
      loaders: {}, // Enables Turbopack
    },
  },
};

export default nextConfig;

images.domains is Deprecated

⚠ The "images.domains" configuration is deprecated. Please use "images.remotePatterns" configuration instead.

Old (Deprecated) Code:

const nextConfig = {
  images: {
    domains: ["example.com", "cdn.example.com"], // ❌ Deprecated
  },
};

New (Correct) Code:

New (Correct) Code:
const nextConfig = {
  images: {
    remotePatterns: [
      { protocol: "https", hostname: "example.com" },
      { protocol: "https", hostname: "cdn.example.com" },
    ],
  },
};

revalidate:false is Deprecated

⚠ The "revalidate: false" setting is deprecated. Use "generateStaticParams" instead.

Old (Deprecated) Code:

export const revalidate = false; // ❌ Deprecated

New (Correct) Code:

export async function generateStaticParams() {
  return []; // Forces fresh SSR on each request
}

Ensure you refactor all instances of these APIs to use await as shown above.

Adjust Caching Behavior

Next.js 15 has updated its caching semantics:

• fetch Requests: No longer cached by default. If caching is desired, specify the cache option in your fetch calls.
• Route Handlers: GET functions are not cached by default. To enable caching, use the dynamic export:

export const dynamic = 'force-static';

export async function GET() {
  // ...
}

Review your data fetching logic and route handlers to align with these new caching behaviors.

Update ESLint Configuration

Next.js 15 supports ESLint 9. If you're upgrading, ensure your ESLint configuration is compatible:

• Upgrade ESLint:

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

• Update Configuration: ESLint 9 introduces a new flat configuration format. Update your .eslintrc configuration accordingly.

Testing and Validation

After completing the upgrade:

• Run Tests: Execute your test suite to identify any issues resulting from the upgrade.
• Manual Testing: Navigate through your application to ensure all functionality works as expected.
• Monitor Logs: Check for any warnings or errors in the console and address them promptly.

By following this guide, you can smoothly transition your application from Next.js 14 to 15, leveraging the latest features and improvements.