diff --git a/docs/quickstarts/express.mdx b/docs/quickstarts/express.mdx index f5dc8d6491..6eb2ee26be 100644 --- a/docs/quickstarts/express.mdx +++ b/docs/quickstarts/express.mdx @@ -30,14 +30,14 @@ description: Learn how to use Clerk to quickly and easily add secure authenticat - Protect your routes using `requireAuth()` -Learn how to integrate Clerk into your Express backend for secure user authentication and management. This guide covers backend implementation only and requires a Clerk frontend SDK in order for any of this to work. +Learn how to integrate Clerk into your Express backend for secure user authentication and management. This guide focuses on backend implementation and requires a Clerk frontend SDK to function correctly. ## Install `@clerk/express` - Clerk's [Express SDK](/docs/references/express/overview) ships with a variety of helpers for the backend to make user authentication easier. + Clerk's [Express SDK](/docs/references/express/overview) gives you access to prebuilt components, React hooks, and helpers to make user authentication easier. - To get started using Clerk with Express, add the SDK to your project: + Run the following command to install the SDK: ```bash {{ filename: 'terminal' }} @@ -88,7 +88,7 @@ Learn how to integrate Clerk into your Express backend for secure user authentic ``` - ## Add `clerkMiddleware()` to your application + ## Add `clerkMiddleware()` to your app The [`clerkMiddleware()`](/docs/references/express/overview#clerk-middleware) function checks the request's cookies and headers for a session JWT and, if found, attaches the [`Auth`](/docs/references/backend/types/auth-object#auth-object){{ target: '_blank' }} object to the `request` object under the `auth` key. @@ -98,10 +98,12 @@ Learn how to integrate Clerk into your Express backend for secure user authentic import { clerkMiddleware } from '@clerk/express' const app = express() + const PORT = 3000 app.use(clerkMiddleware()) - app.listen(3000, () => { + // Start the server and listen on the specified port + app.listen(PORT, () => { console.log(`Example app listening at http://localhost:${PORT}`) }) ``` @@ -110,7 +112,7 @@ Learn how to integrate Clerk into your Express backend for secure user authentic To protect your routes, use the [`requireAuth()`](/docs/references/express/overview#require-auth) middleware. This middleware functions similarly to `clerkMiddleware()`, but also protects your routes by redirecting unauthenticated users to the sign-in page. - In the following example, `requireAuth()` is used to protect the `/protected` route. If the user is not authenticated, they are redirected to the '/sign-in' route. If the user is authenticated, the `req.auth` object is used to get the `userId`, which is passed to [`clerkClient.users.getUser()`](/docs/references/backend/user/get-user){{ target: '_blank' }} to fetch the current user's `User` object. + In the following example, `requireAuth()` is used to protect the `/protected` route. If the user isn't authenticated, they're redirected to the homepage. If the user is authenticated, the [`getAuth()`](/docs/references/express/overview#get-auth) function is used to get the `userId`, which is passed to [`clerkClient.users.getUser()`](/docs/references/backend/user/get-user){{ target: '_blank' }} to fetch the current user's `User` object. ```ts {{ filename: 'index.ts', mark: [3, [7, 11], [13, 16]] }} import 'dotenv/config' @@ -118,22 +120,36 @@ Learn how to integrate Clerk into your Express backend for secure user authentic import { clerkClient, requireAuth } from '@clerk/express' const app = express() + const PORT = 3000 - app.get('/protected', requireAuth({ signInUrl: '/sign-in' }), async (req, res) => { - const { userId } = req.auth + // Use requireAuth() to protect this route + // If user isn't authenticated, requireAuth() will redirect back to the homepage + app.get('/protected', requireAuth(), async (req, res) => { + // Use `getAuth()` to get the user's `userId` + const { userId } = getAuth(req) + + // Use Clerk's JavaScript Backend SDK to get the user's User object const user = await clerkClient.users.getUser(userId) - return res.json({ user }) - }) - app.get('/sign-in', (req, res) => { - // Assuming you have a template engine installed and are using a Clerk JavaScript SDK on this page - res.render('sign-in') + return res.json({ user }) }) - app.listen(3000, () => { + // Start the server and listen on the specified port + app.listen(PORT, () => { console.log(`Example app listening at http://localhost:${PORT}`) }) ``` + + ## Add global TypeScript type (optional) + + If you're using TypeScript, add a global type reference to your project to enable auto-completion and type checking for the `auth` object in Express request handlers. + + 1. In your application's root folder, create a `types/` directory. + 1. Inside this directory, create a `globals.d.ts` file with the following code. + + ```ts {{ filename: 'types/globals.d.ts' }} + /// + ``` ## Next steps diff --git a/docs/references/express/overview.mdx b/docs/references/express/overview.mdx index f937285b40..2bbc391f98 100644 --- a/docs/references/express/overview.mdx +++ b/docs/references/express/overview.mdx @@ -3,9 +3,7 @@ title: Clerk Express SDK description: Learn how to integrate Clerk into your Express application using the Clerk Express SDK. --- -The Clerk Express SDK is the recommended method for integrating Clerk into your Express application. - -See the [quickstart](/docs/quickstarts/express) to get started. +The Clerk Express SDK is the recommended method for integrating Clerk into your Express application. Refer to the [quickstart](/docs/quickstarts/express) to get started. {/* TODO: Remove callout when Node SDK is removed from docs */} @@ -57,13 +55,16 @@ The `clerkMiddleware()` function accepts [these options](https://clerk.com/docs/ ### `requireAuth()` -The `requireAuth()` middleware functions similarly to `clerkMiddleware()`, but also protects your routes by redirecting unauthenticated users to the sign-in page. It will look for a `CLERK_SIGN_IN_URL` environment variable and use that by default. If not present, you must pass a sign in URL to the middleware as an option. +The `requireAuth()` middleware functions similarly to `clerkMiddleware()`, but also protects your routes by redirecting unauthenticated users to the homepage. It accepts the same [options](/docs/references/express/overview#options) as `clerkMiddleware()`. + +You can also specify a custom sign-in URL to redirect unauthenticated users to by setting the `CLERK_SIGN_IN_URL` environment variable or by passing a `signInUrl` option to the middleware. It's recommended to set the environment variable. ```js import { requireAuth } from '@clerk/express' import express from 'express' const app = express() +const PORT = 3000 // Apply middleware to all routes app.use(requireAuth()) @@ -77,13 +78,16 @@ app.get('/protected', requireAuth(), (req, res) => { app.get('/protected', requireAuth({ signInUrl: '/sign-in' }), (req, res) => { res.send('This is a protected route') }) -``` -This middleware accepts the same [options](/docs/references/express/overview#options) as `clerkMiddleware()`. +// Start the server and listen on the specified port +app.listen(PORT, () => { + console.log(`Server is running on http://localhost:${PORT}`) +}) +``` ### `getAuth()` -The `getAuth()` helper retrieves authentication state from the request object. See the [Next.js reference documentation](https://clerk.com/docs/references/nextjs/get-auth) for more information on how to use the returned `auth` object. +The `getAuth()` helper retrieves authentication state from the request object. See the [Next.js reference documentation](https://clerk.com/docs/references/nextjs/get-auth) for more examples on how to use the returned `auth` object. The following example uses `requireAuth()` to protect the route based on _authentication_ status, and then uses `getAuth()` to protect the route based on _authorization_ status. @@ -92,12 +96,12 @@ import { clerkMiddleware, getAuth, requireAuth } from '@clerk/express' import express from 'express' const app = express() -const port = 3000 +const PORT = 3000 // Apply centralized middleware app.use(clerkMiddleware()) -// Protect a route based on authorization status +// Use `getAuth()` to protect a route based on authorization status const hasPermission = (req, res, next) => { const auth = getAuth(req) @@ -109,11 +113,13 @@ const hasPermission = (req, res, next) => { return next() } +// Use `requireAuth()` to protect this route +// If user is not authenticated, requireAuth() will redirect back to the homepage app.get('/path', requireAuth(), hasPermission, (req, res) => res.json(req.auth)) // Start the server and listen on the specified port -app.listen(port, () => { - console.log(`Server is running on http://localhost:${port}`) +app.listen(PORT, () => { + console.log(`Server is running on http://localhost:${PORT}`) }) ``` @@ -121,16 +127,16 @@ app.listen(port, () => { [Clerk's JavaScript Backend SDK](/docs/references/backend/overview) exposes the Backend API resources and low-level authentication utilities for JavaScript environments. For example, if you wanted to get a list of all users in your application, instead of creating a fetch to the `https://api.clerk.com/v1/users` endpoint, you can use the `users.getUserList()` method provided by the JavaScript Backend SDK. -All resource operations are mounted as sub-APIs on the `clerkClient` object. See the [reference documentation](/docs/references/backend/overview#usage) for more information. +All resource operations are mounted as sub-APIs on the `clerkClient` object. See the [reference documentation](/docs/references/backend/overview#usage){{ target: '_blank' }} for more information. ```js import { clerkClient, requireAuth } from '@clerk/express' import express from 'express' const app = express() -const port = 3000 +const PORT = 3000 -app.get('/users', async (req, res) => { +app.get('/user', async (req, res) => { // Get the `userId` from the `Auth` object const userId = req.auth.userId @@ -140,11 +146,12 @@ app.get('/users', async (req, res) => { // Use the userId to get information about the user const user = await clerkClient.users.getUser(userId) + return void res.status(200).json(user) }) // Start the server and listen on the specified port -app.listen(port, () => { - console.log(`Server is running on http://localhost:${port}`) +app.listen(PORT, () => { + console.log(`Server is running on http://localhost:${PORT}`) }) ```