Upgrading from v2 to v3

On March 24, 2022, Clerk launched version 3 of its full suite of JavaScript libraries, including our SDKs for React, Next.js, Gatsby, Remix, and Redwood. This guide helps you with uprading to the next major version of your SDK.

Why upgrade?

Version 3 includes a number of bug fixes, developer experience improvements, and altogether new features, including:

• Support for server-side rendering
• Reduced React re-renders
• Improved Typescript types and IntelliSense autocomplete

Client-side changes (all frameworks)

These changes apply to all frameworks, regardless of which one you use specifically.

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 createEmailLinkFlow and authenticateWithRedirect calls have had parameters renamed to use the word "redirect" instead of "callback."

Next.js server-side changes

API routes

Helpers for API routes have been updated to mirror the new useAuth() hook on the client-side.

• withSession is deprecated and replaced with withAuth
• requireSession is deprecated with replaced with requireAuth
• Instead of decorating the Request object with a Session object, it is now decorated with an Auth object that mirrors useAuth() on the client-side.
  • const { userId, sessionId, getToken } = req.auth;

Example usage

import { withAuth } from "@clerk/nextjs/api";
 
export default withAuth(async (req, res) => {
  const { userId, sessionId, getToken } = req.auth;
  const hasuraToken = await getToken({template: "hasura"});
  // Your handler
});

Edge middleware

Edge middleware has also been updated to mirror the new useAuth() hook on the client-side. The import path has also been changed to avoid confusion.

import { withEdgeMiddlewareAuth } from "@clerk/nextjs/edge-middleware";
 
export const middleware = withEdgeMiddlewareAuth((req, ev) => {
  const { userId, sessionId, getToken } = req.auth;
  // Your middleware
});

Express server-side changes

Middleware

Express middleware been updated to mirror the new useAuth() hook on the client-side.

• ClerkExpressWithSession is deprecated and replaced with ClerkExpressWithAuth
• ClerkExpressRequireSession is deprecated and replaced with ClerkExpressRequireAuth
• Instead of decorating the Request object with a Session object, it is now decorated with an Auth object that mirrors useAuth() on the client-side.
  • const { userId, sessionId, getToken } = req.auth;

Example usage

import { ClerkExpressRequireAuth } from '@clerk/clerk-sdk-node';
 
app.use(ClerkExpressRequireAuth());
app.get('/', (req, res) => {
  const { userId, sessionId, getToken } = req.auth;
  // Your handler...
})