Merge branch 'main' into izaak/orgs-132-dx-guide

clerk · Nov 1, 2024 · 2826a92 · 2826a92
2 parents fe23e75 + 70bd6bc
commit 2826a92
Show file tree

Hide file tree

Showing 2 changed files with 125 additions and 20 deletions.
diff --git a/docs/authentication/social-connections/gitlab.mdx b/docs/authentication/social-connections/gitlab.mdx
@@ -1,36 +1,77 @@
 ---
 title: Add GitLab as a social connection
-description: Learn how to set up social connection with GitLab.
+description: Learn how to allow users to sign up and sign in to your Clerk app with their GitLab account using OAuth.
 ---
 
-How to set up social connection with GitLab
+<TutorialHero
+  beforeYouStart={[
+    {
+      title: "A Clerk app is required.",
+      link: "/docs/quickstarts/setup-clerk",
+      icon: "clerk",
+    },
+    {
+      title: "A GitLab account is required.",
+      link: "https://gitlab.com/users/sign_up",
+      icon: "user-circle",
+    },
+  ]}
+>
+  - Use GitLab to authenticate users with OAuth
+</TutorialHero>
 
-## Overview
+Enabling OAuth with [GitLab](https://docs.gitlab.com/ee/integration/oauth_provider.html) allows your users to sign up and sign in to your Clerk app with their GitLab account.
 
-Adding social connection with GitLab to your app with Clerk is done in a few steps - you only need to set the **Client ID**, **Client Secret** and **Redirect URI** in your instance settings.
+## Configure for your development instance
 
-To make the development flow as smooth as possible, Clerk uses  preconfigured shared OAuth credentials and redirect URIs for development instances - no other configuration is needed.
+For _development instances_, Clerk uses preconfigured shared OAuth credentials and redirect URIs—no other configuration is needed.
 
-For production instances, you will need to generate your own Client ID and Client secret using your GitLab account.
+1. In the Clerk Dashboard, navigate to the [**SSO Connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page.
+1. Select **Add connection** and select **For all users**.
+1. In the **Choose provider** dropdown, select **GitLab**.
+1. Select **Add connection**.
 
-> [!NOTE]
-> The purpose of this guide is to help you create a GitLab account and a  GitLab OAuth app - if you're looking for step-by-step instructions using Clerk to add social connection (OAuth) to your application, follow the [Social connection (OAuth) guide](/docs/authentication/social-connections/oauth).
+## Configure for your production instance
 
-## Before you start
+For _production instances_, you must provide custom credentials which involves generating your own **Client ID** and **Client Secret** using your GitLab account.
 
-- You need to create a Clerk Application in your [Clerk Dashboard](https://dashboard.clerk.com/). For more information, check out our [Set up your application guide](/docs/quickstarts/setup-clerk).
-- You need to have a GitLab account. To create one, [click here](https://gitlab.com/users/sign_up).
+To make the setup process easier, it's recommended to keep two browser tabs open: one for your [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) and one for your [GitLab](https://gitlab.com) account.
 
-## Configuring GitLab social connection
+<Steps>
+  ### Enable GitLab as a social connection in Clerk
 
-First, you need to register a new OAuth GitLab app. Follow the official GitLab instructions on [how to create an OAuth app](https://docs.gitlab.com/ee/integration/oauth_provider.html#user-owned-applications).
+  1. In the Clerk Dashboard, navigate to the [**SSO Connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page.
+  1. Select **Add connection** and select **For all users**.
+  1. In the **Choose provider** dropdown, select **GitLab**.
+  1. Ensure that both **Enable for sign-up and sign-in** and **Use custom credentials** are toggled on.
+  1. Save the **Redirect URI** somewhere secure. Keep the modal and page open.
 
-![Creating an OAuth GitLab app](/docs/images/authentication-providers/gitlab/7e67b1cb88c1df509cac722d6a6b2d7c624686f8-1919x840.png)
+  ### Create a GitLab app
 
-Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections). In the top navigation, select **Configure**. Then in the sidebar, select **SSO Connections**. Select the **Add connection** button, and select **For all users**. In the **Choose provider** dropdown, select **GitLab**. Toggle on **Use custom credentials** and copy **Redirect URI**. Go back to the GitLab panel, paste the value into the **Redirect URI**, select any scopes that would you like your users to provide and save the application.
+  1. In [Gitlab](https://gitlab.com), navigate to the [**Applications**](https://gitlab.com/-/user_settings/applications) page.
+  1. Select **Add new application**.
+  1. Enter your app name in **Name**.
+  1. In **Redirect URI**, paste the **Redirect URI** you saved from the Clerk Dashboard.
+  1. Select the **Scopes** needed for your app. To allow users to sign up and sign in with GitLab, you must at least select `read_user`.
+  1. Select **Save application**. You'll be redirected to your app's settings page. Save the **Application ID** and **Secret** somewhere secure.
 
-Once creation is complete, you'll get redirected to application's panel. Copy the **Application ID** and **Secret.** Go back to the Clerk Dashboard and paste them into the respective fields.
+  ### Set the Client ID and Client Secret in your Clerk Dashboard
 
-![Obtaining the Application ID and Client secret](/docs/images/authentication-providers/gitlab/63d7ad6409b75e250377b4d1e9b792dbcecadae1-1920x841.png)
+  1. Navigate back to your Clerk Dashboard where the modal should still be open. Paste the **Application ID** and **Secret** values in the **Client ID** and **Client Secret** fields, respectively.
+  1. Select **Add connection**.
 
-Finally, select **Add connection** so that the settings are applied. Congratulations! Social connection with GitLab is now configured for your instance.
+  > [!NOTE]
+  > If the modal or page is not still open, navigate to the [**SSO Connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page in the Clerk Dashboard. Select the **GitLab** connection. Under **Use custom credentials**, you can paste the **Client ID** and **Client Secret** into their respective fields.
+
+  ### Test your OAuth
+
+  The simplest way to test your OAuth is to visit your Clerk app's [Account Portal](/docs/customization/account-portal/overview), which is available for all Clerk apps out-of-the-box.
+
+  1. In the Clerk Dashboard, navigate to the [**Account Portal**](https://dashboard.clerk.com/last-active?path=account-portal) page.
+  1. Next to the **Sign-in** URL, select **Visit**. The URL should resemble:
+
+  - **For development** – `https://your-domain.accounts.dev/sign-in`
+  - **For production** – `https://accounts.your-domain.com/sign-in`
+
+  1. Sign in with your GitLab account.
+</Steps>
diff --git a/docs/customization/user-button.mdx b/docs/customization/user-button.mdx
@@ -57,7 +57,7 @@ The `<UserButton />` component must be wrapped in a `<UserButton.MenuItems />` c
 
 The following example demonstrates how to add an action to the `<UserButton />` component.
 
-<Tabs items={["Next.js", "Astro"]}>
+<Tabs items={["Next.js", "Astro", "JavaScript"]}>
   <Tab>
     ```tsx filename="/app/page.tsx"
     'use client'
@@ -139,6 +139,39 @@ The following example demonstrates how to add an action to the `<UserButton />`
     </script>
     ```
   </Tab>
+
+  <Tab>
+    To add custom menu items to the `<UserButton />` component using the [JavaScript SDK](/docs/references/javascript/overview), pass the `customMenuItems` property to the `mountUserButton()` method, as shown in the following example:
+
+    ```js {{ filename: 'main.js' }}
+    import { Clerk } from '@clerk/clerk-js'
+
+    // Initialize Clerk with your Clerk publishable key
+    const clerk = new Clerk('{{pub_key}}')
+    await clerk.load()
+
+    document.getElementById('app').innerHTML = `
+      <div id="user-button"></div>
+    `
+
+    const userButtonDiv = document.getElementById('user-button')
+
+    clerk.mountUserButton(userButtonDiv, {
+      customMenuItems: [
+        {
+          label: 'Help modal',
+          onClick: () => {
+            alert('Open modal') // your custom event
+          },
+          mountIcon: (el) => {
+            el.innerHTML = '👤'
+          },
+          unmountIcon: (el) => {},
+        },
+      ],
+    })
+    ```
+  </Tab>
 </Tabs>
 
 The following example demonstrates how to add an action, as well as a [custom page](/docs/customization/user-profile), to the `<UserButton />` component.
@@ -259,7 +292,7 @@ The `<UserButton />` component must be wrapped in a `<UserButton.MenuItems />` c
 
 The following example demonstrates how to add a link to the `<UserButton />` component.
 
-<Tabs items={["Next.js", "Astro"]}>
+<Tabs items={["Next.js", "Astro", "JavaScript"]}>
   <Tab>
     ```tsx filename="/app/page.tsx"
     'use client'
@@ -316,6 +349,37 @@ The following example demonstrates how to add a link to the `<UserButton />` com
     </header>
     ```
   </Tab>
+
+  <Tab>
+    To add custom menu items to the `<UserButton />` component using the [JavaScript SDK](/docs/references/javascript/overview), pass the `customMenuItems` property to the `mountUserButton()` method, as shown in the following example:
+
+    ```js {{ filename: 'main.js' }}
+    import { Clerk } from '@clerk/clerk-js'
+
+    // Initialize Clerk with your Clerk publishable key
+    const clerk = new Clerk('{{pub_key}}')
+    await clerk.load()
+
+    document.getElementById('app').innerHTML = `
+      <div id="user-button"></div>
+    `
+
+    const userButtonDiv = document.getElementById('user-button')
+
+    clerk.mountUserButton(userButtonDiv, {
+      customMenuItems: [
+        {
+          label: 'User page',
+          href: '/user',
+          mountIcon: (el) => {
+            el.innerHTML = '👤'
+          },
+          unmountIcon: (el) => {},
+        },
+      ],
+    })
+    ```
+  </Tab>
 </Tabs>
 
 ## Reorder default items