Upgrading @clerk/clerk-js to Core 2

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 avatarUrl property of any ExternalAcccount object(opens in a new tab) has been changed to imageUrl.

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

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

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 experimental property Clerk.experimental_canUseCaptcha has been removed. There is no replacement for this functionality currently. If this is problematic for your application, please reach out to our support team(opens in a new tab)!

The experimental property Clerk.experimental_captchaURL has been removed. There is no replacement for this functionality currently. If this is problematic for your application, please reach out to our support team(opens in a new tab)!

The experimental property Clerk.experimental_captchaSiteKey has been removed. There is no replacement for this functionality currently. If this is problematic for your application, please reach out to our support team(opens in a new tab)!

The Clerk.__unstable__invitationUpdate experimental property has been removed, and has no current replacement. If this is an issue in your codebase, please reach out to Clerk support(opens in a new tab)!

The Clerk.__unstable__membershipUpdate experimental property has been removed, and has no current replacement. If this is an issue in your codebase, please reach out to Clerk support(opens in a new tab)!

The param redirect_url of User.createExternalAccount(opens in a new tab) has been updated to redirectUrl. This is a simple text replacement without any signature changes.

The generatedSignature param to Signup.attemptWeb3WalletVerification()(opens in a new tab) 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.

// before
s.attemptWeb3WalletVerification({
  generatedSignature: async () => 'signatureString',
});
 
// after
s.attemptWeb3WalletVerification({ signature: 'signatureString' });
 
// or, if you still need to fetch the signature async
const signatureString = await (async () => 'signatureString');
s.attemptWeb3WalletVerification({ signature: signatureString });

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

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

setActive also supports setting an active organization:

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

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: '...' });

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

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

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

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

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

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

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

The profileImageUrl property of any User object(opens in a new tab) or OrganizationMembershipPublicData object(opens in a new tab) has been changed to imageUrl.

The getOrganizationMemberships method on the Clerk class(opens in a new tab) has been removed. Instead, use getOrganizationMemberships on a user instance.

- Clerk.getOrganizationMemberships();
+ user.getOrganizationMemberships();

If you are using Clerk.addListener(opens in a new tab) 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, please reach out to Clerk support(opens in a new tab) and we can find a way to resolve the issue!

The 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(opens in a new tab)
• If using the Next.js SDK, set with NEXT_PUBLIC_CLERK_AFTER_SIGN_IN_URL or NEXT_PUBLIC_CLERK_AFTER_SIGN_UP_URL
• If using remix SDK, set with CLERK_AFTER_SIGN_IN_URL or CLERK_AFTER_SIGN_UP_URL

We have removed the Clerk.isReady() function - instead, please use the Clerk.loaded property to check whether Clerk has completed loading.

The signOutCallback prop on the <SignOutButton /> component(opens in a new tab) 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>
    )
  }