Express Middleware

For usage with Express, this package also exports ClerkExpressWithAuth (lax) & ClerkExpressRequireAuth (strict) middlewares that can be used in the standard manner:

1
import { ClerkWithAuth } from '@clerk/clerk-sdk-node';
2

3
// Initialize express app the usual way
4

5
app.use(ClerkWithAuth());

The ClerkWithAuth middleware will set the Clerk session information on the request object as req.auth and then call the next middleware.

You can then implement your own logic for handling a logged-in or logged-out user in your express endpoints or custom middleware, depending on whether your users are trying to access a public or protected resource.

If you want to use the Express middleware of your custom Clerk instance, you can use:

app.use(clerk.expressWithAuth());

Where clerk is your own instance.

Optional session

This strategy allows you to detect whether or not there's an active session, and handle each case separately.

1
import { ClerkExpressWithAuth } from '@clerk/clerk-sdk-node';
2

3
//
4
// Initialize express app
5
//
6

7
app.use(ClerkExpressWithAuth());

Required session

This strategy mandates that a session be available. If not, it returns a 401 (Unauthenticated) and your handler is never called.

1
import { ClerkExpressRequireAuth } from '@clerk/clerk-sdk-node';
2

3
//
4
// Initialize express app
5
//
6

7
app.use(ClerkExpressRequireAuth());

onError option

The Express middleware supports an options object as an optional argument. The only key currently supported is onError for providing your own error handler.

The onError function, if provided, should take an Error argument (onError(error)).

Depending on the return value, it can affect the behavior of the middleware as follows:

If an Error is returned, the middleware will call next(err) with that error. If the err has a statusCode it will indicate to Express what HTTP code the response should have.
If anything other than an Error is returned (or nothing is returned at all), then the middleware will call next() without arguments

The default implementations unless overridden are:

// defaultOnError swallows the error
defaultOnError(error: Error) {
  console.error(error.message);
}

// strictOnError returns the error so that Express will halt the request chain
strictOnError(error: Error) {
  console.error(error.message);
  return error;
}

Express Error Handlers

Not to be confused with the onError option mentioned above, Express comes with a default error handler for errors encountered in the middleware chain.

Developers can also implement their own custom error handlers as detailed in the Express error handling guide.

An example error handler can be found in our Express examples folder:

1
// Note: this is just a sample errorHandler that pipes clerk server errors through to your API responses
2
// You will want to apply different handling in your own app to avoid exposing too much info to the client
3
function errorHandler(err, req, res, next) {
4
  const statusCode = err.statusCode || 500;
5
  const body = err.data || { error: err.message };
6

7
  res.status(statusCode).json(body);
8
}

If you are using the strict middleware variant, the err pass to your error handler will contain enough context for you to respond as you deem fit.