feat(clerk-js): Introduce redirect rules

.changeset/plenty-dolls-pick.md

@@ -0,0 +1,5 @@
+---
+'@clerk/clerk-js': minor
+---
+
+Centralize redirect concerns for SignIn

integration/tests/session-tasks-multi-session.test.ts

@@ -61,13 +61,23 @@ testAgainstRunningApps({ withEnv: [appConfigs.envs.withSessionTasks] })(
       // Create second user, to initiate a pending session
       // Don't resolve task and switch to active session afterwards
       await u.po.signIn.goTo();
+      await u.page.waitForURL(/sign-in\/choose/);
+      await u.page.getByText('Add account').click();
+      await u.page.waitForURL(/sign-in$/);
+      await u.po.signIn.waitForMounted();
+      await u.po.signIn.getIdentifierInput().waitFor({ state: 'visible' });
       await u.po.signIn.setIdentifier(user2.email);
       await u.po.signIn.continue();
       await u.po.signIn.setPassword(user2.password);
       await u.po.signIn.continue();
 
       // Sign-in again back with active session
       await u.po.signIn.goTo();
+      await u.page.waitForURL(/sign-in\/choose/);
+      await u.page.getByText('Add account').click();
+      await u.page.waitForURL(/sign-in$/);
+      await u.po.signIn.waitForMounted();
+      await u.po.signIn.getIdentifierInput().waitFor({ state: 'visible' });
       await u.po.signIn.setIdentifier(user1.email);
       await u.po.signIn.continue();
       await u.po.signIn.setPassword(user1.password);

integration/tests/sign-in-single-session-mode.test.ts

@@ -0,0 +1,79 @@
+import type { FakeUser } from '@clerk/testing/playwright';
+import { test } from '@playwright/test';
+
+import type { Application } from '../models/application';
+import { appConfigs } from '../presets';
+import { createTestUtils, testAgainstRunningApps } from '../testUtils';
+
+/**
+ * Tests for single-session mode behavior using the withBilling environment
+ * which is configured for single-session mode in the Clerk Dashboard.
+ */
+testAgainstRunningApps({ withEnv: [appConfigs.envs.withBilling] })(
+  'sign in with active session in single-session mode @generic @nextjs',
+  ({ app }) => {
+    test.describe.configure({ mode: 'serial' });
+
+    let fakeUser: FakeUser;
+
+    test.beforeAll(async () => {
+      const u = createTestUtils({ app });
+      fakeUser = u.services.users.createFakeUser({
+        withPhoneNumber: true,
+        withUsername: true,
+      });
+      await u.services.users.createBapiUser(fakeUser);
+    });
+
+    test.afterAll(async () => {
+      await fakeUser.deleteIfExists();
+    });
+
+    test('redirects to afterSignIn URL when visiting /sign-in with active session in single-session mode', async ({
+      page,
+      context,
+    }) => {
+      const u = createTestUtils({ app, page, context });
+
+      await u.po.signIn.goTo();
+      await u.po.signIn.signInWithEmailAndInstantPassword({ email: fakeUser.email, password: fakeUser.password });
+      await u.po.expect.toBeSignedIn();
+      await u.page.waitForAppUrl('/');
+
+      await u.po.signIn.goTo();
+      await u.page.waitForAppUrl('/');
+      await u.po.expect.toBeSignedIn();
+    });
+
+    test('does NOT show account switcher in single-session mode', async ({ page, context }) => {
+      const u = createTestUtils({ app, page, context });
+
+      await u.po.signIn.goTo();
+      await u.po.signIn.signInWithEmailAndInstantPassword({ email: fakeUser.email, password: fakeUser.password });
+      await u.po.expect.toBeSignedIn();
+
+      await u.page.goToRelative('/sign-in/choose');
+      await u.page.waitForAppUrl('/');
+    });
+
+    test('shows sign-in form when no active session in single-session mode', async ({ page, context }) => {
+      const u = createTestUtils({ app, page, context });
+
+      await u.page.context().clearCookies();
+      await u.po.signIn.goTo();
+      await u.po.signIn.waitForMounted();
+      await u.page.waitForSelector('text=/email address|username|phone/i');
+      await u.page.waitForURL(/sign-in$/);
+    });
+
+    test('can sign in normally when not already authenticated in single-session mode', async ({ page, context }) => {
+      const u = createTestUtils({ app, page, context });
+
+      await u.page.context().clearCookies();
+      await u.po.signIn.goTo();
+      await u.po.signIn.signInWithEmailAndInstantPassword({ email: fakeUser.email, password: fakeUser.password });
+      await u.po.expect.toBeSignedIn();
+      await u.page.waitForAppUrl('/');
+    });
+  },
+);

packages/clerk-js/src/ui/components/SignIn/SignInStart.tsx

@@ -10,43 +10,37 @@ import type {
 } from '@clerk/types';
 import { useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react';
 
+import { ERROR_CODES, SIGN_UP_MODES } from '@/core/constants';
+import { clerkInvalidFAPIResponse } from '@/core/errors';
+import type { SignInStartIdentifier } from '@/ui/common';
+import { buildSSOCallbackURL, getIdentifierControlDisplayValues, groupIdentifiers } from '@/ui/common';
+import { handleCombinedFlowTransfer } from '@/ui/components/SignIn/handleCombinedFlowTransfer';
+import { hasMultipleEnterpriseConnections, useHandleAuthenticateWithPasskey } from '@/ui/components/SignIn/shared';
+import { SignInAlternativePhoneCodePhoneNumberCard } from '@/ui/components/SignIn/SignInAlternativePhoneCodePhoneNumberCard';
+import { SignInSocialButtons } from '@/ui/components/SignIn/SignInSocialButtons';
+import {
+  getPreferredAlternativePhoneChannel,
+  getPreferredAlternativePhoneChannelForCombinedFlow,
+  getSignUpAttributeFromIdentifier,
+} from '@/ui/components/SignIn/utils';
+import { useCoreSignIn, useEnvironment, useSignInContext } from '@/ui/contexts';
+import { Col, descriptors, Flow, localizationKeys } from '@/ui/customizables';
+import { CaptchaElement } from '@/ui/elements/CaptchaElement';
 import { Card } from '@/ui/elements/Card';
 import { useCardState, withCardStateProvider } from '@/ui/elements/contexts';
 import { Form } from '@/ui/elements/Form';
 import { Header } from '@/ui/elements/Header';
 import { LoadingCard } from '@/ui/elements/LoadingCard';
 import { SocialButtonsReversibleContainerWithDivider } from '@/ui/elements/ReversibleContainer';
+import { useAuthRedirect, useLoadingStatus } from '@/ui/hooks';
+import { useSupportEmail } from '@/ui/hooks/useSupportEmail';
+import { useRouter } from '@/ui/router';
 import { handleError } from '@/ui/utils/errorHandler';
 import { isMobileDevice } from '@/ui/utils/isMobileDevice';
+import { signInRedirectRules } from '@/ui/utils/redirectRules';
 import type { FormControlState } from '@/ui/utils/useFormControl';
 import { buildRequest, useFormControl } from '@/ui/utils/useFormControl';
-
-import { ERROR_CODES, SIGN_UP_MODES } from '../../../core/constants';
-import { clerkInvalidFAPIResponse } from '../../../core/errors';
-import { getClerkQueryParam, removeClerkQueryParam } from '../../../utils';
-import type { SignInStartIdentifier } from '../../common';
-import {
-  buildSSOCallbackURL,
-  getIdentifierControlDisplayValues,
-  groupIdentifiers,
-  withRedirectToAfterSignIn,
-  withRedirectToSignInTask,
-} from '../../common';
-import { useCoreSignIn, useEnvironment, useSignInContext } from '../../contexts';
-import { Col, descriptors, Flow, localizationKeys } from '../../customizables';
-import { CaptchaElement } from '../../elements/CaptchaElement';
-import { useLoadingStatus } from '../../hooks';
-import { useSupportEmail } from '../../hooks/useSupportEmail';
-import { useRouter } from '../../router';
-import { handleCombinedFlowTransfer } from './handleCombinedFlowTransfer';
-import { hasMultipleEnterpriseConnections, useHandleAuthenticateWithPasskey } from './shared';
-import { SignInAlternativePhoneCodePhoneNumberCard } from './SignInAlternativePhoneCodePhoneNumberCard';
-import { SignInSocialButtons } from './SignInSocialButtons';
-import {
-  getPreferredAlternativePhoneChannel,
-  getPreferredAlternativePhoneChannelForCombinedFlow,
-  getSignUpAttributeFromIdentifier,
-} from './utils';
+import { getClerkQueryParam, removeClerkQueryParam } from '@/utils';
 
 const useAutoFillPasskey = () => {
   const [isSupported, setIsSupported] = useState(false);
@@ -87,6 +81,7 @@ function SignInStartInternal(): JSX.Element {
   const ctx = useSignInContext();
   const { afterSignInUrl, signUpUrl, waitlistUrl, isCombinedFlow, navigateOnSetActive } = ctx;
   const supportEmail = useSupportEmail();
+
   const identifierAttributes = useMemo<SignInStartIdentifier[]>(
     () => groupIdentifiers(userSettings.enabledFirstFactorIdentifiers),
     [userSettings.enabledFirstFactorIdentifiers],
@@ -109,6 +104,7 @@ function SignInStartInternal(): JSX.Element {
     shouldStartWithPhoneNumberIdentifier ? 'phone_number' : identifierAttributes[0] || '',
   );
   const [hasSwitchedByAutofill, setHasSwitchedByAutofill] = useState(false);
+  const hasInitializedRef = useRef(false);
 
   const organizationTicket = getClerkQueryParam('__clerk_ticket') || '';
   const clerkStatus = getClerkQueryParam('__clerk_status') || '';
@@ -514,7 +510,23 @@ function SignInStartInternal(): JSX.Element {
     return components[identifierField.type as keyof typeof components];
   }, [identifierField.type]);
 
-  if (status.isLoading || clerkStatus === 'sign_up') {
+  // Handle redirect scenarios - must be after all hooks
+  const { isRedirecting } = useAuthRedirect({
+    rules: signInRedirectRules,
+    additionalContext: {
+      afterSignInUrl,
+      hasInitialized: hasInitializedRef.current,
+      organizationTicket,
+      queryParams: new URLSearchParams(window.location.search),
+    },
+  });
+
+  // Mark as initialized after first render
+  useEffect(() => {
+    hasInitializedRef.current = true;
+  }, []);
+
+  if (isRedirecting || status.isLoading || clerkStatus === 'sign_up') {
     // clerkStatus being sign_up will trigger a navigation to the sign up flow, so show a loading card instead of
     // rendering the sign in flow.
     return <LoadingCard />;
@@ -698,6 +710,4 @@ const InstantPasswordRow = ({ field }: { field?: FormControlState<'password'> })
   );
 };
 
-export const SignInStart = withRedirectToSignInTask(
-  withRedirectToAfterSignIn(withCardStateProvider(SignInStartInternal)),
-);
+export const SignInStart = withCardStateProvider(SignInStartInternal);