Audit /users docs; lint /using-proxies (#2079)

Author: alexisintech

docs/_partials/user-object.mdx

@@ -0,0 +1,5 @@
+The `User` object holds all of the information for a single user of your application and provides a set of methods to manage their account. Each `User` has at least one authentication [identifier](/docs/authentication/configuration/sign-up-sign-in-options#identifiers), which might be their email address, phone number, or a username.
+
+A user can be contacted at their primary email address or primary phone number. They can have more than one registered email address, but only one of them will be their primary email address. This goes for phone numbers as well; a user can have more than one, but only one phone number will be their primary. At the same time, a user can also have one or more external accounts by connecting to [social providers](/docs/authentication/social-connections/overview) such as Google, Apple, Facebook, and many more.
+
+Finally, a `User` object holds profile data like the user's name, profile picture, and a set of [metadata](/docs/users/metadata) that can be used internally to store arbitrary information. The metadata are split into `publicMetadata` and `privateMetadata`. Both types are set from the [Backend API](/docs/reference/backend-api){{ target: '_blank' }}, but public metadata can also be accessed from the [Frontend API](/docs/reference/frontend-api){{ target: '_blank' }}.

docs/advanced-usage/using-proxies.mdx

@@ -122,7 +122,7 @@ When using a proxy, all requests to the Frontend API will be made through your d
 
           const proxyUrl = new URL(request.url)
           proxyUrl.host = 'frontend-api.clerk.dev'
-          proxyUrl.port = "443"
+          proxyUrl.port = '443'
           proxyUrl.protocol = 'https'
           proxyUrl.pathname = proxyUrl.pathname.replace('/__clerk', '')
 

docs/references/javascript/user.mdx

@@ -3,11 +3,7 @@ title: '`User` object'
 description: The User object holds all the information for a user of your application and provides a set of methods to manage their account. Users have a unique authentication identifier which might be their email address, phone number or a username.
 ---
 
-The `User` object holds all of the information for a single user of your application and provides a set of methods to manage their account. Each user has a unique authentication identifier which might be their email address, phone number, or a username.
-
-A user can be contacted at their primary email address or primary phone number. They can have more than one registered email address, but only one of them will be their primary email address. This goes for phone numbers as well; a user can have more than one, but only one phone number will be their primary. At the same time, a user can also have one or more external accounts by connecting to [social providers](/docs/authentication/social-connections/overview) such as Google, Apple, Facebook, and many more.
-
-Finally, a `User` object holds profile data like the user's name, profile picture, and a set of [metadata](/docs/users/metadata) that can be used internally to store arbitrary information. The metadata are split into `publicMetadata` and `privateMetadata`. Both types are set from the [Backend API](/docs/reference/backend-api){{ target: '_blank' }}, but public metadata can also be accessed from the [Frontend API](/docs/reference/frontend-api){{ target: '_blank' }}.
+<Include src="_partials/user-object" />
 
 The ClerkJS SDK provides some helper [methods](#methods) on the `User` object to help retrieve and update user information and authentication status.
 

docs/users/creating-users.mdx

@@ -3,41 +3,54 @@ title: Create users
 description: Learn how to create users in your Clerk application.
 ---
 
-There are two ways to create users in Clerk: [through the Clerk Dashboard](#create-users-in-the-clerk-dashboard) or [using the Clerk API](#create-users-using-the-clerk-api).
+There are two ways to create users in Clerk: [in the Clerk Dashboard](#in-the-clerk-dashboard) or [using the Backend API](#using-the-backend-api).
 
-## Create users in the Clerk Dashboard
+## In the Clerk Dashboard
 
 To create users in the Clerk Dashboard:
 
 1. In the top in the Clerk Dashboard, select [**Users**](https://dashboard.clerk.com/last-active?path=users).
 1. Select **Create user**.
 1. Enter the required user details and select **Create**.
 
-## Create users using the Clerk API
+## Using the Backend API
 
-To create users using the Clerk API, you can use the [`createUser()`](/docs/references/backend/user/create-user) method from the `users` sub-api of the `clerkClient` instance.
+You can create users in your app using Clerk's Backend API.
 
-<Tabs items={["Next.js", "Express", "cURL"]}>
+Use the following tabs to see examples of how to create users using one of the following:
+
+- Frontend SDKs, such as Next.js, React, or Remix
+- Express
+- cURL
+
+<Tabs items={["Fullstack SDKs", "Express", "cURL"]}>
   <Tab>
-    ```ts {{ filename: 'app/api/create-user/route.ts' }}
-    import { clerkClient } from '@clerk/nextjs/server'
-    import { NextResponse } from 'next/server'
+    The following example shows how to create a user using the JavaScript Backend SDK's [`createUser()`](/docs/references/backend/user/create-user) method from the `users` sub-api of the `clerkClient` instance.
 
+    ```ts {{ filename: 'route.ts' }}
     export async function POST() {
       try {
-        const client = await clerkClient()
-
-        const user = await client.users.createUser({
+        const user = await clerkClient.users.createUser({
           emailAddress: ['[email protected]'],
           password: 'password',
         })
-        return NextResponse.json({ message: 'User created', user })
+        return Response.json({ message: 'User created', user })
       } catch (error) {
         console.log(error)
-        return NextResponse.json({ error: 'Error creating user' })
+        return Response.json({ error: 'Error creating user' })
       }
     }
     ```
+
+    <If sdk="nextjs">
+      If you're using Next.js, you must `await` the instantiation of the `clerkClient` instance, like so:
+
+      ```ts
+      const client = await clerkClient()
+
+      const response = await client.users.createUser()
+      ```
+    </If>
   </Tab>
 
   <Tab>

docs/users/deleting-users.mdx

@@ -3,38 +3,52 @@ title: Delete users
 description: Learn how to delete users in your Clerk application.
 ---
 
-There are two ways to delete users in Clerk: [through the Clerk Dashboard](#delete-users-in-the-clerk-dashboard) or [using the Clerk API](#delete-users-using-the-clerk-api).
+There are two ways to delete users in Clerk: [in the Clerk Dashboard](#in-the-clerk-dashboard) or [using the Backend API](#using-the-backend-api).
 
-## Delete users in the Clerk Dashboard
+## In the Clerk Dashboard
 
 To delete users in the Clerk Dashboard:
 
 1. At the top of the Clerk Dashboard, select [**Users**](https://dashboard.clerk.com/last-active?path=users).
 1. You can either select the user and then in the side navigation menu, select **Delete user**, or select the menu icon on the right side of the user's row and select **Delete user**.
 
-## Delete users using the Clerk API
+## Using the Backend API
 
-To delete users using the Clerk API, you can use the [`deleteUser()`](/docs/references/backend/user/delete-user) method from the `users` sub-api of the `clerkClient` instance.
+You can delete users in your app using Clerk's Backend API.
 
-<Tabs items={["Next.js", "Express", "cURL"]}>
+Use the following tabs to see examples of how to delete users using one of the following:
+
+- Frontend SDKs, such as Next.js, React, or Remix
+- Express
+- cURL
+
+<Tabs items={["Fullstack SDKs", "Express", "cURL"]}>
   <Tab>
-    ```ts {{ filename: 'app/api/delete-user/route.ts' }}
-    import { clerkClient } from '@clerk/nextjs/server'
-    import { NextResponse } from 'next/server'
+    The following example shows how to delete a user using the JavaScript Backend SDK's [`deleteUser()`](/docs/references/backend/user/delete-user) method from the `users` sub-api of the `clerkClient` instance.
 
+    ```ts {{ filename: 'route.ts' }}
     export async function DELETE() {
       const userId = 'user_123'
 
       try {
-        const client = await clerkClient()
-        await client.users.deleteUser(userId)
-        return NextResponse.json({ message: 'User deleted' })
+        await clerkClient.users.deleteUser(userId)
+        return Response.json({ message: 'User deleted' })
       } catch (error) {
         console.log(error)
-        return NextResponse.json({ error: 'Error deleting user' })
+        return Response.json({ error: 'Error deleting user' })
       }
     }
     ```
+
+    <If sdk="nextjs">
+      If you're using Next.js, you must `await` the instantiation of the `clerkClient` instance, like so:
+
+      ```ts
+      const client = await clerkClient()
+
+      const response = await client.users.deleteUser(userId)
+      ```
+    </If>
   </Tab>
 
   <Tab>

docs/users/invitations.mdx

@@ -90,7 +90,7 @@ curl https://api.clerk.com/v1/invitations -X POST -d '{"email_address": "email@e
 
 ## Revoking invitations
 
-You can revoke an invitation at any time. Revoking an invitation prevents the user from using the invitation link that was sent to them.
+You can revoke an invitation at any time. Revoking an invitation prevents the user from using the invitation link that was sent to them. You can revoke an invitation in the [Clerk Dashboard](#using-clerk-dashboard-2) or [using the Backend API](#using-backend-api-2).
 
 ### Using Clerk Dashboard
 
@@ -101,7 +101,7 @@ To revoke an invitation, navigate to the **Users** page from the top-level menu,
 
 ### Using Backend API
 
-You can either use a cURL command or the [JavaScript Backend SDK](/docs/references/backend/overview) to create an invitation. Use the following tabs to see examples for each method.
+You can either use a cURL command or the [JavaScript Backend SDK](/docs/references/backend/overview) to revoke an invitation. Use the following tabs to see examples for each method.
 
 <Tabs items={["cURL", "Backend SDK"]}>
   <Tab>
@@ -132,4 +132,4 @@ See the [Backend API reference](/docs/reference/backend-api/tag/Invitations#oper
 
 ## Custom flow
 
-Clerk's [prebuilt components](/docs/components/overview) and [Account Portal pages](/docs/account-portal/overview) handle the sign-up flow for you, including the invitation flow. If you want to build a **custom** sign-up flow, see the [custom flow](/docs/custom-flows/application-invitations) guide.
+Clerk's [prebuilt components](/docs/components/overview) and [Account Portal pages](/docs/account-portal/overview) handle the sign-up flow for you, including the invitation flow. If Clerk's prebuilt components don't meet your specific needs or if you require more control over the logic, you can rebuild the existing Clerk flows using the Clerk API. For more information, see the [custom flow for application invitations](/docs/custom-flows/application-invitations).