refactor(clerk-js): Consolidate resource events into single event by bratsos · Pull Request #7980 · clerk/javascript

bratsos · 2026-03-04T21:30:58Z

Description

Resource state changes were spread across three separate events: resource:update, resource:error, and resource:fetch. Each one triggered its own signal write in State, which meant React could re-render between them. After an API call completed, React would briefly see the updated resource while fetchStatus was still 'fetching', because the resource and fetch-status updates arrived independently.

Even after consolidating into one event, a second source of inconsistency remained: fromJSON emits a resource-only event mid-flight (during an API call), which updated the resource signal before runAsyncResourceTask emitted the completion event with fetchStatus: 'idle'.

A third source came from finalize(), which used runAsyncResourceTask and set fetchStatus: 'fetching' on an already-complete resource even though it's just calling setActive, a session-level operation.

How we fixed it

Three changes, each addressing one source of inconsistency:

Consolidated three events into one. resource:update, resource:error, and resource:fetch are now a single resource:state-change event with optional error and fetchStatus fields. The State handler wraps all signal writes in startBatch()/endBatch() from alien-signals so they flush as one notification.
Skip resource-only events while fetching. When State receives a resource-only event (no fetchStatus, no error) and the current fetchStatus is 'fetching', it skips the signal write entirely. Since fromJSON mutates the resource in place, the completion event carries the same already-updated instance.
Removed runAsyncResourceTask from finalize(). Like reset(), finalize() now handles its own async flow without emitting fetchStatus. The sign-in/sign-up is already complete; setActive is a session-level operation that shouldn't affect sign-in/sign-up fetch status.

Demo

(showcasing the finalize() fix)

Before	After
resource-events-before.mov	resource-events-after.mov

Sample code used for the demo

export default function SignInPage() {
  const { signIn, errors, fetchStatus } = useSignIn()
  const router = useRouter()
  const [email, setEmail] = useState('')
  const [password, setPassword] = useState('')
  const [toasts, setToasts] = useState<Toast[]>([])
  const toastIdRef = useRef(0)

  useEffect(() => {
    if (fetchStatus === 'fetching') {
      setToasts(prev => [...prev, { id: ++toastIdRef.current, message: 'Verifying your credentials...', type: 'info' }])
    }

    if (fetchStatus === 'idle') {
      setToasts(prev => prev.filter(t => t.type !== 'info'))
    }
  }, [fetchStatus])

  useEffect(() => {
    if (signIn?.status === 'complete') {
      setToasts(prev => [...prev, { id: ++toastIdRef.current, message: 'Welcome back! Redirecting...', type: 'success' }])
    }
  }, [signIn?.status])

  function dismissToast(id: number) {
    setToasts(prev => prev.filter(t => t.id !== id))
  }

  async function handleSubmit(e: React.FormEvent) {
    e.preventDefault()
    if (!signIn) return
    setToasts([])
    toastIdRef.current = 0
    await signIn.password({ identifier: email, password })

    if (signIn.status === 'complete') {
      await signIn.finalize({
        navigate: async ({ session, decorateUrl }) => {
          if (session?.currentTask) {
            router.push(decorateUrl(`/sign-in/tasks/${session.currentTask.key}`))
            return
          }
          router.push(decorateUrl('/'))
        },
      })
    }
  }

  return (
    <div className="flex min-h-screen items-center justify-center bg-zinc-50 dark:bg-black">
      <ToastContainer toasts={toasts} onDismiss={dismissToast} />

      <div className="w-full max-w-sm rounded-lg border border-zinc-200 bg-white p-8 shadow-sm dark:border-zinc-800 dark:bg-zinc-950">
        <h1 className="mb-6 text-center text-2xl font-semibold text-zinc-900 dark:text-zinc-50">
          Sign in
        </h1>
        <form onSubmit={handleSubmit} className="flex flex-col gap-4">
          <div className="flex flex-col gap-1">
            <label htmlFor="email" className="text-sm font-medium text-zinc-700 dark:text-zinc-300">
              Email
            </label>
            <input
              id="email"
              type="email"
              value={email}
              onChange={(e) => setEmail(e.target.value)}
              placeholder="you@example.com"
              className="rounded-md border border-zinc-300 px-3 py-2 text-sm text-zinc-900 placeholder:text-zinc-400 focus:border-zinc-500 focus:outline-none focus:ring-1 focus:ring-zinc-500 dark:border-zinc-700 dark:bg-zinc-900 dark:text-zinc-50"
            />
            {errors?.fields?.identifier && (
              <p className="text-sm text-red-600">{errors.fields.identifier.message}</p>
            )}
          </div>
          <div className="flex flex-col gap-1">
            <label htmlFor="password" className="text-sm font-medium text-zinc-700 dark:text-zinc-300">
              Password
            </label>
            <input
              id="password"
              type="password"
              value={password}
              onChange={(e) => setPassword(e.target.value)}
              placeholder="Password"
              className="rounded-md border border-zinc-300 px-3 py-2 text-sm text-zinc-900 placeholder:text-zinc-400 focus:border-zinc-500 focus:outline-none focus:ring-1 focus:ring-zinc-500 dark:border-zinc-700 dark:bg-zinc-900 dark:text-zinc-50"
            />
            {errors?.fields?.password && (
              <p className="text-sm text-red-600">{errors.fields.password.message}</p>
            )}
          </div>
          {errors?.global?.map((err, i) => (
            <p key={i} className="text-sm text-red-600">{err.longMessage}</p>
          ))}
          <button
            type="submit"
            disabled={fetchStatus === 'fetching'}
            className="mt-2 rounded-md bg-zinc-900 px-4 py-2 text-sm font-medium text-white transition-colors hover:bg-zinc-800 disabled:opacity-50 dark:bg-zinc-50 dark:text-zinc-900 dark:hover:bg-zinc-200"
          >
            {fetchStatus === 'fetching' ? 'Signing in...' : 'Sign in'}
          </button>
        </form>
        <p className="mt-4 text-center text-sm text-zinc-500">
          Don&apos;t have an account?{' '}
          <Link href="/sign-up" className="font-medium text-zinc-900 hover:underline dark:text-zinc-50">
            Sign up
          </Link>
        </p>
      </div>
    </div>
  )
}

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

Summary by CodeRabbit

Bug Fixes
- Fixed an issue where completion status would incorrectly display as complete during sign-in and sign-up operations while requests were still processing
Improvements
- Enhanced state management and signal handling for more consistent and reliable authentication status tracking

changeset-bot · 2026-03-04T21:31:04Z

🦋 Changeset detected

Latest commit: 59c6aa4

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

This PR includes changesets to release 3 packages

Name	Type
@clerk/clerk-js	Patch
@clerk/chrome-extension	Patch
@clerk/expo	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 · 2026-03-04T21:31:04Z

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

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Mar 5, 2026 6:32pm

nikosdouvlis · 2026-03-05T10:54:26Z

!snapshot

clerk-cookie · 2026-03-05T10:56:56Z

Hey @nikosdouvlis - the snapshot version command generated the following package versions:

Package	Version
@clerk/agent-toolkit	0.3.2-snapshot.v20260305105512
@clerk/astro	3.0.2-snapshot.v20260305105512
@clerk/backend	3.0.2-snapshot.v20260305105512
@clerk/chrome-extension	3.0.2-snapshot.v20260305105512
@clerk/clerk-js	6.0.1-snapshot.v20260305105512
@clerk/dev-cli	0.1.1-snapshot.v20260305105512
@clerk/expo	3.0.2-snapshot.v20260305105512
@clerk/expo-passkeys	1.0.2-snapshot.v20260305105512
@clerk/express	2.0.2-snapshot.v20260305105512
@clerk/fastify	3.0.2-snapshot.v20260305105512
@clerk/hono	0.0.4-snapshot.v20260305105512
@clerk/localizations	4.0.1-snapshot.v20260305105512
@clerk/msw	0.0.2-snapshot.v20260305105512
@clerk/nextjs	7.0.2-snapshot.v20260305105512
@clerk/nuxt	2.0.2-snapshot.v20260305105512
@clerk/react	6.0.2-snapshot.v20260305105512
@clerk/react-router	3.0.2-snapshot.v20260305105512
@clerk/shared	4.0.1-snapshot.v20260305105512
@clerk/tanstack-react-start	1.0.2-snapshot.v20260305105512
@clerk/testing	2.0.2-snapshot.v20260305105512
@clerk/ui	1.0.2-snapshot.v20260305105512
@clerk/upgrade	2.0.2-snapshot.v20260305105512
@clerk/vue	2.0.2-snapshot.v20260305105512

Tip: Use the snippet copy button below to quickly install the required packages.
@clerk/agent-toolkit

npm i @clerk/agent-toolkit@0.3.2-snapshot.v20260305105512 --save-exact

@clerk/astro

npm i @clerk/astro@3.0.2-snapshot.v20260305105512 --save-exact

@clerk/backend

npm i @clerk/backend@3.0.2-snapshot.v20260305105512 --save-exact

@clerk/chrome-extension

npm i @clerk/chrome-extension@3.0.2-snapshot.v20260305105512 --save-exact

@clerk/clerk-js

npm i @clerk/clerk-js@6.0.1-snapshot.v20260305105512 --save-exact

@clerk/dev-cli

npm i @clerk/dev-cli@0.1.1-snapshot.v20260305105512 --save-exact

@clerk/expo

npm i @clerk/expo@3.0.2-snapshot.v20260305105512 --save-exact

@clerk/expo-passkeys

npm i @clerk/expo-passkeys@1.0.2-snapshot.v20260305105512 --save-exact

@clerk/express

npm i @clerk/express@2.0.2-snapshot.v20260305105512 --save-exact

@clerk/fastify

npm i @clerk/fastify@3.0.2-snapshot.v20260305105512 --save-exact

@clerk/hono

npm i @clerk/hono@0.0.4-snapshot.v20260305105512 --save-exact

@clerk/localizations

npm i @clerk/localizations@4.0.1-snapshot.v20260305105512 --save-exact

@clerk/msw

npm i @clerk/msw@0.0.2-snapshot.v20260305105512 --save-exact

@clerk/nextjs

npm i @clerk/nextjs@7.0.2-snapshot.v20260305105512 --save-exact

@clerk/nuxt

npm i @clerk/nuxt@2.0.2-snapshot.v20260305105512 --save-exact

@clerk/react

npm i @clerk/react@6.0.2-snapshot.v20260305105512 --save-exact

@clerk/react-router

npm i @clerk/react-router@3.0.2-snapshot.v20260305105512 --save-exact

@clerk/shared

npm i @clerk/shared@4.0.1-snapshot.v20260305105512 --save-exact

@clerk/tanstack-react-start

npm i @clerk/tanstack-react-start@1.0.2-snapshot.v20260305105512 --save-exact

@clerk/testing

npm i @clerk/testing@2.0.2-snapshot.v20260305105512 --save-exact

@clerk/ui

npm i @clerk/ui@1.0.2-snapshot.v20260305105512 --save-exact

@clerk/upgrade

npm i @clerk/upgrade@2.0.2-snapshot.v20260305105512 --save-exact

@clerk/vue

npm i @clerk/vue@2.0.2-snapshot.v20260305105512 --save-exact

…:state-change` event

coderabbitai · 2026-03-05T18:39:54Z

📝 Walkthrough

Walkthrough

This PR consolidates resource state management in @clerk/clerk-js by replacing three separate events (ResourceUpdate, ResourceError, ResourceFetch) with a unified ResourceStateChange event. The new event payload structure includes resource, optional error, and optional fetchStatus fields. A new signInFetchSignal export is added, and state.ts is updated to batch signal updates via the consolidated event. Resource classes (SignIn, SignUp, Waitlist, Client) are modified to emit the new event type, and runAsyncResourceTask is simplified to align with the new event structure.

Possibly related PRs

feat(clerk-js,types): Signals fetchStatus #6549: Introduces initial fetch-status tracking work that this PR evolves into a unified ResourceStateChange event flow with consolidated state management and signal batching.

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately reflects the main change: consolidating three separate resource events into a single unified event. It clearly describes the primary refactoring effort across the changeset.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

Tip

Try Coding Plans. Let us write the prompt for your AI agent so you can ship faster (with fewer bugs).
Share your feedback on Discord.

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

coderabbitai

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

packages/clerk-js/src/core/resources/SignIn.ts (1)

1293-1312: ⚠️ Potential issue | 🟠 Major

finalize() can reject unexpectedly and mark the flow discardable before success

Line [1296] throws outside the try, so this method can reject instead of returning { error }. Also, setting #canBeDiscarded before setActive succeeds can prematurely allow null-resource replacement on failure.

Proposed fix

 async finalize(params?: SignInFutureFinalizeParams): Promise<{ error: ClerkError | null }> {
   const { navigate } = params || {};
-
-  if (!this.#resource.createdSessionId) {
-    throw new Error('Cannot finalize sign-in without a created session.');
-  }
 
   try {
+    if (!this.#resource.createdSessionId) {
+      throw new Error('Cannot finalize sign-in without a created session.');
+    }
+
     // Reload the client if the created session is not in the client's sessions. This can happen during modal SSO
     // flows where the in-memory client does not have the created session.
     if (SignIn.clerk.client && !SignIn.clerk.client.sessions.some(s => s.id === this.#resource.createdSessionId)) {
       await SignIn.clerk.client.reload();
     }
 
-    this.#canBeDiscarded = true;
     await SignIn.clerk.setActive({ session: this.#resource.createdSessionId, navigate });
+    this.#canBeDiscarded = true;
     return { error: null };
   } catch (err) {
     return { error: err as ClerkError };
   }
 }

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/clerk-js/src/core/resources/SignIn.ts` around lines 1293 - 1312, The
finalize method currently throws if `#resource.createdSessionId` is missing and
sets `#canBeDiscarded` before setActive succeeds, so change finalize to return {
error } instead of throwing and only mark `#canBeDiscarded` true after
SignIn.clerk.setActive completes successfully: move the createdSessionId guard
and any throws into the try/catch (or convert them to an early return of {
error: new ClerkError(...) }) and relocate the assignment of
this.#canBeDiscarded to immediately after await SignIn.clerk.setActive(...)
succeeds; adjust error handling to return the caught error as ClerkError.
Reference finalize, this.#resource.createdSessionId, this.#canBeDiscarded,
SignIn.clerk.client.reload, and SignIn.clerk.setActive.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Outside diff comments:
In `@packages/clerk-js/src/core/resources/SignIn.ts`:
- Around line 1293-1312: The finalize method currently throws if
`#resource.createdSessionId` is missing and sets `#canBeDiscarded` before setActive
succeeds, so change finalize to return { error } instead of throwing and only
mark `#canBeDiscarded` true after SignIn.clerk.setActive completes successfully:
move the createdSessionId guard and any throws into the try/catch (or convert
them to an early return of { error: new ClerkError(...) }) and relocate the
assignment of this.#canBeDiscarded to immediately after await
SignIn.clerk.setActive(...) succeeds; adjust error handling to return the caught
error as ClerkError. Reference finalize, this.#resource.createdSessionId,
this.#canBeDiscarded, SignIn.clerk.client.reload, and SignIn.clerk.setActive.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro

Run ID: d47a6777-69a9-4390-a604-fcc13018fee0

📥 Commits

Reviewing files that changed from the base of the PR and between e13fc29 and 59c6aa4.

📒 Files selected for processing (13)

.changeset/fiery-games-pick.md
packages/clerk-js/src/core/__tests__/state.test.ts
packages/clerk-js/src/core/events.ts
packages/clerk-js/src/core/resources/Client.ts
packages/clerk-js/src/core/resources/SignIn.ts
packages/clerk-js/src/core/resources/SignUp.ts
packages/clerk-js/src/core/resources/Waitlist.ts
packages/clerk-js/src/core/resources/__tests__/SignIn.test.ts
packages/clerk-js/src/core/resources/__tests__/SignUp.test.ts
packages/clerk-js/src/core/resources/__tests__/Waitlist.test.ts
packages/clerk-js/src/core/state.ts
packages/clerk-js/src/utils/__tests__/runAsyncResourceTask.test.ts
packages/clerk-js/src/utils/runAsyncResourceTask.ts

bratsos · 2026-03-05T18:40:33Z

!snapshot

pkg-pr-new · 2026-03-06T14:26:50Z

Open in StackBlitz

@clerk/agent-toolkit

npm i https://pkg.pr.new/@clerk/agent-toolkit@7980

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/dev-cli

npm i https://pkg.pr.new/@clerk/dev-cli@7980

@clerk/expo

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/hono

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: 59c6aa4

dstaley · 2026-03-09T14:39:00Z

This looks great! I just have a few clarifying questions before I approve:

Consolidated three events into one. resource:update, resource:error, and resource:fetch are now a single resource:state-change event with optional error and fetchStatus fields. The State handler wraps all signal writes in startBatch()/endBatch() from alien-signals so they flush as one notification.

I'm pretty sure I understand this, but just to state it again to make sure I understand: with this change we're now able to batch the resource/error/fetchStatus signal updates into a single update when those happen in a single call site. Meaning one event emit results in one signal update, but multiple events aren't batched in any way (which is totally fine, just making sure I understand). So, for example:

eventBus.emit('resource:state-change', { resource, error, fetchStatus })

triggers one signal update. I think I'm fine with this, but it does mean we no longer have the ability to update just the resource, or just the fetch status. As evidenced by this PR that's probably fine? But still worth calling out.

Skip resource-only events while fetching. When State receives a resource-only event (no fetchStatus, no error) and the current fetchStatus is 'fetching', it skips the signal write entirely. Since fromJSON mutates the resource in place, the completion event carries the same already-updated instance.

This one I'm the most unsure of, because there's times when the resource identity isn't stable. However I can't think of an instance in which the resource identity will change during a method that's set fetchStatus to fetching so this is probably fine? Plus I think this is something we can easily revert if we discover that we do need this.

Removed runAsyncResourceTask from finalize(). Like reset(), finalize() now handles its own async flow without emitting fetchStatus. The sign-in/sign-up is already complete; setActive is a session-level operation that shouldn't affect sign-in/sign-up fetch status.

The original intent here was to put the resource into a fetching status since we were doing something that should disable input (waiting for the navigation to be performed). I think it's fine to remove for now, and we can add back if we feel the need or see people doing things like isFinalizing to render specific UI during finalize().

github-actions bot added the clerk-js label Mar 4, 2026

refactor(clerk-js): Consolidate resource events into single `resource…

59c6aa4

…:state-change` event

bratsos force-pushed the alexbratsos/user-4373-signal-update-for-resource-and-fetchstatus-can-happen branch from baab30c to 59c6aa4 Compare March 5, 2026 18:31

vercel bot deployed to Preview March 5, 2026 18:32 View deployment

bratsos marked this pull request as ready for review March 5, 2026 18:33

coderabbitai bot reviewed Mar 5, 2026

View reviewed changes

bratsos closed this Mar 6, 2026

bratsos reopened this Mar 6, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

refactor(clerk-js): Consolidate resource events into single event#7980

refactor(clerk-js): Consolidate resource events into single event#7980
bratsos wants to merge 1 commit intomainfrom
alexbratsos/user-4373-signal-update-for-resource-and-fetchstatus-can-happen

bratsos commented Mar 4, 2026 •

edited by coderabbitai bot

Loading

Uh oh!

changeset-bot bot commented Mar 4, 2026 •

edited

Loading

Uh oh!

vercel bot commented Mar 4, 2026 •

edited

Loading

Uh oh!

nikosdouvlis commented Mar 5, 2026

Uh oh!

clerk-cookie commented Mar 5, 2026

Uh oh!

coderabbitai bot commented Mar 5, 2026

Walkthrough

Possibly related PRs

Uh oh!

coderabbitai bot left a comment

Uh oh!

bratsos commented Mar 5, 2026

Uh oh!

pkg-pr-new bot commented Mar 6, 2026

Uh oh!

dstaley commented Mar 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

bratsos commented Mar 4, 2026 • edited by coderabbitai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

How we fixed it

Demo

Checklist

Type of change

Summary by CodeRabbit

Uh oh!

changeset-bot bot commented Mar 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

vercel bot commented Mar 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

nikosdouvlis commented Mar 5, 2026

Uh oh!

clerk-cookie commented Mar 5, 2026

Uh oh!

coderabbitai bot commented Mar 5, 2026

Walkthrough

Possibly related PRs

Uh oh!

coderabbitai bot left a comment

Choose a reason for hiding this comment

Uh oh!

bratsos commented Mar 5, 2026

Uh oh!

pkg-pr-new bot commented Mar 6, 2026

Uh oh!

dstaley commented Mar 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

bratsos commented Mar 4, 2026 •

edited by coderabbitai bot

Loading

changeset-bot bot commented Mar 4, 2026 •

edited

Loading

vercel bot commented Mar 4, 2026 •

edited

Loading