Upgrading @clerk/clerk-react 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.

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 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(opens in a new tab) 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.

The afterSwitchOrganizationUrl prop on the <OrganizationSwitcher /> component has been renamed to afterSelectOrganizationUrl. This is a quick and simple rename.

- <OrganizationSwitcher afterSwitchOrganizationUrl='...' />
+ <OrganizationSwitcher afterSelectOrganizationUrl='...' />

This 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.

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

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 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.

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

The membershipList param from the useOrganization hook has been removed. Instead, use the memberships param(opens in a new tab). 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 });

Any place where useOrganizations is used should be switched to useOrganizationList(opens in a new tab) or useOrganization(opens in a new tab) 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,
}

The userProfile prop on the UserButton component(opens in a new tab) has been changed to userProfileProps. This is purely a name change, none of the values need to be updated.

- <UserButton userProfile={} />
+ <UserButton userProfileProps={} />

The 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(opens in a new tab). 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)};
};

The 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(opens in a new tab). 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)};
};

The 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(opens in a new tab). 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)};
};

The 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(opens in a new tab). 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;
}

The 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(opens in a new tab). 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;
}

The 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(opens in a new tab). 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 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'

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

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