Client-side changes (all frameworks)

Upgrade dependencies

terminal
npm install @clerk/nextjs@latest

terminal
npm install @clerk/clerk-react@latest

useAuth() introduction

useAuth() is a new, SSR-compatible hook that is recommended for all authentication tasks.

const {
  userId,
  sessionId,
  getToken,
  isLoaded,
  isSignedIn,
  signOut
} = useAuth();

The useAuth() hook unifies the way you access common auth operations. It replaces:

• useSession() to access getToken() or the sessionId
• useUser() to access getToken() for integrations
• useClerk() to access signOut()
• <SignedIn> and <SignedOut> in a way that requires extra components

Hook and component API changes

Version 3 changes several APIs for improved consistency and usability.

useUser() and useSession()

Previously, useUser and useSession could only be called from inside the <SignedIn> component. This restriction has been relaxed, but now developers must manually handle the possibility the user and session objects may not be loaded when the hook is called.

In a future version, we plan to support React <Suspense /> to make this even easier.

<RedirectToSignIn /> and <RedirectToSignUp/>

The behavior enabled by the returnBack prop has now been promoted to default behavior. returnBack is deprecated in favor of using an empty component.

<SignIn /> and <SignUp />

Props which take URLs (absolute or relative) have been standardized to use the Url (camelCase) suffix.

<UserButton />

Props which take URLs (absolute or relative) have been standardized to use the Url (camelCase) suffix.

useSignUp() & useSignIn()

useSignUp() and useSignIn() are no longer required to be contained in <SignedOut> or <ClerkLoaded>. Instead, they have been updated to include a loading state.

Resource changes

In order to make our APIs easier to use in codebases not using Typescript and make them more consistent across frameworks, we removed support for snake_cased method parameters. We also updated all method signatures to always accept a param object instead of plain positional params.

We expect that most users will only need to apply these changes to the user.update(), user.createEmailAddress() and user.createPhoneNumber() methods as shown below.

Users who have built custom auth flows using the SignIn and SignUp resources can consult the SignUp and SignIn section below.

User

User.getToken("token-name") has been deprecated and is now accessible through getToken from the useAuth() hook or Session.getToken().

The new getToken() method accepts an optional { template: string; } object, used to specify the JWT template you want to use.

Please note that If you want to fetch a token for an integration, you must prefix the integration name with integration_, eg: getToken({ template: 'integration_firebase' }).

Moreover, the following methods now accept a params objects instead of positional params: createEmailAddress(), createPhoneNumber(), setProfileImage().

Respecting the camelCase changes we explained at the start of this section, all method params should now use camelCasing. An example for the create method is shown below.

SignUp and SignIn

The createMagicLinkFlow and authenticateWithRedirect calls have had parameters renamed to use the word "redirect" instead of "callback."

Last updated on December 15, 2023