test(shared): add query-client hotload compatibility regression

[jacekradko]

Adds a regression test that locks in useOrganizationList behavior against the legacy @clerk/shared query-client bridge (pre-#8434), where the hook reads Clerk.__internal_queryClient and waits on the queryClientStatus event before swapping out the mock client.

This is the path older framework SDKs still take when they hotload the latest clerk-js, so the test pins down the contract: the hook starts loaded with the mock client, fires /me/organization_memberships once the real client resolves, and settles into a non-loading state with the expected count. Empty changeset since it's test-only.

[changeset-bot]

🦋 Changeset detected

Latest commit: 573c23b

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

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	May 22, 2026 12:48am

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

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

Review profile: CHILL

Plan: Pro

Run ID: 2b5d50d6-c9e7-4793-b246-c79f289ac9b7

📥 Commits

Reviewing files that changed from the base of the PR and between c3759d3 and 573c23b.

📒 Files selected for processing (1)

• packages/shared/src/react/hooks/__tests__/useOrganizationList.hotload-compat.spec.tsx

---

📝 Walkthrough

Walkthrough

This PR adds a new Vitest test suite for useOrganizationList hotload compatibility within the Clerk JavaScript SDK. The test establishes mocked Clerk provider contexts and a hotload-aware query client shim that lazily instantiates TanstackQueryClient and signals readiness via queryClientStatus listeners. The main test verifies that useOrganizationList correctly initiates in a loaded state, asynchronously triggers a single organization memberships request with specific pagination parameters, validates the downstream API request shape to /me/organization_memberships, and confirms final state values after loading completes. A changeset file documents the regression fix.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

• clerk/javascript#8562: Reintroduces the actual __internal_queryClient lazy loader and queryClientStatus "ready" signaling that this test's hotload shim mocks and verifies.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The pull request title clearly describes the main change: adding a regression test for query-client hotload compatibility.
Description check	✅ Passed	The description is relevant and explains the regression test, the legacy query-client bridge scenario, and the specific behavior being tested.
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.

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

---

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

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In
`@packages/shared/src/react/hooks/__tests__/useOrganizationList.hotload-compat.spec.tsx`:
- Around line 76-80: The test registers the listener inside React.useEffect
(clerk.on('queryClientStatus', setLoaded)) which can miss the microtask emission
of readiness earlier (lines ~106-122), causing flakiness; fix by subscribing
synchronously or doing an immediate readiness check after subscription: in the
block where setQueryClientLoaded and clerk.on('queryClientStatus', setLoaded)
are used (the useEffect), either switch to React.useLayoutEffect so the listener
is added earlier, or keep useEffect but add an immediate check after registering
the listener (e.g. if (typeof clerk.isQueryClientReady === 'function' ?
clerk.isQueryClientReady() : clerk.queryClientStatus === 'ready')
setQueryClientLoaded(true)) so the test flips queryClientLoaded to true even if
the event already fired.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

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

Review profile: CHILL

Plan: Pro

Run ID: ef73791d-50d7-418b-af0e-158fed50d8ca

📥 Commits

Reviewing files that changed from the base of the PR and between 2f003bc and c3759d3.

📒 Files selected for processing (2)

• .changeset/query-client-compat-regression.md
• packages/shared/src/react/hooks/__tests__/useOrganizationList.hotload-compat.spec.tsx

[pkg-pr-new]

Open in StackBlitz

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/dev-cli

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

@clerk/expo

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/hono

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: 573c23b