chore(clerk-js,types): Add taskUrls as option

.changeset/whole-knives-attend.md

@@ -0,0 +1,14 @@
+---
+'@clerk/clerk-js': patch
+'@clerk/types': patch
+---
+
+Add `taskUrls` option to customize task flow URLs:
+
+```tsx
+<ClerkProvider
+ taskUrls={{
+ 'org': '/my-custom-org-selector'
+ }}
+/>
+```

.typedoc/__tests__/__snapshots__/file-structure.test.ts.snap

@@ -106,6 +106,7 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
  "types/server-get-token.mdx",
  "types/session-resource.mdx",
  "types/session-status-claim.mdx",
+ "types/session-task.mdx",
  "types/session-verification-level.mdx",
  "types/session-verification-types.mdx",
  "types/set-active-params.mdx",

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',
@@ -2350,7 +2350,7 @@ describe('Clerk singleton', () => {
  reload: jest.fn(() => Promise.resolve(mockSession)),
  };
 
-beforeAll(() => {
+beforeEach(() => {
  mockResource.touch.mockReturnValueOnce(Promise.resolve());
  mockClientFetch.mockReturnValue(Promise.resolve({ signedInSessions: [mockResource] }));
  });
@@ -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

@@ -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 = `/tasks/${INTERNAL_SESSION_TASK_ROUTE_BY_KEY[routeKey]}`;
 
  if (componentNavigationContext) {
  return componentNavigationContext.navigate(componentNavigationContext.indexPath + taskRoute);
@@ -38,13 +38,12 @@ 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,
  },
  { stringify: true },
  );
 
- return globalNavigate(sessionTaskUrl);
+ return globalNavigate(options.taskUrls?.[routeKey] ?? sessionTaskUrl);
 }

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,21 +33,26 @@ export function buildSessionTaskRedirectUrl({
  path,
  baseUrl,
  task,
+ taskUrls,
 }: Pick<SignInContextType | SignUpContextType, 'routing' | 'path'> & {
  baseUrl: string;
  task?: SessionTask;
+ taskUrls?: ClerkOptions['taskUrls'];
 }) {
  if (!task) {
  return null;
  }
 
- return buildRedirectUrl({
- routing,
- baseUrl,
- path,
- endpoint: `/tasks/${SESSION_TASK_ROUTE_BY_KEY[task.key]}`,
- authQueryString: null,
- });
+ return (
+ taskUrls?.[task.key] ??
+ buildRedirectUrl({
+ routing,
+ baseUrl,
+ path,
+ endpoint: `/tasks/${INTERNAL_SESSION_TASK_ROUTE_BY_KEY[task.key]}`,
+ authQueryString: null,
+ })
+ );
 }
 
 export function buildSSOCallbackURL(

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 @@
  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 @@
  * @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 {
@@ -1114,7 +1122,7 @@
  */
  windowNavigate: (to: URL | string) => void;
  },
 ) => Promise<unknown> | unknown;
 
 export type WithoutRouting<T> = Omit<T, 'path' | 'routing'>;
 

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';
 }
 

.changeset/whole-knives-attend.md

@@ -0,0 +1,14 @@
+---
+'@clerk/clerk-js': patch
+'@clerk/types': patch
+---
+
+Add `taskUrls` option to customize task flow URLs:
+
+```tsx
+<ClerkProvider
+ taskUrls={{
+ 'org': '/my-custom-org-selector'
+ }}
+/>
+```

.typedoc/__tests__/__snapshots__/file-structure.test.ts.snap

@@ -106,6 +106,7 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
  "types/server-get-token.mdx",
  "types/session-resource.mdx",
  "types/session-status-claim.mdx",
+ "types/session-task.mdx",
  "types/session-verification-level.mdx",
  "types/session-verification-types.mdx",
  "types/set-active-params.mdx",

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',
@@ -2350,7 +2350,7 @@ describe('Clerk singleton', () => {
  reload: jest.fn(() => Promise.resolve(mockSession)),
  };
 
-beforeAll(() => {
+beforeEach(() => {
  mockResource.touch.mockReturnValueOnce(Promise.resolve());
  mockClientFetch.mockReturnValue(Promise.resolve({ signedInSessions: [mockResource] }));
  });
@@ -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

@@ -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 = `/tasks/${INTERNAL_SESSION_TASK_ROUTE_BY_KEY[routeKey]}`;
 
  if (componentNavigationContext) {
  return componentNavigationContext.navigate(componentNavigationContext.indexPath + taskRoute);
@@ -38,13 +38,12 @@ 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,
  },
  { stringify: true },
  );
 
- return globalNavigate(sessionTaskUrl);
+ return globalNavigate(options.taskUrls?.[routeKey] ?? sessionTaskUrl);
 }

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,21 +33,26 @@ export function buildSessionTaskRedirectUrl({
  path,
  baseUrl,
  task,
+ taskUrls,
 }: Pick<SignInContextType | SignUpContextType, 'routing' | 'path'> & {
  baseUrl: string;
  task?: SessionTask;
+ taskUrls?: ClerkOptions['taskUrls'];
 }) {
  if (!task) {
  return null;
  }
 
- return buildRedirectUrl({
- routing,
- baseUrl,
- path,
- endpoint: `/tasks/${SESSION_TASK_ROUTE_BY_KEY[task.key]}`,
- authQueryString: null,
- });
+ return (
+ taskUrls?.[task.key] ??
+ buildRedirectUrl({
+ routing,
+ baseUrl,
+ path,
+ endpoint: `/tasks/${INTERNAL_SESSION_TASK_ROUTE_BY_KEY[task.key]}`,
+ authQueryString: null,
+ })
+ );
 }
 
 export function buildSSOCallbackURL(

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 @@
  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 @@
  * @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 {
@@ -1114,7 +1122,7 @@
  */
  windowNavigate: (to: URL | string) => void;
  },
 ) => Promise<unknown> | unknown;
 
 export type WithoutRouting<T> = Omit<T, 'path' | 'routing'>;
 

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';
 }
 

.changeset/whole-knives-attend.md

@@ -0,0 +1,14 @@
+---
+'@clerk/clerk-js': patch
+'@clerk/types': patch
+---
+
+Add `taskUrls` option to customize task flow URLs:
+
+```tsx
+<ClerkProvider
+ taskUrls={{
+ 'org': '/my-custom-org-selector'
+ }}
+/>
+```

.typedoc/__tests__/__snapshots__/file-structure.test.ts.snap

@@ -106,6 +106,7 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
  "types/server-get-token.mdx",
  "types/session-resource.mdx",
  "types/session-status-claim.mdx",
+ "types/session-task.mdx",
  "types/session-verification-level.mdx",
  "types/session-verification-types.mdx",
  "types/set-active-params.mdx",

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',
@@ -2350,7 +2350,7 @@ describe('Clerk singleton', () => {
  reload: jest.fn(() => Promise.resolve(mockSession)),
  };
 
-beforeAll(() => {
+beforeEach(() => {
  mockResource.touch.mockReturnValueOnce(Promise.resolve());
  mockClientFetch.mockReturnValue(Promise.resolve({ signedInSessions: [mockResource] }));
  });
@@ -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

@@ -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 = `/tasks/${INTERNAL_SESSION_TASK_ROUTE_BY_KEY[routeKey]}`;
 
  if (componentNavigationContext) {
  return componentNavigationContext.navigate(componentNavigationContext.indexPath + taskRoute);
@@ -38,13 +38,12 @@ 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,
  },
  { stringify: true },
  );
 
- return globalNavigate(sessionTaskUrl);
+ return globalNavigate(options.taskUrls?.[routeKey] ?? sessionTaskUrl);
 }

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,21 +33,26 @@ export function buildSessionTaskRedirectUrl({
  path,
  baseUrl,
  task,
+ taskUrls,
 }: Pick<SignInContextType | SignUpContextType, 'routing' | 'path'> & {
  baseUrl: string;
  task?: SessionTask;
+ taskUrls?: ClerkOptions['taskUrls'];
 }) {
  if (!task) {
  return null;
  }
 
- return buildRedirectUrl({
- routing,
- baseUrl,
- path,
- endpoint: `/tasks/${SESSION_TASK_ROUTE_BY_KEY[task.key]}`,
- authQueryString: null,
- });
+ return (
+ taskUrls?.[task.key] ??
+ buildRedirectUrl({
+ routing,
+ baseUrl,
+ path,
+ endpoint: `/tasks/${INTERNAL_SESSION_TASK_ROUTE_BY_KEY[task.key]}`,
+ authQueryString: null,
+ })
+ );
 }
 
 export function buildSSOCallbackURL(

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 @@
  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 @@
  * @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 {
@@ -1114,7 +1122,7 @@
  */
  windowNavigate: (to: URL | string) => void;
  },
 ) => Promise<unknown> | unknown;
 
 export type WithoutRouting<T> = Omit<T, 'path' | 'routing'>;
 

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';
 }
 

.changeset/whole-knives-attend.md

@@ -0,0 +1,14 @@
+---
+'@clerk/clerk-js': patch
+'@clerk/types': patch
+---
+
+Add `taskUrls` option to customize task flow URLs:
+
+```tsx
+<ClerkProvider
+ taskUrls={{
+ 'org': '/my-custom-org-selector'
+ }}
+/>
+```

.typedoc/__tests__/__snapshots__/file-structure.test.ts.snap

@@ -106,6 +106,7 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
  "types/server-get-token.mdx",
  "types/session-resource.mdx",
  "types/session-status-claim.mdx",
+ "types/session-task.mdx",
  "types/session-verification-level.mdx",
  "types/session-verification-types.mdx",
  "types/set-active-params.mdx",

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',
@@ -2350,7 +2350,7 @@ describe('Clerk singleton', () => {
  reload: jest.fn(() => Promise.resolve(mockSession)),
  };
 
-beforeAll(() => {
+beforeEach(() => {
  mockResource.touch.mockReturnValueOnce(Promise.resolve());
  mockClientFetch.mockReturnValue(Promise.resolve({ signedInSessions: [mockResource] }));
  });
@@ -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

@@ -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 = `/tasks/${INTERNAL_SESSION_TASK_ROUTE_BY_KEY[routeKey]}`;
 
  if (componentNavigationContext) {
  return componentNavigationContext.navigate(componentNavigationContext.indexPath + taskRoute);
@@ -38,13 +38,12 @@ 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,
  },
  { stringify: true },
  );
 
- return globalNavigate(sessionTaskUrl);
+ return globalNavigate(options.taskUrls?.[routeKey] ?? sessionTaskUrl);
 }

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,21 +33,26 @@ export function buildSessionTaskRedirectUrl({
  path,
  baseUrl,
  task,
+ taskUrls,
 }: Pick<SignInContextType | SignUpContextType, 'routing' | 'path'> & {
  baseUrl: string;
  task?: SessionTask;
+ taskUrls?: ClerkOptions['taskUrls'];
 }) {
  if (!task) {
  return null;
  }
 
- return buildRedirectUrl({
- routing,
- baseUrl,
- path,
- endpoint: `/tasks/${SESSION_TASK_ROUTE_BY_KEY[task.key]}`,
- authQueryString: null,
- });
+ return (
+ taskUrls?.[task.key] ??
+ buildRedirectUrl({
+ routing,
+ baseUrl,
+ path,
+ endpoint: `/tasks/${INTERNAL_SESSION_TASK_ROUTE_BY_KEY[task.key]}`,
+ authQueryString: null,
+ })
+ );
 }
 
 export function buildSSOCallbackURL(

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 @@
  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 @@
  * @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 {
@@ -1114,7 +1122,7 @@
  */
  windowNavigate: (to: URL | string) => void;
  },
 ) => Promise<unknown> | unknown;
 
 export type WithoutRouting<T> = Omit<T, 'path' | 'routing'>;
 

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';
 }
 

.changeset/whole-knives-attend.md

@@ -0,0 +1,14 @@
+---
+'@clerk/clerk-js': patch
+'@clerk/types': patch
+---
+
+Add `taskUrls` option to customize task flow URLs:
+
+```tsx
+<ClerkProvider
+ taskUrls={{
+ 'org': '/my-custom-org-selector'
+ }}
+/>
+```

.typedoc/__tests__/__snapshots__/file-structure.test.ts.snap

@@ -106,6 +106,7 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
  "types/server-get-token.mdx",
  "types/session-resource.mdx",
  "types/session-status-claim.mdx",
+ "types/session-task.mdx",
  "types/session-verification-level.mdx",
  "types/session-verification-types.mdx",
  "types/set-active-params.mdx",

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',
@@ -2350,7 +2350,7 @@ describe('Clerk singleton', () => {
  reload: jest.fn(() => Promise.resolve(mockSession)),
  };
 
-beforeAll(() => {
+beforeEach(() => {
  mockResource.touch.mockReturnValueOnce(Promise.resolve());
  mockClientFetch.mockReturnValue(Promise.resolve({ signedInSessions: [mockResource] }));
  });
@@ -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

@@ -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 = `/tasks/${INTERNAL_SESSION_TASK_ROUTE_BY_KEY[routeKey]}`;
 
  if (componentNavigationContext) {
  return componentNavigationContext.navigate(componentNavigationContext.indexPath + taskRoute);
@@ -38,13 +38,12 @@ 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,
  },
  { stringify: true },
  );
 
- return globalNavigate(sessionTaskUrl);
+ return globalNavigate(options.taskUrls?.[routeKey] ?? sessionTaskUrl);
 }

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,21 +33,26 @@ export function buildSessionTaskRedirectUrl({
  path,
  baseUrl,
  task,
+ taskUrls,
 }: Pick<SignInContextType | SignUpContextType, 'routing' | 'path'> & {
  baseUrl: string;
  task?: SessionTask;
+ taskUrls?: ClerkOptions['taskUrls'];
 }) {
  if (!task) {
  return null;
  }
 
- return buildRedirectUrl({
- routing,
- baseUrl,
- path,
- endpoint: `/tasks/${SESSION_TASK_ROUTE_BY_KEY[task.key]}`,
- authQueryString: null,
- });
+ return (
+ taskUrls?.[task.key] ??
+ buildRedirectUrl({
+ routing,
+ baseUrl,
+ path,
+ endpoint: `/tasks/${INTERNAL_SESSION_TASK_ROUTE_BY_KEY[task.key]}`,
+ authQueryString: null,
+ })
+ );
 }
 
 export function buildSSOCallbackURL(

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 @@
  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 @@
  * @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 {
@@ -1114,7 +1122,7 @@
  */
  windowNavigate: (to: URL | string) => void;
  },
 ) => Promise<unknown> | unknown;
 
 export type WithoutRouting<T> = Omit<T, 'path' | 'routing'>;
 

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';
 }
 

.changeset/whole-knives-attend.md

@@ -0,0 +1,14 @@
+---
+'@clerk/clerk-js': patch
+'@clerk/types': patch
+---
+
+Add `taskUrls` option to customize task flow URLs:
+
+```tsx
+<ClerkProvider
+ taskUrls={{
+ 'org': '/my-custom-org-selector'
+ }}
+/>
+```

.typedoc/__tests__/__snapshots__/file-structure.test.ts.snap

@@ -106,6 +106,7 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
  "types/server-get-token.mdx",
  "types/session-resource.mdx",
  "types/session-status-claim.mdx",
+ "types/session-task.mdx",
  "types/session-verification-level.mdx",
  "types/session-verification-types.mdx",
  "types/set-active-params.mdx",

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',
@@ -2350,7 +2350,7 @@ describe('Clerk singleton', () => {
  reload: jest.fn(() => Promise.resolve(mockSession)),
  };
 
-beforeAll(() => {
+beforeEach(() => {
  mockResource.touch.mockReturnValueOnce(Promise.resolve());
  mockClientFetch.mockReturnValue(Promise.resolve({ signedInSessions: [mockResource] }));
  });
@@ -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

@@ -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 = `/tasks/${INTERNAL_SESSION_TASK_ROUTE_BY_KEY[routeKey]}`;
 
  if (componentNavigationContext) {
  return componentNavigationContext.navigate(componentNavigationContext.indexPath + taskRoute);
@@ -38,13 +38,12 @@ 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,
  },
  { stringify: true },
  );
 
- return globalNavigate(sessionTaskUrl);
+ return globalNavigate(options.taskUrls?.[routeKey] ?? sessionTaskUrl);
 }

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,21 +33,26 @@ export function buildSessionTaskRedirectUrl({
  path,
  baseUrl,
  task,
+ taskUrls,
 }: Pick<SignInContextType | SignUpContextType, 'routing' | 'path'> & {
  baseUrl: string;
  task?: SessionTask;
+ taskUrls?: ClerkOptions['taskUrls'];
 }) {
  if (!task) {
  return null;
  }
 
- return buildRedirectUrl({
- routing,
- baseUrl,
- path,
- endpoint: `/tasks/${SESSION_TASK_ROUTE_BY_KEY[task.key]}`,
- authQueryString: null,
- });
+ return (
+ taskUrls?.[task.key] ??
+ buildRedirectUrl({
+ routing,
+ baseUrl,
+ path,
+ endpoint: `/tasks/${INTERNAL_SESSION_TASK_ROUTE_BY_KEY[task.key]}`,
+ authQueryString: null,
+ })
+ );
 }
 
 export function buildSSOCallbackURL(

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 @@
  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 @@
  * @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 {
@@ -1114,7 +1122,7 @@
  */
  windowNavigate: (to: URL | string) => void;
  },
 ) => Promise<unknown> | unknown;
 
 export type WithoutRouting<T> = Omit<T, 'path' | 'routing'>;
 

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';
 }
 

.changeset/whole-knives-attend.md

@@ -0,0 +1,14 @@
+---
+'@clerk/clerk-js': patch
+'@clerk/types': patch
+---
+
+Add `taskUrls` option to customize task flow URLs:
+
+```tsx
+<ClerkProvider
+ taskUrls={{
+ 'org': '/my-custom-org-selector'
+ }}
+/>
+```

.typedoc/__tests__/__snapshots__/file-structure.test.ts.snap

@@ -106,6 +106,7 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
  "types/server-get-token.mdx",
  "types/session-resource.mdx",
  "types/session-status-claim.mdx",
+ "types/session-task.mdx",
  "types/session-verification-level.mdx",
  "types/session-verification-types.mdx",
  "types/set-active-params.mdx",

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',
@@ -2350,7 +2350,7 @@ describe('Clerk singleton', () => {
  reload: jest.fn(() => Promise.resolve(mockSession)),
  };
 
-beforeAll(() => {
+beforeEach(() => {
  mockResource.touch.mockReturnValueOnce(Promise.resolve());
  mockClientFetch.mockReturnValue(Promise.resolve({ signedInSessions: [mockResource] }));
  });
@@ -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

@@ -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 = `/tasks/${INTERNAL_SESSION_TASK_ROUTE_BY_KEY[routeKey]}`;
 
  if (componentNavigationContext) {
  return componentNavigationContext.navigate(componentNavigationContext.indexPath + taskRoute);
@@ -38,13 +38,12 @@ 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,
  },
  { stringify: true },
  );
 
- return globalNavigate(sessionTaskUrl);
+ return globalNavigate(options.taskUrls?.[routeKey] ?? sessionTaskUrl);
 }

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,21 +33,26 @@ export function buildSessionTaskRedirectUrl({
  path,
  baseUrl,
  task,
+ taskUrls,
 }: Pick<SignInContextType | SignUpContextType, 'routing' | 'path'> & {
  baseUrl: string;
  task?: SessionTask;
+ taskUrls?: ClerkOptions['taskUrls'];
 }) {
  if (!task) {
  return null;
  }
 
- return buildRedirectUrl({
- routing,
- baseUrl,
- path,
- endpoint: `/tasks/${SESSION_TASK_ROUTE_BY_KEY[task.key]}`,
- authQueryString: null,
- });
+ return (
+ taskUrls?.[task.key] ??
+ buildRedirectUrl({
+ routing,
+ baseUrl,
+ path,
+ endpoint: `/tasks/${INTERNAL_SESSION_TASK_ROUTE_BY_KEY[task.key]}`,
+ authQueryString: null,
+ })
+ );
 }
 
 export function buildSSOCallbackURL(

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 @@
  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 @@
  * @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 {
@@ -1114,7 +1122,7 @@
  */
  windowNavigate: (to: URL | string) => void;
  },
 ) => Promise<unknown> | unknown;
 
 export type WithoutRouting<T> = Omit<T, 'path' | 'routing'>;
 

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';
 }
 

.changeset/whole-knives-attend.md

@@ -0,0 +1,14 @@
+---
+'@clerk/clerk-js': patch
+'@clerk/types': patch
+---
+
+Add `taskUrls` option to customize task flow URLs:
+
+```tsx
+<ClerkProvider
+ taskUrls={{
+ 'org': '/my-custom-org-selector'
+ }}
+/>
+```

.typedoc/__tests__/__snapshots__/file-structure.test.ts.snap

@@ -106,6 +106,7 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
  "types/server-get-token.mdx",
  "types/session-resource.mdx",
  "types/session-status-claim.mdx",
+ "types/session-task.mdx",
  "types/session-verification-level.mdx",
  "types/session-verification-types.mdx",
  "types/set-active-params.mdx",

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',
@@ -2350,7 +2350,7 @@ describe('Clerk singleton', () => {
  reload: jest.fn(() => Promise.resolve(mockSession)),
  };
 
-beforeAll(() => {
+beforeEach(() => {
  mockResource.touch.mockReturnValueOnce(Promise.resolve());
  mockClientFetch.mockReturnValue(Promise.resolve({ signedInSessions: [mockResource] }));
  });
@@ -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

@@ -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 = `/tasks/${INTERNAL_SESSION_TASK_ROUTE_BY_KEY[routeKey]}`;
 
  if (componentNavigationContext) {
  return componentNavigationContext.navigate(componentNavigationContext.indexPath + taskRoute);
@@ -38,13 +38,12 @@ 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,
  },
  { stringify: true },
  );
 
- return globalNavigate(sessionTaskUrl);
+ return globalNavigate(options.taskUrls?.[routeKey] ?? sessionTaskUrl);
 }

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,21 +33,26 @@ export function buildSessionTaskRedirectUrl({
  path,
  baseUrl,
  task,
+ taskUrls,
 }: Pick<SignInContextType | SignUpContextType, 'routing' | 'path'> & {
  baseUrl: string;
  task?: SessionTask;
+ taskUrls?: ClerkOptions['taskUrls'];
 }) {
  if (!task) {
  return null;
  }
 
- return buildRedirectUrl({
- routing,
- baseUrl,
- path,
- endpoint: `/tasks/${SESSION_TASK_ROUTE_BY_KEY[task.key]}`,
- authQueryString: null,
- });
+ return (
+ taskUrls?.[task.key] ??
+ buildRedirectUrl({
+ routing,
+ baseUrl,
+ path,
+ endpoint: `/tasks/${INTERNAL_SESSION_TASK_ROUTE_BY_KEY[task.key]}`,
+ authQueryString: null,
+ })
+ );
 }
 
 export function buildSSOCallbackURL(

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 @@
  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 @@
  * @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 {
@@ -1114,7 +1122,7 @@
  */
  windowNavigate: (to: URL | string) => void;
  },
 ) => Promise<unknown> | unknown;
 
 export type WithoutRouting<T> = Omit<T, 'path' | 'routing'>;
 

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';
 }