Upgrading @clerk/clerk-react to Core 2
Core 2 is included in the React 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 React project to use @clerk/clerk-react v5. You’ll learn how to update your dependencies, resolve breaking changes, and find deprecations. Step-by-step instructions will lead you through the process.
Preparing to upgrade
Before uprading, it's highly recommended that you update your Clerk SDKs to the latest Core 1 version (npm i @clerk/clerk-react@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 minumum 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 install react@latest react-dom@latestyarn add react@latest react-dom@latestpnpm add react@latest react-dom@latestIf you are upgrading from React 17 or lower, make sure to learn about how to upgrade your React version to 18 as well.
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 install @clerk/clerk-reactyarn add @clerk/clerk-reactpnpm add @clerk/clerk-reactCLI upgrade helper
Clerk now provides a @clerk/upgrade CLI tool that you can use to ease the upgrade process. The tool will scan your codebase and produce a list of changes you'll need to apply to your project. It should catch the vast majority of the changes needed for a successful upgrade to any SDK including Core 2. This can save you a lot of time reading through changes that don't apply to your project.
To run the CLI tool, navigate to your project and run it in the terminal:
npx @clerk/upgradeyarn dlx @clerk/upgradepnpm dlx @clerk/upgradeIf 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.
<UserButton afterSignOutUrl='/' />
<UserButton />afterSignXUrl changes
Some changes are being made to the way that "after sign up/in url"s and redirect url props are handled as part of this new version, in order to make behavior more clear and predictable.
Previously, setting afterSignInUrl or afterSignOutUrl would only actually redirect some of the time. If the user clicks on any form of link that takes them to a sign up/in page, Clerk automatically sets redirect_url in the querystring such that after the sign up or in, the user is returned back to the page they were on before. This is a common pattern for sign up/in flows, as it leads to the least interruption of the user's navigation through your app. When a redirect_url is present, any value passed to afterSignInUrl or afterSignUpUrl is ignored. However, if the user navigates directly to a sign up/in page, there’s no redirect url in the querystring and in this case the afterSignInUrl or afterSignOutUrl would take effect. This behavior was not intuitive and didn't give a way to force a redirect after sign up/in, so the behavior is changing to address both of these issues.
All afterSignXUrl props and CLERK_AFTER_SIGN_X_URL environment variables have been removed, and should be replaced by one of the following options:
signXForceRedirectUrl/CLERK_SIGN_X_FORCE_REDIRECT_URL- 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.signXFallbackRedirectUrl/CLERK_SIGN_UP_FALLBACK_REDIRECT_URL- if set, this will mirror the previous behavior, only redirecting to the provided URL if there is noredirect_urlin the querystring.
If neither value is set, Clerk will redirect to the redirect_url if present, otherwise it will redirect to /. If you'd like 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' />navigate prop to ClerkProvider replaced by routerPush and 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. We have now added the capability for the router to push or replace, and as such, upgraded the provider prop so that it can handle either depending on the circumstance.
Two new props have been added to ClerkProvider that replace the single navigate prop, and can be used to override the default navigation behavior for either a push or replace navigation. For more information on what push and replace mean in relation to the browser history api, check out these wonderful MDN 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 and the behavior will be identical. For example:
<ClerkProvider navigate={ x => x } />
<ClerkProvider routerPush={ x => x } routerReplace={ x => x } />However, you now have the option to differentiate behavior based on whether the navigation will be a push or replace.
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)).sessionClaimsFastify
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.
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:
<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" />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.imageUrlThe logoUrl property of any Organization object has been changed to imageUrl.
User.profileImageUrl -> .imageUrl
User.profileImageUrl -> .imageUrlThe profileImageUrl property of any User object has been changed to imageUrl.
ExternalAccount.avatarUrl -> .imageUrl
ExternalAccount.avatarUrl -> .imageUrlThe avatarUrl property of any ExternalAcccount object has been changed to imageUrl.
OrganizationMembershipPublicUserData.profileImageUrl -> .imageUrl
OrganizationMembershipPublicUserData.profileImageUrl -> .imageUrlThe 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, arugments, methods, etc. have been removed. Additionally there have been some changes to things that are only used internally, or only used very rarely. It's highly unlikely that any given app will encounter any of these items, but they are all breaking changes, so they have all been documented below.
Deprecation removals
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:
user.update({ password: 'foo' });
user.updatePassword({
currentPassword: 'bar',
newPassword: 'foo',
signOutOfOtherSessions: true,
});frontendApi -> publishableKey as prop to ClerkProvider
frontendApi -> publishableKey as prop to ClerkProviderThe frontendApi prop passed to <ClerkProvider> was renamed to publishableKey. Note: The values are different, so this is not just a key replacement. You can visit your Clerk dashboard to copy/paste the new keys after choosing your framework. Make sure to update this in all environments (e.g. dev, staging, production). More information.
afterSwitchOrganizationUrl -> afterSelectOrganizationUrl in OrganizationSwitcher
afterSwitchOrganizationUrl -> afterSelectOrganizationUrl in OrganizationSwitcherThe afterSwitchOrganizationUrl prop on the <OrganizationSwitcher /> component has been renamed to afterSelectOrganizationUrl. This is a quick and simple rename.
<OrganizationSwitcher afterSwitchOrganizationUrl='...' />
<OrganizationSwitcher afterSelectOrganizationUrl='...' />ClerkProviderOptionsWrapper type removed
ClerkProviderOptionsWrapper type removedThis type was extending ClerkProviderProps with but was not necessary. This type is typically used internally and is not required to be imported and used directly. If needed, import and use ClerkProviderProps instead.
Other Breaking changes
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:
const { data } = await organization.getRoles({
limit: 10,
pageSize: 10,
offset: 10,
initialPage: 2,
})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:
const { data } = await organization.getMemberships({
limit: 10,
pageSize: 10,
offset: 10,
initialPage: 2,
})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:
const { data } = await organization.getDomains({
limit: 10,
pageSize: 10,
offset: 10,
initialPage: 2,
})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:
const { data } = await organization.getInvitations({
limit: 10,
pageSize: 10,
offset: 10,
initialPage: 2,
})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:
const { data } = await organization.getMembershipRequests({
limit: 10,
pageSize: 10,
offset: 10,
initialPage: 2,
})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:
const { data } = await user.getOrganizationInvitations({
limit: 10,
pageSize: 10,
offset: 10,
initialPage: 2,
})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:
const { data } = await user.getOrganizationSuggestions({
limit: 10,
pageSize: 10,
offset: 10,
initialPage: 2,
})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:
const { data } = await user.getOrganizationMemberships({
limit: 10,
pageSize: 10,
offset: 10,
initialPage: 2,
})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:
const data = await clerkClient.users.getOrganizationMembershipList()
const { data, totalCount } = await clerkClient.users.getOrganizationMembershipList()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:
const data = await clerkClient.users.getOrganizationInvitationList()
const { data, totalCount } = await clerkClient.users.getOrganizationInvitationList()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 Clerk's 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
User.getOrganizationMembershipList return type changedThe return type for this function was previously [Items] but has now been updated to { data: [Items], totalCount: number }. Since Clerk's 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 { user } = useUser()
const membershipList = user.getOrganizationMembershipList()
membershipList.forEach(() => {})
membershipList.data.forEach(() => {})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:
const data = await clerkClient.users.getOrganizationList()
const { data, totalCount } = await clerkClient.users.getOrganizationList()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 Clerk's 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 { organization } = useOrganization()
const orgList = organization.getOrganizationList()
orgList.forEach(() => {})
orgList.data.forEach(() => {})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:
const data = await clerkClient.invitations.getInvitationList()
const { data, totalCount } = await clerkClient.invitations.getInvitationList()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:
const data = await clerkClient.sessions.getSessionList()
const { data, totalCount } = await clerkClient.sessions.getSessionList()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:
const data = await clerkClient.users.getUserList()
const { data, totalCount } = await clerkClient.users.getUserList()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:
const data = await clerkClient.allowlistIdentifiers.getAllowlistIdentifierList()
const { data, totalCount } = await clerkClient.allowlistIdentifiers.getAllowlistIdentifierList()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:
const data = await clerkClient.clients.getClientList()
const { data, totalCount } = await clerkClient.allowlistIdentifiers.getClientList()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:
const data = await clerkClient.redirectUrls.getRedirectUrlList()
const { data, totalCount } = await clerkClient.redirectUrls.getRedirectUrlList()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:
const data = await clerkClient.users.getUserOauthAccessToken()
const { data, totalCount } = await clerkClient.users.getUserOauthAccessToken()MagicLinkErrorCode -> EmailLinkErrorCode
MagicLinkErrorCode -> EmailLinkErrorCodeAcross Clerk's documentation and codebases the term "magic link" was changed to "email link" as it more accurately reflects the functionality.
useMagicLink -> useEmailLink
useMagicLink -> useEmailLinkAcross Clerk's documentation and codebases the term "magic link" was changed to "email link" as it more accurately reflects functionality.
isMagicLinkError -> isEmailLinkError
isMagicLinkError -> isEmailLinkErrorAcross Clerk's documentation and codebases the term "magic link" was changed to "email link" as it more accurately reflects the functionality.
MagicLinkError -> EmailLinkError
MagicLinkError -> EmailLinkErrorAcross Clerk's documentation and codebases the term "magic link" was changed to "email link" as it more accurately reflects the functionality.
handleMagicLinkVerification -> handleEmailLinkVerification
handleMagicLinkVerification -> handleEmailLinkVerificationAcross Clerk's documentation and codebases the term "magic link" was changed to "email link" as it more accurately reflects functionality.
invitationList -> invitations as param to useOrganizations
invitationList -> invitations as param to useOrganizationsThe invitationList param to the useOrganizations hook has been replaced by invitations. This param also has a slightly different way of working, examples included below. Note also that useOrganizations is deprecated and should be updated to useOrganization instead.
// before
const { invitationList } = useOrganization({
invitationList: { limit: 10, offset: 1 },
});
// after
const { invitations } = useOrganization({
invitations: {
initialPage: 1,
pageSize: 10,
},
});
// you can also simply return all invitations
const { invitations } = useOrganization({ invitations: true });membershipList -> members as param to useOrganization
membershipList -> members as param to useOrganizationThe membershipList param from the useOrganization hook has been removed. Instead, use the memberships param. Examples of each can be seen here:
// before
const { membershipList } = useOrganization({
membershipList: { limit: 10, offset: 1 },
});
// after
const { memberships } = useOrganization({
memberships: {
initialPage: 1,
pageSize: 10,
},
});
// you can also simply return all memberships
const { memberships } = useOrganization({ memberships: true });useOrganizations -> useOrganizationList
useOrganizations -> useOrganizationListAny place where useOrganizations is used should be switched to useOrganizationList or useOrganization instead. The return signature has also changed, so take note of this when making the upgrade.
// before: useOrganizations return values
{
isLoaded: boolean,
createOrganization: clerk.createOrganization,
getOrganizationMemberships: clerk.getOrganizationMemberships,
getOrganization: clerk.getOrganization,
}
// after: useOrganizationList return values
{
isLoaded: boolean,
createOrganization: clerk.createOrganization,
userMemberships: PaginatedResourcesWithDefault<...> | PaginatedResources<...>,
userInvitations: PaginatedResourcesWithDefault<...> | PaginatedResources<...>,
userSuggestions: PaginatedResourcesWithDefault<...> | PaginatedResources<...>,
setActive: clerk.setActive,
}userProfile -> userProfileProps for UserButton
userProfile -> userProfileProps for UserButtonThe 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.
<UserButton userProfile={} />
<UserButton userProfileProps={} />WithSession component removed
WithSession component removedThe 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
WithClerk component removedThe 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
WithUser component removedThe 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
withClerk function removedThe 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
withSession function removedThe 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
withUser function removedThe 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;
}MultisessionAppSupport import moved to /internal
MultisessionAppSupport import moved to /internalMultiSessionAppSupport is a component that handles the intermediate “undefined” state for multisession apps by unmounting and remounting the components during the session switch (setActive call) in order to solve theoretical edge-cases that can arise while switching sessions. It is undocumented and intended only for internal use, so it has been moved to an /internal import path. Please note that internal imports are not intended for public use, and are outside the scope of semver.
import { MultiSessionAppSupport } from '@clerk/clerk-react'
import { MultiSessionAppSupport } from '@clerk/clerk-react/internal'Replace signOutCallback prop on SignOutButton with redirectUrl
signOutCallback prop on SignOutButton with redirectUrlThe 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>
)
}setSession -> setActive
setSession -> setActivesetSession 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' })
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' })
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' });