feat(clerk-js,clerk-react,types): Navigate to next task

[LauraBeatris]

Description

Resolves ORGS-581

Handles navigation to next tasks on an after-auth flow. Once all tasks get completed, it navigates to the redirectUrlComplete option, which defaults to after sign-in/sign-up URL based on the Clerk.client state.

Developer flows

For AIO components, there's no signature changes and it'll work out of the box

For custom flows, Clerk.nextTask should be called after performing a FAPI mutation that resolves a task. Here's an example for the upcoming force MFA task:

await fapiClient.configureTotp(...) 
await Clerk.__experimental_nextTask()

Building your on custom React "onboarding" components:

function MyFirstOnboardingPage(){ 
  const clerk = useClerk()

  const handleOrganizationSelection = async (organization: string) => {
   // Select the organization into the current session 
    await setActive({ organization })

   // Proceed with verifying if there's a next task, either navigating to it 
   // or to `redirectUrlComplete` once session transitions to active
    await clerk.__experimental_nextTask()
  }

  return <MyCustomOrganizationList onOrgSelection={handleOrgSelection} />
}

function MySecondOnboardingPage(){ 
  const clerk = useClerk()
  return <ConfigureMFA onSuccess={clerk.__experimental_nextTask} />
}

---

CleanShot.2025-03-17.at.19.07.02-converted.mp4

Checklist

• pnpm test runs as expected.
• pnpm build runs as expected.
• (If applicable) JSDoc comments have been added or updated for any package exports
• (If applicable) Documentation has been updated

Type of change

• 🐛 Bug fix
• 🌟 New feature
• 🔨 Breaking change
• 📖 Refactoring / dependency upgrade / documentation
• other:

[changeset-bot]

🦋 Changeset detected

Latest commit: f8b7a53

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 21 packages

Name	Type
@clerk/clerk-js	Patch
@clerk/clerk-react	Patch
@clerk/types	Patch
@clerk/chrome-extension	Patch
@clerk/clerk-expo	Patch
@clerk/elements	Patch
@clerk/nextjs	Patch
@clerk/react-router	Patch
@clerk/remix	Patch
@clerk/agent-toolkit	Patch
@clerk/astro	Patch
@clerk/backend	Patch
@clerk/expo-passkeys	Patch
@clerk/express	Patch
@clerk/fastify	Patch
@clerk/localizations	Patch
@clerk/nuxt	Patch
@clerk/shared	Patch
@clerk/testing	Patch
@clerk/themes	Patch
@clerk/vue	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
clerk-js-sandbox	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Mar 21, 2025 9:59am

[izaaklauer]

For posterity: I'm always just a little nervous of including random routable URLs in tests.

Truly unlikely security threat potential: If we actually GET this URL, and someone knows we're getting it, they could register the domain and have it serve some exploit that gets us to leak our CI secrets.

I'm not even proposing you change this - it's the pattern laid down elsewhere in the test - but when in doubt, I like example.com or cnames of it. It's not routable. https://foocorp.example.com/add-organization is safer in my book.

[LauraBeatris]

Makes sense! Also just to note that our tests only run if the triggering actor (owner of the PR) has the GitHub org permissions to access secrets, otherwise it'll fail

For URLs like those that are used to trigger navigation rather than HTTP requests, then I think it's fine!

[izaaklauer]

❓ Not afterSignInUrl ?

[LauraBeatris]

This is within the isCombinedFlow routes, so those are the sign-up routes rendered within SignIn component therefore it uses signUpContext

[izaaklauer]

A relatively superficial review, but it looks correct and reasonable to me. Left a few comments. 👍