Skip to Content
Clerk logo

Clerk Docs

Ctrl + K
Go to clerkstage.dev

Upgrading Next.js from v4 to v5

By the end of this guide, you’ll have successfully upgraded your Next.js project to use @clerk/nextjs v5. You’ll learn how to update your dependencies, resolve breaking changes, and find deprecations.

Step-by-step instructions will lead you through the process. If you’re looking for a reference list of changes, check out the general upgrading from v4 to v5 guide.

To aid you in this upgrade, Clerk built a CLI called @clerk/upgrade. Throughout this guide you'll see prompts to use the CLI which you can invoke directly in your terminal.

terminal
npx @clerk/upgrade
terminal
yarn dlx @clerk/upgrade
terminal
pnpm dlx @clerk/upgrade

Minimum version requirements

The minimum version requirements for Node.js, React, and Next.js have been updated. Versions that are no longer supported or are at end-of-life are no longer guaranteed to work correctly with Clerk. Please take a moment to check your dependencies and ensure you are up to date!

Updating Node.js

You need to have Node.js 18.17.0 or later installed. Last year, Node.js 16 entered EOL (End of life) status so it's time to bump the required version for @clerk/nextjs, too. You can check your Node.js version by running node -v in your terminal. Learn more about how to update and install Node.js.

Updating React

@clerk/nextjs now requires you to use React 18 or higher. You can update your project by installing the latest version of react and react-dom.

terminal
npm install react@latest react-dom@latest
terminal
yarn add react@latest react-dom@latest
terminal
pnpm add react@latest react-dom@latest

If you are upgrading from React 17 or lower, make sure to learn about how to upgrade to React 18 as well.

Updating Next.js

@clerk/nextjs now requires you to use Next.js 13.0.4 or later. Check out Next's upgrade guides for more guidance if you have not yet upgraded to Next.js 13:

Redesigned components

The new version ships with improved design and UX across all of Clerk's UI components. If you have used the appearance prop or tokens for a custom theme, you will likely need to make some adjustments to ensure your styling is still looking great. If you're using the localization prop you will likely need to make adjustments to account for added or removed localization keys.

If you are not customizing the appearance of your components, or using localization, you can skip this section. Otherwise it's recommended to use the CLI (npx @clerk/upgrade) to scan for changes required as part of the component redesign.

The sections below contain more info on each change made to the customization IDs and localization keys for reference. Regardless of how thoroughly you have reviewed the following information, you should still take some time to manually look through each of your views to ensure that everything looks allright.

Appearance changes

Localization changes

New Middleware architecture

User and customer feedback about authMiddleware() has been clear in that Middleware logic was a often friction point. As such, in v5 you will find a completely new Middleware helper called clerkMiddleware() that will hopefully alleviate all of the issues folks had with authMiddleware().

Additionally, there are now new helpers that enable controlling auth on a per-page and/or per-layout basis when using App Router. While you can still configure which routes are protected via Middleware, the page-based protection strategy is what is now recommended, as the co-location of auth protection configuration with the code for the pages themselves results in a superior developer experience that adds clarity as you navigate your codebase.

Per-route auth config

Sometimes, code speaks louder than words. Let's get right into an example. auth().protect() is added to a layout and and all of its children will be gated by auth.

app/src/dashboard/layout.tsx
import { auth } from '@clerk/nextjs/server'
 
export default async function DashboardLayout({ children }) {
    auth().protect();
    // 👆 This one line is all it takes - the layout and all its children
    // will now redirect to your sign in page for un-authenticated users.
 
    return <>{children}</>
}

Want to get more specific with permission gating? Add the role you are gating as a parameter:

app/src/admin/layout.tsx
import { auth } from '@clerk/nextjs/server'
 
export default async function AdminLayout({ children }) {
    auth().protect({ role: 'org:admin' });
 
    return <>{children}</>
}

Note that in order for this to work, you will still need Middleware to be present, but it only requires the most minimal configuration:

middleware.ts
import { clerkMiddleware } from '@clerk/nextjs/server'
 
export default clerkMiddleware()
 
export const config = {
  matcher: ["/((?!.*\\..*|_next).*)", "/", "/(api|trpc)(.*)"],
}

If you are using the Pages Router, please use the setup explained in the next section.

Middleware auth config

If you prefer to define your auth logic within the Middleware, you can still do this with the new version of @clerk/nextjs. The primary change was to make clerkMiddleware() not protect any routes by default, instead requiring the developer to add routes they would like to be protected by auth. This is a substantial contrast to the previous authMiddleware(), which protected all routes by default, requiring the developer to add exceptions. The API was substantially simplified and makes it easier to combine clerkMiddleware() with other Middleware helpers.

Here's an example that replicates the auth protection scheme above, but entirely inside the Middleware:

middleware.ts
import {
  clerkMiddleware,
  createRouteMatcher,
} from "@clerk/nextjs/server"
 
const isDashboardRoute = createRouteMatcher(["/dashboard(.*)"])
const isAdminRoute = createRouteMatcher(["/admin"])
 
export default clerkMiddleware((auth, req) => {
  // Restrict admin route to users with specific role
  if (isAdminRoute(req)) auth().protect({ role: "org:admin" })
 
  // Restrict dashboard routes to logged in users
  if (isDashboardRoute(req)) auth().protect()
})
 
export const config = {
  matcher: ["/((?!.*\\..*|_next).*)", "/", "/(api|trpc)(.*)"],
}

A couple things to note here:

  • The createRouteMatcher helper makes it easy to define route groups that you can leverage inside the Middleware function and check in whichever order you'd like. Note that it can take an array of routes as well.
  • With clerkMiddleware, you're defining the routes you want to be protected, rather than the routes you don't want to be protected.
  • You are able to use the same auth().protect() helpers that you can use within layouts/pages here in the Middleware.

Migrating to clerkMiddleware()

Clerk strongly recommends migrating to the new clerkMiddleware() for an improved DX and access to all present and upcoming features, but also want to note that authMiddleware(), while deprecated, will continue to work in v5 and will not be removed until the next major version, so you do not need to make any changes to your Middleware setup this version.

The most basic migration will be updating the import and changing out the default export.

- import { authMiddleware } from "@clerk/nextjs"
+ import { clerkMiddleware } from '@clerk/nextjs/server'
 
- export default authMiddleware()
+ export default clerkMiddleware()
 
  export const config = {
    matcher: ["/((?!.*\\..*|_next).*)", "/", "/(api|trpc)(.*)"],
  }

Of course, in most cases you'll have a more complicated setup than this. You can find some examples below for how to migrate a few common use cases. Be sure to review the clerkMiddleware() documentation and route protection guide if your specific use case is not mentioned.

Changes to top-level exports

As part of this release, Clerk changed some of the top-level exports of @clerk/nextjs in order to improve bundle size and tree-shaking efficiency. These changes have resulted in a ~75% reduction in build size for Middleware bundles. However, you will likely need to make some changes to import paths as a result.

Use the CLI tool, npx @clerk/upgrade, to automatically find occurences of old imports.

After sign up/in/out URL handling

Defining redirect URLs for after sign up, in, and/or out via the Clerk dashboard has been removed in v5. In your Clerk dashboard, under "paths", there is a section called "Component paths", where URLs could be defined that had a deprecation warning. In v5, this functionality has been removed, and specifying redirect paths via the dashboard will no longer work. If you need to pass a redirect URL for after sign in/up/out, there are a few different ways this can be done, from environment variables to Middleware to supplying them directly to the relevant components.

As part of this change, the default URL for each of these props has been set to /, so if you are passing / explicitly to any one of the above props, that line is no longer necessary and can be removed.

- <UserButton afterSignOutUrl='/' />
+ <UserButton />

Deprecation removals & housekeeping

As part of this major version, a large number of previously deprecated props, arguments, methods, etc. have been removed. It's highly unlikely that any given app will encounter any of these items, as they have been used internally or very rarely.

For this section more than any other one, please use the CLI upgrade tool (npx @clerk/upgrade). As there are a lot of changes, each of which are very unlikely to appear in your codebase, it would take a long time to look for them manually.

Deprecation removals

Other breaking changes

What did you think of this content?

Clerk © 2024