Upgrading from v4 to v5

Clerk's SDKs include React, Next.js, Remix, Expo, Redwood, and others. This guide helps you with uprading to the next major version of your SDK.

Version 5 ships with an improved design and UX for its built-in components, no "flash of white page" when authenticating, and a new middleware for Next.js which defaults to not protecting any routes. Along with these highly requested features some smaller DX improvements and housekeeping items made its way into the release. If you want to know everything that's new, read the v5 announcement post.

If you're curious about Clerk's approach to versioning and support, head to the long term support document. Version 5 includes potentially breaking changes, as well as the removal of previously deprecated features.

For most users we expect a smooth upgrade path as only a couple of changes will be required: Update dependencies, run the @clerk/upgrade CLI, update Clerk, and handle any breaking changes.

If you're using Next.js, you can read a more streamlined Upgrading Next.js from v4 to v5 guide.

Handle deprecations

Before uprading, Clerk highly recommends updating your packages to the latest v4 version. Some changes required for v5 can be applied incrementally to the latest v4, 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 some breaking changes for v5.

As of this major version Clerk also provides a @clerk/upgrade CLI you can use to ease the upgrade. A questionnaire will ask you a couple of questions and afterwards you'll get a list of changes you'll need to apply to your project. Navigate to your project and run it in the terminal:

terminal
npx @clerk/upgrade

terminal
yarn dlx @clerk/upgrade

terminal
pnpm dlx @clerk/upgrade

Update dependencies

This section explains breaking changes for peer dependencies and tooling. In order to successfully upgrade, you need to resolve these changes. Clerk's SDKs enforce these requirements through setting peerDependencies and engines keys in their package.json.

Update Node.js

All SDKs that rely on Node.js require you 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, too. Learn how to update and install Node.js.

Update React

All SDKs that rely on React require you to use React 18. 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

Update Next.js

If you're using @clerk/nextjs you will need to update your Next.js project to 13.0.4 or later. Check out Next's upgrade guides:

• Upgrading from 12 to 13
• Upgrading from 13 to 14

Update Clerk

Update each Clerk dependency to the latest version using your package manager. Below you can find some snippets for popular SDKs.

terminal
npm install @clerk/nextjs@latest

terminal
yarn add @clerk/nextjs@latest

terminal
pnpm add @clerk/nextjs@latest

terminal
npm install @clerk/clerk-react@latest

terminal
yarn add @clerk/clerk-react@latest

terminal
pnpm add @clerk/clerk-react@latest

terminal
npm install @clerk/remix@latest

terminal
yarn add @clerk/remix@latest

terminal
pnpm add @clerk/remix@latest

terminal
npm install @clerk/clerk-js@latest

terminal
yarn add @clerk/clerk-js@latest

terminal
pnpm add @clerk/clerk-js@latest

terminal
npm install @clerk/clerk-sdk-node@latest

terminal
yarn add @clerk/clerk-sdk-node@latest

terminal
pnpm add @clerk/clerk-sdk-node@latest

Breaking Changes

This section explains breaking changes that were made across SDKs or only in individual ones. In order to successfully upgrade, you need to resolve these changes. All documentation is updated to refer to only the current, supported code.

@clerk/nextjs

As this package uses @clerk/clerk-react under the hood, you potentially have to take its Clerk v5 changes into account, too. @clerk/nextjs re-exports functions and components from @clerk/clerk-react.

A couple of subpath imports have been removed, but functionality remains the same.

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

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

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

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

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

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

  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 recent versions Next.js enforced the convention that public environment variables should be prefixed with NEXT_PUBLIC_. This also applies to Clerk's environment variables. Please apply these changes:

A couple of exported constants have been removed from @clerk/nextjs as you should use your defined environment variables instead.

import { API_URL } from "@clerk/nextjs"

@clerk/clerk-react

The @clerk/clerk-react package is used by all SDKs based on React and as such any change in this package can potentially affect those packages, too. SDKs based on React re-export certain components and functions from @clerk/clerk-react. Please check your code for the changes below, even if you didn't explicitly install it.

Routing

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

With Clerk v5 the default routing strategy has become 'path'. Unless you change the routing prop, you'll need to define the path prop. The affected components are:

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

Here's how you'd 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 don't 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" />

However, there are two exceptions to this behavior. If you're using @clerk/nextjs or @clerk/remix, you can set environment variables for <SignIn /> and <SignUp />.

.env.local
NEXT_PUBLIC_CLERK_SIGN_IN_URL=/sign-in
NEXT_PUBLIC_CLERK_SIGN_UP_URL=/sign-up

.env
CLERK_SIGN_IN_URL=/sign-in
CLERK_SIGN_UP_URL=/sign-up

Only if you're using one of these two frameworks and defined both environment variables, you're able to use the <SignIn /> and <SignUp /> components without any props.

// Only works for Next.js / Remix when environment variables are set
<SignIn />
<SignUp />

Replace navigate with routerPush & routerReplace

The navigate prop on <ClerkProvider> allowed developers to override the default navigation behavior with a custom function. However, navigate was only able to push, not replace routes. The router is now able to do both, and as such, the props for <ClerkProvider> were updated. The routerPush and routerReplace props replace the old navigate prop.

For more information on what push and replace mean in relation to the browser history api, check out the "Working with the History API" docs.

If you’d like to keep the same behavior as you had with the single navigate prop, pass the exact same function to both routerPush and routerReplace. For example:

- <ClerkProvider navigate={x => x} />
+ <ClerkProvider routerPush={x => x} routerReplace={x => x} />

Removal of higher order functions & components

The withUser, withSession, and withClerk higher order functions (HOF) have been removed. The WithUser, WithSession, and WithClerk higher order components (HOC) have been removed. Clerk recommends using React hooks going forward.

If you would still like to use these functions and components, you can reimplement them on your own.

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;
}

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

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;
}

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

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;
}

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

Other @clerk/clerk-react changes

• The MultisessionAppSupport export has moved from @clerk/clerk-react to @clerk/clerk-react/internal

• The following exports have moved from @clerk/clerk-react to @clerk/clerk-react/errors: isClerkAPIResponseError, isEmailLinkError, isKnownError, isMetamaskError, MagicLinkErrorCode, and isMagicLinkError

• The MembershipRole type was replaced with OrganizationCustomRoleKey (related to roles and permissions). This TypeScript type can be found in such use cases:

  import { useAuth } from "@clerk/clerk-react"
   
  const { orgRole } = useAuth()

  To support the existing roles admin, basic_member, and guest_member apply interface merging using the following snippet:

  interface ClerkAuthorization {
    permission: ''
    role: 'admin' | 'basic_member' | 'guest_member'
  }

• Replace signOutCallback prop on the <SignOutButton /> with redirectUrl. This aligns the API surface with other UI components provided by @clerk/clerk-react.

    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>
      )
    }

• Further changes to types:

  • redirectToUserProfile now returns Promise<unknown> instead of void
  • redirectToOrganizationProfile now returns Promise<unknown> instead of void
  • redirectToCreateOrganization now returns Promise<unknown> instead of void

• The default values of afterSignOutUrl, afterSignInUrl, and afterSignUpUrl have been changed to /. The URLs defined in your Dashboard > Account Portal > Redirects won't affect these anymore. Read the Customizing your Account Portal redirects to learn how to override these defaults.

@clerk/remix

As this package uses @clerk/clerk-react under the hood you potentially have to take its changes into account, too. This package re-exports functions and components from @clerk/clerk-react.

The ClerkErrorBoundary helper has been removed as it's no longer needed.

  import { rootAuthLoader } from "@clerk/remix/ssr.server"
- import { ClerkApp, ClerkErrorBoundary } from "@clerk/remix"
+ import { ClerkApp } from "@clerk/remix"
 
  export const loader = (args: DataFunctionArgs) => {
    return rootAuthLoader(args);
  }
 
  export default ClerkApp(App)
- export const ErrorBoundary = ClerkErrorBoundary()

If you used the default Clerk import, you'll need to use a named createClerkClient import.

- import Clerk from "@clerk/remix"
+ import { createClerkClient } from "@clerk/remix"

@clerk/backend

If you're using an SDK based on React like @clerk/nextjs or @clerk/remix most changes are already handled for you.

• The top level Clerk import was moved from a default export to a named createClerkClient export. It's a name change and functionality stayed the same.

  - import Clerk from "@clerk/backend"
  + import { createClerkClient } from "@clerk/backend"

• You need to pass a Request to the first argument of the authenticateRequest() method.

  - const state = await clerkClient.authenticateRequest({
  + const state = await clerkClient.authenticateRequest(req, {
      secretKey: "",
      publishableKey: "",
  -   origin: req.headers.get("origin"),
  -   host: req.headers.get("host"),
  -   // ...etc
    })

• The createEmail() method (and as such the emails API endpoint) has been removed. For the time being no alternative method will be provided for creating and sending emails directly from Clerk's JavaScript SDKs. If you're currently relying on this functionality and wish to update, please reach out to Clerk's support.

• The following exports have been moved from @clerk/backend to @clerk/backend/jwt: verifyJwt, decodeJwt, and signJwt

• The following exports have been moved from @clerk/backend to @clerk/backend/internal: constants, redirect, createAuthenticateRequest, and createIsomorphicRequest

• The following exports have been moved from @clerk/backend to @clerk/backend/errors: SignJWTError, TokenVerificationError, TokenVerificationErrorAction, TokenVerificationErrorCode, and TokenVerificationErrorReason

@clerk/clerk-js

If you're using an SDK based on React like @clerk/nextjs or @clerk/clerk-react most changes are already handled for you.

Pagination response & parameters

For every method that returns a paginated list the ClerkPaginatedResponse has changed from [Item] to { totalCount: number; data: [Item] }.

The affected methods are:

• Organization.getRoles()
• Organization.getDomains()
• Organization.getMembershipRequests()
• Organization.getMemberships()
• Organization.getInvitations()
• Organization.getOrganizationList()
• Organization.getOrganizationInvitationList()
• User.getOrganizationInvitations()
• User.getOrganizationSuggestions()
• User.getOrganizationMemberships()
• User.getOrganizationMembershipList()

Here's a before/after example:

  import Clerk from "@clerk/clerk-js"
 
  const clerk = new Clerk()
  await clerk.load()
 
- const orgs = await clerk.user.getOrganizationMemberships()
+ const { data: orgs } = await clerk.user.getOrganizationMemberships()

The pagination parameters on some methods have changed from { limit: number; offset: number } to { initialPage: number; pageSize: number }.

The affected methods are:

• Organization.getRoles()
• Organization.getDomains()
• Organization.getMembershipRequests()
• Organization.getMemberships()
• Organization.getInvitations()
• User.getOrganizationInvitations()
• User.getOrganizationSuggestions()
• User.getOrganizationMemberships()

Here's a before/after example:

  import Clerk from "@clerk/clerk-js"
 
  const clerk = new Clerk()
  await clerk.load()
 
  const { data: orgs } = await clerk.user.getOrganizationMemberships({
-   limit: 10,
+   pageSize: 10,
-   offset: 10,
+   initialPage: 2,
  })

Other @clerk/clerk-js changes

• The User.update() method no longer accepts password as a parameter. If you'd like to update a users's password, please use User.updatePassword() instead.

  - User.update({ password: "new" })
  + User.updatePassword({ newPassword: "new" })

• The default values of afterSignOutUrl, afterSignInUrl, and afterSignUpUrl have been changed to /. The URLs defined in your Dashboard > Account Portal > Redirects won't affect these anymore. Read the Customizing your Account Portal redirects to learn how to override these defaults.

• The Clerk.redirectToHome() method has been removed. You can use Clerk.redirectToAfterSignUp() or Clerk.redirectToAfterSignIn() instead.

• The navigate option of Clerk.load() was removed. It allowed developers to override the default navigation behavior with a custom function. However, navigate was only able to push, not replace routes. The router is now able to do both, and as such, routerPush and routerReplace replace the old navigate function.

  - Clerk.load({ navigate: x => x })
  + Clerk.load({ routerPush: x => x, routerReplace: x => x })

Some more niche use cases and their changes:

  const clerk = new Clerk()
- clerk.user.profileImageUrl
+ clerk.user.imageUrl

Other packages

@clerk/chrome-extension

As this package uses @clerk/clerk-react under the hood you potentially have to take its changes into account, too. This package re-exports functions and components from @clerk/clerk-react. In most cases you probably only need to check if the change in default routing behavior affects you.

• The tokenCache prop on <ClerkProvider> was renamed to storageCache.

  - <ClerkProvider tokenCache={}>
  + <ClerkProvider storageCache={}>

  The storageCache interface has been expanded to allow more flexibility:

  type StorageCache = {
    createKey: (...keys: string[]) => string;
    get: <T = any>(key: string) => Promise<T>;
    remove: (key: string) => Promise<void>;
    set: (key: string, value: string) => Promise<void>;
  }

@clerk/clerk-expo

As this package uses @clerk/clerk-react under the hood you potentially have to take its changes into account, too. This package re-exports functions and components from @clerk/clerk-react. In most cases you probably only need to check if the change in default routing behavior affects you.

@clerk/localizations

If you're using Clerk's localization feature to provide your own localizations, you will need to update your data as the underlying structure has changed. If you're just using one of Clerk's default localizations (e.g. through import { frFR } from "@clerk/localizations") you need to install the latest version of @clerk/localizations.

The en-US localization object has changed in three ways: New keys, deleted keys, and changed values.

const newKeys = {
  formFieldInputPlaceholder__confirmDeletionUserAccount: "Delete account",
  formButtonPrimary__verify: "Verify",
  signIn: {
    forgotPassword: {
      title: "Reset password",
      subtitle_email: "First, enter the code sent to your email ID",
      subtitle_phone: "First, enter the code sent to your phone",
    },
    alternativeMethods: {
      subtitle: "Facing issues? You can use any of these methods to sign in.",
      actionText: "Don’t have any of these?",
    },
    accountSwitcher: {
      title: 'Choose an account',
      subtitle: 'Select the account with which you wish to continue.',
    },
  },
  userProfile: {
    mfaPhoneCodePage: {
      backButton: "Use existing number",
      successTitle: "SMS code verification enabled",
      successMessage1:
        "When signing in, you will need to enter a verification code sent to this phone number as an additional step.",
      successMessage2:
        "Save these backup codes and store them somewhere safe. If you lose access to your authentication device, you can use backup codes to sign in.",
    },
  },
  userProfile: {
    navbar: {
      title: "Account",
      description: "Manage your account info.",
      account: "Profile",
      security: "Security",
    },
    start: {
      profileSection: {
        primaryButton: "Edit Profile",
      },
    },
  },
  organizationProfile: {
    navbar: {
      title: "Organization",
      description: "Manage your organization.",
      general: "General",
      members: "Members",
    },
    start: {
      headerTitle__general: "General",
      profileSection: {
        title: "Organization Profile",
        primaryButton: "Edit profile",
        uploadAction__title: "Logo",
      },
    },
    profilePage: {
      domainSection: {
        menuAction__verify: "Verify",
        menuAction__remove: "Delete",
        menuAction__manage: "Manage",
      },
    },
    verifyDomainPage: {
      title: "Verify domain",
    },
    invitePage: {
      selectDropdown__role: "Select role",
    }
  },
  unstable__errors: {
    form_param_format_invalid__phone_number: "Phone number must be in a valid international format",
  },
}

import { merge } from "lodash-es"
 
const localization = merge({}, yourOldOject, newKeys)

const deletedKeys = [
  "signIn.forgotPassword.title_email",
  "signIn.forgotPassword.title_phone",
  "signIn.forgotPassword.formSubtitle_email",
  "signIn.forgotPassword.formSubtitle_phone",
  "signIn.emailCode.formSubtitle",
  "signIn.phoneCode.formSubtitle",
  "signIn.phoneCodeMfa.formSubtitle",
  "signIn.totpMfa.formSubtitle",
  "signIn.backupCodeMfa.formTitle",
  "signIn.backupCodeMfa.formSubtitle",
  "userProfile.start.emailAddressesSection.detailsTitle__primary",
  "userProfile.start.emailAddressesSection.detailsSubtitle__primary",
  "userProfile.start.emailAddressesSection.detailsTitle__nonPrimary",
  "userProfile.start.emailAddressesSection.detailsSubtitle__nonPrimary",
  "userProfile.start.emailAddressesSection.detailsTitle__unverified",
  "userProfile.start.emailAddressesSection.detailsSubtitle__unverified",
  "userProfile.start.emailAddressesSection.destructiveActionTitle",
  "userProfile.start.emailAddressesSection.destructiveActionSubtitle",
  "userProfile.start.phoneNumbersSection.detailsTitle__primary",
  "userProfile.start.phoneNumbersSection.detailsSubtitle__primary",
  "userProfile.start.phoneNumbersSection.detailsTitle__nonPrimary",
  "userProfile.start.phoneNumbersSection.detailsSubtitle__nonPrimary",
  "userProfile.start.phoneNumbersSection.detailsTitle__unverified",
  "userProfile.start.phoneNumbersSection.detailsSubtitle__unverified",
  "userProfile.start.phoneNumbersSection.destructiveActionTitle",
  "userProfile.start.phoneNumbersSection.destructiveActionSubtitle",
  "userProfile.start.connectedAccountsSection.title__conectionFailed",
  "userProfile.start.connectedAccountsSection.title__connectionFailed",
  "userProfile.start.connectedAccountsSection.title__reauthorize",
  "userProfile.start.connectedAccountsSection.subtitle__reauthorize",
  "userProfile.start.connectedAccountsSection.actionLabel__conectionFailed",
  "userProfile.start.connectedAccountsSection.destructiveActionSubtitle",
  "userProfile.start.connectedAccountsSection.destructiveActionAccordionSubtitle",
  "userProfile.start.mfaSection.phoneCode.destructiveActionTitle",
  "userProfile.start.mfaSection.phoneCode.destructiveActionSubtitle",
  "userProfile.start.mfaSection.phoneCode.title__default",
  "userProfile.start.mfaSection.phoneCode.title__setDefault",
  "userProfile.start.mfaSection.phoneCode.subtitle__default",
  "userProfile.start.mfaSection.phoneCode.subtitle__setDefault",
  "userProfile.start.mfaSection.totp.title",
  "userProfile.start.mfaSection.totp.subtitle",
  "userProfile.start.mfaSection.totp.destructiveActionSubtitle",
  "userProfile.start.mfaSection.totp.destructiveActionLabel",
  "userProfile.start.activeDevicesSection.primaryButton",
  "userProfile.start.activeDevicesSection.detailsTitle",
  "userProfile.start.activeDevicesSection.detailsSubtitle",
  "userProfile.start.activeDevicesSection.destructiveActionTitle",
  "userProfile.start.activeDevicesSection.destructiveActionSubtitle",
  "userProfile.start.web3WalletsSection.destructiveActionTitle",
  "userProfile.start.web3WalletsSection.destructiveActionSubtitle",
  "userProfile.start.dangerSection.deleteAccountTitle",
  "userProfile.start.dangerSection.deleteAccountDescription",
  "userProfile.start.headerSubtitle__account",
  "userProfile.start.headerSubtitle__security",
  "organizationProfile.start.headerTitle__settings",
  "organizationProfile.start.headerSubtitle__members",
  "organizationProfile.start.headerSubtitle__settings",
  "organizationProfile.profilePage.domainSection.unverifiedDomain_menuAction__verify",
  "organizationProfile.profilePage.domainSection.unverifiedDomain_menuAction__remove",
  "organizationProfile.profilePage.subtitle",
  "organizationProfile.membersPage.start.headerTitle__active",
  "organizationProfile.membersPage.start.headerTitle__invited",
  "createOrganization.subtitle",
  "formFieldLabel__emailAddress_phoneNumber",
  "formFieldLabel__phoneNumber_username",
  "formFieldLabel__emailAddress_phoneNumber_username",
  "formFieldInputPlaceholder__emailAddress_phoneNumber",
  "formFieldInputPlaceholder__phoneNumber_username",
  "formFieldInputPlaceholder__emailAddress_phoneNumber_username",
  "userProfile.phoneNumberPage.infoText__secondary",
  "userProfile.mfaPhoneCodePage.successMessage",
  "userProfile.profilePage.fileDropAreaTitle",
  "userProfile.profilePage.fileDropAreaAction"
]

import { omit } from "lodash-es"
 
const localization = omit(yourOldOject, deletedKeys)

const newValues = {
  formFieldLabel__organizationName: 'Name',
  formFieldLabel__organizationSlug: 'Slug',
  formFieldInputPlaceholder__emailAddresses: 'example@email.com, example2@email.com',
  formFieldInputPlaceholder__organizationSlug: 'my-org',
  signUp: {
    start: {
      subtitle: 'Welcome! Please fill in the details to get started.',
      actionText: 'Already have an account?',
    },
    emailCode: {
      subtitle: 'Enter the verification code sent to your email',
    },
    phoneCode: {
      subtitle: 'Enter the verification code sent to your phone',
    },
    continue: {
      subtitle: 'Please fill in the remaining details to continue.',
      actionText: 'Already have an account?',
    },
  },
  signIn: {
    start: {
      title: 'Sign in to {{applicationName}}',
      subtitle: 'Welcome back! Please sign in to continue',
      actionText: 'Don’t have an account?',
    },
    password: {
      subtitle: 'Enter the password associated with your account',
    },
    forgotPasswordAlternativeMethods: {
      label__alternativeMethods: 'Or, sign in with another method',
    },
    resetPassword: {
      title: 'Set new password',
    },
    phoneCodeMfa: {
      subtitle: 'To continue, please enter the verification code sent to your phone',
    },
    totpMfa: {
      subtitle: 'To continue, please enter the verification code generated by your authenticator app',
    },
    backupCodeMfa: {
      subtitle: 'Your backup code is the one you got when setting up two-step authentication.',
    },
  },
  userProfile: {
    formButtonPrimary__continue: 'Save',
    start: {
      headerTitle__account: 'Profile details',
      profileSection: {
        primaryButton: 'Edit profile',
      },
      emailAddressesSection: {
        detailsAction__unverified: 'Verify',
        destructiveAction: 'Remove email',
      },
      mfaSection: {
        phoneCode: {
          destructiveActionLabel: 'Remove',
        },
        backupCodes: {
          actionLabel__regenerate: 'Regenerate',
        },
      },
      dangerSection: {
        title: 'Account termination',
        deleteAccountButton: 'Delete account',
      },
    },
    profilePage: {
      imageFormSubtitle: 'Upload',
      imageFormDestructiveActionSubtitle: 'Remove',
    },
    phoneNumberPage: {
      title: 'Add a phone number',
      infoText:
        'A text message containing a verification link will be sent to this phone number. Message and data rates may apply.',
    },
    connectedAccountPage: {
      socialButtonsBlockButton: '{{provider|titleize}}',
    },
    mfaPhoneCodePage: {
      subtitle__availablePhoneNumbers:
        'Select an existing phone number to register for SMS code two-step verification or add a new one.',
      subtitle__unavailablePhoneNumbers:
        'There are no available phone numbers to register for SMS code two-step verification, please add a new one.',
    },
    deletePage: {
      actionDescription: 'Type "Delete account" below to continue.',
    },
  },
  organizationSwitcher: {
    action__createOrganization: 'Create organization',
    action__manageOrganization: 'Manage',
  },
  organizationProfile: {
    profilePage: {
      title: 'Update Profile',
      dangerSection: {
        title: 'Danger',
        leaveOrganization: {
          actionDescription: 'Type "{{organizationName}}" below to continue.',
        },
        deleteOrganization: {
          actionDescription: 'Type "{{organizationName}}" below to continue.',
        },
      },
    },
    invitePage: {
      title: 'Invite new members',
      subtitle: 'Enter or paste one or more email addresses, separated by spaces or commas.',
    },
  },
  createOrganization: {
    title: 'Create organization',
  },
  organizationList: {
    title: 'Choose an account',
    titleWithoutPersonal: 'Choose an organization',
  },
}

@clerk/clerk-sdk-node

• Use createClerkClient and pass options to it instead of using these removed setters: setClerkApiVersion, setClerkHttpOptions, setClerkServerApiUrl, and setClerkApiKey.

  - import { clerkClient, setClerkApiKey } from "@clerk/clerk-sdk-node"
  + import { createClerkClient } from "@clerk/clerk-sdk-node"
   
  - setClerkApiKey("")
  + const clerkClient = createClerkClient({ secretKey: "" })
    await clerkClient.users.getUser(userId)

• The request.auth object type has changed from LegacyAuthObject to AuthObject

• If you used the default Clerk import, you'll need to use a named createClerkClient import.

  - import Clerk from "@clerk/clerk-sdk-node"
  + import { createClerkClient } from "@clerk/clerk-sdk-node"

@clerk/fastify

If you used the default Clerk import, you'll need to use a named createClerkClient import.

- import Clerk from "@clerk/fastify"
+ import { createClerkClient } from "@clerk/fastify"

Common

This section explains changes that were made across multiple packages. Depending on which package you use you'll need to change these common changes in multiple places.

API_URL value has changed

The API_URL export has changed from https://api.clerk.dev to https://api.clerk.com. Subsequently the default value for the CLERK_API_URL environment variable has also changed.

Component appearance

As mentioned in the v5 announcement post Clerk's prebuilt components got a new look and UX. These changes may impact your style customization applied through the appearance prop or tokens for a custom theme. Below you'll learn about the biggest changes and what to look out for.

New styling defaults

Note: If you want your components to appear exactly as the Clerk team designed them you can skip this section.

The default values of some appearance variables have changed which may impact your UI (if you are not already overriding them).

• The default colorPrimary value changed from #103FEF to #2F3037. As the new color is a dark grey, the colorPrimary of the dark theme was changed to #FFFFFF.
• The default fontSize value changed from 1rem to 0.8125rem
• The default fontWeight values changed from { normal: 400, medium: 500, bold: 600 } to { normal: 400, medium: 500, bold: 700 }
• Previously, the default value for fontSmoothing was auto. This value is now unset. If you want to pass a custom value to it, you can still do so.

Changes to elements

Note: If you're not using the elements appearance property you can skip this section.

You're able to pass additional classes to Clerk component elements by using the elements property on appearance. Some keys have changed or have been completely removed. Clerk recommends using IntelliSense in your IDE to inspect the type of appearance.elements.

Here are some more details on individual component changes.

Localization

Note: If you're not using the localization prop you can skip this section.

The @clerk/localizations package and the underlying structure has changed. Read the dedicated localization upgrade guide to learn more.

Pagination changes in @clerk/clerk-js

The pagination response & parameters changes inside @clerk/clerk-js can also potentially affect you if you use SDKs like @clerk/clerk-react, @clerk/nextjs, or @clerk/remix. Double check if you're using any of the mentioned methods in your application.

Deprecated

The following deprecated features are no longer supported and documented. Please update your project as these deprecations will be dropped in v6.

authMiddleware

The authMiddleware API from @clerk/nextjs has been marked as deprecated. We highly recommend using clerkMiddleware going forward. clerkMiddleware protects no routes by default and you need to add your individual routes you want to opt into protection. Here's an example of having all routes public except for everything under /dashboard.

middleware.ts
import { authMiddleware } from "@clerk/nextjs"
 
export default authMiddleware({
  publicRoutes: (req) => !req.url.includes("/dashboard"),
})
 
export const config = {
  matcher: ["/((?!.+\\.[\\w]+$|_next).*)", "/", "/(api|trpc)(.*)"],
}

middleware.ts
import {
  clerkMiddleware,
  createRouteMatcher
} from "@clerk/nextjs/server"
 
const isProtectedRoute = createRouteMatcher(["/dashboard(.*)"])
 
export default clerkMiddleware((auth, request) => {
  if (isProtectedRoute(request)) {
    auth().protect()
  }
})
 
export const config = {
  matcher: ["/((?!.+\\.[\\w]+$|_next).*)", "/", "/(api|trpc)(.*)"],
}

You can also read the How to migrate section of the Next.js upgrade guide for more examples.

Previously deprecated features

The following deprecated features have been entirely removed from any SDK and can no longer be used. It's recommended to first handle any deprecations before trying the upgrade. In order to successfully upgrade, you need to resolve these changes and there will no longer be any supporting documentation for these old features.

terminal
npx @clerk/upgrade

terminal
yarn dlx @clerk/upgrade

terminal
pnpm dlx @clerk/upgrade

Renamed: apiKey

The CLERK_API_KEY environment variable was renamed to CLERK_SECRET_KEY. Make sure to update this in all environments (e.g. dev, staging, production).

The apiKey parameter was renamed to secretKey. You are using this with createClerkClient for example.

You can visit your Clerk dashboard to copy/paste the new keys after choosing your framework.

- import { Clerk } from "@clerk/backend"
+ import { createClerkClient } from "@clerk/backend"
 
- const clerkClient = Clerk({ apiKey: "" })
+ const clerkClient = createClerkClient({ secretKey: "" })

- createClerkClient({ apiKey: "" })
+ createClerkClient({ secretKey: "" })

- import { authMiddleware } from "@clerk/nextjs"
+ import { clerkMiddleware } from "@clerk/nextjs/server"
 
- export default authMiddleware({ apiKey: "" })
+ export default clerkMiddleware({ secretKey: "" })

- createClerkClient({ apiKey: "" })
+ createClerkClient({ secretKey: "" })

- getAuth(args, { apiKey: "" })
+ getAuth(args, { secretKey: "" })

- rootAuthLoader(args, { apiKey: "" })
+ rootAuthLoader(args, { secretKey: "" })

- createClerkClient({ apiKey: "" })
+ createClerkClient({ secretKey: "" })

- getAuth(args, { apiKey: "" })
+ getAuth(args, { secretKey: "" })

- createClerkClient({ apiKey: "" })
+ createClerkClient({ secretKey: "" })

- createClerkExpressRequireAuth({ apiKey: "" })
+ createClerkExpressRequireAuth({ secretKey: "" })

- createClerkExpressWithAuth({ apiKey: "" })
+ createClerkExpressWithAuth({ secretKey: "" })

- const clerkClient = createClerkClient({ apiKey: "" })
- setClerkApiKey("")
+ const clerkClient = createClerkClient({ secretKey: "" })

Removed: frontendApi

The CLERK_FRONTEND_API environment variable was removed. Use CLERK_PUBLISHABLE_KEY on your frontend instead. Make sure to update this in all environments (e.g. dev, staging, production).

The frontendApi prop passed to <ClerkProvider> was removed and you should use publishableKey. The function parameter was also renamed (you are using this with createClerkClient for example).

- import { Clerk } from "@clerk/backend"
+ import { createClerkClient } from "@clerk/backend"
 
- const clerkClient = Clerk({ frontendApi: "" })
+ const clerkClient = createClerkClient({ publishableKey: "" })

- const clerkFrontendApi = "pk_[frontend_api]"
+ const clerkPublishableKey = "pk_[publishable_key]"
 
- const clerk = new Clerk(clerkFrontendApi)
+ const clerk = new Clerk(clerkPublishableKey)

- const clerkFrontendApi = "pk_[frontend_api]"
+ const clerkPublishableKey = "pk_[publishable_key]"
 
  const s = document.createElement("script")
- s.setAttribute("data-clerk-frontend-api", clerkFrontendApi)
+ s.setAttribute("data-clerk-publishable-key", clerkPublishableKey)

- <ClerkProvider frontendApi="">
+ <ClerkProvider publishableKey="">

- createClerkClient({ frontendApi: "" })
+ createClerkClient({ publishableKey: "" })

- fastify.register(clerkPlugin, { frontendApi: "" })
+ fastify.register(clerkPlugin, { publishableKey: "" })

- <ClerkProvider frontendApi="">
+ <ClerkProvider publishableKey="">

- import { authMiddleware } from "@clerk/nextjs"
+ import { clerkMiddleware } from "@clerk/nextjs/server"
 
- export default authMiddleware({ frontendApi: "" })
+ export default clerkMiddleware({ publishableKey: "" })

- <ClerkProvider frontendApi="">
+ <ClerkProvider publishableKey="">

- <ClerkProvider frontendApi="">
+ <ClerkProvider publishableKey="">

- rootAuthLoader(args, { frontendApi: "" })
+ rootAuthLoader(args, { publishableKey: "" })

- createClerkClient({ frontendApi: "" })
+ createClerkClient({ publishableKey: "" })

- createClerkExpressRequireAuth({ frontendApi: "" })
+ createClerkExpressRequireAuth({ publishableKey: "" })

- createClerkExpressWithAuth({ frontendApi: "" })
+ createClerkExpressWithAuth({ publishableKey: "" })

Renamed: Magic link

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

Inside your code, change the following values:

• handleMagicLinkVerification => handleEmailLinkVerification
• isMagicLinkError => isEmailLinkError
• MagicLinkError => EmailLinkError
• MagicLinkErrorCode => EmailLinkErrorCode
• useMagicLink => useEmailLink
• createMagicLinkFlow() => createEmailLinkFlow()

Functionality stayed the same and only the name changed.

Removed: setSession

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:

import { useSignIn } from "@clerk/clerk-react"
 
export default function SignIn() {
  const { setActive } = useSignIn()
 
- 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
})

Or as part of the Clerk class of @clerk/clerk-js:

import Clerk from "@clerk/clerk-js"
 
const clerkPublishableKey = ​your_publishable_key​
const clerk = new Clerk(clerkPublishableKey)
await clerk.load()
 
await clerk.setActive({ session: "" })

Removed: orgs claim on JWT

In v4 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. In v5 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
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.

@clerk/nextjs

withClerkMiddleware has been removed. Use clerkMiddleware instead. Here's an example of having all routes public except for everything under /dashboard.

middleware.ts
import { withClerkMiddleware } from "@clerk/nextjs/server"
import { getAuth } from "@clerk/nextjs/server"
import { NextResponse } from "next/server"
import type { NextRequest } from "next/server"
 
const publicPaths = ["/", "/sign-in*", "/sign-up*"]
 
const isPublic = (path: string) => {
  return publicPaths.find((x) =>
    path.match(new RegExp(`^${x}$`.replace("*$", "($|/)")))
  )
}
 
export default withClerkMiddleware((request: NextRequest) => {
  if (isPublic(request.nextUrl.pathname)) {
    return NextResponse.next();
  }
  const { userId } = getAuth(request)
 
  if (!userId) {
    const signInUrl = new URL("/sign-in", request.url)
    return NextResponse.redirect(signInUrl)
  }
  return NextResponse.next()
})
 
export const config = {
  matcher: ["/((?!.+\\.[\\w]+$|_next).*)", "/", "/(api|trpc)(.*)"],
}

middleware.ts
import {
  clerkMiddleware,
  createRouteMatcher
} from "@clerk/nextjs/server"
import { NextResponse } from "next/server"
 
const isProtectedRoute = createRouteMatcher(["/dashboard(.*)"])
 
export default clerkMiddleware((auth, request) => {
  if (isProtectedRoute(request)) {
    auth().protect()
  }
 
  return NextResponse.next()
})
 
export const config = {
  matcher: ["/((?!.+\\.[\\w]+$|_next).*)", "/", "/(api|trpc)(.*)"],
}

@clerk/clerk-react

• The useOrganizations hook was removed. Use useOrganizationList instead. Please note that the latter has different function signatures.

• The userProfile prop on the UserButton component has been changed to userProfileProps. This is purely a name change, none of the values need to be updated.

• The afterSwitchOrganizationUrl prop on the <OrganizationSwitcher /> component has been renamed to afterSelectOrganizationUrl.

  - <OrganizationSwitcher afterSwitchOrganizationUrl="" />
  + <OrganizationSwitcher afterSelectOrganizationUrl="" />

• The invitationList and membershipList parameter for the useOrganization hook was renamed to invitations and memberships. In v4 you'd pass in limit and offset, now you have to use initialPage and pageSize.

  Before:

  const { invitationList, membershipList } = useOrganization({
    invitationList: { limit: 10, offset: 1 },
    membershipList: { limit: 10, offset: 1 },
  })

  After:

  const { invitations, memberships } = useOrganization({
    invitations: { initialPage: 1, pageSize: 10 },
    memberships: { initialPage: 1, pageSize: 10 },
  })

  For more information, read the useOrganization docs.

@clerk/backend

• clockSkewInSeconds was renamed to clockSkewInMs but the default value stayed the same. That change affects all methods related to VerifyJwtOptions.

  Examples

  verifyJwt
    import { verifyJwt } from "@clerk/backend/jwt"
   
  - verifyJwt(jwt, { clockSkewInSeconds: 4000 })
  + verifyJwt(jwt, { clockSkewInMs: 4000 })

  verifyToken
    import { verifyToken } from "@clerk/backend"
   
  - verifyToken(token, { clockSkewInSeconds: 4000 })
  + verifyToken(token, { clockSkewInMs: 4000 })

  authenticateRequest
    import { createClerkClient } from "@clerk/backend"
    const clerk = createClerkClient({})
   
  - clerk.authenticateRequest(request, { clockSkewInSeconds: 4000 })
  + clerk.authenticateRequest(request, { clockSkewInMs: 4000 })

  createAuthenticateRequest
    import { createAuthenticateRequest } from "@clerk/backend/internal"
    const authenticateRequest = createAuthenticateRequest(params)
   
  - authenticateRequest(request, { clockSkewInSeconds: 4000 })
  + authenticateRequest(request, { clockSkewInMs: 4000 })

  signedInAuthObject
    import { signedInAuthObject } from "@clerk/backend/internal"
   
  - signedInAuthObject({ clockSkewInSeconds: 4000 }, sessionClaims)
  + signedInAuthObject({ clockSkewInMs: 4000 }, sessionClaims)

  signedOutAuthObject
    import { signedOutAuthObject} from "@clerk/backend/internal"
   
  - signedOutAuthObject({ clockSkewInSeconds: 4000 }, sessionClaims)
  + signedOutAuthObject({ clockSkewInMs: 4000 }, sessionClaims)

  Also the following types are affected:

  • import type { VerifyJwtOptions } from "@clerk/backend/jwt"
  • import type { VerifyTokenOptions } from "@clerk/backend"
  • import type { AuthenticateRequestOptions } from "@clerk/backend/internal"

• Replace organizations.getPendingOrganizationInvitationList with organizations.getOrganizationInvitationList and pass a status parameter.

  - clerkClient.organizations.getPendingOrganizationInvitationList({
  -   ...params
  - })
  + clerkClient.organizations.getOrganizationInvitationList({
  +   ...params, status: ["pending"]
  + })

Some more niche use cases and their changes.

- const r = buildRequest({ httpsOptions: { headers: {} }})
+ const request = buildRequest()
+ request({ headerParams: {} })

- loadInterstitialFromLocal({ pkgVersion: "" })
+ loadInterstitialFromLocal({ clerkJSVersion: "" })

import { createClerkClient } from "@clerk/backend"
 
const clerkClient = createClerkClient({ secretKey: "" })
 
const { data: user } = await clerkClient.users.getUser("")

  import { createClerkClient } from "@clerk/backend"
 
  const clerkClient = createClerkClient({ secretKey: "old" })
 
- clerkClient.__unstable_options.secretKey = "new"
+ const newClerkClient = createClerkClient({ secretKey: "new" })

@clerk/clerk-js

• The getOrganizationMemberships() method on the Clerk class has been removed. Use getOrganizationMemberships() on a user instance instead.

    const clerk = new Clerk()
  - clerk.getOrganizationMemberships()
  + clerk.user.getOrganizationMemberships()

  Also note that the response has changed from Array<Organization> to { totalCount: number; data: Array<Organization> }.

• Organization.create() has a new function signature.

  const clerk = new Clerk()
   
  - clerk.organization.create("example")
  + clerk.organization.crete({ name: "example" })

• Removed Organization.getPendingInvitations(), you need to use Organization.getInvitations() instead.

    const clerk = new Clerk()
   
  - clerk.organization.getPendingInvitations()
  + clerk.organization.getInvitations({ status: "pending" })

• In User.createExternalAccount() the redirect_url parameter was renamed to redirectUrl.

• In Signup.attemptWeb3WalletVerification() the parameters have changed. Use signature instead of identifier.

    const clerk = new Clerk()
   
  - clerk.client.signUp.attemptWeb3WalletVerification({ identifier: "" })
  + clerk.client.signUp.attemptWeb3WalletVerification({ signature: "" })

• The Clerk.isReady() method has been removed. You can use the Clerk.loaded property instead.

    const clerk = new Clerk()
  - clerk.isReady()
  + clerk.loaded

Other packages

@clerk/clerk-sdk-node

Use @clerk/clerk-sdk-node as an import, regardless of using CJS or ESM.

- import { } from "@clerk/clerk-sdk-node/cjs/instance"
- import { } from "@clerk/clerk-sdk-node/esm/instance"
+ import { } from "@clerk/clerk-sdk-node"

Community resources

Know a good resource for upgrading from v4 to v5? Edit this page and add a link below!

Known issues

Please check the GitHub issues for any reported issues, or file an issue yourself.