Upgrade from Clerk's Node SDK to the Express SDK
Install the Express SDK
To upgrade from the Clerk Node SDK to the Clerk Express SDK, uninstall the Node SDK by running the following command:
Then, install the Express SDK by running the following command:
Migrate from withAuth()
If you previously used withAuth()
to wrap your route handlers, you can now retrieve the authentication state within your Express route handlers using the req.auth
object.
clerkMiddleware()
is required to be set in the middleware chain before this util is used, as shown in the following example.
requireAuth()
usage changes
In the Node SDK, requireAuth()
wrapped route handlers. With the Express SDK, you must instead pass requireAuth)
as a middleware function before your handler instead of wrapping your handler. Additionally, requireAuth()
will now redirect un-authenticated users to the sign in page, where previously it would emit an error.
If you'd like to retain the previous behavior of requireAuth()
(emitting an error rather than redirecting), you can accomplish this as such:
You also want to make sure to catch and handle the error using an error middleware below.
Migrate from ClerkExpressWithAuth
To replace your existing Node SDK middleware ClerkExpressWithAuth()
, which allows requests to proceed even when users are not authenticated, you need to write your own middleware that uses req.auth
object to retrieve the auth state and then return an empty object if the user is not authenticated.
Migrate from ClerkExpressRequireAuth
To enforce strict authentication, replace your existing Node SDK strict middleware, ClerkExpressRequireAuth
, with the new Express SDK middleware, requireAuth()
.
requireAuth()
is a middleware function that you can use to protect routes in your Express.js application. This function checks if the user is authenticated, and redirects to the configured sign in URl if they are not.
If you'd like to retain the previous behavior of ClerkExpressRequireAuth
(emitting an error rather than redirecting), you can accomplish this as such:
You also want to make sure to catch and handle the error using an error middleware below.
Migrate from createClerkExpressWithAuth
and createClerkExpressRequireAuth
If you previously used createClerkExpressWithAuth
or createClerkExpressRequireAuth
to create custom middleware by passing in custom Clerk keys, a custom clerkClient
instance, and/or a custom API URL, you can no longer use these methods with the Express SDK. Instead, use clerkMiddleware
to create your custom middleware.
If you were passing custom Clerk keys or a custom API URL, pass those to createClerkClient
from the Backend SDK and then pass the custom clerkClient
into the middleware.
Backend SDK
Removed imports
With the Node SDK, you could import any of the Backend SDK methods directly from the Node SDK. With the Express SDK, you need to import the Backend SDK methods from the @clerk/backend
package.
clerkClient
import
The clerkClient
is used to access the Backend SDK, which exposes Clerk's backend API resources. If you were importing clerkClient
from the Node SDK, you can import it from the Express SDK.
Instantiating a custom clerkClient
If you were instantiating a custom clerkClient
with createClerkClient
, you can no longer import this method from the Express SDK. You must import it from the Backend SDK.
Feedback
Last updated on