Add tasksUrl as option

Author: LauraBeatris

.changeset/whole-knives-attend.md

@@ -0,0 +1,16 @@
+---
+'@clerk/clerk-js': patch
+'@clerk/types': patch
+---
+
+Add `taskUrls` option to customize task flow URLs:
+
+```tsx
+<ClerkProvider
+  taskUrls={{
+    'org': '/my-custom-org-selector'
+  }}
+/>
+```
+
+**Breaking**: Task key renamed from `'select-organization'` to `'org'`.

packages/clerk-js/src/core/__tests__/clerk.test.ts

@@ -2331,7 +2331,7 @@ describe('Clerk singleton', () => {
     });
   });
 
-  describe('nextTask', () => {
+  describe('navigateToTask', () => {
     describe('with `pending` session status', () => {
       const mockSession = {
         id: '1',
@@ -2360,7 +2360,7 @@ describe('Clerk singleton', () => {
         mockResource.touch.mockReset();
       });
 
-      it('navigates to next task', async () => {
+      it('navigates to next task with default internal routing for AIOs', async () => {
         const sut = new Clerk(productionPublishableKey);
         await sut.load(mockedLoadOptions);
 
@@ -2369,6 +2369,21 @@ describe('Clerk singleton', () => {
 
         expect(mockNavigate.mock.calls[0][0]).toBe('/sign-in#/tasks/add-organization');
       });
+
+      it('navigates to next task with custom routing from clerk options', async () => {
+        const sut = new Clerk(productionPublishableKey);
+        await sut.load({
+          ...mockedLoadOptions,
+          taskUrls: {
+            org: '/onboarding/select-organization',
+          },
+        });
+
+        await sut.setActive({ session: mockResource as any as PendingSessionResource });
+        await sut.__internal_navigateToTaskIfAvailable();
+
+        expect(mockNavigate.mock.calls[0][0]).toBe('/onboarding/select-organization');
+      });
     });
 
     describe('with `active` session status', () => {

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

@@ -30,9 +30,9 @@ import type {
   AuthenticateWithGoogleOneTapParams,
   AuthenticateWithMetamaskParams,
   AuthenticateWithOKXWalletParams,
-  Clerk as ClerkInterface,
   ClerkAPIError,
   ClerkAuthenticateWithWeb3Params,
+  Clerk as ClerkInterface,
   ClerkOptions,
   ClientJSONSnapshot,
   ClientResource,
@@ -1317,7 +1317,7 @@ export class Clerk implements ClerkInterface {
       eventBus.emit(events.TokenUpdate, { token: null });
     }
 
-    // Only triggers navigation for internal AIO components routing
+    // Only triggers navigation for internal AIO components routing or custom URLs
     const shouldNavigateOnSetActive = this.#componentNavigationContext;
     if (newSession?.currentTask && shouldNavigateOnSetActive) {
       await navigateToTask(session.currentTask.key, {

packages/clerk-js/src/core/sessionTasks.ts

@@ -7,7 +7,7 @@ import type {
 
 import { buildURL } from '../utils';
 
-export const SESSION_TASK_ROUTE_BY_KEY: Record<SessionTask['key'], string> = {
+export const INTERNAL_SESSION_TASK_ROUTE_BY_KEY: Record<SessionTask['key'], string> = {
   org: 'add-organization',
 } as const;
 
@@ -24,10 +24,10 @@ interface NavigateToTaskOptions {
  * @internal
  */
 export function navigateToTask(
-  routeKey: keyof typeof SESSION_TASK_ROUTE_BY_KEY,
+  routeKey: keyof typeof INTERNAL_SESSION_TASK_ROUTE_BY_KEY,
   { componentNavigationContext, globalNavigate, options, environment }: NavigateToTaskOptions,
 ) {
-  const taskRoute = `/tasks/${SESSION_TASK_ROUTE_BY_KEY[routeKey]}`;
+  const taskRoute = options.taskUrls?.[routeKey] ?? `/tasks/${INTERNAL_SESSION_TASK_ROUTE_BY_KEY[routeKey]}`;
 
   if (componentNavigationContext) {
     return componentNavigationContext.navigate(componentNavigationContext.indexPath + taskRoute);
@@ -38,7 +38,6 @@ export function navigateToTask(
   const isReferrerSignUpUrl = window.location.href.startsWith(signUpUrl);
 
   const sessionTaskUrl = buildURL(
-    // TODO - Accept custom URL option for custom flows in order to eject out of `signInUrl/signUpUrl`
     {
       base: isReferrerSignUpUrl ? signUpUrl : signInUrl,
       hashPath: taskRoute,

packages/clerk-js/src/ui/common/redirects.ts

@@ -1,6 +1,6 @@
-import type { SessionTask } from '@clerk/types';
+import type { ClerkOptions, SessionTask } from '@clerk/types';
 
-import { SESSION_TASK_ROUTE_BY_KEY } from '../../core/sessionTasks';
+import { INTERNAL_SESSION_TASK_ROUTE_BY_KEY } from '../../core/sessionTasks';
 import { buildURL } from '../../utils/url';
 import type { SignInContextType, SignUpContextType, UserProfileContextType } from './../contexts';
 
@@ -33,9 +33,11 @@ export function buildSessionTaskRedirectUrl({
   path,
   baseUrl,
   task,
+  taskUrls,
 }: Pick<SignInContextType | SignUpContextType, 'routing' | 'path'> & {
   baseUrl: string;
   task?: SessionTask;
+  taskUrls?: ClerkOptions['taskUrls'];
 }) {
   if (!task) {
     return null;
@@ -45,7 +47,7 @@ export function buildSessionTaskRedirectUrl({
     routing,
     baseUrl,
     path,
-    endpoint: `/tasks/${SESSION_TASK_ROUTE_BY_KEY[task.key]}`,
+    endpoint: taskUrls?.[task.key] ?? `/tasks/${INTERNAL_SESSION_TASK_ROUTE_BY_KEY[task.key]}`,
     authQueryString: null,
   });
 }

packages/clerk-js/src/ui/components/SessionTasks/index.tsx

@@ -6,7 +6,7 @@ import { Card } from '@/ui/elements/Card';
 import { withCardStateProvider } from '@/ui/elements/contexts';
 import { LoadingCardContainer } from '@/ui/elements/LoadingCard';
 
-import { SESSION_TASK_ROUTE_BY_KEY } from '../../../core/sessionTasks';
+import { INTERNAL_SESSION_TASK_ROUTE_BY_KEY } from '../../../core/sessionTasks';
 import { SignInContext, SignUpContext } from '../../../ui/contexts';
 import { SessionTasksContext, useSessionTasksContext } from '../../contexts/components/SessionTasks';
 import { Route, Switch, useRouter } from '../../router';
@@ -38,7 +38,7 @@ const SessionTasksStart = () => {
 function SessionTaskRoutes(): JSX.Element {
   return (
     <Switch>
-      <Route path={SESSION_TASK_ROUTE_BY_KEY['org']}>
+      <Route path={INTERNAL_SESSION_TASK_ROUTE_BY_KEY['org']}>
         <ForceOrganizationSelectionTask />
       </Route>
       <Route index>

packages/clerk-js/src/ui/contexts/components/SignIn.ts

@@ -126,6 +126,7 @@ export const useSignInContext = (): SignInContextType => {
     path: ctx.path,
     routing: ctx.routing,
     baseUrl: signInUrl,
+    taskUrls: clerk.__internal_getOption('taskUrls'),
   });
 
   return {

packages/clerk-js/src/ui/contexts/components/SignUp.ts

@@ -121,6 +121,7 @@ export const useSignUpContext = (): SignUpContextType => {
     path: ctx.path,
     routing: ctx.routing,
     baseUrl: signUpUrl,
+    taskUrls: clerk.__internal_getOption('taskUrls'),
   });
 
   return {

packages/types/src/clerk.ts

@@ -48,7 +48,7 @@ import type {
   SignUpFallbackRedirectUrl,
   SignUpForceRedirectUrl,
 } from './redirects';
-import type { PendingSessionOptions, SignedInSessionResource } from './session';
+import type { PendingSessionOptions, SessionTask, SignedInSessionResource } from './session';
 import type { SessionVerificationLevel } from './sessionVerification';
 import type { SignInResource } from './signIn';
 import type { SignUpResource } from './signUp';
@@ -1050,6 +1050,14 @@ export type ClerkOptions = PendingSessionOptions &
      * @internal
      */
     __internal_keyless_dismissPrompt?: (() => Promise<void>) | null;
+
+    /**
+     * Customize the URL paths users are redirected to after sign-in or sign-up when specific
+     * session tasks need to be completed.
+     *
+     * @default undefined - Uses Clerk's default task flow URLs
+     */
+    taskUrls?: Record<SessionTask['key'], string>;
   };
 
 export interface NavigateOptions {

packages/types/src/session.ts

@@ -326,7 +326,14 @@ export interface PublicUserData {
   userId?: string;
 }
 
+/**
+ * Represents a required action that a user must complete
+ * before their session becomes fully active
+ */
 export interface SessionTask {
+  /**
+   * The unique identifier for the type of task that needs to be completed
+   */
   key: 'org';
 }