Upgrading @clerk/clerk-js
to Core 2
Core 2 is included in the Javascript SDK starting with version 5. This new version ships with an improved design and UX for its built-in components, no "flash of white page" when authenticating, 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 JS project to use @clerk/clerk-js
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/clerk-js@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 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.
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:
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 »
After sign up/in/out default value change
Defining redirect URLs for after sign up, in, and/or out via the Clerk Dashboard has been removed in Core 2. In your Clerk Dashboard, under "paths", there is a section called "Component paths", where URLs could be defined that had a deprecation warning. In Core 2, this functionality has been removed, and specifying redirect paths via the dashboard will no longer work. If you need to pass a redirect URL for after sign in/up/out, there are a few different ways this can be done, from environment variables to middleware to supplying them directly to the relevant components.
As part of this change, the default URL for each of these props has been set to /
, so if you are passing /
explicitly to any one of the above props, that line is no longer necessary and can be removed.
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 noredirect_url
in the querystring.
In general, use the environment variables over the props.
To retain the current behavior of your app without any changes, you can switch afterSignXUrl
with signXFallbackRedirectUrl
as such:
Why this is changing
To make redirect behavior more clear and predictable, Clerk is changing the way "after sign up/in url"s and redirect url props are handled in Core 2.
The afterSignXUrl
props and CLERK_AFTER_SIGN_X_URL
environment variables behave differently based on how a user reaches a sign up/in page:
- Via a link – When users visit a sign up/in page via a link, Clerk sets the previous page URL to a
redirect_url
querystring. When done signing up/in, these users are redirected to the previous page, and theCLERK_AFTER_SIGN_X_URL
variables are ignored. This is a common sign up/in flow pattern that interrupts the user's navigation the least. - Direct navigation – When users navigate directly to a sign up/in page, no value is set to
redirect_url
and the appropriateCLERK_AFTER_SIGN_X_URL
is used.
Overall, this behavior is unintuitive and doesn't give a way to force a redirect after sign up/in, so the behavior is changing.
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
Fastify
@clerk/backend
@clerk/clerk-sdk-node
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' | 'virtual'
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'
. 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:
If you don't define the path
prop an error will be thrown. Of course, you can still use routing="hash"
or routing="virtual"
.
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
Organization.logoUrl
-> Organization.imageUrl
The logoUrl
property of any Organization
object has been changed to imageUrl
.
User.profileImageUrl
-> .imageUrl
User.profileImageUrl
-> .imageUrl
The profileImageUrl
property of any User
object has been changed to imageUrl
.
ExternalAccount.avatarUrl
-> .imageUrl
ExternalAccount.avatarUrl
-> .imageUrl
The avatarUrl
property of any ExternalAccount
object has been changed to imageUrl
.
OrganizationMembershipPublicUserData.profileImageUrl
-> .imageUrl
OrganizationMembershipPublicUserData.profileImageUrl
-> .imageUrl
The profileImageUrl
property of any OrganizationMembershipPublicUserData
object has been changed to imageUrl
.
Changes to pagination arguments for some functions
There were some changes made to pagination-related arguments passed into functions, in order to make it more clear how to control paginated results. See each function impacted by these changes below:
Organization.getRoles
arguments changed
Organization.getRoles
arguments changedThere 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:
Organization.getMemberships
arguments changed
Organization.getMemberships
arguments changedThere 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:
Organization.getDomains
arguments changed
Organization.getDomains
arguments changedThere 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:
Organization.getInvitations
arguments changed
Organization.getInvitations
arguments changedThere 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:
Organization.getMembershipRequests
arguments changed
Organization.getMembershipRequests
arguments changedThere 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:
User.getOrganizationInvitations
arguments changed
User.getOrganizationInvitations
arguments changedThere 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:
User.getOrganizationSuggestions
arguments changed
User.getOrganizationSuggestions
arguments changedThere 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:
User.getOrganizationMemberships
arguments changed
User.getOrganizationMemberships
arguments changedThere 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:
Changes to some function return signatures
There have been changes to return signatures for some functions. Since the Clerk API responses are paginated, the totalCount
property is helpful in determining the total number of items in the response easily. This change also aligns the response shape with what is returned from the Clerk Backend API. Each impacted function is listed below, along with code examples:
Users.getOrganizationMembershipList
return signature changed
Users.getOrganizationMembershipList
return signature changedThe 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:
Users.getOrganizationInvitationList
return signature changed
Users.getOrganizationInvitationList
return signature changedThe 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:
Organizations.getOrganizationInvitationList
return type changed
Organizations.getOrganizationInvitationList
return type changedThe 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:
User.getOrganizationMembershipList
return type changed
User.getOrganizationMembershipList
return type changedThe 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:
Users.getOrganizationList
return signature changed
Users.getOrganizationList
return signature changedThe 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:
Organization.getOrganizationList
return type changed
Organization.getOrganizationList
return type changedThe 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:
Invitations.getInvitationList
return signature changed
Invitations.getInvitationList
return signature changedThe 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:
Sessions.getSessionList
return signature changed
Sessions.getSessionList
return signature changedThe 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:
Users.getUserList
return signature changed
Users.getUserList
return signature changedThe 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:
AllowlistIdentifiers.getAllowlistIdentifierList
return signature changed
AllowlistIdentifiers.getAllowlistIdentifierList
return signature changedThe 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:
Clients.getClientList
return signature changed
Clients.getClientList
return signature changedThe 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:
RedirectUrls.getRedirectUrlList
return signature changed
RedirectUrls.getRedirectUrlList
return signature changedThe 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:
Users.getUserOauthAccessToken
return signature changed
Users.getUserOauthAccessToken
return signature changedThe 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:
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.
User.update({ password: 'x' })
-> User.updatePassword('x')
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:
Clerk.experimental_canUseCaptcha
property removed
Clerk.experimental_canUseCaptcha
property removedThe experimental property Clerk.experimental_canUseCaptcha
has been removed. There is no replacement for this functionality currently. If this is problematic for your application, contact support!
Clerk.experimental_captchaURL
property removed
Clerk.experimental_captchaURL
property removedThe experimental property Clerk.experimental_captchaURL
has been removed. There is no replacement for this functionality currently. If this is problematic for your application, contact support!
Clerk.experimental_captchaSiteKey
property removed
Clerk.experimental_captchaSiteKey
property removedThe experimental property Clerk.experimental_captchaSiteKey
has been removed. There is no replacement for this functionality currently. If this is problematic for your application, contact support!
Clerk.__unstable__invitationUpdate
removed
Clerk.__unstable__invitationUpdate
removedThe Clerk.__unstable__invitationUpdate
experimental property has been removed, and has no current replacement. If this is an issue in your codebase, contact support!
Clerk.__unstable__membershipUpdate
removed
Clerk.__unstable__membershipUpdate
removedThe Clerk.__unstable__membershipUpdate
experimental property has been removed, and has no current replacement. If this is an issue in your codebase, contact support!
redirect_url
-> redirectUrl
as param of User.createExternalAccount
redirect_url
-> redirectUrl
as param of User.createExternalAccount
The param redirect_url
of User.createExternalAccount
has been updated to redirectUrl
. This is a simple text replacement without any signature changes.
generatedSignature
-> signature
as param of Signup.attemptWeb3WalletVerification
generatedSignature
-> signature
as param of Signup.attemptWeb3WalletVerification
The generatedSignature
param to Signup.attemptWeb3WalletVerification()
has been removed. Instead, use the signature
param. Note that this param takes a string, where the generatedSignature
param took a function, so both key and value will need to change.
setSession
-> setActive
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:
setActive
also supports setting an active organization:
Organization.create('x')
-> Organization.create({ name: 'x' })
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.getPendingInvitations()
-> Organization.getInvitations({ status: 'pending' })
Organization.getPendingInvitations()
-> Organization.getInvitations({ status: 'pending' })
The Organization.getPendingInvitations()
method has been removed. You can use Organization.getInvitations
instead.
MagicLinkError
-> EmailLinkError
MagicLinkError
-> EmailLinkError
Across Clerk's documentation and codebases the term "magic link" was changed to "email link" as it more accurately reflects the functionality.
isMagicLinkError
-> isEmailLinkError
isMagicLinkError
-> isEmailLinkError
Across Clerk's documentation and codebases the term "magic link" was changed to "email link" as it more accurately reflects the functionality.
MagicLinkErrorCode
-> EmailLinkErrorCode
MagicLinkErrorCode
-> EmailLinkErrorCode
Across Clerk's documentation and codebases the term "magic link" was changed to "email link" as it more accurately reflects the functionality.
useMagicLink
-> useEmailLink
useMagicLink
-> useEmailLink
Across Clerk's documentation and codebases the term "magic link" was changed to "email link" as it more accurately reflects functionality.
handleMagicLinkVerification
-> handleEmailLinkVerification
handleMagicLinkVerification
-> handleEmailLinkVerification
Across Clerk's documentation and codebases the term "magic link" was changed to "email link" as it more accurately reflects functionality.
[User|OrganizationMembershipPublicData].profileImageUrl
-> [User|OrganizationMembershipPublicData].imageUrl
[User|OrganizationMembershipPublicData].profileImageUrl
-> [User|OrganizationMembershipPublicData].imageUrl
The profileImageUrl
property of any User
object or OrganizationMembershipPublicData
object has been changed to imageUrl
.
Clerk.getOrganizationMemberships()
-> user.getOrganizationMemberships()
Clerk.getOrganizationMemberships()
-> user.getOrganizationMemberships()
The getOrganizationMemberships
method on the Clerk
class has been removed. Instead, use getOrganizationMemberships
on a user instance.
lastOrganizationInvitation
and lastOrganizationMember
dropped from event emitter
lastOrganizationInvitation
and lastOrganizationMember
dropped from event emitterIf you are using Clerk.addListener
or OrganizationContext
and utilizing either the lastOrganizationInvitation
and/or lastOrganizationMember
emitted events, these properties have been removed, as they were only relevant for internal use. We are not providing a way to backfill this functionality at the moment. If you are using it and this is an issue for you, contact support and we can find a way to resolve the issue!
Clerk.redirectToHome()
removed
Clerk.redirectToHome()
removedThe Clerk.redirectToHome
method has been removed. If you are looking for a generic replacement for this method, you can instead use window.Clerk.redirectToAfterSignUp()
or window.Clerk.redirectAfterSignIn()
.
To set the afterSignUpUrl
or afterSignInUrl
, you can:
- If not using a react-based SDK, pass the values into
Clerk.load
as such:Clerk.load({ afterSignUpUrl: 'x', afterSignInUrl: 'y' })
- If using a React-based SDK, pass the desired values into
<ClerkProvider>
. - If using the Next.js SDK, set with
NEXT_PUBLIC_CLERK_SIGN_IN_FALLBACK_URL
orNEXT_PUBLIC_CLERK_SIGN_UP_FALLBACK_URL
- If using remix SDK, set with
CLERK_SIGN_IN_FALLBACK_URL
orCLERK_SIGN_UP_FALLBACK_URL
Clerk.isReady()
removed
Clerk.isReady()
removedWe have removed the Clerk.isReady()
function - instead, use the Clerk.loaded
property to check whether Clerk has completed loading.
Replace signOutCallback
prop on SignOutButton
with redirectUrl
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:
Clerk
import changed
Clerk
import changedThe top level Clerk
import was changed to a named export, like { Clerk }
. This is just a name change and can be treated as a text replacement, no changes to the params or return types.
Feedback
Last updated on