How to Safely Upgrade to Next.js 15

📅

loading..🐩🐩🐩🐩

Before We Begin 🔗

Next.js continues to evolve, offering a faster and more efficient environment for building web applications.

Next.js 15

, released in 2024, introduced several significant changes, so prepare carefully before upgrading an existing project.

This guide walks through upgrading from Next.js 14 to 15 with examples. If you're on an earlier version, consider upgrading to 14 first.

Main Changes at a Glance 🔗

Before upgrading, review the areas covered in this guide:

The priority prop in next/image.
The fallback option in next/font.
Turbopack updates.
A new approach to MDX support.
Stricter Strict Mode behavior.
The introduction of Async Request APIs.
Official codemods to automate parts of the migration.
We'll look at these changes in more detail below.

Check Versions and Update Dependencies 🔗

Start by checking the version of Next.js in your project and reviewing the related dependencies.

npm list next

If you're on 14.x, use the following command to upgrade to version 15.

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

If you use Yarn, run this instead.

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

Update React and React DOM together with Next.js. Their versions are closely related, and mismatched dependencies can cause errors.

Troubleshooting 🔗

1. Review the `priority` Prop in `next/image` 🔗

The original guide treats the priority prop as deprecated in Next.js 15 and uses the following example.

<Image src="/logo.png" alt="logo" width={100} height={100} priority />

It suggests removing priority and using <link rel="preload"> directly or considering loading="eager".

<Image src="/logo.png" alt="logo" width={100} height={100} loading="eager" />

2. Review the `next/font` fallback Configuration 🔗

The previous configuration in this example sets fallback fonts as follows.

const inter = Inter({ subsets: ['latin'], fallback: ['Arial'] });

The original guide describes a change to how fallback handles string arrays and notes that you may see a warning. If you do, check the font configuration documentation for your installed version.

3. Check Projects Using Turbopack 🔗

Next.js 15 improved Turbopack. The following example shows how to configure it explicitly in next.config.js.

const nextConfig = {
  experimental: {
    turbo: true,
  },
};
module.exports = nextConfig;

Some features may still cause compatibility issues. If you run into problems, consider disabling Turbopack.

4. Adopt Async Request APIs 🔗

Next.js 15 introduced

Async Request APIs

. These affect access to request data in server-side code, including request.cookies and request.headers in the examples below.

The original synchronous approach uses a helper such as headers().

import { headers } from 'next/headers';
export default async function Page() {
  const headerList = headers();
  const token = headerList.get('Authorization');
  return <div>Header 확인</div>;
}

The second example in the original guide illustrates asynchronous access using a request object passed through props.

export default async function Page({ request }) {
  const token = await request.headers.get('Authorization');
  return <div>Header 확인</div>;
}

This pattern illustrates how to access properties such as cookies, headers, url, and body. Treat this example as experimental, and consult the official Async Request API codemod documentation↗ before migrating your project.

5. Automate Migration with Codemods 🔗

Next.js 15 provides

codemods

for repetitive and error-prone changes. Common tasks include:

Removing or updating deprecated props, such as priority where applicable.
Refactoring code to use new APIs.
Updating calls affected by Async Request APIs.
Here's how to run a codemod.

npx @next/codemod <transform> <path>

The original example for removing priority is shown below.

npx @next/codemod remove-priority-image ./src

Check the available codemods in the official documentation↗. Commit or back up your code in a version control system such as Git before applying a transform.

Conclusion 🔗

Upgrading to Next.js 15 takes care, but working through the changes one at a time makes the migration manageable. Review the release notes closely when dealing with deprecated props or configuration.

If you see unexpected build or runtime errors, start by identifying which features changed from the previous release.

Further Considerations 🔗

Did you also update eslint-config-next to a compatible version?
If you've used Turbopack in your project, record what worked well and where it caused problems.
Note what made the Async Request APIs easier to use and what differed from your expectations.
Compare the changes codemods automated with the changes you had to make by hand.

References 🔗

How to Safely Upgrade to Next.js 15 | PromleeBlog

How to Safely Upgrade to Next.js 15

How to Safely Upgrade to Next.js 15

Before We Begin 🔗

Main Changes at a Glance 🔗

Check Versions and Update Dependencies 🔗

Troubleshooting 🔗

1. Review the priority Prop in next/image 🔗

2. Review the next/font fallback Configuration 🔗

3. Check Projects Using Turbopack 🔗

4. Adopt Async Request APIs 🔗

5. Automate Migration with Codemods 🔗

Conclusion 🔗

Further Considerations 🔗

References 🔗

1. Review the `priority` Prop in `next/image` 🔗

2. Review the `next/font` fallback Configuration 🔗