docs review

clerk · Jan 15, 2025 · bc8f807 · bc8f807
1 parent 8d808dc
commit bc8f807
Show file tree

Hide file tree

Showing 6 changed files with 173 additions and 283 deletions.
diff --git a/docs/_partials/clerk-options.mdx b/docs/_partials/clerk-options.mdx
@@ -0,0 +1,83 @@
+<Properties>
+  - `secretKey` (required)
+  - `string`
+
+  The Clerk Secret Key from the [**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page in the Clerk Dashboard.
+
+  ---
+
+  - `jwtKey?`
+  - `string`
+
+  The PEM public key from the **[**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page -> Show JWT public key -> PEM Public Key** section in the Clerk Dashboard. For more information, refer to [Manual JWT verification](/docs/backend-requests/handling/manual-jwt).
+
+  ---
+
+  - `publishableKey?`
+  - `string`
+
+  The Clerk Publishable Key from the [**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page in the Clerk Dashboard.
+
+  ---
+
+  - `domain?`
+  - `string`
+
+  The domain of a [satellite application](/docs/advanced-usage/satellite-domains) in a multi-domain setup.
+
+  ---
+
+  - `isSatellite?`
+  - `boolean`
+
+  Whether the instance is a satellite domain in a multi-domain setup. Defaults to `false`.
+
+  ---
+
+  - `proxyUrl?`
+  - `string`
+
+  The proxy URL from a multi-domain setup.
+
+  ---
+
+  - `sdkMetadata?`
+  - `{ name: string, version: string }`
+
+  Metadata about the SDK.
+
+  ---
+
+  - `telemetry?`
+  - `{ disabled: boolean, debug: boolean }`
+
+  [Telemetry](/docs/telemetry) configuration.
+
+  ---
+
+  - `userAgent?`
+  - `string`
+
+  The User-Agent request header passed to the Clerk API.
+
+  ---
+
+  - `apiUrl?`
+  - `string`
+
+  The [Clerk Backend API](/docs/reference/backend-api){{ target: '_blank' }} endpoint. Defaults to `'https://api.clerk.com'`.
+
+  ---
+
+  - `apiVersion?`
+  - `string`
+
+  The version passed to the Clerk API. Defaults to `'v1'`.
+
+  ---
+
+  - `audience?`
+  - `string | string[]`
+
+  A string or list of [audiences](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.3).
+</Properties>
diff --git a/docs/_partials/fastify/get-auth.mdx b/docs/_partials/fastify/get-auth.mdx
@@ -0,0 +1,48 @@
+The following example uses `getAuth()` to protect a route and load the user's data. If the user is authenticated, their `userId` is passed to [`clerkClient.users.getUser()`](/docs/references/backend/user/get-user){{ target: '_blank' }} to get the current user's [`User`](/docs/references/javascript/user/user){{ target: '_blank' }} object. If not authenticated, the request is rejected with a `403` status code.
+
+```ts
+// dotenv must be imported before @clerk/fastify
+import 'dotenv/config'
+import Fastify from 'fastify'
+import { clerkClient, clerkPlugin, getAuth } from '@clerk/fastify'
+
+const fastify = Fastify({ logger: true })
+
+fastify.register(clerkPlugin)
+
+// Use `getAuth()` to protect this route
+fastify.get('/protected', async (request, reply) => {
+  try {
+    // Use `getAuth()` to get the user's ID
+    const { userId } = getAuth(request)
+
+    // If user isn't authenticated, return a 403 error
+    if (!userId) {
+      return reply.code(403).send({ error: 'Unauthorized request' })
+    }
+
+    // Use `clerkClient` to access Clerk's Backend SDK methods
+    // and get the user's User object
+    const user = userId ? await clerkClient.users.getUser(userId) : null
+
+    return reply.send({
+      message: 'User retrieved successfully',
+      user,
+    })
+  } catch (error) {
+    fastify.log.error(error)
+    return reply.code(500).send({ error: 'Failed to retrieve user' })
+  }
+})
+
+const start = async () => {
+  try {
+    await fastify.listen({ port: 8080 })
+  } catch (error) {
+    fastify.log.error(error)
+    process.exit(1)
+  }
+}
+
+start()
+```
diff --git a/docs/backend-requests/handling/js-backend-sdks.mdx b/docs/backend-requests/handling/js-backend-sdks.mdx
diff --git a/docs/quickstarts/fastify.mdx b/docs/quickstarts/fastify.mdx
@@ -43,7 +43,7 @@ Learn how to integrate Clerk into your Fastify backend for secure user authentic
 
   [Clerk's Fastify SDK](https://github.com/clerk/javascript/tree/main/packages/fastify) provides a range of backend utilities to simplify user authentication and management in your application.
 
-  To get started using Clerk with Fastify, add the SDK to your project:
+  Run the following command to install the SDK:
 
   <CodeBlockTabs options={["npm", "yarn", "pnpm"]}>
     ```bash {{ filename: 'terminal' }}
@@ -78,11 +78,11 @@ Learn how to integrate Clerk into your Fastify backend for secure user authentic
   CLERK_SECRET_KEY={{secret}}
   ```
 
-  ## Configure `clerkPlugin` for all routes
+  ## Configure `clerkPlugin()` for all routes
 
-  The `clerkPlugin` is a Fastify plugin provided by Clerk to integrate authentication into your Fastify application. To ensure that Clerk's authentication and user management features are applied across your Fastify application, configure the `clerkPlugin` to handle all routes or limit it to specific ones.
+  The `clerkPlugin()` function is a Fastify plugin provided by Clerk to integrate authentication into your Fastify application. To ensure that Clerk's authentication and user management features are applied across your Fastify application, configure the `clerkPlugin()` to handle all routes or limit it to specific ones.
 
-  The following example registers the plugin for all routes. To register the plugin for specific routes only, refer to the [**Using Clerk for specific pages only**](/docs/references/fastify/overview#configure-clerk-plugin-for-specific-routes) section.
+  The following example registers the plugin for all routes. To register the plugin for specific routes, see the [reference docs](/docs/references/fastify/overview#configure-clerk-plugin-for-specific-routes).
 
   > [!IMPORTANT]
   > The `dotenv/config` module must be imported before any Clerk modules. This order is important because Clerk instances are created during the import process and rely on environment variables, such as API keys, to be initialized correctly. For more information, refer to the [Fastify docs](https://fastify.dev/docs/latest/Guides/Getting-Started/#loading-order-of-your-plugins).
@@ -108,44 +108,9 @@ Learn how to integrate Clerk into your Fastify backend for secure user authentic
   start()
   ```
 
-  ## Use `getAuth()` to access the auth state and protect routes
+  ## Protect your routes using `getAuth()`
 
-  The following example uses [`getAuth()`](/docs/references/nextjs/get-auth){{ target: '_blank' }} to retrieve the `userId`, which is used to protect the route and is passed to [`clerkClient.users.getUser()`](/docs/references/backend/user/get-user){{ target: '_blank' }} to retrieve the current user's `User` object.
+  The [`getAuth()`](/docs/references/fastify/overview#get-auth) helper retrieves the current user's authentication state from the `request` object. It returns the [`Auth` object](/docs/references/backend/types/auth-object#auth-object){{ target: '_blank' }}.
 
-  ```ts {{ filename: 'index.ts' }}
-  import 'dotenv/config'
-  import Fastify from 'fastify'
-  import { clerkClient, clerkPlugin, getAuth } from '@clerk/fastify'
-
-  const fastify = Fastify({ logger: true })
-
-  fastify.register(clerkPlugin)
-
-  fastify.get('/', async (request, reply) => {
-    const { userId } = getAuth(request)
-
-    // Protect the route from unauthenticated users
-    if (!userId) {
-      return reply.code(403).send({ error: 'Unauthorized request.' })
-    }
-
-    const user = userId ? await clerkClient.users.getUser(userId) : null
-
-    return reply.send({
-      message: 'User retrieved successfully.',
-      user,
-    })
-  })
-
-  const start = async () => {
-    try {
-      await fastify.listen({ port: 8080 })
-    } catch (error) {
-      fastify.log.error(error)
-      process.exit(1)
-    }
-  }
-
-  start()
-  ```
+  <Include src="_partials/fastify/get-auth" />
 </Steps>
diff --git a/docs/references/backend/overview.mdx b/docs/references/backend/overview.mdx
@@ -285,89 +285,7 @@ The `createClerkClient()` function requires an `options` object. It is recommend
 
 The following options are available:
 
-<Properties>
-  - `secretKey` (required)
-  - `string`
-
-  The Clerk Secret Key from the [**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page in the Clerk Dashboard.
-
-  ---
-
-  - `jwtKey?`
-  - `string`
-
-  The PEM public key from the **[**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page -> Show JWT public key -> PEM Public Key** section in the Clerk Dashboard. For more information, refer to [Manual JWT verification](/docs/backend-requests/handling/manual-jwt).
-
-  ---
-
-  - `publishableKey?`
-  - `string`
-
-  The Clerk Publishable Key from the [**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page in the Clerk Dashboard.
-
-  ---
-
-  - `domain?`
-  - `string`
-
-  The domain of a [satellite application](/docs/advanced-usage/satellite-domains) in a multi-domain setup.
-
-  ---
-
-  - `isSatellite?`
-  - `boolean`
-
-  Whether the instance is a satellite domain in a multi-domain setup. Defaults to `false`.
-
-  ---
-
-  - `proxyUrl?`
-  - `string`
-
-  The proxy URL from a multi-domain setup.
-
-  ---
-
-  - `sdkMetadata?`
-  - `{ name: string, version: string }`
-
-  Metadata about the SDK.
-
-  ---
-
-  - `telemetry?`
-  - `{ disabled: boolean, debug: boolean }`
-
-  [Telemetry](/docs/telemetry) configuration.
-
-  ---
-
-  - `userAgent?`
-  - `string`
-
-  The User-Agent request header passed to the Clerk API.
-
-  ---
-
-  - `apiUrl?`
-  - `string`
-
-  The [Clerk Backend API](/docs/reference/backend-api){{ target: '_blank' }} endpoint. Defaults to `'https://api.clerk.com'`.
-
-  ---
-
-  - `apiVersion?`
-  - `string`
-
-  The version passed to the Clerk API. Defaults to `'v1'`.
-
-  ---
-
-  - `audience?`
-  - `string | string[]`
-
-  A string or list of [audiences](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.3).
-</Properties>
+<Include src="_partials/clerk-options" />
 
 ## Get the `userId` and other properties