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/templates/next-app-router/next.config.js

@@ -1,9 +1,19 @@
+const path = require('path');
+
 /** @type {import('next').NextConfig} */
 const nextConfig = {
   eslint: {
     ignoreDuringBuilds: true,
   },
-  outputFileTracingRoot: '/',
+  outputFileTracingRoot: path.resolve(__dirname, '../../../'),
+  webpack: config => {
+    // Exclude macOS .Trash directory and other system directories to prevent permission errors
+    config.watchOptions = {
+      ...config.watchOptions,
+      ignored: ['**/.Trash/**', '**/node_modules/**', '**/.git/**'],
+    };
+    return config;
+  },
 };
 
 module.exports = nextConfig;

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,36 @@ 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 { useLoadingStatus, useSignInRedirect } 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 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 +80,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],
@@ -514,7 +508,12 @@ function SignInStartInternal(): JSX.Element {
     return components[identifierField.type as keyof typeof components];
   }, [identifierField.type]);
 
-  if (status.isLoading || clerkStatus === 'sign_up') {
+  const { isRedirecting } = useSignInRedirect({
+    afterSignInUrl,
+    organizationTicket,
+  });
+
+  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 +697,4 @@ const InstantPasswordRow = ({ field }: { field?: FormControlState<'password'> })
   );
 };
 
-export const SignInStart = withRedirectToSignInTask(
-  withRedirectToAfterSignIn(withCardStateProvider(SignInStartInternal)),
-);
+export const SignInStart = withCardStateProvider(SignInStartInternal);

packages/clerk-js/src/ui/components/UserButton/useMultisessionActions.tsx

@@ -5,6 +5,7 @@ import { navigateIfTaskExists } from '@/core/sessionTasks';
 import { useEnvironment } from '@/ui/contexts';
 import { useCardState } from '@/ui/elements/contexts';
 import { sleep } from '@/ui/utils/sleep';
+import { buildURL } from '@/utils/url';
 
 import { windowNavigate } from '../../../utils/windowNavigate';
 import { useMultipleSessions } from '../../hooks/useMultipleSessions';
@@ -25,7 +26,7 @@ export const useMultisessionActions = (opts: UseMultisessionActionsParams) => {
   const { setActive, signOut, openUserProfile } = useClerk();
   const card = useCardState();
   const { signedInSessions, otherSessions } = useMultipleSessions({ user: opts.user });
-  const { navigate } = useRouter();
+  const { navigate, queryParams } = useRouter();
   const { displayConfig } = useEnvironment();
 
   const handleSignOutSessionClicked = (session: SignedInSessionResource) => () => {
@@ -99,7 +100,15 @@ export const useMultisessionActions = (opts: UseMultisessionActionsParams) => {
   };
 
   const handleAddAccountClicked = () => {
-    windowNavigate(opts.signInUrl || window.location.href);
+    const baseUrl = opts.signInUrl || (typeof window !== 'undefined' ? window.location.href : '');
+    const url = buildURL(
+      {
+        base: baseUrl,
+        searchParams: new URLSearchParams({ ...queryParams, __clerk_add_account: 'true' }),
+      },
+      { stringify: true },
+    );
+    windowNavigate(url);
     return sleep(2000);
   };