Upgrading `@clerk/nextjs` to Core 2

Preparing to upgrade
Updating to Core 2
CLI upgrade helper
Breaking Changes

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 upgrading, 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.

Additionally, some of the minimum version requirements for some base dependencies have been updated such that versions that are no longer supported or are at end-of-life 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.

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

yarn

pnpm

bun

terminal

npm install react@latest react-dom@latest

terminal

yarn add react@latest react-dom@latest

terminal

pnpm add react@latest react-dom@latest

terminal

bun 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 as well.

Updating Next.js

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

Updating to Core 2

Whenever you feel ready, go ahead and install the latest 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 version.

npm

yarn

pnpm

bun

terminal

npm install @clerk/nextjs

terminal

yarn add @clerk/nextjs

terminal

pnpm add @clerk/nextjs

terminal

bun add @clerk/nextjs

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:

npm

yarn

pnpm

bun

terminal

npx @clerk/upgrade --from=core-1

terminal

yarn dlx @clerk/upgrade --from=core-1

terminal

pnpm dlx @clerk/upgrade --from=core-1

terminal

bun dlx @clerk/upgrade --from=core-1

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:

middleware.ts

import { clerkMiddleware, createRouteMatcher } from '@clerk/nextjs/server'

const isDashboardRoute = createRouteMatcher(['/dashboard(.*)'])
const isAdminRoute = createRouteMatcher(['/admin(.*)'])

export default clerkMiddleware(async (auth, req) => {
  // Restrict admin route to users with specific role
  if (isAdminRoute(req)) await auth.protect({ role: 'org:admin' })

  // Restrict dashboard routes to signed in users
  if (isDashboardRoute(req)) await auth.protect()
})

export const config = {
  matcher: [
    // Skip Next.js internals and all static files, unless found in search params
    '/((?!_next|[^?]*\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)',
    // Always run for API routes
    '/(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() helper is used extensively here. See its reference doc 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 except /sign-in or /sign-up by doing the following:

- import { authMiddleware } from '@clerk/nextjs/server'
+ import { clerkMiddleware, createRouteMatcher } from '@clerk/nextjs/server'
  
+ const isPublicRoute = createRouteMatcher(['/sign-in(.*)', '/sign-up(.*)'])
  
- export default authMiddleware()
+ export default clerkMiddleware(async (auth, request) => {
+   if (!isPublicRoute(request)) {
+     await 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.

Protecting all routes except one or more public paths

By default, clerkMiddleware() treats all pages as public unless explicitly protected. If you prefer for it to operate the other way around (all pages are protected unless explicitly made public), you can reverse the middleware logic in this way:

Before:

middleware.ts

import { authMiddleware } from '@clerk/nextjs/server'

export default authMiddleware({
  publicRoutes: ['/', '/contact'],
})

export const config = {
  matcher: [
    // Skip Next.js internals and all static files, unless found in search params
    '/((?!_next|[^?]*\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)',
    // Always run for API routes
    '/(api|trpc)(.*)',
  ],
}

After:

middleware.ts

import { clerkMiddleware, createRouteMatcher } from '@clerk/nextjs/server'

const isPublicRoute = createRouteMatcher(['/', '/contact(.*)'])

export default clerkMiddleware(async (auth, req) => {
  if (isPublicRoute(req)) return // if it's a public route, do nothing
  await auth.protect() // for any other route, require auth
})

export const config = {
  matcher: [
    // Skip Next.js internals and all static files, unless found in search params
    '/((?!_next|[^?]*\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)',
    // Always run for API routes
    '/(api|trpc)(.*)',
  ],
}

Protecting a single route path

An example can be seen below of code that ensures that all routes are public except everything under /dashboard.

Before:

middleware.ts

import { authMiddleware } from '@clerk/nextjs/server'

export default authMiddleware({
  publicRoutes: (req) => !req.url.includes('/dashboard'),
})

export const config = {
  matcher: [
    // Skip Next.js internals and all static files, unless found in search params
    '/((?!_next|[^?]*\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)',
    // Always run for API routes
    '/(api|trpc)(.*)',
  ],
}

After:

middleware.ts

import { clerkMiddleware, createRouteMatcher } from '@clerk/nextjs/server'

const isDashboardRoute = createRouteMatcher(['/dashboard(.*)'])

export default clerkMiddleware(async (auth, request) => {
  if (isDashboardRoute(request)) await auth.protect()
})

export const config = {
  matcher: [
    // Skip Next.js internals and all static files, unless found in search params
    '/((?!_next|[^?]*\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)',
    // Always run for API routes
    '/(api|trpc)(.*)',
  ],
}

Combining with other Middlewares (like i18n)

You can call other Middlewares inside clerkMiddleware(), giving you more direct control over what is called where. An example would be next-intl to add internationalization to your app.

Before:

middleware.ts

import { authMiddleware } from '@clerk/nextjs/server'
import createMiddleware from 'next-intl/middleware'

const intlMiddleware = createMiddleware({
  locales: ['en', 'de'],
  defaultLocale: 'en',
})

export default authMiddleware({
  beforeAuth: (req) => {
    return intlMiddleware(req)
  },
  publicRoutes: ['((?!^/dashboard/).*)'],
})

export const config = {
  matcher: [
    // Skip Next.js internals and all static files, unless found in search params
    '/((?!_next|[^?]*\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)',
    // Always run for API routes
    '/(api|trpc)(.*)',
  ],
}

After:

middleware.ts

import { clerkMiddleware, createRouteMatcher } from '@clerk/nextjs/server'
import createMiddleware from 'next-intl/middleware'

const intlMiddleware = createMiddleware({
  locales: ['en', 'de'],
  defaultLocale: 'en',
})

const isDashboardRoute = createRouteMatcher(['/dashboard(.*)'])

export default clerkMiddleware(async (auth, request) => {
  if (isDashboardRoute(request)) await auth.protect()

  return intlMiddleware(request)
})

export const config = {
  matcher: [
    // Skip Next.js internals and all static files, unless found in search params
    '/((?!_next|[^?]*\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)',
    // Always run for API routes
    '/(api|trpc)(.*)',
  ],
}

Using the redirectToSignIn method

You can now access redirectToSignIn from the auth() object, rather than importing at the top level.

Before:

middleware.ts

import { authMiddleware, redirectToSignIn } from "@clerk/nextjs/server"

export default authMiddleware({
  if (someCondition) redirectToSignIn()
})

export const config = {
  matcher: [
    // Skip Next.js internals and all static files, unless found in search params
    '/((?!_next|[^?]*\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)',
    // Always run for API routes
    '/(api|trpc)(.*)',
  ],
};

After:

middleware.ts

import { clerkMiddleware } from '@clerk/nextjs/server'

export default clerkMiddleware(async (auth, req) => {
  const { redirectToSignIn } = await auth()
  if (someCondition) redirectToSignIn()
})

export const config = {
  matcher: [
    // Skip Next.js internals and all static files, unless found in search params
    '/((?!_next|[^?]*\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)',
    // Always run for API routes
    '/(api|trpc)(.*)',
  ],
}

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.

Note

Use the CLI tool to automatically find occurrences of imports that need to be changed.

@clerk/nextjs/server

Previously these exports have been exported both from @clerk/nextjs and @clerk/nextjs/server. As of v5 they are only exported from the latter. Going forward, the expectation can be that any imports that are intended to run within react on the client-side, will come from @clerk/nextjs and imports that are intended to run on the server, will come from @clerk/nextjs/server.

  import {
    auth,
    currentUser,
    authMiddleware,
    buildClerkProps,
    verifyToken,
    verifyJwt,
    decodeJwt,
    signJwt,
    constants,
    redirect,
    createAuthenticateRequest,
    createIsomorphicRequest,
- } from '@clerk/nextjs'
+ } from '@clerk/nextjs/server'

@clerk/nextjs/errors

Exports related to errors are now under @clerk/nextjs/errors.

  import {
    isClerkAPIResponseError,
    isEmailLinkError,
    isKnownError,
    isMetamaskError,
    EmailLinkErrorCode,
- } from '@clerk/nextjs'
+ } from '@clerk/nextjs/errors'

@clerk/nextjs/app-beta

The @clerk/nextjs import will work with both the App and Pages Router.

- import { } from '@clerk/nextjs/app-beta'
+ import { } from '@clerk/nextjs'

Some behavior may have changed between Clerk's beta and the stable release. Check on your end if behavior stayed the same.

@clerk/nextjs/ssr

The top-level exports support SSR by default now.

- import { } from '@clerk/nextjs/ssr'
+ import { } from '@clerk/nextjs'

@clerk/nextjs/edge-middleware

- import { } from '@clerk/nextjs/edge-middleware'
+ import { } from '@clerk/nextjs'

@clerk/nextjs/edge-middlewarefiles

- import { } from '@clerk/nextjs/edge-middlewarefiles'
+ import { } from '@clerk/nextjs'

@clerk/nextjs/api

Important

The Node SDK is no longer supported. Upgrade to the Express SDK.

The @clerk/nextjs/api subpath was removed completely. It re-exported helpers from @clerk/clerk-sdk-node and its types. If you relied on these, import from @clerk/clerk-sdk-node directly instead.

  import type {
    ClerkMiddleware,
    ClerkMiddlewareOptions,
    LooseAuthProp,
    RequireAuthProp,
    StrictAuthProp,
    WithAuthProp,
- } from '@clerk/nextjs/api'
+ } from '@clerk/clerk-sdk-node'
  
- import { requireAuth, withAuth } from '@clerk/nextjs/api'
+ import { requireAuth, withAuth } from '@clerk/clerk-sdk-node'

In Core 2, defining redirect URLs for after sign-up, sign-in, or sign-out via the Clerk Dashboard has been removed. Previously, the "Paths" section in the Clerk Dashboard included "Component paths" where URLs could be defined, accompanied by a deprecation warning. This functionality is now removed, and specifying redirect paths via the dashboard is no longer supported.

If you need to pass a redirect URL for after sign-up, sign-in, or sign-out, there are several ways to achieve this, including environment variables, middleware, or passing them directly to the relevant components.

As part of this change, the default redirect 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 />

`afterSignXUrl` changes

Note

This section refers to afterSignXUrl where X could be Up or In depending on the context.

All afterSignXUrl props and CLERK_AFTER_SIGN_X_URL environment variables have been deprecated, and should be replaced by one of the following options:

CLERK_SIGN_X_FORCE_REDIRECT_URL / signXForceRedirectUrl – If set, Clerk will always redirect to provided URL, regardless of what page the user was on before. Use this option with caution, as it will interrupt the user's flow by taking them away from the page they were on before.
CLERK_SIGN_X_FALLBACK_REDIRECT_URL / signXFallbackRedirectUrl – If set, this will mirror the previous behavior, only redirecting to the provided URL if there is no redirect_url in the querystring.

In general, use the environment variables over the props.

Warning

If neither value is set, Clerk will redirect to the redirect_url if present, otherwise it will redirect to /.

To retain the current behavior of your app without any changes, you can switch afterSignXUrl with signXFallbackRedirectUrl as such:

- <SignIn afterSignInUrl="/foo" />
+ <SignIn signInFallbackRedirectUrl="/foo" />

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.

Next.js

import { getAuth } from '@clerk/nextjs/server'
const claims: JwtPayload = getAuth(request).sessionClaims

import { getAuth } from '@clerk/ssr.server'
const claims: JwtPayload = (await getAuth(request)).sessionClaims

Fastify

import { getAuth } from '@clerk/fastify'
const claims: JwtPayload = (await getAuth(request)).sessionClaims

@clerk/backend

import { createClerkClient } from '@clerk/backend'

const clerkClient = createClerkClient({ secretKey: '' })
const requestState = await clerkClient.authenticateRequest(request, { publishableKey: '' })
const claims: JwtPayload = requestState.toAuth().sessionClaims

@clerk/clerk-sdk-node

Important

The Node SDK is no longer supported. Upgrade to the Express SDK.

@clerk/clerk-sdk-node

import { clerkClient } from '@clerk/clerk-sdk-node'

router.use((...args) => clerkClient.expressRequireAuth()(...args))
router.get('/me', async (req, reply: Response) => {
  return reply.json({ auth: req.auth })
})

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 can be set to 'hash' | 'path' and describes the routing strategy that should be used. path defines where the component is mounted when routing="path" is used. Learn more about Clerk routing.

In Core 2, the default routing strategy has become 'path' for the Next.js SDK. Of course, you can still use routing='hash'.

<UserProfile routing="hash" />

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:

Organization.logoUrl -> Organization.imageUrl

The logoUrl property of any Organization object has been changed to imageUrl.

User.profileImageUrl -> .imageUrl

The profileImageUrl property of any User object has been changed to imageUrl.

ExternalAccount.avatarUrl -> .imageUrl

The avatarUrl property of any ExternalAccount object has been changed to imageUrl.

OrganizationMembershipPublicUserData.profileImageUrl -> .imageUrl

The profileImageUrl property of any OrganizationMembershipPublicUserData object has been changed to imageUrl.

Deprecation removals & housekeeping

As part of this major version, a number of previously deprecated props, arguments, 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.

Note

For this section more than any other one, 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

User.update({ password: 'x' }) -> User.updatePassword('x')

If you are updating a user's password via the User.update method, it must be changed to User.updatePassword instead. This method will require the current password as well as the desired new password. We made this update to improve the security of password changes. Example below:

- user.update({ password: 'foo' })
  
+ user.updatePassword({
+   currentPassword: 'bar',
+   newPassword: 'foo',
+   signOutOfOtherSessions: true,
+ })

CLERK_API_KEY replaced by CLERK_SECRET_KEY

The CLERK_API_KEY environment variable was renamed to CLERK_SECRET_KEY. To update, go to the API keys page in the Clerk Dashboard. After choosing your framework, copy and paste the new keys. Ensure this update is applied across all environments (e.g., development, staging, production).

CLERK_FRONTEND_API replaced by CLERK_PUBLISHABLE_KEY

The CLERK_FRONTEND_API environment variable was renamed to CLERK_PUBLISHABLE_KEY. To update, go to the API keys page in the Clerk Dashboard. After choosing your framework, copy and paste the new keys. Ensure this update is applied across all environments (e.g., development, staging, production). Note: The values are different, so this isn't just a key replacement. More information.

CLERK_JS_VERSION should be NEXT_PUBLIC_CLERK_JS_VERSION

If you are using CLERK_JS_VERSION as an environment variable, it should be changed to NEXT_PUBLIC_CLERK_JS_VERSION instead.

This change brings our SDK up to date with the latest standards for next.js - that public environment variables should have the NEXT_PUBLIC_ prefix. This env variable is not private, so it should get the public prefix.

apiKey -> secretKey as param to authMiddleware

The apiKey argument passed to authMiddleware must be changed to secretKey.

  import { authMiddleware } from '@clerk/nextjs/server'
  
- authMiddleware({ apiKey: '...' })
+ authMiddleware({ secretKey: '...' })

frontendApi -> publishableKey as param to authMiddleware

The frontendApi argument passed to authMiddleware must be changed to publishableKey

  import { authMiddleware } from '@clerk/nextjs/server'
  
- authMiddleware({ frontendApi: '...' })
+ authMiddleware({ publishableKey: '...' })

apiKey -> secretKey as param to createClerkClient

The apiKey argument passed to createClerkClient must be changed to secretKey.

  import { createClerkClient } from '@clerk/nextjs/server'
  
- createClerkClient({ apiKey: '...' })
+ createClerkClient({ secretKey: '...' })

frontendApi -> publishableKey as param to createClerkClient

The frontendApi argument passed to createClerkClient must be changed to publishableKey. Note that the values of the two keys are different, so both keys and values need to be changed. You can find your application's Publishable Key in the Clerk Dashboard.

  import { createClerkClient } from '@clerk/nextjs/server'
  
- createClerkClient({ frontendApi: '...' })
+ createClerkClient({ publishableKey: '...' })

apiKey -> secretKey as param to getAuth

The apiKey argument passed to getAuth must be changed to secretKey.

- getAuth({ apiKey: '...' })
+ getAuth({ secretKey: '...' })

frontendApi -> publishableKey as prop to ClerkProvider

The frontendApi prop passed to <ClerkProvider> was renamed to publishableKey. To update, go to the API keys page in the Clerk Dashboard. After choosing your framework, copy and paste the new keys. Ensure this update is applied across all environments (e.g., development, staging, production). Note: The values are different, so this isn't just a key replacement. More information.

@clerk/nextjs/app-beta import removed

If you are using the @clerk/nextjs/app-beta import anywhere, it should use @clerk/nextjs instead. The app-beta import has been removed as our App Router support is stable.

Make this change carefully as some behavior may have changed between our beta and stable releases. You can refer to our documentation and/or approuter example for up-to-date usage.

The @clerk/nextjs import will work with both App Router and Pages Router.

@clerk/nextjs/ssr import removed

If you are importing from @clerk/nextjs/ssr, you can use @clerk/nextjs instead. Our top-level import supports SSR functionality by default now, so the subpath on the import is no longer needed. This import can be directly replaced without any other considerations.

@clerk/nextjs/edge-middleware import removed

This deprecated import has been replaced by @clerk/nextjs/server. Usage should now look as such: import { authMiddleware } from @clerk/nextjs/server. There may be changes in functionality between the two exports depending on how old the version used is, so upgrade with caution.

@clerk/nextjs/edge-middlewarefiles import removed

API_URL constant removed

This deprecated constant has been removed as an export from @clerk/nextjs. Instead, set and use the CLERK_API_URL environment variable.

API_VERSION constant removed

This deprecated constant has been removed as an export from @clerk/nextjs. Instead, set and use the CLERK_API_VERSION environment variable.

CLERK_JS_URL constant removed

This deprecated constant has been removed as an export from @clerk/nextjs. Instead, set and use the NEXT_PUBLIC_CLERK_JS_URL environment variable.

CLERK_JS_VERSION constant removed

This deprecated constant has been removed as an export from @clerk/nextjs. Instead, set and use the NEXT_PUBLIC_CLERK_JS_VERSION environment variable.

DOMAIN constant removed

This deprecated constant has been removed as an export from @clerk/nextjs. Instead, set and use the NEXT_PUBLIC_CLERK_DOMAIN environment variable.

IS_SATELLITE constant removed

This deprecated constant has been removed as an export from @clerk/nextjs. Instead, set and use the NEXT_PUBLIC_CLERK_IS_SATELLITE environment variable.

PROXY_URL constant removed

This deprecated constant has been removed as an export from @clerk/nextjs. Instead, set and use the NEXT_PUBLIC_CLERK_PROXY_URL environment variable.

PUBLISHABLE_KEY constant removed

This deprecated constant has been removed as an export from @clerk/nextjs. Instead, set and use the NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY environment variable.

SECRET_KEY constant removed

This deprecated constant has been removed as an export from @clerk/nextjs. Instead, set and use the CLERK_SECRET_KEY environment variable.

SIGN_IN_URL constant removed

This deprecated constant has been removed as an export from @clerk/nextjs. Instead, set and use the NEXT_PUBLIC_CLERK_SIGN_IN_URL environment variable.

SIGN_UP_URL constant removed

This deprecated constant has been removed as an export from @clerk/nextjs. Instead, set and use the NEXT_PUBLIC_CLERK_SIGN_UP_URL environment variable.

@clerk/nextjs/api import removed

Important

The Node SDK is no longer supported. Upgrade to the Express SDK.

The import subpath @clerk/nextjs/api has been removed. This includes the following imports:

// These have been removed
import {
  ClerkMiddleware,
  ClerkMiddlewareOptions,
  LooseAuthProp,
  RequireAuthProp,
  StrictAuthProp,
  WithAuthProp,
} from '@clerk/nextjs/api'

If you still need to use any of these functions, they can be instead imported from @clerk/clerk-sdk-node.

MultiSessionAppSupport import moved under /internal

The MultiSessionAppSupport import path has changed from @clerk/nextjs to @clerk/nextjs/internal. You must update your import path in order for it to work correctly. Note that internal imports are not intended for usage and are outside the scope of semver. Example below of the fix that needs to be made:

- import { MultiSessionAppSupport } from '@clerk/nextjs'
+ import { MultiSessionAppSupport } from '@clerk/nextjs/internal'

NEXT_PUBLIC_CLERK_JS should be NEXT_PUBLIC_CLERK_JS_URL

If you are using NEXT_PUBLIC_CLERK_JS as an environment variable, it should be changed to NEXT_PUBLIC_CLERK_JS_URL instead. This variable was renamed for consistency across public APIs. Make sure to also check your production host configuration when changing environment variable values.

Other Breaking changes

Organization.getRoles arguments changed

There have been a couple changes to the pagination arguments that can be passed into this function - limit has been renamed to pageSize, and offset has been renamed to initialPage. This will help to make it more clear and simple to reason about pagination control. Example of how changes might look below:

  const { data } = await organization.getRoles({
-   limit: 10,
+   pageSize: 10,
-   offset: 10,
+   initialPage: 2,
  })

Organization.getMemberships arguments changed

  const { data } = await organization.getMemberships({
-   limit: 10,
+   pageSize: 10,
-   offset: 10,
+   initialPage: 2,
  })

Organization.getDomains arguments changed

  const { data } = await organization.getDomains({
-   limit: 10,
+   pageSize: 10,
-   offset: 10,
+   initialPage: 2,
  })

Organization.getInvitations arguments changed

  const { data } = await organization.getInvitations({
-   limit: 10,
+   pageSize: 10,
-   offset: 10,
+   initialPage: 2,
  })

Organization.getMembershipRequests arguments changed

  const { data } = await organization.getMembershipRequests({
-   limit: 10,
+   pageSize: 10,
-   offset: 10,
+   initialPage: 2,
  })

User.getOrganizationInvitations arguments changed

  const { data } = await user.getOrganizationInvitations({
-   limit: 10,
+   pageSize: 10,
-   offset: 10,
+   initialPage: 2,
  })

User.getOrganizationSuggestions arguments changed

  const { data } = await user.getOrganizationSuggestions({
-   limit: 10,
+   pageSize: 10,
-   offset: 10,
+   initialPage: 2,
  })

User.getOrganizationMemberships arguments changed

  const { data } = await user.getOrganizationMemberships({
-   limit: 10,
+   pageSize: 10,
-   offset: 10,
+   initialPage: 2,
  })

Users.getOrganizationMembershipList return signature changed

The response payload of Users.getOrganizationMembershipList was changed as part of the core 2 release. Rather than directly returning data, the return signature is now { data, totalCount }. Since Backend API responses are paginated, the totalCount property is helpful in determining the total number of items in the response easily, and this change in the backend SDK aligns the response shape with what the Backend API returns directly.

Here's an example of how the response shape would change with this modification:

- const data = await clerkClient.users.getOrganizationMembershipList()
+ const { data, totalCount } = await clerkClient.users.getOrganizationMembershipList()

Users.getOrganizationInvitationList return signature changed

The response payload of Users.getOrganizationInvitationList was changed as part of the core 2 release. Rather than directly returning data, the return signature is now { data, totalCount }. Since Backend API responses are paginated, the totalCount property is helpful in determining the total number of items in the response easily, and this change in the backend SDK aligns the response shape with what the Backend API returns directly.

Here's an example of how the response shape would change with this modification:

- const data = await clerkClient.users.getOrganizationInvitationList()
+ const { data, totalCount } = await clerkClient.users.getOrganizationInvitationList()

Organizations.getOrganizationInvitationList return type changed

The return type for this function was previously [Items] but has now been updated to { data: [Items], totalCount: number }. Since the Clerk API responses are paginated, the totalCount property is helpful in determining the total number of items in the response easily. A before/after code example can be seen below:

  const data = await clerkClient.organizations.getOrganizationInvitationList({
    organizationId: '...',
  })
  
- data.forEach(() => {})
+ data.data.forEach(() => {})

User.getOrganizationMembershipList return type changed

  const { user } = useUser()
  const membershipList = user.getOrganizationMembershipList()
  
- membershipList.forEach(() => {})
+ membershipList.data.forEach(() => {})

Users.getOrganizationList return signature changed

The response payload of Users.getOrganizationList was changed as part of the core 2 release. Rather than directly returning data, the return signature is now { data, totalCount }. Since Backend API responses are paginated, the totalCount property is helpful in determining the total number of items in the response easily, and this change in the backend SDK aligns the response shape with what the Backend API returns directly.

Here's an example of how the response shape would change with this modification:

- const data = await clerkClient.users.getOrganizationList()
+ const { data, totalCount } = await clerkClient.users.getOrganizationList()

Organization.getOrganizationList return type changed

  const { organization } = useOrganization()
  const orgList = organization.getOrganizationList()
  
- orgList.forEach(() => {})
+ orgList.data.forEach(() => {})

Invitations.getInvitationList return signature changed

The response payload of Invitations.getInvitationList was changed as part of the core 2 release. Rather than directly returning data, the return signature is now { data, totalCount }. Since Backend API responses are paginated, the totalCount property is helpful in determining the total number of items in the response easily, and this change in the backend SDK aligns the response shape with what the Backend API returns directly.

Here's an example of how the response shape would change with this modification:

- const data = await clerkClient.invitations.getInvitationList()
+ const { data, totalCount } = await clerkClient.invitations.getInvitationList()

Sessions.getSessionList return signature changed

The response payload of Sessions.getSessionList was changed as part of the core 2 release. Rather than directly returning data, the return signature is now { data, totalCount }. Since Backend API responses are paginated, the totalCount property is helpful in determining the total number of items in the response easily, and this change in the backend SDK aligns the response shape with what the Backend API returns directly.

Here's an example of how the response shape would change with this modification:

- const data = await clerkClient.sessions.getSessionList()
+ const { data, totalCount } = await clerkClient.sessions.getSessionList()

Users.getUserList return signature changed

The response payload of Users.getUserList was changed as part of the core 2 release. Rather than directly returning data, the return signature is now { data, totalCount }. Since Backend API responses are paginated, the totalCount property is helpful in determining the total number of items in the response easily, and this change in the backend SDK aligns the response shape with what the Backend API returns directly.

Here's an example of how the response shape would change with this modification:

- const data = await clerkClient.users.getUserList()
+ const { data, totalCount } = await clerkClient.users.getUserList()

AllowlistIdentifiers.getAllowlistIdentifierList return signature changed

The response payload of AllowlistIdentifiers.getAllowlistIdentifierList was changed as part of the core 2 release. Rather than directly returning data, the return signature is now { data, totalCount }. Since Backend API responses are paginated, the totalCount property is helpful in determining the total number of items in the response easily, and this change in the backend SDK aligns the response shape with what the Backend API returns directly.

Here's an example of how the response shape would change with this modification:

- const data = await clerkClient.allowlistIdentifiers.getAllowlistIdentifierList()
+ const { data, totalCount } = await clerkClient.allowlistIdentifiers.getAllowlistIdentifierList()

Clients.getClientList return signature changed

The response payload of Clients.getClientList was changed as part of the core 2 release. Rather than directly returning data, the return signature is now { data, totalCount }. Since Backend API responses are paginated, the totalCount property is helpful in determining the total number of items in the response easily, and this change in the backend SDK aligns the response shape with what the Backend API returns directly.

Here's an example of how the response shape would change with this modification:

- const data = await clerkClient.clients.getClientList()
+ const { data, totalCount } = await clerkClient.allowlistIdentifiers.getClientList()

RedirectUrls.getRedirectUrlList return signature changed

The response payload of RedirectUrls.getRedirectUrlList was changed as part of the core 2 release. Rather than directly returning data, the return signature is now { data, totalCount }. Since Backend API responses are paginated, the totalCount property is helpful in determining the total number of items in the response easily, and this change in the backend SDK aligns the response shape with what the Backend API returns directly.

Here's an example of how the response shape would change with this modification:

- const data = await clerkClient.redirectUrls.getRedirectUrlList()
+ const { data, totalCount } = await clerkClient.redirectUrls.getRedirectUrlList()

Users.getUserOauthAccessToken return signature changed

The response payload of Users.getUserOauthAccessToken was changed as part of the core 2 release. Rather than directly returning data, the return signature is now { data, totalCount }. Since Backend API responses are paginated, the totalCount property is helpful in determining the total number of items in the response easily, and this change in the backend SDK aligns the response shape with what the Backend API returns directly.

Here's an example of how the response shape would change with this modification:

- const data = await clerkClient.users.getUserOauthAccessToken()
+ const { data, totalCount } = await clerkClient.users.getUserOauthAccessToken()

setSession -> setActive

setSession should be replaced with setActive. The format of the parameters has changed slightly - setActive takes an object where setSession took params directly. The setActive function also can accept an organization param that is used to set the currently active organization. The return signature did not change. Read the API documentation for more detail. This function should be expected to be returned from one of the following Clerk hooks: useSessionList, useSignUp, or useSignIn. Some migration examples:

- await setSession('sessionID', () => void)
+ await setActive({ session: 'sessionID', beforeEmit: () => void })
  
- await setSession(sessionObj)
+ await setActive({ session: sessionObj })
  
- await setSession(sessionObj, () => void)
+ await setActive({ session: sessionObj, beforeEmit: () => void })

setActive also supports setting an active organization:

await setActive({
  session: 'sessionID',
  organization: 'orgID',
  beforeEmit: () => void,
})

await setActive({
  session: sessionObj,
  organization: orgObj,
  beforeEmit: () => void,
})

Organization.create('x') -> Organization.create({ name: 'x' })

Passing a string as an argument to Organization.create is no longer possible - instead, pass an object with the name property.

- Organization.create('...')
+ Organization.create({ name: '...' })

Organization.getPendingInvitations() -> Organization.getInvitations({ status: 'pending' })

The Organization.getPendingInvitations() method has been removed. You can use Organization.getInvitations instead.

- Organization.getPendingInvitations()
+ Organization.getInvitations({ status: 'pending' })

API_URL value has changed

The value of this export has changed from https://api.clerk.dev to https://api.clerk.com. If you were relying on the text content of this value not changing, you may need to make adjustments.

isMagicLinkError -> isEmailLinkError

Across Clerk's documentation and codebases the term "magic link" was changed to "email link" as it more accurately reflects the functionality.

useMagicLink -> useEmailLink

Across Clerk's documentation and codebases the term "magic link" was changed to "email link" as it more accurately reflects functionality.

MagicLinkErrorCode -> EmailLinkErrorCode

Across Clerk's documentation and codebases the term "magic link" was changed to "email link" as it more accurately reflects the functionality.

isMetamaskError import moved under /errors

The isMetamaskError import path has changed from @clerk/react to @clerk/react/errors. You must update your import path in order for it to work correctly. Example below of the fix that needs to be made:

- import { isMetamaskError } from '@clerk/react'
+ import { isMetamaskError } from '@clerk/react/errors'

WithSession component removed

The WithSession higher order component has been removed. If you would still like to use this function in the way its implemented, it can be created quickly using Clerk's custom hooks. An example of how to do so is below:

export const WithSession = ({ children }) => {
  const session = useSession()
  if (typeof children !== 'function') throw new Error()

  return children(session)
}

WithClerk component removed

The WithClerk higher order component has been removed. If you would still like to use this function in the way its implemented, it can be created quickly using Clerk's custom hooks. An example of how to do so is below:

export const WithClerk = ({ children }) => {
  const clerk = useClerk()
  if (typeof children !== 'function') throw new Error()

  return children(clerk)
}

WithUser component removed

The WithUser higher order component has been removed. If you would still like to use this function in the way its implemented, it can be created quickly using Clerk's custom hooks. An example of how to do so is below:

export const WithUser = ({ children }) => {
  const user = useUser()
  if (typeof children !== 'function') throw new Error()

  return children(user)
}

withClerk function removed

The withClerk higher order function has been removed. If you would still like to use this function in the way its implemented, it can be created quickly using Clerk's custom hooks. An example of how to do so is below:

function withClerk(Component, displayName) {
  displayName = displayName || Component.displayName || Component.name || 'Component'
  Component.displayName = displayName
  const HOC = (props) => {
    const clerk = useIsomorphicClerkContext()

    if (!clerk.loaded) return null

    return <Component {...props} clerk={clerk} />
  }

  HOC.displayName = `withClerk(${displayName})`
  return HOC
}

withSession function removed

The withSession higher order function has been removed. If you would still like to use this function in the way its implemented, it can be created quickly using Clerk's custom hooks. An example of how to do so is below:

function withSession(Component, displayName) {
  displayName = displayName || Component.displayName || Component.name || 'Component'
  Component.displayName = displayName
  const HOC = (props) => {
    const session = useSessionContext()

    if (!session) return null

    return <Component {...props} session={session} />
  }

  HOC.displayName = `withSession(${displayName})`
  return HOC
}

withUser function removed

The withUser higher order function has been removed. If you would still like to use this function in the way its implemented, it can be created quickly using Clerk's custom hooks. An example of how to do so is below:

function withUser(Component, displayName) {
  displayName = displayName || Component.displayName || Component.name || 'Component'
  Component.displayName = displayName
  const HOC = (props) => {
    const clerk = useUserContext()

    if (!user) return null

    return <Component {...props} user={user} />
  }

  HOC.displayName = `withUser(${displayName})`
  return HOC
}

Replace signOutCallback prop on SignOutButton with redirectUrl

The signOutCallback prop on the <SignOutButton /> component has been removed. Instead, you can use the redirectUrl prop. Example below:

  import { SignOutButton } from '@clerk/clerk-react'
  
  export const Signout = () => {
    return (
      <SignOutButton
-       signOutCallback={() => {
-         window.location.href = '/your-path'
-       }}
+       redirectUrl="/your-path"
      >
        <button>Sign Out</button>
      </SignOutButton>
    )
  }

Edit on GitHub

Last updated on Oct 24, 2025

Upgrading @clerk/nextjs to Core 2

Feedback

Upgrading `@clerk/nextjs` to Core 2