Add Waitlist guide; add setup instructions to waitlist component reference

docs/authentication/configuration/restrictions.mdx

@@ -11,8 +11,7 @@ Clerk supports multiple sign-up modes, giving you flexibility in managing user a
 
 To configure sign-up modes:
 
-1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/restrictions).
-1. In the top navigation, select **Configure**. Then in the sidebar, select **Restrictions**.
+1. In the Clerk Dashboard, navigate to the [**Restrictions**](https://dashboard.clerk.com/last-active?path=user-authentication/restrictions) page.
 1. Under the **Sign-up modes** section, you can enable one of the following options:
    - **[Public](#public)**
    - **[Restricted](#restricted)**
@@ -47,10 +46,18 @@ Additional features available in **Waitlist** mode:
 
 - The [`<SignUp />`](/docs/components/authentication/sign-up) is accessible only to users who have been invited and have a valid invitation link. Users who don't have access will see a message indicating that they need an invitation to sign up.
 
-- The [`<Waitlist />`](/docs/components/waitlist/overview) component provides a form where users can submit their details to join the waitlist. Once approved by admins, users will receive an email with access instructions.
+- The [`<Waitlist />`](/docs/components/waitlist) component provides a form where users can submit their details to join the waitlist. Once approved by admins, users will receive an email with access instructions.
 
 - If you're using the `<Waitlist />` component, you must provide the `waitlistUrl` prop either in the [`<ClerkProvider>`](/docs/components/clerk-provider#properties) or [`<SignIn />`](/docs/components/authentication/sign-in#properties) component to ensure proper functionality.
 
+#### Manage waitlist entries
+
+To manage a user on your waitlist:
+
+1. In the Clerk Dashboard, navigate to the [**Waitlist**](https://dashboard.clerk.com/last-active?path=waitlist) page.
+1. On the right-side of the user's row, select the menu icon (...).
+1. Select **Invite** to invite the user to your application. Select **Deny** to deny the user access to your application.
+
 ## Allowlist
 
 > [!NOTE]

docs/components/authentication/sign-in.mdx

@@ -88,7 +88,7 @@ All props are optional.
   - `waitlistUrl?`
   - `string`
 
-  Full URL or path to the waitlist page. If `undefined`, will redirect to the [Account Portal waitlist page](/docs/customization/account-portal/overview#waitlist).
+  Full URL or path to the waitlist page. Use this property to provide the target of the 'Waitlist' link that's rendered. If `undefined`, will redirect to the [Account Portal waitlist page](/docs/customization/account-portal/overview#waitlist). If you've passed the `waitlistUrl` prop to the [`<ClerkProvider>`](/docs/components/clerk-provider) component, it will infer from that, and you can omit this prop.
 </Properties>
 
 ## Usage with frameworks

docs/components/waitlist/overview.mdx → docs/components/waitlist.mdx

@@ -5,11 +5,20 @@ description: The <Waitlist /> component renders a waitlist form that allows user
 
 ![The \<Waitlist /> component renders a form that allows users to join for early access to your app.](/docs/images/ui-components/waitlist.png){{ style: { maxWidth: '460px' } }}
 
+In **Waitlist** mode, users can register their interest in your app by joining a waitlist. This mode is ideal for apps in early development stages or those wanting to generate interest before launch. [Learn more about additional features available in **Waitlist** mode](/docs/authentication/configuration/restrictions#waitlist).
+
 The `<Waitlist />` component renders a form that allows users to join for early access to your app.
 
 > [!NOTE]
 > If you're using Next.js, the`<Waitlist />` component is available in `@clerk/[email protected]` and above.
 
+## Enable Waitlist mode
+
+Before using the `<Waitlist />` component, you must enable **Waitlist** mode in the Clerk Dashboard:
+
+1. In the Clerk Dashboard, navigate to the [**Restrictions**](https://dashboard.clerk.com/last-active?path=user-authentication/restrictions) page.
+1. Under the **Sign-up modes** section, enable **Waitlist**.
+
 ## Properties
 
 All props are optional.
@@ -37,6 +46,9 @@ All props are optional.
 
 ## Usage with frameworks
 
+> [!WARNING]
+> Before using the `<Waitlist />` component, you must provide the `waitlistUrl` prop either in the [`<ClerkProvider>`](/docs/components/clerk-provider#properties) or [`<SignIn />`](/docs/components/authentication/sign-in#properties) component to ensure proper functionality.
+
 The following example includes a basic implementation of the `<Waitlist />` component. You can use this as a starting point for your own implementation.
 
 <Tabs items={["Next.js", "React"]}>

docs/customization/account-portal/overview.mdx

@@ -70,6 +70,6 @@ Redirect your authenticated users to their organization profile page using the [
 
 ### Waitlist
 
-The waitlist page hosts the prebuilt [`<Waitlist />`](/docs/components/waitlist/overview) component which renders a form that allows users to join for early access to your app.
+The waitlist page hosts the prebuilt [`<Waitlist />`](/docs/components/waitlist) component which renders a form that allows users to join for early access to your app.
 
 ![The Account Portal waitliste page hosts the \<Waitlist /> component](/docs/images/account-portal/waitlist.png)

docs/guides/waitlist.mdx

@@ -0,0 +1,152 @@
+---
+title: Set up a waitlist in your Next.js app
+description: Learn how to add a waitlist to your Next.js application.
+---
+
+In [**Waitlist** mode](/docs/authentication/configuration/restrictions#waitlist), users can register their interest in your app by joining a waitlist. This mode is ideal for apps in early development stages or those wanting to generate interest before launch. This guide shows you how to get Clerk integrated and how to add a waitlist to your Next.js application.
+
+<Steps>
+  ### Install `@clerk/nextjs`
+
+  Clerk's [Next.js SDK](/docs/references/nextjs/overview) gives you access to prebuilt components, React hooks, and helpers to make user authentication easier.
+
+  Run the following command to install the SDK:
+
+  <CodeBlockTabs options={["npm", "yarn", "pnpm"]}>
+    ```bash {{ filename: 'terminal' }}
+    npm install @clerk/nextjs
+    ```
+
+    ```bash {{ filename: 'terminal' }}
+    yarn add @clerk/nextjs
+    ```
+
+    ```bash {{ filename: 'terminal' }}
+    pnpm add @clerk/nextjs
+    ```
+  </CodeBlockTabs>
+
+  ### Set your Clerk API keys
+
+  <If condition={experiment.enabled}>
+    <ExperimentCreateAccountFromDocsQuickstart params={experiment} />
+  </If>
+
+  <If condition={!experiment.enabled}>
+    <SignedIn>
+      Add the following keys to your `.env.local` file. These keys can always be retrieved from the [**API Keys**](https://dashboard.clerk.com/last-active?path=api-keys) page of your Clerk Dashboard.
+    </SignedIn>
+
+    <SignedOut>
+      1. In the Clerk Dashboard, navigate to the [**API Keys**](https://dashboard.clerk.com/last-active?path=api-keys){{ track: 'exp_create_account_nextjs_quickstart' }} page.
+      1. In the **Quick Copy** section, copy your Clerk publishable and secret key.
+      1. Paste your keys into your `.env.local` file.
+
+      The final result should resemble the following:
+    </SignedOut>
+  </If>
+
+  ```env {{ filename: '.env.local' }}
+  NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY={{pub_key}}
+  CLERK_SECRET_KEY={{secret}}
+  ```
+
+  ### Enable Waitlist mode
+
+  To enable **Waitlist** mode, follow these steps:
+
+  1. In the Clerk Dashboard, navigate to the [**Restrictions**](https://dashboard.clerk.com/last-active?path=user-authentication/restrictions) page.
+  1. Under the **Sign-up modes** section, enable **Waitlist**.
+
+  To manage users on your waitlist:
+
+  1. In the Clerk Dashboard, navigate to the [**Waitlist**](https://dashboard.clerk.com/last-active?path=waitlist) page.
+  1. On the right-side of a user's row, select the menu icon (...).
+  1. Select **Invite** to invite the user to your application. Select **Deny** to deny the user access to your application.
+
+  ### Add the `<Waitlist />` component
+
+  The [`<Waitlist />`](/docs/components/waitlist) component renders a form that allows users to join for early access to your app.
+
+  The following example includes a basic implementation of the `<Waitlist />` component hosted on the `/` route (the home page). You can use this as a starting point for your own implementation.
+
+  ```jsx {{ filename: '/app/page.tsx' }}
+  import { Waitlist } from '@clerk/nextjs'
+
+  export default function Page() {
+    return <Waitlist />
+  }
+  ```
+
+  ### Add `<ClerkProvider>` to your app
+
+  The [`<ClerkProvider>`](/docs/components/clerk-provider) component wraps your app to provide active session and user context to Clerk's hooks and other components. To use the `<Waitlist />` component in your app, you must provide the `waitlistUrl` prop, which points to the URL of your waitlist page.
+
+  ```tsx {{ filename: 'app/layout.tsx', mark: [6] }}
+  import { ClerkProvider } from '@clerk/nextjs'
+  import './globals.css'
+
+  export default function RootLayout({ children }: { children: React.ReactNode }) {
+    return (
+      <ClerkProvider waitlistUrl="/">
+        <html lang="en">
+          <body>{children}</body>
+        </html>
+      </ClerkProvider>
+    )
+  }
+  ```
+
+  ### Add sign-in functionality
+
+  To allow users to sign in once they've been approved from the waitlist, you must:
+
+  - [Add `clerkMiddleware()` to your app.](#add-clerkmiddleware-to-your-app)
+  - [Add a sign-in page.](#add-a-sign-in-page)
+
+  #### Add `clerkMiddleware()` to your app
+
+  [`clerkMiddleware()`](/docs/references/nextjs/clerk-middleware#clerk-middleware) grants you access to user authentication state throughout your app, on any route or page. It also allows you to protect specific routes from unauthenticated users. To add `clerkMiddleware()` to your app, follow these steps:
+
+  1. Create a `middleware.ts` file.
+
+  - If you're using the `/src` directory, create `middleware.ts` in the `/src` directory.
+  - If you're not using the `/src` directory, create `middleware.ts` in the root directory alongside `.env.local`.
+
+  1. In your `middleware.ts` file, export the `clerkMiddleware()` helper:
+
+  ```tsx {{ filename: 'middleware.ts' }}
+  import { clerkMiddleware } from '@clerk/nextjs/server'
+
+  export default clerkMiddleware()
+
+  export const config = {
+    matcher: [
+      // Skip Next.js internals and all static files, unless found in search params
+      '/((?!_next|[^?]*\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)',
+      // Always run for API routes
+      '/(api|trpc)(.*)',
+    ],
+  }
+  ```
+
+  1. By default, `clerkMiddleware()` will not protect any routes. All routes are public and you must opt-in to protection for routes. See the [`clerkMiddleware()` reference](/docs/references/nextjs/clerk-middleware) to learn how to require authentication for specific routes.
+
+  #### Add a sign-in page
+
+  The following example demonstrates how to render the `<SignIn />` component.
+
+  ```tsx {{ filename: 'app/sign-in/[[...sign-in]]/page.tsx' }}
+  import { SignIn } from '@clerk/nextjs'
+
+  export default function Page() {
+    return <SignIn />
+  }
+  ```
+
+  Update your environment variables to point to your custom sign-in page. For more information on building custom sign-in and sign-up pages, see the [dedicated guide](/docs/references/nextjs/custom-signup-signin-pages).
+
+  ```env {{ filename: '.env.local' }}
+  NEXT_PUBLIC_CLERK_SIGN_IN_URL="/sign-in"
+  ```
+</Steps>

docs/manifest.json

@@ -111,6 +111,10 @@
               "title": "Add custom onboarding to your authentication flow",
               "href": "/docs/guides/add-onboarding-flow"
             },
+            {
+              "title": "Set up a waitlist",
+              "href": "/docs/guides/waitlist"
+            },
             {
               "title": "Architecture scenarios",
               "href": "/docs/guides/architecture-scenarios"
@@ -238,7 +242,7 @@
                   {
                     "title": "`<Waitlist />`",
                     "wrap": false,
-                    "href": "/docs/components/waitlist/overview"
+                    "href": "/docs/components/waitlist"
                   }
                 ]
               ]

docs/references/javascript/clerk/clerk.mdx

@@ -527,10 +527,10 @@ The `Clerk` class also contains a number of methods for interacting with prebuil
 
 ### `<Waitlist />`
 
-- [`mountWaitlist()`](/docs/components/waitlist/overview#mount-waitlist)
-- [`unmountWaitlist()`](/docs/components/waitlist/overview#unmount-waitlist)
-- [`openWaitlist()`](/docs/components/waitlist/overview#open-waitlist)
-- [`closeWaitlist()`](/docs/components/waitlist/overview#close-waitlist)
+- [`mountWaitlist()`](/docs/components/waitlist#mount-waitlist)
+- [`unmountWaitlist()`](/docs/components/waitlist#unmount-waitlist)
+- [`openWaitlist()`](/docs/components/waitlist#open-waitlist)
+- [`closeWaitlist()`](/docs/components/waitlist#close-waitlist)
 
 ## Additional methods