Rename RedirectToTask control component to RedirectToTasks

LauraBeatris · LauraBeatris · commit eae9575af6e2 · 2025-08-12T10:04:39.000-03:00
diff --git a/.changeset/warm-rocks-flow.md b/.changeset/warm-rocks-flow.md
@@ -1,12 +1,11 @@
 ---
 '@clerk/tanstack-react-start': minor
 '@clerk/react-router': minor
-'@clerk/clerk-js': minor
 '@clerk/nextjs': minor
 '@clerk/clerk-react': minor
 '@clerk/remix': minor
 '@clerk/types': minor
 '@clerk/vue': minor
 ---
 
-Remove `RedirectToTask` control component
+Rename `RedirectToTask` control component to `RedirectToTasks`
diff --git a/packages/clerk-js/src/core/clerk.ts b/packages/clerk-js/src/core/clerk.ts
@@ -151,7 +151,11 @@ import {
   Organization,
   Waitlist,
 } from './resources/internal';
-import { navigateIfTaskExists, warnMissingPendingTaskHandlers } from './sessionTasks';
+import {
+  INTERNAL_SESSION_TASK_ROUTE_BY_KEY,
+  navigateIfTaskExists,
+  warnMissingPendingTaskHandlers,
+} from './sessionTasks';
 import { State } from './state';
 import { warnings } from './warnings';
 
@@ -1560,6 +1564,28 @@ export class Clerk implements ClerkInterface {
     return this.buildUrlWithAuth(this.environment.displayConfig.organizationProfileUrl);
   }
 
+  public buildTasksUrl(): string {
+    const currentTask = this.session?.currentTask;
+    if (!currentTask) {
+      return '';
+    }
+
+    const customTaskUrl = this.#options.taskUrls?.[currentTask.key];
+    if (customTaskUrl) {
+      return customTaskUrl;
+    }
+
+    return buildURL(
+      {
+        base: this.buildSignInUrl(),
+        hashPath: `/tasks/${INTERNAL_SESSION_TASK_ROUTE_BY_KEY[currentTask.key]}`,
+      },
+      {
+        stringify: true,
+      },
+    );
+  }
+
   #redirectToSatellite = async (): Promise<unknown> => {
     if (!inBrowser()) {
       return;
@@ -1650,6 +1676,13 @@ export class Clerk implements ClerkInterface {
     return;
   };
 
+  public redirectToTasks = async (): Promise<unknown> => {
+    if (inBrowser()) {
+      return this.navigate(this.buildTasksUrl());
+    }
+    return;
+  };
+
   public handleEmailLinkVerification = async (
     params: HandleEmailLinkVerificationParams,
     customNavigate?: (to: string) => Promise<unknown>,
diff --git a/packages/clerk-js/src/core/sessionTasks.ts b/packages/clerk-js/src/core/sessionTasks.ts
@@ -13,7 +13,7 @@ export const INTERNAL_SESSION_TASK_ROUTE_BY_KEY: Record<SessionTask['key'], stri
 /**
  * @internal
  */
-export function buildTaskURL(task: SessionTask, opts: Pick<Parameters<typeof buildURL>[0], 'base'>) {
+export function buildTasksUrl(task: SessionTask, opts: Pick<Parameters<typeof buildURL>[0], 'base'>) {
   return buildURL(
     {
       base: opts.base,
@@ -41,7 +41,7 @@ export function navigateIfTaskExists(
     return;
   }
 
-  return navigate(buildTaskURL(currentTask, { base: baseUrl }));
+  return navigate(buildTasksUrl(currentTask, { base: baseUrl }));
 }
 
 export function warnMissingPendingTaskHandlers(options: Record<string, unknown>) {
diff --git a/packages/clerk-js/src/ui/components/SignIn/shared.ts b/packages/clerk-js/src/ui/components/SignIn/shared.ts
@@ -2,7 +2,6 @@ import { isClerkRuntimeError, isUserLockedError } from '@clerk/shared/error';
 import { useClerk } from '@clerk/shared/react';
 import { useCallback, useEffect } from 'react';
 
-import { navigateIfTaskExists } from '@/core/sessionTasks';
 import { useCardState } from '@/ui/elements/contexts';
 import { useRouter } from '@/ui/router';
 import { handleError } from '@/ui/utils/errorHandler';
@@ -17,7 +16,7 @@ function useHandleAuthenticateWithPasskey(onSecondFactor: () => Promise<unknown>
   // @ts-expect-error -- private method for the time being
   const { setActive, __internal_navigateWithError } = useClerk();
   const supportEmail = useSupportEmail();
-  const { afterSignInUrl, signInUrl } = useSignInContext();
+  const { afterSignInUrl, signInUrl, navigateOnSetActive } = useSignInContext();
   const { authenticateWithPasskey } = useCoreSignIn();
   const { navigate } = useRouter();
 
@@ -35,15 +34,7 @@ function useHandleAuthenticateWithPasskey(onSecondFactor: () => Promise<unknown>
           return setActive({
             session: res.createdSessionId,
             navigate: async ({ session }) => {
-              if (!session.currentTask) {
-                await navigate(afterSignInUrl);
-                return;
-              }
-
-              await navigateIfTaskExists(session, {
-                baseUrl: signInUrl,
-                navigate: navigate,
-              });
+              await navigateOnSetActive({ session, redirectUrl: afterSignInUrl });
             },
           });
         case 'needs_second_factor':
diff --git a/packages/clerk-js/src/ui/contexts/components/SignIn.ts b/packages/clerk-js/src/ui/contexts/components/SignIn.ts
@@ -3,7 +3,7 @@ import { isAbsoluteUrl } from '@clerk/shared/url';
 import type { SessionResource } from '@clerk/types';
 import { createContext, useContext, useMemo } from 'react';
 
-import { buildTaskURL, INTERNAL_SESSION_TASK_ROUTE_BY_KEY } from '@/core/sessionTasks';
+import { buildTasksUrl, INTERNAL_SESSION_TASK_ROUTE_BY_KEY } from '@/core/sessionTasks';
 
 import { SIGN_IN_INITIAL_VALUE_KEYS } from '../../../core/constants';
 import { buildURL } from '../../../utils';
@@ -37,7 +37,7 @@ export const SignInContext = createContext<SignInCtx | null>(null);
 
 export const useSignInContext = (): SignInContextType => {
   const context = useContext(SignInContext);
-  const { navigate } = useRouter();
+  const { navigate, indexPath } = useRouter();
   const { displayConfig, userSettings } = useEnvironment();
   const { queryParams, queryString } = useRouter();
   const signUpMode = userSettings.signUp.mode;
@@ -126,12 +126,12 @@ export const useSignInContext = (): SignInContextType => {
       return navigate(redirectUrl);
     }
 
-    return navigate(`../tasks/${INTERNAL_SESSION_TASK_ROUTE_BY_KEY[currentTask.key]}`);
+    return navigate(indexPath + `/tasks/${INTERNAL_SESSION_TASK_ROUTE_BY_KEY[currentTask.key]}`);
   };
 
   const taskUrl = clerk.session?.currentTask
     ? (clerk.__internal_getOption('taskUrls')?.[clerk.session?.currentTask.key] ??
-      buildTaskURL(clerk.session?.currentTask, { base: signInUrl }))
+      buildTasksUrl(clerk.session?.currentTask, { base: signInUrl }))
     : null;
 
   return {
diff --git a/packages/clerk-js/src/ui/contexts/components/SignUp.ts b/packages/clerk-js/src/ui/contexts/components/SignUp.ts
@@ -3,7 +3,7 @@ import { isAbsoluteUrl } from '@clerk/shared/url';
 import type { SessionResource } from '@clerk/types';
 import { createContext, useContext, useMemo } from 'react';
 
-import { buildTaskURL, INTERNAL_SESSION_TASK_ROUTE_BY_KEY } from '@/core/sessionTasks';
+import { buildTasksUrl, INTERNAL_SESSION_TASK_ROUTE_BY_KEY } from '@/core/sessionTasks';
 
 import { SIGN_UP_INITIAL_VALUE_KEYS } from '../../../core/constants';
 import { buildURL } from '../../../utils';
@@ -36,7 +36,7 @@ export const SignUpContext = createContext<SignUpCtx | null>(null);
 
 export const useSignUpContext = (): SignUpContextType => {
   const context = useContext(SignUpContext);
-  const { navigate } = useRouter();
+  const { navigate, indexPath } = useRouter();
   const { displayConfig, userSettings } = useEnvironment();
   const { queryParams, queryString } = useRouter();
   const signUpMode = userSettings.signUp.mode;
@@ -121,12 +121,12 @@ export const useSignUpContext = (): SignUpContextType => {
       return navigate(redirectUrl);
     }
 
-    return navigate(`../tasks/${INTERNAL_SESSION_TASK_ROUTE_BY_KEY[currentTask.key]}`);
+    return navigate(indexPath + `/tasks/${INTERNAL_SESSION_TASK_ROUTE_BY_KEY[currentTask.key]}`);
   };
 
   const taskUrl = clerk.session?.currentTask
     ? (clerk.__internal_getOption('taskUrls')?.[clerk.session?.currentTask.key] ??
-      buildTaskURL(clerk.session?.currentTask, { base: signUpUrl }))
+      buildTasksUrl(clerk.session?.currentTask, { base: signUpUrl }))
     : null;
 
   return {
diff --git a/packages/nextjs/src/client-boundary/controlComponents.ts b/packages/nextjs/src/client-boundary/controlComponents.ts
@@ -11,6 +11,7 @@ export {
   RedirectToOrganizationProfile,
   RedirectToSignIn,
   RedirectToSignUp,
+  RedirectToTasks,
   RedirectToUserProfile,
   SignedIn,
   SignedOut,
diff --git a/packages/react-router/src/__tests__/__snapshots__/exports.test.ts.snap b/packages/react-router/src/__tests__/__snapshots__/exports.test.ts.snap
@@ -20,6 +20,7 @@ exports[`root public exports > should not change unexpectedly 1`] = `
   "RedirectToOrganizationProfile",
   "RedirectToSignIn",
   "RedirectToSignUp",
+  "RedirectToTasks",
   "RedirectToUserProfile",
   "SignIn",
   "SignInButton",
diff --git a/packages/react/src/components/controlComponents.tsx b/packages/react/src/components/controlComponents.tsx
@@ -166,6 +166,26 @@ export const RedirectToSignUp = withClerk(({ clerk, ...props }: WithClerkProp<Re
   return null;
 }, 'RedirectToSignUp');
 
+export const RedirectToTasks = withClerk(({ clerk }: WithClerkProp) => {
+  const { session } = clerk;
+
+  React.useEffect(() => {
+    if (!session) {
+      void clerk.redirectToSignIn();
+      return;
+    }
+
+    if (!session.currentTask) {
+      void clerk.redirectToAfterSignIn();
+      return;
+    }
+
+    void clerk.redirectToTasks();
+  }, []);
+
+  return null;
+}, 'RedirectToTasks');
+
 /**
  * @function
  * @deprecated Use [`redirectToUserProfile()`](https://clerk.com/docs/references/javascript/clerk#redirect-to-user-profile) instead.
diff --git a/packages/react/src/components/index.ts b/packages/react/src/components/index.ts
@@ -25,6 +25,7 @@ export {
   RedirectToOrganizationProfile,
   RedirectToSignIn,
   RedirectToSignUp,
+  RedirectToTasks,
   RedirectToUserProfile,
   SignedIn,
   SignedOut,
diff --git a/packages/react/src/isomorphicClerk.ts b/packages/react/src/isomorphicClerk.ts
@@ -388,6 +388,15 @@ export class IsomorphicClerk implements IsomorphicLoadedClerk {
     }
   };
 
+  buildTasksUrl = (): string | void => {
+    const callback = () => this.clerkjs?.buildTasksUrl() || '';
+    if (this.clerkjs && this.loaded) {
+      return callback();
+    } else {
+      this.premountMethodCalls.set('buildTasksUrl', callback);
+    }
+  };
+
   buildUrlWithAuth = (to: string): string | void => {
     const callback = () => this.clerkjs?.buildUrlWithAuth(to) || '';
     if (this.clerkjs && this.loaded) {
@@ -1267,6 +1276,16 @@ export class IsomorphicClerk implements IsomorphicLoadedClerk {
     }
   };
 
+  redirectToTasks = async () => {
+    const callback = () => this.clerkjs?.redirectToTasks();
+    if (this.clerkjs && this.loaded) {
+      return callback();
+    } else {
+      this.premountMethodCalls.set('redirectToTasks', callback);
+      return;
+    }
+  };
+
   handleRedirectCallback = async (params: HandleOAuthCallbackParams): Promise<void> => {
     const callback = () => this.clerkjs?.handleRedirectCallback(params);
     if (this.clerkjs && this.loaded) {
diff --git a/packages/remix/src/__tests__/__snapshots__/exports.test.ts.snap b/packages/remix/src/__tests__/__snapshots__/exports.test.ts.snap
@@ -21,6 +21,7 @@ exports[`root public exports > should not change unexpectedly 1`] = `
   "RedirectToOrganizationProfile",
   "RedirectToSignIn",
   "RedirectToSignUp",
+  "RedirectToTasks",
   "RedirectToUserProfile",
   "SignIn",
   "SignInButton",
diff --git a/packages/tanstack-react-start/src/__tests__/__snapshots__/exports.test.ts.snap b/packages/tanstack-react-start/src/__tests__/__snapshots__/exports.test.ts.snap
@@ -32,6 +32,7 @@ exports[`root public exports > should not change unexpectedly 1`] = `
   "RedirectToOrganizationProfile",
   "RedirectToSignIn",
   "RedirectToSignUp",
+  "RedirectToTasks",
   "RedirectToUserProfile",
   "SignIn",
   "SignInButton",
diff --git a/packages/types/src/clerk.ts b/packages/types/src/clerk.ts
@@ -675,6 +675,11 @@ export interface Clerk {
    */
   buildOrganizationProfileUrl(): string;
 
+  /**
+   * Returns the configured url where tasks are mounted.
+   */
+  buildTasksUrl(): string;
+
   /**
    * Returns the configured afterSignInUrl of the instance.
    */
@@ -762,6 +767,11 @@ export interface Clerk {
    */
   redirectToWaitlist: () => void;
 
+  /**
+   * Redirects to the configured URL where tasks are mounted.
+   */
+  redirectToTasks(): Promise<unknown>;
+
   /**
    * Completes a Google One Tap redirection flow started by
    * {@link Clerk.authenticateWithGoogleOneTap}
diff --git a/packages/vue/src/components/controlComponents.ts b/packages/vue/src/components/controlComponents.ts
@@ -60,6 +60,26 @@ export const RedirectToSignUp = defineComponent((props: RedirectOptions) => {
   return () => null;
 });
 
+export const RedirectToTasks = defineComponent((props: RedirectOptions) => {
+  const { sessionCtx } = useClerkContext();
+
+  useClerkLoaded(clerk => {
+    if (!sessionCtx.value) {
+      void clerk.redirectToSignIn(props);
+      return;
+    }
+
+    if (!sessionCtx.value?.currentTask) {
+      void clerk.redirectToAfterSignIn();
+      return;
+    }
+
+    void clerk.redirectToTasks();
+  });
+
+  return () => null;
+});
+
 /**
  * @deprecated Use [`redirectToUserProfile()`](https://clerk.com/docs/references/javascript/clerk/redirect-methods#redirect-to-user-profile) instead.
  */

Original file line number	Diff line number	Diff line change
`@@ -13,7 +13,7 @@ export const INTERNAL_SESSION_TASK_ROUTE_BY_KEY: Record<SessionTask['key'], stri`
`13`	`13`	`/**`
`14`	`14`	`* @internal`
`15`	`15`	`*/`
`16`		`-export function buildTaskURL(task: SessionTask, opts: Pick<Parameters<typeof buildURL>[0], 'base'>) {`
	`16`	`+export function buildTasksUrl(task: SessionTask, opts: Pick<Parameters<typeof buildURL>[0], 'base'>) {`
`17`	`17`	`return buildURL(`
`18`	`18`	`{`
`19`	`19`	`base: opts.base,`
`@@ -41,7 +41,7 @@ export function navigateIfTaskExists(`
`41`	`41`	`return;`
`42`	`42`	`}`
`43`	`43`
`44`		`- return navigate(buildTaskURL(currentTask, { base: baseUrl }));`
	`44`	`+ return navigate(buildTasksUrl(currentTask, { base: baseUrl }));`
`45`	`45`	`}`
`46`	`46`
`47`	`47`	`export function warnMissingPendingTaskHandlers(options: Record<string, unknown>) {`