Upgrading @clerk/backend to Core 2

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

- import { verifyJwt } from "@clerk/backend"
+ import { verifyJwt } from "@clerk/backend/tokens"

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

- import { decodeJwt } from "@clerk/backend"
+ import { decodeJwt } from "@clerk/backend/tokens"

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

- import { signJwt } from "@clerk/backend"
+ import { signJwt } from "@clerk/backend/tokens"

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

- import { constants } from "@clerk/backend"
+ import { constants } from "@clerk/backend/internal"

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

- import { redirect } from "@clerk/backend"
+ import { redirect } from "@clerk/backend/internal"

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

- import { createAuthenticateRequest } from "@clerk/backend"
+ import { createAuthenticateRequest } from "@clerk/backend/internal"

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

- import { createIsomorphicRequest } from "@clerk/backend"
+ import { createIsomorphicRequest } from "@clerk/backend/internal"

The createIsomorphicRequest import was intended for those building custom Clerk integrations for frameworks and has been moved to @clerk/backend/internal to reflect this. Please use caution when using internal imports as they are outside the bounds of semver.

- import { createIsomorphicRequest } from "@clerk/backend"
+ import { createIsomorphicRequest } from "@clerk/backend/internal"

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

- import { SignJWTError } from "@clerk/backend"
+ import { SignJWTError } from "@clerk/backend/errors"

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

- import { TokenVerificationError } from "@clerk/backend"
+ import { TokenVerificationError } from "@clerk/backend/errors"

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

- import { TokenVerificationErrorAction } from "@clerk/backend"
+ import { TokenVerificationErrorAction } from "@clerk/backend/errors"

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

- import { TokenVerificationErrorReason } from "@clerk/backend"
+ import { TokenVerificationErrorReason } from "@clerk/backend/errors"

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The response payload of Users.getOrganizationInvitationList was changed as part of the v5 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()

The 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(() => {})

The 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(() => {})

The response payload of Users.getOrganizationList was changed as part of the v5 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()

The 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(() => {})

The response payload of Users.getOrganizationMembershipList was changed as part of the v5 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()

The logoUrl property of any Organization object(opens in a new tab) has been changed to imageUrl.

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

The picture property of any ExternalAcccount object(opens in a new tab) has been changed to imageUrl.

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

The logo_url property of any OrganizationJSON object has been changed to imageUrl.

The profile_image_url property of any UserJSON object has been changed to imageUrl.

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

The profile_image_url property of any OrganizationMembershipPublicUserDataJSON object has been changed to imageUrl.

If you are updating a user's password via the User.update method(opens in a new tab), it must be changed to User.updatePassword(opens in a new tab) 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,
+ });

The frontendApi argument passed to createClerkClient must be changed to publishableKey. Note that the values of the two keys are different, so both keys and values need to be changed. You can find your application's publishable key in the Clerk dashboard. Also note that the import value has changed for creating a new Clerk client, which will be addressed by a separate line item if relevant to your codebase.

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

The apiKey argument passed to createClerkClient must be changed to secretKey. Also note that the import value has changed for creating a new Clerk client, which will be addressed by a separate line item if relevant to your codebase.

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

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

The top level Clerk import was renamed to createClerkClient. This is just a name change and can be treated as a text replacement, no changes to the params or return types.

// before
import { Clerk } from '@clerk/backend';
 
// after
import { createClerkClient } from '@clerk/backend';

The pkgVersion parameter was removed from the loadInterstitialFromLocal, loadInterstitialFromBAPI, and buildPublicInterstitialUrl functions. Use clerkJSVersion instead. Example:

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

The clerkClient.__unstable_options property was removed. Previously, you could use it to update the internal options. Instead, create a new clerkClient instance using createClerkClient and pass the options in this way. For example:

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

The createEmail import has been removed. There is no replacement at this time because we need to rethink how createEmail behaves and align it with the newer sendSms method. If this is an issue for your implementation, please contact Clerk support(opens in a new tab).

The MembershipRole type was replaced with OrganizationCustomRoleKey (related to roles and permissions(opens in a new tab)). An example of where this type might be found:

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

The buildRequestUrl import was intended for those building custom Clerk integrations for frameworks and has been removed in favor of other methods internally. If you were relying on this function and this is an issue, please reach out to Clerk support(opens in a new tab).