Client-side changes (all frameworks)

Upgrade dependencies

Next.js

npm install @clerk/nextjs@latest

Gatsby, React, Redwood

npm install @clerk/clerk-react@latest

useAuth() introduction

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

1
const {
2
  userId,
3
  sessionId,
4
  getToken,
5
  isLoaded,
6
  isSignedIn,
7
  signOut
8
} = 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.

Old API	New API
const user = useUser();	const { isLoaded, isSignedIn, user } = useUser();
const session = useSession();	const { isLoaded, isSignedIn, session } = useSession(); If you only call useSession for the ID or getToken, please switch to useAuth instead.

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

Old API	New API
<RedirectToSignIn returnBack/>	<RedirectToSignIn />
<RedirectToSignUp returnBack/>	<RedirectToSignUp />

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

Old API	New API
afterSignIn	afterSignInUrl
afterSignUp	afterSignUpUrl
signUpURL	signUpUrl
signInURL	signInUrl

<UserButton />

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

Old API	New API
afterSwitchSession	afterSwitchSessionUrl
userProfileURL	userProfileUrl
signInURL	signInUrl
afterSignOutAll	afterSignOutUrl
afterSignOutOne	afterMultiSessionSingleSignOutUrl

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

Old API	New API
const signUp = useSignUp();	const { isLoaded, signUp } = useSignUp();
const signIn = useSignIn();	const { isLoaded, signIn } = useSignIn();

Resource changes

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

Old API	New API
User.getToken("token-name")	const { getToken } = useAuth() getToken({template: "integration_token-name"}) or Session.getToken({template: "integration_token-name"})
User.createEmailAddress(value)	User.createEmailAddress({ email: value })
User.createPhoneNumber(value)	User.createPhoneNumber({ phoneNumber: value })
User.setProfileImage(file)	User.setProfileImage({ file })
User.update({ first_name: '', last_name: '' })	User.update({ firstName: '', lastName: '' })

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

Old API	New API
createMagicLinkFlow({ callbackUrl })	createMagicLinkFlow({ redirectUrl })
authenticateWithRedirect({ callbackUrl, callbackUrlComplete })	authenticateWithRedirect({ redirectUrl, redirectUrlComplete })