From c12e98b080bf2ec54ca874ed0b47924058ee4cad Mon Sep 17 00:00:00 2001 From: Emmanouela Date: Sun, 30 Jun 2024 23:38:25 +0300 Subject: [PATCH] Update clerk express SDK docs --- docs/manifest.json | 2 +- docs/references/express/available-methods.mdx | 11 +++++----- .../express/migrate-from-node-to-express.mdx | 15 ++++++------- docs/references/express/overview.mdx | 21 +++++++++++-------- 4 files changed, 26 insertions(+), 23 deletions(-) diff --git a/docs/manifest.json b/docs/manifest.json index 32a1c53b59..74a88b0221 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -1769,7 +1769,7 @@ "href": "/docs/references/express/token-verification" }, { - "title": "Migrating from Clerk Node SDK to Clerk Express", + "title": "Migrating from Clerk Node SDK to Clerk Express SDK", "href": "/docs/references/express/migrate-from-node-to-express"} ] ] diff --git a/docs/references/express/available-methods.mdx b/docs/references/express/available-methods.mdx index 1953581cf5..0460b96d0b 100644 --- a/docs/references/express/available-methods.mdx +++ b/docs/references/express/available-methods.mdx @@ -49,13 +49,13 @@ const clientList = await clerkClient.clients.getClientList(); ``` ```js -const Clerk = require('@clerk/clerk-sdk-node/cjs/instance').default; +const { createClerkClient } = require('@clerk/express/cjs'); -const clerkClient = Clerk({ secretKey: '{{secret}}' }); +const clerkClient = createClerkClient({ secretKey: '{{secret}}' }); -clerkClient.sessions - .getSessionList() - .then((sessions) => console.log(sessions)) +clerkClient.clients + .getClientList() + .then((clientList) => console.log(clientList)) .catch((error) => console.error(error)); ``` @@ -75,7 +75,6 @@ The following options are available for you to customize the behaviour of the `c | `secretKey` | Server key for `api.clerk.com`. Can be found in your Clerk Dashboard on the **[API Keys](https://dashboard.clerk.com/last-active?path=api-keys)** page. | none | `CLERK_SECRET_KEY` | | `apiVersion` | API version to use | `v4` | `CLERK_API_VERSION` | | `apiUrl` | For debugging | `https://api.clerk.com` | `CLERK_API_URL` | -| `httpOptions` | HTTP client options | `{}` | N/A | {/* TODO: I think more of a description and example can be added for httpOptions. Also, we need to add information for audience, proxyUrl, jwtKey, publishableKey, domain, isSallite, telemetry */} diff --git a/docs/references/express/migrate-from-node-to-express.mdx b/docs/references/express/migrate-from-node-to-express.mdx index ae10509d0d..0d4cea12bc 100644 --- a/docs/references/express/migrate-from-node-to-express.mdx +++ b/docs/references/express/migrate-from-node-to-express.mdx @@ -1,11 +1,11 @@ --- -title: Clerk Express.js SDK -description: Learn how to migrate from Node.js to Express.js. +title: Clerk Express SDK +description: Learn how to migrate from Clerk Node SDK to Express SDK. --- -# Clerk Express.js SDK +# Clerk Express SDK -## Migrating from Clerk Node SDK to Clerk Express +## Migrating from Clerk Node SDK to Clerk Express SDK @@ -51,10 +51,10 @@ You can find an example [here](/docs/backend-requests/handling/nodejs#clerk-expr - **Centralized Middleware:** Use `clerkMiddleware` to authenticate all incoming requests without blocking them. This middleware will handle the handshake mechanism. - **Require Authentication in Specific Routes or Handlers:** -Use `requireAuth()` to enforce authentication on specific routes. This middleware returns an HTTP 401 response for unauthenticated request. +Use `requireAuth` to enforce authentication on specific routes. This middleware returns an HTTP 401 response for unauthenticated request. ```js const express = require('express'); -const { clerkMiddleware, requireAuth } = require('@clerk/clerk-express'); +const { clerkMiddleware, requireAuth } = require('@clerk/express'); const app = express(); @@ -84,9 +84,10 @@ To access the authentication state within your routes or handlers, use `getAuth( ```jsx const express = require('express'); -const { getAuth } = require('@clerk/clerk-express'); +const { clerkMiddleware, getAuth } = require('@clerk/express'); const app = express(); +app.use(clerkMiddleware()) app.get('/auth-state', (req, res) => { const authState = getAuth(req); diff --git a/docs/references/express/overview.mdx b/docs/references/express/overview.mdx index 0b339c5a5f..0588c4fb04 100644 --- a/docs/references/express/overview.mdx +++ b/docs/references/express/overview.mdx @@ -33,7 +33,8 @@ pnpm add @clerk/express ### Set environment variables -Below is an example of an `.env.local` file. +The developers have to load the environment variables from the .env.local file by using dotenv or any other library of their preference. +Below is an example of an .env.local file. **Pro tip!** If you are signed into your Clerk Dashboard, your secret key should become visible by clicking on the eye icon. Otherwise, you can find your keys in the Clerk Dashboard on the [API Keys](https://dashboard.clerk.com/last-active?path=api-keys) page. @@ -52,22 +53,24 @@ CLERK_SECRET_KEY={{secret}} All resource operations are mounted as sub-APIs on the `clerkClient` object. To access the resource operations, [you must first instantiate a `clerkClient` instance](/docs/references/express/available-methods). -## Multi-session applications - -If Clerk is running in multi-session mode, it's important to ensure your frontend sends the Session ID that is making the request. - -Our middleware will look for a query string parameter named `_clerk_session_id`. If this parameter is not found, the middleware will instead choose the last active session, which may be subject to race conditions and should not be relied on for authenticating actions. - ## Error handling Express SDK functions throw errors (`ClerkAPIResponseError`) when something goes wrong. You'll need to catch them in a `try/catch` block and handle them gracefully. For example: ```ts filename="example.ts" +import { clerkClient } from '@clerk/express'; + try { - const res = await someBackendApiCall(); + const userList = await clerkClient.users.getUserList(); } catch (error) { // Error handling } ``` -> See the guide on [using Clerk with Express.js](/docs/backend-requests/handling/nodejs#express-error-handlers) to learn about Express error handling. +### Express error handlers + +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](https://expressjs.com/en/guide/error-handling.html). An example error handler can be found above. + +If you are using the strict middleware variant, the `err` passed to your error handler will contain enough context for you to respond as you deem fit.