feat(react): Implement waitlist hook with signal primitives

.changeset/young-areas-divide.md

@@ -0,0 +1,7 @@
+---
+'@clerk/clerk-js': minor
+'@clerk/shared': minor
+'@clerk/react': minor
+---
+
+Introduce `useWaitlist()` hook

integration/presets/envs.ts

@@ -117,9 +117,9 @@ const withLegalConsent = base
   .setEnvVariable('private', 'CLERK_SECRET_KEY', instanceKeys.get('with-legal-consent').sk)
   .setEnvVariable('public', 'CLERK_PUBLISHABLE_KEY', instanceKeys.get('with-legal-consent').pk);
 
-const withWaitlistdMode = withEmailCodes
+const withWaitlistMode = withEmailCodes
   .clone()
-  .setId('withWaitlistdMode')
+  .setId('withWaitlistMode')
   .setEnvVariable('private', 'CLERK_SECRET_KEY', instanceKeys.get('with-waitlist-mode').sk)
   .setEnvVariable('public', 'CLERK_PUBLISHABLE_KEY', instanceKeys.get('with-waitlist-mode').pk);
 
@@ -213,7 +213,7 @@ export const envs = {
   withSignInOrUpEmailLinksFlow,
   withSignInOrUpFlow,
   withSignInOrUpwithRestrictedModeFlow,
-  withWaitlistdMode,
+  withWaitlistMode,
   withWhatsappPhoneCode,
   withProtectService,
 } as const;

integration/templates/custom-flows-react-vite/src/main.tsx

@@ -7,6 +7,7 @@ import { Home } from './routes/Home';
 import { SignIn } from './routes/SignIn';
 import { SignUp } from './routes/SignUp';
 import { Protected } from './routes/Protected';
+import { Waitlist } from './routes/Waitlist';
 
 // Import your Publishable Key
 const PUBLISHABLE_KEY = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY;
@@ -43,6 +44,10 @@ createRoot(document.getElementById('root')!).render(
                 path='/sign-up'
                 element={<SignUp />}
               />
+              <Route
+                path='/waitlist'
+                element={<Waitlist />}
+              />
               <Route
                 path='/protected'
                 element={<Protected />}

integration/templates/custom-flows-react-vite/src/routes/Waitlist.tsx

@@ -0,0 +1,112 @@
+'use client';
+
+import { cn } from '@/lib/utils';
+import { Button } from '@/components/ui/button';
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/components/ui/card';
+import { Input } from '@/components/ui/input';
+import { Label } from '@/components/ui/label';
+import { useWaitlist } from '@clerk/react';
+import { NavLink } from 'react-router';
+
+export function Waitlist({ className, ...props }: React.ComponentProps<'div'>) {
+  const { waitlist, errors, fetchStatus } = useWaitlist();
+
+  const handleSubmit = async (formData: FormData) => {
+    const emailAddress = formData.get('emailAddress') as string | null;
+
+    if (!emailAddress) {
+      return;
+    }
+
+    await waitlist.join({ emailAddress });
+  };
+
+  if (waitlist?.id) {
+    return (
+      <div
+        className={cn('flex flex-col gap-6', className)}
+        {...props}
+      >
+        <Card>
+          <CardHeader className='text-center'>
+            <CardTitle className='text-xl'>Successfully joined!</CardTitle>
+            <CardDescription>You&apos;re on the waitlist</CardDescription>
+          </CardHeader>
+          <CardContent>
+            <div className='grid gap-6'>
+              <div className='text-center text-sm'>
+                Already have an account?{' '}
+                <NavLink
+                  to='/sign-in'
+                  className='underline underline-offset-4'
+                  data-testid='sign-in-link'
+                >
+                  Sign in
+                </NavLink>
+              </div>
+            </div>
+          </CardContent>
+        </Card>
+      </div>
+    );
+  }
+
+  return (
+    <div
+      className={cn('flex flex-col gap-6', className)}
+      {...props}
+    >
+      <Card>
+        <CardHeader className='text-center'>
+          <CardTitle className='text-xl'>Join the Waitlist</CardTitle>
+          <CardDescription>Enter your email address to join the waitlist</CardDescription>
+        </CardHeader>
+        <CardContent>
+          <form action={handleSubmit}>
+            <div className='grid gap-6'>
+              <div className='grid gap-6'>
+                <div className='grid gap-3'>
+                  <Label htmlFor='emailAddress'>Email address</Label>
+                  <Input
+                    id='emailAddress'
+                    type='email'
+                    placeholder='Email address'
+                    required
+                    name='emailAddress'
+                    data-testid='email-input'
+                  />
+                  {errors.fields.emailAddress && (
+                    <p
+                      className='text-sm text-red-600'
+                      data-testid='email-error'
+                    >
+                      {errors.fields.emailAddress.longMessage}
+                    </p>
+                  )}
+                </div>
+                <Button
+                  type='submit'
+                  className='w-full'
+                  disabled={fetchStatus === 'fetching'}
+                  data-testid='submit-button'
+                >
+                  Join Waitlist
+                </Button>
+              </div>
+              <div className='text-center text-sm'>
+                Already have an account?{' '}
+                <NavLink
+                  to='/sign-in'
+                  className='underline underline-offset-4'
+                  data-testid='sign-in-link'
+                >
+                  Sign in
+                </NavLink>
+              </div>
+            </div>
+          </form>
+        </CardContent>
+      </Card>
+    </div>
+  );
+}

integration/testUtils/index.ts

@@ -8,6 +8,7 @@ import { createInvitationService } from './invitationsService';
 import { createOrganizationsService } from './organizationsService';
 import type { FakeAPIKey, FakeOrganization, FakeUser, FakeUserWithEmail } from './usersService';
 import { createUserService } from './usersService';
+import { createWaitlistService } from './waitlistService';
 
 export type { FakeAPIKey, FakeOrganization, FakeUser, FakeUserWithEmail };
 
@@ -40,6 +41,7 @@ export const createTestUtils = <
     users: createUserService(clerkClient),
     invitations: createInvitationService(clerkClient),
     organizations: createOrganizationsService(clerkClient),
+    waitlist: createWaitlistService(clerkClient),
   };
 
   if (!params.page) {

integration/testUtils/waitlistService.ts

@@ -0,0 +1,19 @@
+import type { ClerkClient } from '@clerk/backend';
+
+export type WaitlistService = {
+  clearWaitlistByEmail: (email: string) => Promise<void>;
+};
+
+export const createWaitlistService = (clerkClient: ClerkClient) => {
+  const self: WaitlistService = {
+    clearWaitlistByEmail: async (email: string) => {
+      const { data: entries } = await clerkClient.waitlistEntries.list({ query: email, status: 'pending' });
+
+      if (entries.length > 0) {
+        await clerkClient.waitlistEntries.delete(entries[0].id);
+      }
+    },
+  };
+
+  return self;
+};

integration/tests/custom-flows/waitlist.test.ts

@@ -0,0 +1,100 @@
+import { parsePublishableKey } from '@clerk/shared/keys';
+import { clerkSetup } from '@clerk/testing/playwright';
+import { expect, test } from '@playwright/test';
+
+import type { Application } from '../../models/application';
+import { hash } from '../../models/helpers';
+import { appConfigs } from '../../presets';
+import { createTestUtils } from '../../testUtils';
+
+test.describe('Custom Flows Waitlist @custom', () => {
+  test.describe.configure({ mode: 'parallel' });
+  let app: Application;
+  const fakeEmails: string[] = [];
+
+  test.beforeAll(async () => {
+    app = await appConfigs.customFlows.reactVite.clone().commit();
+    await app.setup();
+    await app.withEnv(appConfigs.envs.withWaitlistMode);
+    await app.dev();
+
+    const publishableKey = appConfigs.envs.withWaitlistMode.publicVariables.get('CLERK_PUBLISHABLE_KEY');
+    const secretKey = appConfigs.envs.withWaitlistMode.privateVariables.get('CLERK_SECRET_KEY');
+    const apiUrl = appConfigs.envs.withWaitlistMode.privateVariables.get('CLERK_API_URL');
+    const { frontendApi: frontendApiUrl } = parsePublishableKey(publishableKey);
+
+    await clerkSetup({
+      publishableKey,
+      frontendApiUrl,
+      secretKey,
+      // @ts-expect-error
+      apiUrl,
+      dotenv: false,
+    });
+  });
+
+  test.afterAll(async () => {
+    const u = createTestUtils({ app });
+    await Promise.all(fakeEmails.map(email => u.services.waitlist.clearWaitlistByEmail(email)));
+    await app.teardown();
+  });
+
+  test('can join waitlist with email', async ({ page, context }) => {
+    const fakeEmail = `${hash()}+clerk_test@clerkcookie.com`;
+    fakeEmails.push(fakeEmail);
+
+    const u = createTestUtils({ app, page, context });
+    await u.page.goToRelative('/waitlist');
+    await u.page.waitForClerkJsLoaded();
+    await expect(u.page.getByText('Join the Waitlist', { exact: true })).toBeVisible();
+
+    const emailInput = u.page.getByTestId('email-input');
+    const submitButton = u.page.getByTestId('submit-button');
+
+    await emailInput.fill(fakeEmail);
+    await submitButton.click();
+
+    await expect(u.page.getByText('Successfully joined!')).toBeVisible();
+    await expect(u.page.getByText("You're on the waitlist")).toBeVisible();
+  });
+
+  test('renders error with invalid email', async ({ page, context }) => {
+    const u = createTestUtils({ app, page, context });
+    await u.page.goToRelative('/waitlist');
+    await u.page.waitForClerkJsLoaded();
+    await expect(u.page.getByText('Join the Waitlist', { exact: true })).toBeVisible();
+
+    const emailInput = u.page.getByTestId('email-input');
+    const submitButton = u.page.getByTestId('submit-button');
+
+    await emailInput.fill('invalid-email@com');
+    await submitButton.click();
+
+    await expect(u.page.getByTestId('email-error')).toBeVisible();
+  });
+
+  test('displays loading state while joining', async ({ page, context }) => {
+    const fakeEmail = `${hash()}+clerk_test@clerkcookie.com`;
+    fakeEmails.push(fakeEmail);
+
+    const u = createTestUtils({ app, page, context });
+    await u.page.goToRelative('/waitlist');
+    await u.page.waitForClerkJsLoaded();
+    await expect(u.page.getByText('Join the Waitlist', { exact: true })).toBeVisible();
+
+    const emailInput = u.page.getByTestId('email-input');
+    const submitButton = u.page.getByTestId('submit-button');
+
+    await emailInput.fill(fakeEmail);
+
+    const submitPromise = submitButton.click();
+
+    // Check that button is disabled during fetch
+    await expect(submitButton).toBeDisabled();
+
+    await submitPromise;
+
+    // Wait for success state
+    await expect(u.page.getByText('Successfully joined!')).toBeVisible();
+  });
+});

integration/tests/waitlist-mode.test.ts

@@ -78,7 +78,7 @@ test.describe('Waitlist mode', () => {
       )
       .commit();
     await app.setup();
-    await app.withEnv(appConfigs.envs.withWaitlistdMode);
+    await app.withEnv(appConfigs.envs.withWaitlistMode);
     await app.dev();
 
     const m = createTestUtils({ app });

packages/clerk-js/src/core/resources/Waitlist.ts

@@ -1,6 +1,9 @@
+import type { ClerkError } from '@clerk/shared/error';
 import type { JoinWaitlistParams, WaitlistJSON, WaitlistResource } from '@clerk/shared/types';
 
 import { unixEpochToDate } from '../../utils/date';
+import { runAsyncResourceTask } from '../../utils/runAsyncResourceTask';
+import { eventBus } from '../events';
 import { BaseResource } from './internal';
 
 export class Waitlist extends BaseResource implements WaitlistResource {
@@ -10,7 +13,7 @@ export class Waitlist extends BaseResource implements WaitlistResource {
   updatedAt: Date | null = null;
   createdAt: Date | null = null;
 
-  constructor(data: WaitlistJSON) {
+  constructor(data: WaitlistJSON | null = null) {
     super();
     this.fromJSON(data);
   }
@@ -23,18 +26,24 @@ export class Waitlist extends BaseResource implements WaitlistResource {
     this.id = data.id;
     this.updatedAt = unixEpochToDate(data.updated_at);
     this.createdAt = unixEpochToDate(data.created_at);
+
+    eventBus.emit('resource:update', { resource: this });
     return this;
   }
 
+  async join(params: JoinWaitlistParams): Promise<{ error: ClerkError | null }> {
+    return runAsyncResourceTask(this, async () => {
+      await Waitlist.join(params);
+    });
+  }
+
   static async join(params: JoinWaitlistParams): Promise<WaitlistResource> {
-    const json = (
-      await BaseResource._fetch<WaitlistJSON>({
-        path: '/waitlist',
-        method: 'POST',
-        body: params as any,
-      })
-    )?.response as unknown as WaitlistJSON;
-
-    return new Waitlist(json);
+    const json = await BaseResource._fetch<WaitlistJSON>({
+      path: '/waitlist',
+      method: 'POST',
+      body: params as any,
+    });
+
+    return new Waitlist(json as unknown as WaitlistJSON);
   }
 }