Skip to content

feat(mosaic): wire up sign-up with step routing - #10881

Draft
austincalvelage wants to merge 45 commits into
austin/shared-sign-up-next-step-orderfrom
austin/mosaic-sign-up-routing
Draft

austincalvelage wants to merge 45 commits into
austin/shared-sign-up-next-step-orderfrom
austin/mosaic-sign-up-routing

Conversation

@austincalvelage

@austincalvelage austincalvelage commented Nov 17, 2026 •

Copy link
Copy Markdown
Member

Description

Hooks the Mosaic sign-up screens up to Clerk. SignUp now takes someone from the first form to a signed-in session: details, email or phone code, then on to the app. It is not exported from the package entry yet.

Stacked on #10883. The PRs under that are #10867 and #10868.

How it works

  • Clerk says where the sign-up is. The route says which screen the user asked for. If the two disagree, the route is swapped for the one Clerk allows.
  • Each screen is its own component, and it mounts when its route is active. sign-up.view.tsx reads as the list of routes.
  • The form lives above the screens, so what you typed, password included, is still there when you come back from the code screen.
  • The code screen sends its code when it opens and none has been sent. That covers a submit, a reload and a redirect the same way.
  • The code screens also live under continue/, like the old sign-up, so Back knows where to go.

When the sign-up finishes

  • Clerk clears the sign-up as soon as the session exists. Without care, the empty form flashes before the app navigates. The code screen now stays up, still busy, until the navigation happens.
  • If the new session has to choose an organization, that step shows inside the same card. The code screen waits until the organizations have loaded, so there is no loading skeleton in between.
  • If the app set its own URL for that task in taskUrls, sign-up goes there.

Not in this PR

Social and OAuth buttons, enterprise SSO, email links, Web3, other phone channels, the Protect check, tickets and invitations, handing off to sign-in, the combined flow, and URL routing (#10780). Where one of these comes up, the user sees Start over. Routing is in-memory only for now.

Changes outside sign-up

  • The organization task can render without its own card, so sign-up can show it in its card. The standalone task is unchanged.
  • The start-over notice moved into blocks/auth, so sign-in can share it.
  • A feature can have a <feature>.routes.ts file.
  • The test fake for sign-up now clears a finished sign-up from the client, as the real API does. That is what exposed the flash above.
  • Swingset's live sandbox sends sign-up, the waitlist and the MFA task to the Mosaic pages. The sign-up stories pick a screen.

Different from the old sign-up, on purpose

  • If fields are still missing after the first form, they are asked for on the continue screen. The old one stays on the first form.
  • The continue screen drops the password field once a password is set.
  • Optional fields are hidden unless showOptionalFields is set. Same default as before, but it is a prop now.
  • The sign-in and waitlist links come from clerk.buildSignInUrl() and clerk.buildWaitlistUrl().
  • A failure while finishing shows in the banner, not on the code field.

Known gaps, not fixed here

  • The continue screen cannot set a password, because SignUpFuture.update does not take one.
  • Someone already signed in is not sent away from sign-up.
  • Required fields can be submitted empty.
  • With email or phone both allowed and both empty, only one field shows an error.
  • A legal consent error from the server marks the checkbox but shows no message.
  • Only the choose-organization task shows in the card. Any other task, or a second task after it, leaves for its own page.

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:

getSignInNextStep and getSignUpNextStep now return SignInNextStep and
SignUpNextStep, so a sign-up caller can switch over its steps exhaustively
without handling sign-in steps it never receives. NextStep stays as their union.
…sing fields

getSignUpNextStep followed navigateToNextStepSignUp's order, which only the
OAuth return and sign-up-if-missing paths use. It now follows
completeSignUpFlow, the order the sign-up forms use.
signUpRoutes keeps legacy's segments. routeFor maps each sign-up step to its
route, and allowedRoute decides whether the current route may stay, as the
sign-in and sign-up flow guide describes.
…ngSignup

It now takes the fields it reads instead of the legacy SignUpResource, so
Mosaic can pass the SignUpFuture resource.
useSignUpModel reads the sign-up through the shared signal hook and the
environment, and exposes the next step, the start and continue fields from
legacy's rules, and callbacks that return the next step.
SignInStartOver becomes AuthStartOver, which takes its copy as messages like
the other shared auth screens, so sign-up can show it too.
The view renders AuthStartOver for a sign-up step it cannot continue, with a
Swingset story beside the other flow notices.
FAPI names the sign-up field email_address, so save routes its errors to the
field without a mapping. Sign-in keeps identifier for its first screen; its
Swingset story copies the email into emailAddress when the combined flow
moves to the sign-up details.
It picks the screen from the route and the sign-up step, builds the view's
step, submits the start and continue forms and verification codes, and moves
on with the step each call returns. Sending codes comes next.
A small machine sends the code when the flow moves to a verify screen and the
step says none is out yet, and locks resend for 30 seconds.
SignUp composes the sign-up model, controller and view with virtual routing.
It is exported from the sign-up feature only, not from the package entry.
… on Continue

finalize ran as a second action inside the code action's lock, so it was
dropped and the session never became active. next now awaits finalize itself.
Continue on a code screen verified nothing and resubmitted the details form;
it now verifies the entered code.
@vercel

vercel Bot commented Nov 17, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
clerk-js-sandbox Ready Ready Preview Nov 18, 2026 6:03pm UTC
mosaic-docs Error Error Nov 18, 2026 6:03pm UTC
swingset Ready Ready Preview Nov 18, 2026 6:03pm UTC

Request Review

@coderabbitai

coderabbitai Bot commented Nov 17, 2026

Copy link
Copy Markdown
Contributor

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

  • Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

@changeset-bot

changeset-bot Bot commented Nov 17, 2026 •

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: 4e21cc0

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

This PR includes changesets to release 0 packages

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

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

TaskChooseOrganizationContent renders the task's steps and skeleton with no Card.Root, so another flow can show the task inside its own card. useTaskChooseOrganizationReady reports when the task's data has loaded. The standalone TaskChooseOrganization is unchanged.
clerk-js expects FAPI to clear the sign-up from the client once it completes, and swaps in an empty one after finalize. The fake kept it, which hid the start form flashing while a sign-up leaves.
SignUpView takes a screen and one props object per screen, and each Flow step mounts that screen's component. The controller above the routes holds the details form, so a typed password survives a trip to a verify screen.

- Verify routes nest under continue, as in ui, so Back comes from the route.
- A verify screen sends its code when it mounts on a step with none out.
- While a sign-up finishes, the controller renders the model it left from, so the start form no longer shows when FAPI clears the sign-up.
- A choose-organization task renders in the same card on tasks/choose-organization. The code screen stays up until the task's data has loaded.
@pkg-pr-new

pkg-pr-new Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

Open in StackBlitz

@clerk/astro

npm i https://pkg.pr.new/@clerk/astro@10881

@clerk/backend

npm i https://pkg.pr.new/@clerk/backend@10881

@clerk/chrome-extension

npm i https://pkg.pr.new/@clerk/chrome-extension@10881

@clerk/clerk-js

npm i https://pkg.pr.new/@clerk/clerk-js@10881

@clerk/electron

npm i https://pkg.pr.new/@clerk/electron@10881

@clerk/electron-passkeys

npm i https://pkg.pr.new/@clerk/electron-passkeys@10881

@clerk/eslint-plugin

npm i https://pkg.pr.new/@clerk/eslint-plugin@10881

@clerk/expo

npm i https://pkg.pr.new/@clerk/expo@10881

@clerk/expo-biometrics

npm i https://pkg.pr.new/@clerk/expo-biometrics@10881

@clerk/expo-google-signin

npm i https://pkg.pr.new/@clerk/expo-google-signin@10881

@clerk/expo-native-components

npm i https://pkg.pr.new/@clerk/expo-native-components@10881

@clerk/expo-passkeys

npm i https://pkg.pr.new/@clerk/expo-passkeys@10881

@clerk/express

npm i https://pkg.pr.new/@clerk/express@10881

@clerk/fastify

npm i https://pkg.pr.new/@clerk/fastify@10881

@clerk/hono

npm i https://pkg.pr.new/@clerk/hono@10881

@clerk/localizations

npm i https://pkg.pr.new/@clerk/localizations@10881

@clerk/mosaic

npm i https://pkg.pr.new/@clerk/mosaic@10881

@clerk/nextjs

npm i https://pkg.pr.new/@clerk/nextjs@10881

@clerk/nuxt

npm i https://pkg.pr.new/@clerk/nuxt@10881

@clerk/react

npm i https://pkg.pr.new/@clerk/react@10881

@clerk/react-router

npm i https://pkg.pr.new/@clerk/react-router@10881

@clerk/shared

npm i https://pkg.pr.new/@clerk/shared@10881

@clerk/tanstack-react-start

npm i https://pkg.pr.new/@clerk/tanstack-react-start@10881

@clerk/testing

npm i https://pkg.pr.new/@clerk/testing@10881

@clerk/ui

npm i https://pkg.pr.new/@clerk/ui@10881

@clerk/upgrade

npm i https://pkg.pr.new/@clerk/upgrade@10881

@clerk/vue

npm i https://pkg.pr.new/@clerk/vue@10881

commit: 4e21cc0

SignUpCodeStep had one caller left once the view stopped rendering step kinds. SignUpVerify now calls its controller and renders the shared VerificationCode block itself.
The local Screen wrapper only typed the step ids. Every other Mosaic view writes Flow.Step, so the wrapper cost more to read than it saved.
The controller and the route test each spelled the rule out, and the test's copy left out the unknown step. Both now call one function from sign-up.routes.ts.
…effect

The screen took verifyCode and onVerified and joined them itself, which put the next step type in the view contract. The flow controller now joins them and the screen gets a callback that resolves with nothing.
sign-up.controller.ts keeps what outlives a screen: the route, the form and finishing. The code machine and the verify screen's controller sit in sign-up-verify.controller.ts.
…th enabled

The task, organization list and create-organization models take an enabled option, default true, and pass it to the organization list and creation default hooks. A caller that mounts the task model before the session has the task can keep it from fetching.
…model's step

The model reports leaving until the task's data has loaded, then task. The finish machine holds the code screen in a handingOff state whose always transition reads the live step, so the TASK_READY event, the effect-only readiness component and finalize's task-or-leaving answer go away. Sign-up mounts the task model with enabled set only while the session has the task, so a sign-up without one fetches no organization lists.

This branch was successfully deployed

2 active deployments
Preview – swingset — 4e21cc05 Deployed Nov 18, 2026 by vercel[bot]
Preview – clerk-js-sandbox — 4e21cc05 Deployed Nov 18, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant