Skip to content

fix(shared): verify the sign-up email and phone before collecting missing fields - #10883

Open
austincalvelage wants to merge 7 commits into
austin/shared-sign-up-form-fieldsfrom
austin/shared-sign-up-next-step-order
Open

austincalvelage wants to merge 7 commits into
austin/shared-sign-up-form-fieldsfrom
austin/shared-sign-up-next-step-order

Conversation

@austincalvelage

Copy link
Copy Markdown
Member

Description

getSignUpNextStep now returns the email and phone verification steps before the fields step. This is the order completeSignUpFlow follows in the current sign-up form: verify the email, then the phone, then collect the missing fields.

The order of sign-up steps is a client decision. FAPI completes a sign-up once every requirement is met, whatever order they are met in, so one function in shared can keep every JS client on the same order.

Also in this PR:

  • NextStep is split into SignInNextStep and SignUpNextStep, so a sign-up caller cannot receive a sign-in step. NextStep stays as the union of the two.
  • A TODO marks the one case that still returns unknown: FAPI computes the missing requirement but does not send it.
  • The Mosaic flow guide lists the sign-up steps in the new order and names where the order comes from.

Nothing on main calls these helpers outside their tests, so no shipped behavior changes. The Mosaic sign-up in #10881 is the first caller.

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.
@vercel

vercel Bot commented Nov 18, 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 12:26am UTC
mosaic-docs Error Error Nov 18, 2026 12:26am UTC
swingset Ready Ready Preview Nov 18, 2026 12:26am UTC

Request Review

@changeset-bot

changeset-bot Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: eeeeaca

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

@coderabbitai

coderabbitai Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Explain Change →

No actionable comments were generated in the recent review.

Walkthrough

The next-step types now distinguish sign-in and sign-up results. Sign-up resolution checks email and phone verification before returning missing fields. The updated test expects email verification when an email address is unverified, and the documentation describes the same order. The changeset file contains empty frontmatter.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

  • clerk/javascript#10742: Adds getSignUpNextStep, which this PR changes to return verification steps before the fields step.

Suggested reviewers: alexcarpenter, ephem

Merge Risk: Minimal · up to eeeea

This change reorders sign-up next steps so email and phone verification come before collecting missing fields, and it narrows the step types by flow. No actionable merge-blocking issue was found. Confirm that tests and build pass, and check the failed docs deployment, before merging.

Pre-merge checks: Passed 4

Check name Status Explanation
Title check Passed The title names the main change: sign-up email and phone verification steps now come before the missing-fields step in getSignUpNextStep. It is specific and matches the raw summary and objectives. The…
Description check Passed The description states that getSignUpNextStep now returns email and phone verification steps before the fields step. It also covers the NextStep split into SignInNextStep and SignUpNextStep, the TODO …
Linked Issues check Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed Check skipped because no linked issues were found for this pull request.
Full details: Title check

Explanation

The title names the main change: sign-up email and phone verification steps now come before the missing-fields step in getSignUpNextStep. It is specific and matches the raw summary and objectives. The title uses the conventional fix(shared) prefix, which is accepted here.

Full details: Description check

Explanation

The description states that getSignUpNextStep now returns email and phone verification steps before the fields step. It also covers the NextStep split into SignInNextStep and SignUpNextStep, the TODO for the unknown case, and the Mosaic flow guide update. It is related to the changeset.

Finishing Touches

Fix failing CI checks

  • Commit to this branch
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Warning

Linked repositories: Some configured repositories could not be included in this review. Cross-repository analysis may be incomplete. Please check linked-repository access and settings.

Recent review info

Run configuration

Commits

Reviewing files that changed from the base of the PR and between 3b1d6d9 and eeeeaca.

Files selected for processing: 1

  • packages/mosaic/docs/internals/sign-in-sign-up-flow.md
Linked repositories identified

CodeRabbit considers these linked repositories for cross-repo context during reviews:

Included review availability: This review used your included allowance. 7 included reviews remain after this review. Your included PR review attempts over the past 7 days set your current allowance at 10 reviews per hour.

@blacksmith-sh

blacksmith-sh Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

Matches Verify email/phone before fields

Tested on 3b1d6d94, untouched since — With a field missing, the step is now verify email, then verify phone, then fields; before it returned fields in all three states.

Merge-base

Three states

This PR 3b1d6d94

Three states

Also checked · 2 match

Matches Same order as completeSignUpFlow
Matches Sign-up type excludes sign-in steps

Proof on eeeeacae (from 3b1d6d94) · Did Proof get it right? Yes · No

View full Proof report · React 👎 or comment @codesmith dismiss this proof to dismiss

@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@10883

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/electron

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

@clerk/electron-passkeys

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

@clerk/eslint-plugin

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

@clerk/expo

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

@clerk/expo-biometrics

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

@clerk/expo-google-signin

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

@clerk/expo-native-components

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/hono

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

@clerk/localizations

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

@clerk/mosaic

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: eeeeaca

@github-actions

github-actions Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

API Changes Report

Generated by Break Check on 2026-11-18T00:28:32.455Z

Summary

Metric Count
Packages analyzed 20
Packages with changes 1
🔴 Breaking changes 0
🟡 Non-breaking changes 1
🟢 Additions 8

🤖 This report was reviewed by claude-sonnet-4-6.


@clerk/shared

Current version: 4.46.0
Recommended bump: MINOR → 4.47.0

Subpath ./internal/clerk-js/actionBlocked

🟢 Additions (1)

Added: ./internal/clerk-js/actionBlocked

New subpath export ./internal/clerk-js/actionBlocked (3 exported members)

Subpath ./internal/clerk-js/nextStep

🟡 Non-breaking Changes (1)

Modified: NextStep
- type NextStep = {
-   type: 'identifier';
- } | {
-   type: 'first_factor';
-   strategy: string | null;
-   sent: boolean;
- } | {
-   type: 'second_factor';
-   strategy: string | null;
-   sent: boolean;
- } | {
-   type: 'client_trust';
- } | {
-   type: 'new_password';
- } | {
-   type: 'protect';
- } | {
-   type: 'transfer';
- } | {
-   type: 'start';
- } | {
-   type: 'enterprise_sso';
- } | {
-   type: 'fields';
-   fields: SignUpField[];
- } | {
-   type: 'verify_email';
-   target: string | null;
-   sent: boolean;
- } | {
-   type: 'verify_phone';
-   target: string | null;
-   sent: boolean;
- } | {
-   type: 'complete';
-   createdSessionId: string | null;
- } | {
-   type: 'unknown';
- };
+ type NextStep = SignInNextStep | SignUpNextStep;

Static analyzer: Breaking change in type alias NextStep: Type changed: {type:'client_trust';}|{type:'complete';createdSessionId:null|string;}|{type:'enterprise_sso';}|{type:'fields';fields:i… → import("@clerk/shared").SignInNextStep|import("@clerk/shared").SignUpNextStep

🤖 AI review (reclassified as non-breaking) (85%): Resolving SignInNextStep and SignUpNextStep from the provided definitions, their union covers all the same discriminated variants as the old inline union (identifier, first_factor, second_factor, client_trust, new_password, protect, transfer, start, enterprise_sso, fields, verify_email, verify_phone, complete, unknown via SharedNextStep) — the structural shape is identical, just refactored into named aliases, so no well-typed consumer code is affected.

🟢 Additions (2)

Added: SignInNextStep
+ type SignInNextStep = SharedNextStep | {
+   type: 'identifier';
+ } | {
+   type: 'first_factor';
+   strategy: string | null;
+   sent: boolean;
+ } | {
+   type: 'second_factor';
+   strategy: string | null;
+   sent: boolean;
+ } | {
+   type: 'client_trust';
+ } | {
+   type: 'new_password';
+ };

Added type alias SignInNextStep

Added: SignUpNextStep
+ type SignUpNextStep = SharedNextStep | {
+   type: 'start';
+ } | {
+   type: 'enterprise_sso';
+ } | {
+   type: 'fields';
+   fields: SignUpField[];
+ } | {
+   type: 'verify_email';
+   target: string | null;
+   sent: boolean;
+ } | {
+   type: 'verify_phone';
+   target: string | null;
+   sent: boolean;
+ };

Added type alias SignUpNextStep

Subpath ./internal/clerk-js/signUpFormFields

🟢 Additions (1)

Added: ./internal/clerk-js/signUpFormFields

New subpath export ./internal/clerk-js/signUpFormFields (11 exported members)

Subpath ./react

🟢 Additions (4)

Added: __internal_useClerkSignal
+ declare function __internal_useClerkSignal(signal: 'signIn'): SignInSignalValue;

Added function __internal_useClerkSignal

Added: __internal_useClerkSignal
+ declare function __internal_useClerkSignal(signal: 'signUp'): SignUpSignalValue;

Added function __internal_useClerkSignal

Added: __internal_useClerkSignal
+ declare function __internal_useClerkSignal(signal: 'waitlist'): WaitlistSignalValue;

Added function __internal_useClerkSignal

Added: __internal_useClerkSignal
+ declare function __internal_useClerkSignal(signal: 'signIn' | 'signUp' | 'waitlist'): SignInSignalValue | SignUpSignalValue | WaitlistSignalValue;

Added function __internal_useClerkSignal


Report generated by Break Check

Last ran on eeeeaca.

This branch was successfully deployed

2 active deployments
Preview – swingset — eeeeacae Deployed Nov 18, 2026 by vercel[bot]
Preview – clerk-js-sandbox — eeeeacae 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

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant