Skip to Content
You are viewing a beta version of Clerk Docs
Visit the latest docs
Clerk logo

Clerk Docs

Ctrl + K
Go to

Upgrading @clerk/nextjs to Core 2

Core 2 is included in the Next.js SDK starting with version 5.0.0. This new version ships with an improved design and UX for its built-in components, no "flash of white page" when authenticating, a substantially improved middleware import, and a variety of smaller DX improvements and housekeeping items. Each of the potentially breaking changes are detailed in this guide, below.

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.

Preparing to upgrade

Before uprading, it's highly recommended that you update your Clerk SDKs to the latest Core 1 version (npm i @clerk/nextjs@4). Some changes required for Core 2 SDKs can be applied incrementally to the v5 release, which should contribute to a smoother upgrading experience. After updating, look out for deprecation messages in your terminal and browser console. By resolving these deprecations you'll be able to skip many breaking changes from Core 2.

Note that Core 2 is currently in beta, while we field feedback and ensure stability. Deploying beta versions to production is not recommended and should be done at your own risk.

Additionally, some of the minumum version requirements for some base dependencies have been updated such that versions that are no longer supported or are at end-of-life and are no longer guaranteed to work correctly with Clerk.

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 support for this version has been removed across Clerk SDKs. You can check your Node.js version by running node -v in your terminal. Learn more about how to update and install Node.js(opens in a new tab).

Updating React

All react-dependent Clerk SDKs now require you to use React 18 or higher. You can update your project by installing the latest version of react and react-dom.

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

If you are upgrading from React 17 or lower, make sure to learn about how to upgrade your React version to 18(opens in a new tab) as well.

Updating Next.js

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

Updating to Core 2 Beta

Whenever you feel ready, go ahead and install the latest beta version of any Clerk SDKs you are using. Make sure that you are prepared to patch some breaking changes before your app will work properly, however. The commands below demonstrate how to install the latest beta.

npm install @clerk/nextjs@beta
yarn add @clerk/nextjs@beta
pnpm add @clerk/nextjs@beta

CLI upgrade helper

Clerk now provides a @clerk/upgrade CLI tool that you can use to ease the upgrade process. The tool will scan your codebase and produce a list of changes you'll need to apply to your project. It should catch the vast majority of the changes needed for a successful upgrade to any SDK including Core 2. This can save you a lot of time reading through changes that don't apply to your project.

To run the CLI tool, navigate to your project and run it in the terminal:

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

If you are having trouble with npx, it's also possible to install directly with npm i @clerk/upgrade -g, and can then be run with the clerk-upgrade command.

Breaking Changes

Component design adjustments

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.

More detail on these 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 should alleviate the issues folks had with authMiddleware().

The primary change from the previous authMiddleware() is that clerkMiddleware() does 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 also substantially simplified, and it has become easier to combine with other Middleware helpers smoothly as well.

Here's an example that demonstrates route protection based on both authentication and authorization:

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 signed 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.
  • The auth().protect()(opens in a new tab) helper is utilized heavily here, check out its docs for more info.

See the clerkMiddleware() docs for more information and detailed usage examples.

Migrating to clerkMiddleware()

Clerk strongly recommends migrating to the new clerkMiddleware() for an improved DX and access to all present and upcoming features. However, 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, then mirroring the previous behavior of protecting all routes as such:

- import { authMiddleware } from "@clerk/nextjs" + import { clerkMiddleware } from '@clerk/nextjs/server' - export default authMiddleware() + export default clerkMiddleware((auth) => auth().protect()) 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 if your specific use case is not mentioned.

Changes to top-level exports

As part of this release, some of the top-level exports of @clerk/nextjs have been changed 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 to automatically find occurences of imports that need to be changed.

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 Core 2. In your Clerk Dashboard, under Paths in the sidebar on the left, there is a section called Component paths that has a deprecation warning. In Core 2, 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(opens in a new tab), 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 />

Removed: orgs claim on JWT

In the previous version of Clerk's SDKs, if you decode the session token that Clerk returns from the server, you'll currently find an orgs claim on it. It lists all the orgs associated with the given user. Now, Clerk returns the org_id, org_slug, and org_role of the active organization.

The orgs claim was part of the JwtPayload. Here are a few examples of where the JwtPayload could be found.

If you would like to have your JWT return all of the user's organizations, you can create a custom JWT template in your dashboard. Add { "orgs": "user.organizations" } to it.

Path routing is now the default

On components like <SignIn /> you can define the props routing and path. routing describes the routing strategy that should be used and can be set to 'hash' | 'path' | 'virtual'. path defines where the component is mounted when routing='path' is used.

In the latest version, the default routing strategy has become 'path'. Unless you change the routing prop, you will need to define the path prop. The affected components are:

  • <SignIn />
  • <SignUp />
  • <UserProfile />
  • <CreateOrganization />
  • <OrganizationProfile />

Here is how you would use the components going forward:

<SignIn path="/sign-in" /> <SignUp path="/sign-up" /> <UserProfile path="/user-profile" /> <CreateOrganization path="/create-org" /> <OrganizationProfile path="/org-profile" />

If you do not define the path prop, an error will be thrown. Of course, you can still use routing='hash' or routing='virtual'.

<UserProfile routing="hash" /> <OrganizationProfile routing="virtual" />

For the @clerk/nextjs SDK, you can avoid needing to explicitly pass the path to the <SignIn /> and <SignUp /> components by setting environment variables for the sign in/up URLs like so:


If you have defined both environment variables as above, you can use the <SignIn /> and <SignUp /> components without any props:

<SignIn /> <SignUp />

Image URL Name Consolidation

There are a number of Clerk primitives that contain images, and previously they each had different property names, like avatarUrl, logoUrl, profileImageUrl, etc. In order to promote consistency and make it simpler for developers to know where to find associated images, all image properties are now named imageUrl. See the list below for all affected classes:

Deprecation removals & housekeeping

As part of this major version, a number of previously deprecated props, arugments, methods, etc. have been removed. Additionally there have been some changes to things that are only used internally, or only used very rarely. It's highly unlikely that any given app will encounter any of these items, but they are all breaking changes, so they have all been documented below.

For this section more than any other one, please use the CLI upgrade tool (npx @clerk/upgrade). Changes in this section are very unlikely to appear in your codebase, the tool will save time looking for them.

Deprecation removals

Other Breaking changes

What did you think of this content?

Clerk © 2024