chore(shared): Add React Query variant of usePageOrInfinite

.changeset/fuzzy-keys-smell.md

@@ -0,0 +1,5 @@
+---
+'@clerk/shared': patch
+---
+
+Build internal variants of all paginated hooks that use React Query instead of SWR.

.github/workflows/ci.yml

@@ -191,7 +191,7 @@ jobs:
  unit-tests:
  needs: [check-permissions, build-packages]
  if: ${{ github.event_name != 'pull_request' || github.event.pull_request.draft == false }}
- name: Unit Tests
+ name: Unit Tests (${{ matrix.node-version }}, ${{ matrix.filter-label }}${{ matrix.clerk-use-rq == 'true' && ', RQ' || '' }})
  permissions:
  contents: read
  actions: write # needed for actions/upload-artifact
@@ -205,11 +205,17 @@ jobs:
  TURBO_SUMMARIZE: false
 
  strategy:
- fail-fast: true
+ fail-fast: false
  matrix:
  include:
  - node-version: 22
  test-filter: "**"
+ clerk-use-rq: "false"
+ filter-label: "**"
+ - node-version: 22
+ test-filter: "--filter=@clerk/shared --filter=@clerk/clerk-js"
+ clerk-use-rq: "true"
+ filter-label: "shared, clerk-js"
 
  steps:
  - name: Checkout Repo
@@ -229,22 +235,35 @@ jobs:
  turbo-team: ${{ vars.TURBO_TEAM }}
  turbo-token: ${{ secrets.TURBO_TOKEN }}
 
+ - name: Rebuild @clerk/shared with CLERK_USE_RQ=true
+ if: ${{ matrix.clerk-use-rq == 'true' }}
+ run: pnpm turbo build $TURBO_ARGS --filter=@clerk/shared --force
+ env:
+ CLERK_USE_RQ: true
+
+ - name: Rebuild dependent packages with CLERK_USE_RQ=true
+ if: ${{ matrix.clerk-use-rq == 'true' }}
+ run: pnpm turbo build $TURBO_ARGS --filter=@clerk/shared^... --force
+ env:
+ CLERK_USE_RQ: true
+
  - name: Run tests in packages
  run: |
  if [ "${{ matrix.test-filter }}" = "**" ]; then
- echo "Running full test suite on Node ${{ matrix.node-version }}."
+ echo "Running full test suite on Node ${{ matrix.node-version }}"
  pnpm turbo test $TURBO_ARGS
  else
- echo "Running LTS subset on Node ${{ matrix.node-version }}."
+ echo "Running tests: ${{ matrix.filter-label }}"
  pnpm turbo test $TURBO_ARGS ${{ matrix.test-filter }}
  fi
  env:
  NODE_VERSION: ${{ matrix.node-version }}
+ CLERK_USE_RQ: ${{ matrix.clerk-use-rq }}
 
  - name: Run Typedoc tests
  run: |
- # Only run Typedoc tests for one matrix version
- if [ "${{ matrix.node-version }}" == "22" ]; then
+ # Only run Typedoc tests for one matrix version and main test run
+ if [ "${{ matrix.node-version }}" == "22" ] && [ "${{ matrix.test-filter }}" = "**" ]; then
  pnpm test:typedoc
  fi
  env:
@@ -255,14 +274,14 @@ jobs:
  if: ${{ env.TURBO_SUMMARIZE == 'true' }}
  continue-on-error: true
  with:
- name: turbo-summary-report-unit-${{ github.run_id }}-${{ github.run_attempt }}-node-${{ matrix.node-version }}
+ name: turbo-summary-report-unit-${{ github.run_id }}-${{ github.run_attempt }}-node-${{ matrix.node-version }}${{ matrix.clerk-use-rq == 'true' && '-rq' || '' }}
  path: .turbo/runs
  retention-days: 5
 
  integration-tests:
  needs: [check-permissions, build-packages]
  if: ${{ github.event_name != 'pull_request' || github.event.pull_request.draft == false }}
- name: Integration Tests
+ name: Integration Tests (${{ matrix.test-name }}, ${{ matrix.test-project }}${{ matrix.next-version && format(', {0}', matrix.next-version) || '' }}${{ matrix.clerk-use-rq == 'true' && ', RQ' || '' }})
  permissions:
  contents: read
  actions: write # needed for actions/upload-artifact
@@ -291,18 +310,28 @@ jobs:
  'vue',
  'nuxt',
  'react-router',
- 'billing',
  'machine',
  'custom',
  ]
  test-project: ["chrome"]
  include:
+ - test-name: 'billing'
+ test-project: 'chrome'
+ clerk-use-rq: 'false'
+ - test-name: 'billing'
+ test-project: 'chrome'
+ clerk-use-rq: 'true'
  - test-name: 'nextjs'
  test-project: 'chrome'
  next-version: '14'
  - test-name: 'nextjs'
  test-project: 'chrome'
  next-version: '15'
+ clerk-use-rq: 'false'
+ - test-name: 'nextjs'
+ test-project: 'chrome'
+ next-version: '15'
+ clerk-use-rq: 'true'
  - test-name: 'nextjs'
  test-project: 'chrome'
  next-version: '16'
@@ -360,12 +389,24 @@ jobs:
  echo "affected=${AFFECTED}"
  echo "affected=${AFFECTED}" >> $GITHUB_OUTPUT
 
+ - name: Rebuild @clerk/shared with CLERK_USE_RQ=true
+ if: ${{ steps.task-status.outputs.affected == '1' && matrix.clerk-use-rq == 'true' }}
+ run: pnpm turbo build $TURBO_ARGS --filter=@clerk/shared --force
+ env:
+ CLERK_USE_RQ: true
+
+ - name: Rebuild dependent packages with CLERK_USE_RQ=true
+ if: ${{ steps.task-status.outputs.affected == '1' && matrix.clerk-use-rq == 'true' }}
+ run: pnpm turbo build $TURBO_ARGS --filter=@clerk/shared^... --force
+ env:
+ CLERK_USE_RQ: true
+
  - name: Verdaccio
  if: ${{ steps.task-status.outputs.affected == '1' }}
  uses: ./.github/actions/verdaccio
  with:
  publish-cmd: |
- if [ "$(pnpm config get registry)" = "https://registry.npmjs.org/" ]; then echo 'Error: Using default registry' && exit 1; else pnpm turbo build $TURBO_ARGS --only && pnpm changeset publish --no-git-tag; fi
+ if [ "$(pnpm config get registry)" = "https://registry.npmjs.org/" ]; then echo 'Error: Using default registry' && exit 1; else CLERK_USE_RQ=${{ matrix.clerk-use-rq }} pnpm turbo build $TURBO_ARGS --only && pnpm changeset publish --no-git-tag; fi
 
  - name: Edit .npmrc [link-workspace-packages=false]
  run: sed -i -E 's/link-workspace-packages=(deep|true)/link-workspace-packages=false/' .npmrc
@@ -425,6 +466,7 @@ jobs:
  E2E_NEXTJS_VERSION: ${{ matrix.next-version }}
  E2E_PROJECT: ${{ matrix.test-project }}
  E2E_CLERK_ENCRYPTION_KEY: ${{ matrix.clerk-encryption-key }}
+ CLERK_USE_RQ: ${{ matrix.clerk-use-rq }}
  INTEGRATION_INSTANCE_KEYS: ${{ secrets.INTEGRATION_INSTANCE_KEYS }}
  MAILSAC_API_KEY: ${{ secrets.MAILSAC_API_KEY }}
  NODE_EXTRA_CA_CERTS: ${{ github.workspace }}/integration/certs/rootCA.pem
@@ -433,7 +475,7 @@ jobs:
  if: ${{ cancelled() || failure() }}
  uses: actions/upload-artifact@v4
  with:
- name: playwright-traces-${{ github.run_id }}-${{ github.run_attempt }}-${{ matrix.test-name }}
+ name: playwright-traces-${{ github.run_id }}-${{ github.run_attempt }}-${{ matrix.test-name }}${{ matrix.next-version && format('-next{0}', matrix.next-version) || '' }}${{ matrix.clerk-use-rq == 'true' && '-rq' || '' }}
  path: integration/test-results
  retention-days: 1
 

packages/clerk-js/src/test/mock-helpers.ts

@@ -1,6 +1,7 @@
 import type { ActiveSessionResource, LoadedClerk } from '@clerk/shared/types';
 import { type Mocked, vi } from 'vitest';
 
+import { QueryClient } from '../core/query-core';
 import type { RouteContextValue } from '../ui/router';
 
 type FunctionLike = (...args: any) => any;
@@ -45,6 +46,20 @@ export const mockClerkMethods = (clerk: LoadedClerk): DeepVitestMocked<LoadedCle
  // Cast clerk to any to allow mocking properties
  const clerkAny = clerk as any;
 
+ const defaultQueryClient = {
+ __tag: 'clerk-rq-client' as const,
+ client: new QueryClient({
+ defaultOptions: {
+ queries: {
+ retry: false,
+ // Setting staleTime to Infinity will not cause issues between tests as long as each test
+ // case has its own wrapper that initializes a Clerk instance with a new QueryClient.
+ staleTime: Infinity,
+ },
+ },
+ }),
+ };
+
  mockMethodsOf(clerkAny);
  if (clerkAny.client) {
  mockMethodsOf(clerkAny.client.signIn);
@@ -76,6 +91,13 @@ export const mockClerkMethods = (clerk: LoadedClerk): DeepVitestMocked<LoadedCle
  if (clerkAny.billing) {
  mockMethodsOf(clerkAny.billing);
  }
+
+ // Mock the __internal_queryClient getter property
+ Object.defineProperty(clerkAny, '__internal_queryClient', {
+ get: vi.fn(() => defaultQueryClient),
+ configurable: true,
+ });
+
  mockProp(clerkAny, 'navigate');
  mockProp(clerkAny, 'setActive');
  mockProp(clerkAny, 'redirectWithAuth');

packages/clerk-js/src/ui/components/Checkout/__tests__/Checkout.test.tsx

@@ -316,6 +316,12 @@ describe('Checkout', () => {
  });
 
  const freeTrialEndsAt = new Date('2025-08-19');
+
+ fixtures.clerk.user?.getPaymentMethods.mockResolvedValue({
+ data: [],
+ total_count: 0,
+ });
+
  fixtures.clerk.billing.startCheckout.mockResolvedValue({
  id: 'chk_trial_1',
  status: 'needs_confirmation',
@@ -1033,13 +1039,18 @@ describe('Checkout', () => {
  { wrapper },
  );
 
- await waitFor(async () => {
+ await waitFor(() => {
  expect(getByRole('heading', { name: 'Checkout' })).toBeVisible();
- const addPaymentMethodButton = getByText('Add payment method');
- expect(addPaymentMethodButton).toBeVisible();
- await userEvent.click(addPaymentMethodButton);
  });
 
+ const addPaymentMethodButton = await waitFor(() => {
+ const button = getByText('Add payment method');
+ expect(button).toBeVisible();
+ return button;
+ });
+
+ await userEvent.click(addPaymentMethodButton);
+
  await waitFor(() => {
  expect(getByRole('button', { name: 'Start free trial' })).toBeInTheDocument();
  });

packages/clerk-js/src/ui/components/OrganizationList/__tests__/OrganizationList.test.tsx

@@ -45,7 +45,7 @@ describe('OrganizationList', () => {
  });
  });
 
- fixtures.clerk.user?.getOrganizationMemberships.mockReturnValueOnce(
+ fixtures.clerk.user?.getOrganizationMemberships.mockReturnValue(
  Promise.resolve({
  data: [
  createFakeUserOrganizationMembership({
@@ -117,7 +117,7 @@ describe('OrganizationList', () => {
  });
  });
 
- fixtures.clerk.user?.getOrganizationMemberships.mockReturnValueOnce(
+ fixtures.clerk.user?.getOrganizationMemberships.mockReturnValue(
  Promise.resolve({
  data: [
  createFakeUserOrganizationMembership({
@@ -156,7 +156,7 @@ describe('OrganizationList', () => {
  }),
  );
 
- fixtures.clerk.user?.getOrganizationInvitations.mockReturnValueOnce(
+ fixtures.clerk.user?.getOrganizationInvitations.mockReturnValue(
  Promise.resolve({
  data: [invitation],
  total_count: 1,
@@ -342,7 +342,7 @@ describe('OrganizationList', () => {
  });
 
  await waitFor(async () => {
- fixtures.clerk.setActive.mockReturnValueOnce(Promise.resolve());
+ fixtures.clerk.setActive.mockReturnValue(Promise.resolve());
  await userEvent.click(getByText(/Personal account/i));
 
  expect(fixtures.router.navigate).toHaveBeenCalledWith(`/user/test_user_id`);
@@ -376,7 +376,7 @@ describe('OrganizationList', () => {
  },
  });
 
- fixtures.clerk.user?.getOrganizationMemberships.mockReturnValueOnce(
+ fixtures.clerk.user?.getOrganizationMemberships.mockReturnValue(
  Promise.resolve({
  data: [membership],
  total_count: 1,
@@ -392,7 +392,7 @@ describe('OrganizationList', () => {
  });
 
  await waitFor(async () => {
- fixtures.clerk.setActive.mockReturnValueOnce(Promise.resolve());
+ fixtures.clerk.setActive.mockReturnValue(Promise.resolve());
  await userEvent.click(getByRole('button', { name: /Org1/i }));
  expect(fixtures.clerk.setActive).toHaveBeenCalledWith(
  expect.objectContaining({
@@ -423,7 +423,7 @@ describe('OrganizationList', () => {
  wrapper,
  });
 
- fixtures.clerk.setActive.mockReturnValueOnce(Promise.resolve());
+ fixtures.clerk.setActive.mockReturnValue(Promise.resolve());
  await waitFor(async () =>
  expect(await findByRole('menuitem', { name: 'Create organization' })).toBeInTheDocument(),
  );

.changeset/fuzzy-keys-smell.md

@@ -0,0 +1,5 @@
+---
+'@clerk/shared': patch
+---
+
+Build internal variants of all paginated hooks that use React Query instead of SWR.

.github/workflows/ci.yml

@@ -191,7 +191,7 @@ jobs:
  unit-tests:
  needs: [check-permissions, build-packages]
  if: ${{ github.event_name != 'pull_request' || github.event.pull_request.draft == false }}
- name: Unit Tests
+ name: Unit Tests (${{ matrix.node-version }}, ${{ matrix.filter-label }}${{ matrix.clerk-use-rq == 'true' && ', RQ' || '' }})
  permissions:
  contents: read
  actions: write # needed for actions/upload-artifact
@@ -205,11 +205,17 @@ jobs:
  TURBO_SUMMARIZE: false
 
  strategy:
- fail-fast: true
+ fail-fast: false
  matrix:
  include:
  - node-version: 22
  test-filter: "**"
+ clerk-use-rq: "false"
+ filter-label: "**"
+ - node-version: 22
+ test-filter: "--filter=@clerk/shared --filter=@clerk/clerk-js"
+ clerk-use-rq: "true"
+ filter-label: "shared, clerk-js"
 
  steps:
  - name: Checkout Repo
@@ -229,22 +235,35 @@ jobs:
  turbo-team: ${{ vars.TURBO_TEAM }}
  turbo-token: ${{ secrets.TURBO_TOKEN }}
 
+ - name: Rebuild @clerk/shared with CLERK_USE_RQ=true
+ if: ${{ matrix.clerk-use-rq == 'true' }}
+ run: pnpm turbo build $TURBO_ARGS --filter=@clerk/shared --force
+ env:
+ CLERK_USE_RQ: true
+
+ - name: Rebuild dependent packages with CLERK_USE_RQ=true
+ if: ${{ matrix.clerk-use-rq == 'true' }}
+ run: pnpm turbo build $TURBO_ARGS --filter=@clerk/shared^... --force
+ env:
+ CLERK_USE_RQ: true
+
  - name: Run tests in packages
  run: |
  if [ "${{ matrix.test-filter }}" = "**" ]; then
- echo "Running full test suite on Node ${{ matrix.node-version }}."
+ echo "Running full test suite on Node ${{ matrix.node-version }}"
  pnpm turbo test $TURBO_ARGS
  else
- echo "Running LTS subset on Node ${{ matrix.node-version }}."
+ echo "Running tests: ${{ matrix.filter-label }}"
  pnpm turbo test $TURBO_ARGS ${{ matrix.test-filter }}
  fi
  env:
  NODE_VERSION: ${{ matrix.node-version }}
+ CLERK_USE_RQ: ${{ matrix.clerk-use-rq }}
 
  - name: Run Typedoc tests
  run: |
- # Only run Typedoc tests for one matrix version
- if [ "${{ matrix.node-version }}" == "22" ]; then
+ # Only run Typedoc tests for one matrix version and main test run
+ if [ "${{ matrix.node-version }}" == "22" ] && [ "${{ matrix.test-filter }}" = "**" ]; then
  pnpm test:typedoc
  fi
  env:
@@ -255,14 +274,14 @@ jobs:
  if: ${{ env.TURBO_SUMMARIZE == 'true' }}
  continue-on-error: true
  with:
- name: turbo-summary-report-unit-${{ github.run_id }}-${{ github.run_attempt }}-node-${{ matrix.node-version }}
+ name: turbo-summary-report-unit-${{ github.run_id }}-${{ github.run_attempt }}-node-${{ matrix.node-version }}${{ matrix.clerk-use-rq == 'true' && '-rq' || '' }}
  path: .turbo/runs
  retention-days: 5
 
  integration-tests:
  needs: [check-permissions, build-packages]
  if: ${{ github.event_name != 'pull_request' || github.event.pull_request.draft == false }}
- name: Integration Tests
+ name: Integration Tests (${{ matrix.test-name }}, ${{ matrix.test-project }}${{ matrix.next-version && format(', {0}', matrix.next-version) || '' }}${{ matrix.clerk-use-rq == 'true' && ', RQ' || '' }})
  permissions:
  contents: read
  actions: write # needed for actions/upload-artifact
@@ -291,18 +310,28 @@ jobs:
  'vue',
  'nuxt',
  'react-router',
- 'billing',
  'machine',
  'custom',
  ]
  test-project: ["chrome"]
  include:
+ - test-name: 'billing'
+ test-project: 'chrome'
+ clerk-use-rq: 'false'
+ - test-name: 'billing'
+ test-project: 'chrome'
+ clerk-use-rq: 'true'
  - test-name: 'nextjs'
  test-project: 'chrome'
  next-version: '14'
  - test-name: 'nextjs'
  test-project: 'chrome'
  next-version: '15'
+ clerk-use-rq: 'false'
+ - test-name: 'nextjs'
+ test-project: 'chrome'
+ next-version: '15'
+ clerk-use-rq: 'true'
  - test-name: 'nextjs'
  test-project: 'chrome'
  next-version: '16'
@@ -360,12 +389,24 @@ jobs:
  echo "affected=${AFFECTED}"
  echo "affected=${AFFECTED}" >> $GITHUB_OUTPUT
 
+ - name: Rebuild @clerk/shared with CLERK_USE_RQ=true
+ if: ${{ steps.task-status.outputs.affected == '1' && matrix.clerk-use-rq == 'true' }}
+ run: pnpm turbo build $TURBO_ARGS --filter=@clerk/shared --force
+ env:
+ CLERK_USE_RQ: true
+
+ - name: Rebuild dependent packages with CLERK_USE_RQ=true
+ if: ${{ steps.task-status.outputs.affected == '1' && matrix.clerk-use-rq == 'true' }}
+ run: pnpm turbo build $TURBO_ARGS --filter=@clerk/shared^... --force
+ env:
+ CLERK_USE_RQ: true
+
  - name: Verdaccio
  if: ${{ steps.task-status.outputs.affected == '1' }}
  uses: ./.github/actions/verdaccio
  with:
  publish-cmd: |
- if [ "$(pnpm config get registry)" = "https://registry.npmjs.org/" ]; then echo 'Error: Using default registry' && exit 1; else pnpm turbo build $TURBO_ARGS --only && pnpm changeset publish --no-git-tag; fi
+ if [ "$(pnpm config get registry)" = "https://registry.npmjs.org/" ]; then echo 'Error: Using default registry' && exit 1; else CLERK_USE_RQ=${{ matrix.clerk-use-rq }} pnpm turbo build $TURBO_ARGS --only && pnpm changeset publish --no-git-tag; fi
 
  - name: Edit .npmrc [link-workspace-packages=false]
  run: sed -i -E 's/link-workspace-packages=(deep|true)/link-workspace-packages=false/' .npmrc
@@ -425,6 +466,7 @@ jobs:
  E2E_NEXTJS_VERSION: ${{ matrix.next-version }}
  E2E_PROJECT: ${{ matrix.test-project }}
  E2E_CLERK_ENCRYPTION_KEY: ${{ matrix.clerk-encryption-key }}
+ CLERK_USE_RQ: ${{ matrix.clerk-use-rq }}
  INTEGRATION_INSTANCE_KEYS: ${{ secrets.INTEGRATION_INSTANCE_KEYS }}
  MAILSAC_API_KEY: ${{ secrets.MAILSAC_API_KEY }}
  NODE_EXTRA_CA_CERTS: ${{ github.workspace }}/integration/certs/rootCA.pem
@@ -433,7 +475,7 @@ jobs:
  if: ${{ cancelled() || failure() }}
  uses: actions/upload-artifact@v4
  with:
- name: playwright-traces-${{ github.run_id }}-${{ github.run_attempt }}-${{ matrix.test-name }}
+ name: playwright-traces-${{ github.run_id }}-${{ github.run_attempt }}-${{ matrix.test-name }}${{ matrix.next-version && format('-next{0}', matrix.next-version) || '' }}${{ matrix.clerk-use-rq == 'true' && '-rq' || '' }}
  path: integration/test-results
  retention-days: 1
 

packages/clerk-js/src/test/mock-helpers.ts

@@ -1,6 +1,7 @@
 import type { ActiveSessionResource, LoadedClerk } from '@clerk/shared/types';
 import { type Mocked, vi } from 'vitest';
 
+import { QueryClient } from '../core/query-core';
 import type { RouteContextValue } from '../ui/router';
 
 type FunctionLike = (...args: any) => any;
@@ -45,6 +46,20 @@ export const mockClerkMethods = (clerk: LoadedClerk): DeepVitestMocked<LoadedCle
  // Cast clerk to any to allow mocking properties
  const clerkAny = clerk as any;
 
+ const defaultQueryClient = {
+ __tag: 'clerk-rq-client' as const,
+ client: new QueryClient({
+ defaultOptions: {
+ queries: {
+ retry: false,
+ // Setting staleTime to Infinity will not cause issues between tests as long as each test
+ // case has its own wrapper that initializes a Clerk instance with a new QueryClient.
+ staleTime: Infinity,
+ },
+ },
+ }),
+ };
+
  mockMethodsOf(clerkAny);
  if (clerkAny.client) {
  mockMethodsOf(clerkAny.client.signIn);
@@ -76,6 +91,13 @@ export const mockClerkMethods = (clerk: LoadedClerk): DeepVitestMocked<LoadedCle
  if (clerkAny.billing) {
  mockMethodsOf(clerkAny.billing);
  }
+
+ // Mock the __internal_queryClient getter property
+ Object.defineProperty(clerkAny, '__internal_queryClient', {
+ get: vi.fn(() => defaultQueryClient),
+ configurable: true,
+ });
+
  mockProp(clerkAny, 'navigate');
  mockProp(clerkAny, 'setActive');
  mockProp(clerkAny, 'redirectWithAuth');

packages/clerk-js/src/ui/components/Checkout/__tests__/Checkout.test.tsx

@@ -316,6 +316,12 @@ describe('Checkout', () => {
  });
 
  const freeTrialEndsAt = new Date('2025-08-19');
+
+ fixtures.clerk.user?.getPaymentMethods.mockResolvedValue({
+ data: [],
+ total_count: 0,
+ });
+
  fixtures.clerk.billing.startCheckout.mockResolvedValue({
  id: 'chk_trial_1',
  status: 'needs_confirmation',
@@ -1033,13 +1039,18 @@ describe('Checkout', () => {
  { wrapper },
  );
 
- await waitFor(async () => {
+ await waitFor(() => {
  expect(getByRole('heading', { name: 'Checkout' })).toBeVisible();
- const addPaymentMethodButton = getByText('Add payment method');
- expect(addPaymentMethodButton).toBeVisible();
- await userEvent.click(addPaymentMethodButton);
  });
 
+ const addPaymentMethodButton = await waitFor(() => {
+ const button = getByText('Add payment method');
+ expect(button).toBeVisible();
+ return button;
+ });
+
+ await userEvent.click(addPaymentMethodButton);
+
  await waitFor(() => {
  expect(getByRole('button', { name: 'Start free trial' })).toBeInTheDocument();
  });

packages/clerk-js/src/ui/components/OrganizationList/__tests__/OrganizationList.test.tsx

@@ -45,7 +45,7 @@ describe('OrganizationList', () => {
  });
  });
 
- fixtures.clerk.user?.getOrganizationMemberships.mockReturnValueOnce(
+ fixtures.clerk.user?.getOrganizationMemberships.mockReturnValue(
  Promise.resolve({
  data: [
  createFakeUserOrganizationMembership({
@@ -117,7 +117,7 @@ describe('OrganizationList', () => {
  });
  });
 
- fixtures.clerk.user?.getOrganizationMemberships.mockReturnValueOnce(
+ fixtures.clerk.user?.getOrganizationMemberships.mockReturnValue(
  Promise.resolve({
  data: [
  createFakeUserOrganizationMembership({
@@ -156,7 +156,7 @@ describe('OrganizationList', () => {
  }),
  );
 
- fixtures.clerk.user?.getOrganizationInvitations.mockReturnValueOnce(
+ fixtures.clerk.user?.getOrganizationInvitations.mockReturnValue(
  Promise.resolve({
  data: [invitation],
  total_count: 1,
@@ -342,7 +342,7 @@ describe('OrganizationList', () => {
  });
 
  await waitFor(async () => {
- fixtures.clerk.setActive.mockReturnValueOnce(Promise.resolve());
+ fixtures.clerk.setActive.mockReturnValue(Promise.resolve());
  await userEvent.click(getByText(/Personal account/i));
 
  expect(fixtures.router.navigate).toHaveBeenCalledWith(`/user/test_user_id`);
@@ -376,7 +376,7 @@ describe('OrganizationList', () => {
  },
  });
 
- fixtures.clerk.user?.getOrganizationMemberships.mockReturnValueOnce(
+ fixtures.clerk.user?.getOrganizationMemberships.mockReturnValue(
  Promise.resolve({
  data: [membership],
  total_count: 1,
@@ -392,7 +392,7 @@ describe('OrganizationList', () => {
  });
 
  await waitFor(async () => {
- fixtures.clerk.setActive.mockReturnValueOnce(Promise.resolve());
+ fixtures.clerk.setActive.mockReturnValue(Promise.resolve());
  await userEvent.click(getByRole('button', { name: /Org1/i }));
  expect(fixtures.clerk.setActive).toHaveBeenCalledWith(
  expect.objectContaining({
@@ -423,7 +423,7 @@ describe('OrganizationList', () => {
  wrapper,
  });
 
- fixtures.clerk.setActive.mockReturnValueOnce(Promise.resolve());
+ fixtures.clerk.setActive.mockReturnValue(Promise.resolve());
  await waitFor(async () =>
  expect(await findByRole('menuitem', { name: 'Create organization' })).toBeInTheDocument(),
  );

.changeset/fuzzy-keys-smell.md

@@ -0,0 +1,5 @@
+---
+'@clerk/shared': patch
+---
+
+Build internal variants of all paginated hooks that use React Query instead of SWR.

.github/workflows/ci.yml

@@ -191,7 +191,7 @@ jobs:
  unit-tests:
  needs: [check-permissions, build-packages]
  if: ${{ github.event_name != 'pull_request' || github.event.pull_request.draft == false }}
- name: Unit Tests
+ name: Unit Tests (${{ matrix.node-version }}, ${{ matrix.filter-label }}${{ matrix.clerk-use-rq == 'true' && ', RQ' || '' }})
  permissions:
  contents: read
  actions: write # needed for actions/upload-artifact
@@ -205,11 +205,17 @@ jobs:
  TURBO_SUMMARIZE: false
 
  strategy:
- fail-fast: true
+ fail-fast: false
  matrix:
  include:
  - node-version: 22
  test-filter: "**"
+ clerk-use-rq: "false"
+ filter-label: "**"
+ - node-version: 22
+ test-filter: "--filter=@clerk/shared --filter=@clerk/clerk-js"
+ clerk-use-rq: "true"
+ filter-label: "shared, clerk-js"
 
  steps:
  - name: Checkout Repo
@@ -229,22 +235,35 @@ jobs:
  turbo-team: ${{ vars.TURBO_TEAM }}
  turbo-token: ${{ secrets.TURBO_TOKEN }}
 
+ - name: Rebuild @clerk/shared with CLERK_USE_RQ=true
+ if: ${{ matrix.clerk-use-rq == 'true' }}
+ run: pnpm turbo build $TURBO_ARGS --filter=@clerk/shared --force
+ env:
+ CLERK_USE_RQ: true
+
+ - name: Rebuild dependent packages with CLERK_USE_RQ=true
+ if: ${{ matrix.clerk-use-rq == 'true' }}
+ run: pnpm turbo build $TURBO_ARGS --filter=@clerk/shared^... --force
+ env:
+ CLERK_USE_RQ: true
+
  - name: Run tests in packages
  run: |
  if [ "${{ matrix.test-filter }}" = "**" ]; then
- echo "Running full test suite on Node ${{ matrix.node-version }}."
+ echo "Running full test suite on Node ${{ matrix.node-version }}"
  pnpm turbo test $TURBO_ARGS
  else
- echo "Running LTS subset on Node ${{ matrix.node-version }}."
+ echo "Running tests: ${{ matrix.filter-label }}"
  pnpm turbo test $TURBO_ARGS ${{ matrix.test-filter }}
  fi
  env:
  NODE_VERSION: ${{ matrix.node-version }}
+ CLERK_USE_RQ: ${{ matrix.clerk-use-rq }}
 
  - name: Run Typedoc tests
  run: |
- # Only run Typedoc tests for one matrix version
- if [ "${{ matrix.node-version }}" == "22" ]; then
+ # Only run Typedoc tests for one matrix version and main test run
+ if [ "${{ matrix.node-version }}" == "22" ] && [ "${{ matrix.test-filter }}" = "**" ]; then
  pnpm test:typedoc
  fi
  env:
@@ -255,14 +274,14 @@ jobs:
  if: ${{ env.TURBO_SUMMARIZE == 'true' }}
  continue-on-error: true
  with:
- name: turbo-summary-report-unit-${{ github.run_id }}-${{ github.run_attempt }}-node-${{ matrix.node-version }}
+ name: turbo-summary-report-unit-${{ github.run_id }}-${{ github.run_attempt }}-node-${{ matrix.node-version }}${{ matrix.clerk-use-rq == 'true' && '-rq' || '' }}
  path: .turbo/runs
  retention-days: 5
 
  integration-tests:
  needs: [check-permissions, build-packages]
  if: ${{ github.event_name != 'pull_request' || github.event.pull_request.draft == false }}
- name: Integration Tests
+ name: Integration Tests (${{ matrix.test-name }}, ${{ matrix.test-project }}${{ matrix.next-version && format(', {0}', matrix.next-version) || '' }}${{ matrix.clerk-use-rq == 'true' && ', RQ' || '' }})
  permissions:
  contents: read
  actions: write # needed for actions/upload-artifact
@@ -291,18 +310,28 @@ jobs:
  'vue',
  'nuxt',
  'react-router',
- 'billing',
  'machine',
  'custom',
  ]
  test-project: ["chrome"]
  include:
+ - test-name: 'billing'
+ test-project: 'chrome'
+ clerk-use-rq: 'false'
+ - test-name: 'billing'
+ test-project: 'chrome'
+ clerk-use-rq: 'true'
  - test-name: 'nextjs'
  test-project: 'chrome'
  next-version: '14'
  - test-name: 'nextjs'
  test-project: 'chrome'
  next-version: '15'
+ clerk-use-rq: 'false'
+ - test-name: 'nextjs'
+ test-project: 'chrome'
+ next-version: '15'
+ clerk-use-rq: 'true'
  - test-name: 'nextjs'
  test-project: 'chrome'
  next-version: '16'
@@ -360,12 +389,24 @@ jobs:
  echo "affected=${AFFECTED}"
  echo "affected=${AFFECTED}" >> $GITHUB_OUTPUT
 
+ - name: Rebuild @clerk/shared with CLERK_USE_RQ=true
+ if: ${{ steps.task-status.outputs.affected == '1' && matrix.clerk-use-rq == 'true' }}
+ run: pnpm turbo build $TURBO_ARGS --filter=@clerk/shared --force
+ env:
+ CLERK_USE_RQ: true
+
+ - name: Rebuild dependent packages with CLERK_USE_RQ=true
+ if: ${{ steps.task-status.outputs.affected == '1' && matrix.clerk-use-rq == 'true' }}
+ run: pnpm turbo build $TURBO_ARGS --filter=@clerk/shared^... --force
+ env:
+ CLERK_USE_RQ: true
+
  - name: Verdaccio
  if: ${{ steps.task-status.outputs.affected == '1' }}
  uses: ./.github/actions/verdaccio
  with:
  publish-cmd: |
- if [ "$(pnpm config get registry)" = "https://registry.npmjs.org/" ]; then echo 'Error: Using default registry' && exit 1; else pnpm turbo build $TURBO_ARGS --only && pnpm changeset publish --no-git-tag; fi
+ if [ "$(pnpm config get registry)" = "https://registry.npmjs.org/" ]; then echo 'Error: Using default registry' && exit 1; else CLERK_USE_RQ=${{ matrix.clerk-use-rq }} pnpm turbo build $TURBO_ARGS --only && pnpm changeset publish --no-git-tag; fi
 
  - name: Edit .npmrc [link-workspace-packages=false]
  run: sed -i -E 's/link-workspace-packages=(deep|true)/link-workspace-packages=false/' .npmrc
@@ -425,6 +466,7 @@ jobs:
  E2E_NEXTJS_VERSION: ${{ matrix.next-version }}
  E2E_PROJECT: ${{ matrix.test-project }}
  E2E_CLERK_ENCRYPTION_KEY: ${{ matrix.clerk-encryption-key }}
+ CLERK_USE_RQ: ${{ matrix.clerk-use-rq }}
  INTEGRATION_INSTANCE_KEYS: ${{ secrets.INTEGRATION_INSTANCE_KEYS }}
  MAILSAC_API_KEY: ${{ secrets.MAILSAC_API_KEY }}
  NODE_EXTRA_CA_CERTS: ${{ github.workspace }}/integration/certs/rootCA.pem
@@ -433,7 +475,7 @@ jobs:
  if: ${{ cancelled() || failure() }}
  uses: actions/upload-artifact@v4
  with:
- name: playwright-traces-${{ github.run_id }}-${{ github.run_attempt }}-${{ matrix.test-name }}
+ name: playwright-traces-${{ github.run_id }}-${{ github.run_attempt }}-${{ matrix.test-name }}${{ matrix.next-version && format('-next{0}', matrix.next-version) || '' }}${{ matrix.clerk-use-rq == 'true' && '-rq' || '' }}
  path: integration/test-results
  retention-days: 1
 

packages/clerk-js/src/test/mock-helpers.ts

@@ -1,6 +1,7 @@
 import type { ActiveSessionResource, LoadedClerk } from '@clerk/shared/types';
 import { type Mocked, vi } from 'vitest';
 
+import { QueryClient } from '../core/query-core';
 import type { RouteContextValue } from '../ui/router';
 
 type FunctionLike = (...args: any) => any;
@@ -45,6 +46,20 @@ export const mockClerkMethods = (clerk: LoadedClerk): DeepVitestMocked<LoadedCle
  // Cast clerk to any to allow mocking properties
  const clerkAny = clerk as any;
 
+ const defaultQueryClient = {
+ __tag: 'clerk-rq-client' as const,
+ client: new QueryClient({
+ defaultOptions: {
+ queries: {
+ retry: false,
+ // Setting staleTime to Infinity will not cause issues between tests as long as each test
+ // case has its own wrapper that initializes a Clerk instance with a new QueryClient.
+ staleTime: Infinity,
+ },
+ },
+ }),
+ };
+
  mockMethodsOf(clerkAny);
  if (clerkAny.client) {
  mockMethodsOf(clerkAny.client.signIn);
@@ -76,6 +91,13 @@ export const mockClerkMethods = (clerk: LoadedClerk): DeepVitestMocked<LoadedCle
  if (clerkAny.billing) {
  mockMethodsOf(clerkAny.billing);
  }
+
+ // Mock the __internal_queryClient getter property
+ Object.defineProperty(clerkAny, '__internal_queryClient', {
+ get: vi.fn(() => defaultQueryClient),
+ configurable: true,
+ });
+
  mockProp(clerkAny, 'navigate');
  mockProp(clerkAny, 'setActive');
  mockProp(clerkAny, 'redirectWithAuth');

packages/clerk-js/src/ui/components/Checkout/__tests__/Checkout.test.tsx

@@ -316,6 +316,12 @@ describe('Checkout', () => {
  });
 
  const freeTrialEndsAt = new Date('2025-08-19');
+
+ fixtures.clerk.user?.getPaymentMethods.mockResolvedValue({
+ data: [],
+ total_count: 0,
+ });
+
  fixtures.clerk.billing.startCheckout.mockResolvedValue({
  id: 'chk_trial_1',
  status: 'needs_confirmation',
@@ -1033,13 +1039,18 @@ describe('Checkout', () => {
  { wrapper },
  );
 
- await waitFor(async () => {
+ await waitFor(() => {
  expect(getByRole('heading', { name: 'Checkout' })).toBeVisible();
- const addPaymentMethodButton = getByText('Add payment method');
- expect(addPaymentMethodButton).toBeVisible();
- await userEvent.click(addPaymentMethodButton);
  });
 
+ const addPaymentMethodButton = await waitFor(() => {
+ const button = getByText('Add payment method');
+ expect(button).toBeVisible();
+ return button;
+ });
+
+ await userEvent.click(addPaymentMethodButton);
+
  await waitFor(() => {
  expect(getByRole('button', { name: 'Start free trial' })).toBeInTheDocument();
  });

packages/clerk-js/src/ui/components/OrganizationList/__tests__/OrganizationList.test.tsx

@@ -45,7 +45,7 @@ describe('OrganizationList', () => {
  });
  });
 
- fixtures.clerk.user?.getOrganizationMemberships.mockReturnValueOnce(
+ fixtures.clerk.user?.getOrganizationMemberships.mockReturnValue(
  Promise.resolve({
  data: [
  createFakeUserOrganizationMembership({
@@ -117,7 +117,7 @@ describe('OrganizationList', () => {
  });
  });
 
- fixtures.clerk.user?.getOrganizationMemberships.mockReturnValueOnce(
+ fixtures.clerk.user?.getOrganizationMemberships.mockReturnValue(
  Promise.resolve({
  data: [
  createFakeUserOrganizationMembership({
@@ -156,7 +156,7 @@ describe('OrganizationList', () => {
  }),
  );
 
- fixtures.clerk.user?.getOrganizationInvitations.mockReturnValueOnce(
+ fixtures.clerk.user?.getOrganizationInvitations.mockReturnValue(
  Promise.resolve({
  data: [invitation],
  total_count: 1,
@@ -342,7 +342,7 @@ describe('OrganizationList', () => {
  });
 
  await waitFor(async () => {
- fixtures.clerk.setActive.mockReturnValueOnce(Promise.resolve());
+ fixtures.clerk.setActive.mockReturnValue(Promise.resolve());
  await userEvent.click(getByText(/Personal account/i));
 
  expect(fixtures.router.navigate).toHaveBeenCalledWith(`/user/test_user_id`);
@@ -376,7 +376,7 @@ describe('OrganizationList', () => {
  },
  });
 
- fixtures.clerk.user?.getOrganizationMemberships.mockReturnValueOnce(
+ fixtures.clerk.user?.getOrganizationMemberships.mockReturnValue(
  Promise.resolve({
  data: [membership],
  total_count: 1,
@@ -392,7 +392,7 @@ describe('OrganizationList', () => {
  });
 
  await waitFor(async () => {
- fixtures.clerk.setActive.mockReturnValueOnce(Promise.resolve());
+ fixtures.clerk.setActive.mockReturnValue(Promise.resolve());
  await userEvent.click(getByRole('button', { name: /Org1/i }));
  expect(fixtures.clerk.setActive).toHaveBeenCalledWith(
  expect.objectContaining({
@@ -423,7 +423,7 @@ describe('OrganizationList', () => {
  wrapper,
  });
 
- fixtures.clerk.setActive.mockReturnValueOnce(Promise.resolve());
+ fixtures.clerk.setActive.mockReturnValue(Promise.resolve());
  await waitFor(async () =>
  expect(await findByRole('menuitem', { name: 'Create organization' })).toBeInTheDocument(),
  );

.changeset/fuzzy-keys-smell.md

@@ -0,0 +1,5 @@
+---
+'@clerk/shared': patch
+---
+
+Build internal variants of all paginated hooks that use React Query instead of SWR.

.github/workflows/ci.yml

@@ -191,7 +191,7 @@ jobs:
  unit-tests:
  needs: [check-permissions, build-packages]
  if: ${{ github.event_name != 'pull_request' || github.event.pull_request.draft == false }}
- name: Unit Tests
+ name: Unit Tests (${{ matrix.node-version }}, ${{ matrix.filter-label }}${{ matrix.clerk-use-rq == 'true' && ', RQ' || '' }})
  permissions:
  contents: read
  actions: write # needed for actions/upload-artifact
@@ -205,11 +205,17 @@ jobs:
  TURBO_SUMMARIZE: false
 
  strategy:
- fail-fast: true
+ fail-fast: false
  matrix:
  include:
  - node-version: 22
  test-filter: "**"
+ clerk-use-rq: "false"
+ filter-label: "**"
+ - node-version: 22
+ test-filter: "--filter=@clerk/shared --filter=@clerk/clerk-js"
+ clerk-use-rq: "true"
+ filter-label: "shared, clerk-js"
 
  steps:
  - name: Checkout Repo
@@ -229,22 +235,35 @@ jobs:
  turbo-team: ${{ vars.TURBO_TEAM }}
  turbo-token: ${{ secrets.TURBO_TOKEN }}
 
+ - name: Rebuild @clerk/shared with CLERK_USE_RQ=true
+ if: ${{ matrix.clerk-use-rq == 'true' }}
+ run: pnpm turbo build $TURBO_ARGS --filter=@clerk/shared --force
+ env:
+ CLERK_USE_RQ: true
+
+ - name: Rebuild dependent packages with CLERK_USE_RQ=true
+ if: ${{ matrix.clerk-use-rq == 'true' }}
+ run: pnpm turbo build $TURBO_ARGS --filter=@clerk/shared^... --force
+ env:
+ CLERK_USE_RQ: true
+
  - name: Run tests in packages
  run: |
  if [ "${{ matrix.test-filter }}" = "**" ]; then
- echo "Running full test suite on Node ${{ matrix.node-version }}."
+ echo "Running full test suite on Node ${{ matrix.node-version }}"
  pnpm turbo test $TURBO_ARGS
  else
- echo "Running LTS subset on Node ${{ matrix.node-version }}."
+ echo "Running tests: ${{ matrix.filter-label }}"
  pnpm turbo test $TURBO_ARGS ${{ matrix.test-filter }}
  fi
  env:
  NODE_VERSION: ${{ matrix.node-version }}
+ CLERK_USE_RQ: ${{ matrix.clerk-use-rq }}
 
  - name: Run Typedoc tests
  run: |
- # Only run Typedoc tests for one matrix version
- if [ "${{ matrix.node-version }}" == "22" ]; then
+ # Only run Typedoc tests for one matrix version and main test run
+ if [ "${{ matrix.node-version }}" == "22" ] && [ "${{ matrix.test-filter }}" = "**" ]; then
  pnpm test:typedoc
  fi
  env:
@@ -255,14 +274,14 @@ jobs:
  if: ${{ env.TURBO_SUMMARIZE == 'true' }}
  continue-on-error: true
  with:
- name: turbo-summary-report-unit-${{ github.run_id }}-${{ github.run_attempt }}-node-${{ matrix.node-version }}
+ name: turbo-summary-report-unit-${{ github.run_id }}-${{ github.run_attempt }}-node-${{ matrix.node-version }}${{ matrix.clerk-use-rq == 'true' && '-rq' || '' }}
  path: .turbo/runs
  retention-days: 5
 
  integration-tests:
  needs: [check-permissions, build-packages]
  if: ${{ github.event_name != 'pull_request' || github.event.pull_request.draft == false }}
- name: Integration Tests
+ name: Integration Tests (${{ matrix.test-name }}, ${{ matrix.test-project }}${{ matrix.next-version && format(', {0}', matrix.next-version) || '' }}${{ matrix.clerk-use-rq == 'true' && ', RQ' || '' }})
  permissions:
  contents: read
  actions: write # needed for actions/upload-artifact
@@ -291,18 +310,28 @@ jobs:
  'vue',
  'nuxt',
  'react-router',
- 'billing',
  'machine',
  'custom',
  ]
  test-project: ["chrome"]
  include:
+ - test-name: 'billing'
+ test-project: 'chrome'
+ clerk-use-rq: 'false'
+ - test-name: 'billing'
+ test-project: 'chrome'
+ clerk-use-rq: 'true'
  - test-name: 'nextjs'
  test-project: 'chrome'
  next-version: '14'
  - test-name: 'nextjs'
  test-project: 'chrome'
  next-version: '15'
+ clerk-use-rq: 'false'
+ - test-name: 'nextjs'
+ test-project: 'chrome'
+ next-version: '15'
+ clerk-use-rq: 'true'
  - test-name: 'nextjs'
  test-project: 'chrome'
  next-version: '16'
@@ -360,12 +389,24 @@ jobs:
  echo "affected=${AFFECTED}"
  echo "affected=${AFFECTED}" >> $GITHUB_OUTPUT
 
+ - name: Rebuild @clerk/shared with CLERK_USE_RQ=true
+ if: ${{ steps.task-status.outputs.affected == '1' && matrix.clerk-use-rq == 'true' }}
+ run: pnpm turbo build $TURBO_ARGS --filter=@clerk/shared --force
+ env:
+ CLERK_USE_RQ: true
+
+ - name: Rebuild dependent packages with CLERK_USE_RQ=true
+ if: ${{ steps.task-status.outputs.affected == '1' && matrix.clerk-use-rq == 'true' }}
+ run: pnpm turbo build $TURBO_ARGS --filter=@clerk/shared^... --force
+ env:
+ CLERK_USE_RQ: true
+
  - name: Verdaccio
  if: ${{ steps.task-status.outputs.affected == '1' }}
  uses: ./.github/actions/verdaccio
  with:
  publish-cmd: |
- if [ "$(pnpm config get registry)" = "https://registry.npmjs.org/" ]; then echo 'Error: Using default registry' && exit 1; else pnpm turbo build $TURBO_ARGS --only && pnpm changeset publish --no-git-tag; fi
+ if [ "$(pnpm config get registry)" = "https://registry.npmjs.org/" ]; then echo 'Error: Using default registry' && exit 1; else CLERK_USE_RQ=${{ matrix.clerk-use-rq }} pnpm turbo build $TURBO_ARGS --only && pnpm changeset publish --no-git-tag; fi
 
  - name: Edit .npmrc [link-workspace-packages=false]
  run: sed -i -E 's/link-workspace-packages=(deep|true)/link-workspace-packages=false/' .npmrc
@@ -425,6 +466,7 @@ jobs:
  E2E_NEXTJS_VERSION: ${{ matrix.next-version }}
  E2E_PROJECT: ${{ matrix.test-project }}
  E2E_CLERK_ENCRYPTION_KEY: ${{ matrix.clerk-encryption-key }}
+ CLERK_USE_RQ: ${{ matrix.clerk-use-rq }}
  INTEGRATION_INSTANCE_KEYS: ${{ secrets.INTEGRATION_INSTANCE_KEYS }}
  MAILSAC_API_KEY: ${{ secrets.MAILSAC_API_KEY }}
  NODE_EXTRA_CA_CERTS: ${{ github.workspace }}/integration/certs/rootCA.pem
@@ -433,7 +475,7 @@ jobs:
  if: ${{ cancelled() || failure() }}
  uses: actions/upload-artifact@v4
  with:
- name: playwright-traces-${{ github.run_id }}-${{ github.run_attempt }}-${{ matrix.test-name }}
+ name: playwright-traces-${{ github.run_id }}-${{ github.run_attempt }}-${{ matrix.test-name }}${{ matrix.next-version && format('-next{0}', matrix.next-version) || '' }}${{ matrix.clerk-use-rq == 'true' && '-rq' || '' }}
  path: integration/test-results
  retention-days: 1
 

packages/clerk-js/src/test/mock-helpers.ts

@@ -1,6 +1,7 @@
 import type { ActiveSessionResource, LoadedClerk } from '@clerk/shared/types';
 import { type Mocked, vi } from 'vitest';
 
+import { QueryClient } from '../core/query-core';
 import type { RouteContextValue } from '../ui/router';
 
 type FunctionLike = (...args: any) => any;
@@ -45,6 +46,20 @@ export const mockClerkMethods = (clerk: LoadedClerk): DeepVitestMocked<LoadedCle
  // Cast clerk to any to allow mocking properties
  const clerkAny = clerk as any;
 
+ const defaultQueryClient = {
+ __tag: 'clerk-rq-client' as const,
+ client: new QueryClient({
+ defaultOptions: {
+ queries: {
+ retry: false,
+ // Setting staleTime to Infinity will not cause issues between tests as long as each test
+ // case has its own wrapper that initializes a Clerk instance with a new QueryClient.
+ staleTime: Infinity,
+ },
+ },
+ }),
+ };
+
  mockMethodsOf(clerkAny);
  if (clerkAny.client) {
  mockMethodsOf(clerkAny.client.signIn);
@@ -76,6 +91,13 @@ export const mockClerkMethods = (clerk: LoadedClerk): DeepVitestMocked<LoadedCle
  if (clerkAny.billing) {
  mockMethodsOf(clerkAny.billing);
  }
+
+ // Mock the __internal_queryClient getter property
+ Object.defineProperty(clerkAny, '__internal_queryClient', {
+ get: vi.fn(() => defaultQueryClient),
+ configurable: true,
+ });
+
  mockProp(clerkAny, 'navigate');
  mockProp(clerkAny, 'setActive');
  mockProp(clerkAny, 'redirectWithAuth');

packages/clerk-js/src/ui/components/Checkout/__tests__/Checkout.test.tsx

@@ -316,6 +316,12 @@ describe('Checkout', () => {
  });
 
  const freeTrialEndsAt = new Date('2025-08-19');
+
+ fixtures.clerk.user?.getPaymentMethods.mockResolvedValue({
+ data: [],
+ total_count: 0,
+ });
+
  fixtures.clerk.billing.startCheckout.mockResolvedValue({
  id: 'chk_trial_1',
  status: 'needs_confirmation',
@@ -1033,13 +1039,18 @@ describe('Checkout', () => {
  { wrapper },
  );
 
- await waitFor(async () => {
+ await waitFor(() => {
  expect(getByRole('heading', { name: 'Checkout' })).toBeVisible();
- const addPaymentMethodButton = getByText('Add payment method');
- expect(addPaymentMethodButton).toBeVisible();
- await userEvent.click(addPaymentMethodButton);
  });
 
+ const addPaymentMethodButton = await waitFor(() => {
+ const button = getByText('Add payment method');
+ expect(button).toBeVisible();
+ return button;
+ });
+
+ await userEvent.click(addPaymentMethodButton);
+
  await waitFor(() => {
  expect(getByRole('button', { name: 'Start free trial' })).toBeInTheDocument();
  });

packages/clerk-js/src/ui/components/OrganizationList/__tests__/OrganizationList.test.tsx

@@ -45,7 +45,7 @@ describe('OrganizationList', () => {
  });
  });
 
- fixtures.clerk.user?.getOrganizationMemberships.mockReturnValueOnce(
+ fixtures.clerk.user?.getOrganizationMemberships.mockReturnValue(
  Promise.resolve({
  data: [
  createFakeUserOrganizationMembership({
@@ -117,7 +117,7 @@ describe('OrganizationList', () => {
  });
  });
 
- fixtures.clerk.user?.getOrganizationMemberships.mockReturnValueOnce(
+ fixtures.clerk.user?.getOrganizationMemberships.mockReturnValue(
  Promise.resolve({
  data: [
  createFakeUserOrganizationMembership({
@@ -156,7 +156,7 @@ describe('OrganizationList', () => {
  }),
  );
 
- fixtures.clerk.user?.getOrganizationInvitations.mockReturnValueOnce(
+ fixtures.clerk.user?.getOrganizationInvitations.mockReturnValue(
  Promise.resolve({
  data: [invitation],
  total_count: 1,
@@ -342,7 +342,7 @@ describe('OrganizationList', () => {
  });
 
  await waitFor(async () => {
- fixtures.clerk.setActive.mockReturnValueOnce(Promise.resolve());
+ fixtures.clerk.setActive.mockReturnValue(Promise.resolve());
  await userEvent.click(getByText(/Personal account/i));
 
  expect(fixtures.router.navigate).toHaveBeenCalledWith(`/user/test_user_id`);
@@ -376,7 +376,7 @@ describe('OrganizationList', () => {
  },
  });
 
- fixtures.clerk.user?.getOrganizationMemberships.mockReturnValueOnce(
+ fixtures.clerk.user?.getOrganizationMemberships.mockReturnValue(
  Promise.resolve({
  data: [membership],
  total_count: 1,
@@ -392,7 +392,7 @@ describe('OrganizationList', () => {
  });
 
  await waitFor(async () => {
- fixtures.clerk.setActive.mockReturnValueOnce(Promise.resolve());
+ fixtures.clerk.setActive.mockReturnValue(Promise.resolve());
  await userEvent.click(getByRole('button', { name: /Org1/i }));
  expect(fixtures.clerk.setActive).toHaveBeenCalledWith(
  expect.objectContaining({
@@ -423,7 +423,7 @@ describe('OrganizationList', () => {
  wrapper,
  });
 
- fixtures.clerk.setActive.mockReturnValueOnce(Promise.resolve());
+ fixtures.clerk.setActive.mockReturnValue(Promise.resolve());
  await waitFor(async () =>
  expect(await findByRole('menuitem', { name: 'Create organization' })).toBeInTheDocument(),
  );

.changeset/fuzzy-keys-smell.md

@@ -0,0 +1,5 @@
+---
+'@clerk/shared': patch
+---
+
+Build internal variants of all paginated hooks that use React Query instead of SWR.

.github/workflows/ci.yml

@@ -191,7 +191,7 @@ jobs:
  unit-tests:
  needs: [check-permissions, build-packages]
  if: ${{ github.event_name != 'pull_request' || github.event.pull_request.draft == false }}
- name: Unit Tests
+ name: Unit Tests (${{ matrix.node-version }}, ${{ matrix.filter-label }}${{ matrix.clerk-use-rq == 'true' && ', RQ' || '' }})
  permissions:
  contents: read
  actions: write # needed for actions/upload-artifact
@@ -205,11 +205,17 @@ jobs:
  TURBO_SUMMARIZE: false
 
  strategy:
- fail-fast: true
+ fail-fast: false
  matrix:
  include:
  - node-version: 22
  test-filter: "**"
+ clerk-use-rq: "false"
+ filter-label: "**"
+ - node-version: 22
+ test-filter: "--filter=@clerk/shared --filter=@clerk/clerk-js"
+ clerk-use-rq: "true"
+ filter-label: "shared, clerk-js"
 
  steps:
  - name: Checkout Repo
@@ -229,22 +235,35 @@ jobs:
  turbo-team: ${{ vars.TURBO_TEAM }}
  turbo-token: ${{ secrets.TURBO_TOKEN }}
 
+ - name: Rebuild @clerk/shared with CLERK_USE_RQ=true
+ if: ${{ matrix.clerk-use-rq == 'true' }}
+ run: pnpm turbo build $TURBO_ARGS --filter=@clerk/shared --force
+ env:
+ CLERK_USE_RQ: true
+
+ - name: Rebuild dependent packages with CLERK_USE_RQ=true
+ if: ${{ matrix.clerk-use-rq == 'true' }}
+ run: pnpm turbo build $TURBO_ARGS --filter=@clerk/shared^... --force
+ env:
+ CLERK_USE_RQ: true
+
  - name: Run tests in packages
  run: |
  if [ "${{ matrix.test-filter }}" = "**" ]; then
- echo "Running full test suite on Node ${{ matrix.node-version }}."
+ echo "Running full test suite on Node ${{ matrix.node-version }}"
  pnpm turbo test $TURBO_ARGS
  else
- echo "Running LTS subset on Node ${{ matrix.node-version }}."
+ echo "Running tests: ${{ matrix.filter-label }}"
  pnpm turbo test $TURBO_ARGS ${{ matrix.test-filter }}
  fi
  env:
  NODE_VERSION: ${{ matrix.node-version }}
+ CLERK_USE_RQ: ${{ matrix.clerk-use-rq }}
 
  - name: Run Typedoc tests
  run: |
- # Only run Typedoc tests for one matrix version
- if [ "${{ matrix.node-version }}" == "22" ]; then
+ # Only run Typedoc tests for one matrix version and main test run
+ if [ "${{ matrix.node-version }}" == "22" ] && [ "${{ matrix.test-filter }}" = "**" ]; then
  pnpm test:typedoc
  fi
  env:
@@ -255,14 +274,14 @@ jobs:
  if: ${{ env.TURBO_SUMMARIZE == 'true' }}
  continue-on-error: true
  with:
- name: turbo-summary-report-unit-${{ github.run_id }}-${{ github.run_attempt }}-node-${{ matrix.node-version }}
+ name: turbo-summary-report-unit-${{ github.run_id }}-${{ github.run_attempt }}-node-${{ matrix.node-version }}${{ matrix.clerk-use-rq == 'true' && '-rq' || '' }}
  path: .turbo/runs
  retention-days: 5
 
  integration-tests:
  needs: [check-permissions, build-packages]
  if: ${{ github.event_name != 'pull_request' || github.event.pull_request.draft == false }}
- name: Integration Tests
+ name: Integration Tests (${{ matrix.test-name }}, ${{ matrix.test-project }}${{ matrix.next-version && format(', {0}', matrix.next-version) || '' }}${{ matrix.clerk-use-rq == 'true' && ', RQ' || '' }})
  permissions:
  contents: read
  actions: write # needed for actions/upload-artifact
@@ -291,18 +310,28 @@ jobs:
  'vue',
  'nuxt',
  'react-router',
- 'billing',
  'machine',
  'custom',
  ]
  test-project: ["chrome"]
  include:
+ - test-name: 'billing'
+ test-project: 'chrome'
+ clerk-use-rq: 'false'
+ - test-name: 'billing'
+ test-project: 'chrome'
+ clerk-use-rq: 'true'
  - test-name: 'nextjs'
  test-project: 'chrome'
  next-version: '14'
  - test-name: 'nextjs'
  test-project: 'chrome'
  next-version: '15'
+ clerk-use-rq: 'false'
+ - test-name: 'nextjs'
+ test-project: 'chrome'
+ next-version: '15'
+ clerk-use-rq: 'true'
  - test-name: 'nextjs'
  test-project: 'chrome'
  next-version: '16'
@@ -360,12 +389,24 @@ jobs:
  echo "affected=${AFFECTED}"
  echo "affected=${AFFECTED}" >> $GITHUB_OUTPUT
 
+ - name: Rebuild @clerk/shared with CLERK_USE_RQ=true
+ if: ${{ steps.task-status.outputs.affected == '1' && matrix.clerk-use-rq == 'true' }}
+ run: pnpm turbo build $TURBO_ARGS --filter=@clerk/shared --force
+ env:
+ CLERK_USE_RQ: true
+
+ - name: Rebuild dependent packages with CLERK_USE_RQ=true
+ if: ${{ steps.task-status.outputs.affected == '1' && matrix.clerk-use-rq == 'true' }}
+ run: pnpm turbo build $TURBO_ARGS --filter=@clerk/shared^... --force
+ env:
+ CLERK_USE_RQ: true
+
  - name: Verdaccio
  if: ${{ steps.task-status.outputs.affected == '1' }}
  uses: ./.github/actions/verdaccio
  with:
  publish-cmd: |
- if [ "$(pnpm config get registry)" = "https://registry.npmjs.org/" ]; then echo 'Error: Using default registry' && exit 1; else pnpm turbo build $TURBO_ARGS --only && pnpm changeset publish --no-git-tag; fi
+ if [ "$(pnpm config get registry)" = "https://registry.npmjs.org/" ]; then echo 'Error: Using default registry' && exit 1; else CLERK_USE_RQ=${{ matrix.clerk-use-rq }} pnpm turbo build $TURBO_ARGS --only && pnpm changeset publish --no-git-tag; fi
 
  - name: Edit .npmrc [link-workspace-packages=false]
  run: sed -i -E 's/link-workspace-packages=(deep|true)/link-workspace-packages=false/' .npmrc
@@ -425,6 +466,7 @@ jobs:
  E2E_NEXTJS_VERSION: ${{ matrix.next-version }}
  E2E_PROJECT: ${{ matrix.test-project }}
  E2E_CLERK_ENCRYPTION_KEY: ${{ matrix.clerk-encryption-key }}
+ CLERK_USE_RQ: ${{ matrix.clerk-use-rq }}
  INTEGRATION_INSTANCE_KEYS: ${{ secrets.INTEGRATION_INSTANCE_KEYS }}
  MAILSAC_API_KEY: ${{ secrets.MAILSAC_API_KEY }}
  NODE_EXTRA_CA_CERTS: ${{ github.workspace }}/integration/certs/rootCA.pem
@@ -433,7 +475,7 @@ jobs:
  if: ${{ cancelled() || failure() }}
  uses: actions/upload-artifact@v4
  with:
- name: playwright-traces-${{ github.run_id }}-${{ github.run_attempt }}-${{ matrix.test-name }}
+ name: playwright-traces-${{ github.run_id }}-${{ github.run_attempt }}-${{ matrix.test-name }}${{ matrix.next-version && format('-next{0}', matrix.next-version) || '' }}${{ matrix.clerk-use-rq == 'true' && '-rq' || '' }}
  path: integration/test-results
  retention-days: 1
 

packages/clerk-js/src/test/mock-helpers.ts

@@ -1,6 +1,7 @@
 import type { ActiveSessionResource, LoadedClerk } from '@clerk/shared/types';
 import { type Mocked, vi } from 'vitest';
 
+import { QueryClient } from '../core/query-core';
 import type { RouteContextValue } from '../ui/router';
 
 type FunctionLike = (...args: any) => any;
@@ -45,6 +46,20 @@ export const mockClerkMethods = (clerk: LoadedClerk): DeepVitestMocked<LoadedCle
  // Cast clerk to any to allow mocking properties
  const clerkAny = clerk as any;
 
+ const defaultQueryClient = {
+ __tag: 'clerk-rq-client' as const,
+ client: new QueryClient({
+ defaultOptions: {
+ queries: {
+ retry: false,
+ // Setting staleTime to Infinity will not cause issues between tests as long as each test
+ // case has its own wrapper that initializes a Clerk instance with a new QueryClient.
+ staleTime: Infinity,
+ },
+ },
+ }),
+ };
+
  mockMethodsOf(clerkAny);
  if (clerkAny.client) {
  mockMethodsOf(clerkAny.client.signIn);
@@ -76,6 +91,13 @@ export const mockClerkMethods = (clerk: LoadedClerk): DeepVitestMocked<LoadedCle
  if (clerkAny.billing) {
  mockMethodsOf(clerkAny.billing);
  }
+
+ // Mock the __internal_queryClient getter property
+ Object.defineProperty(clerkAny, '__internal_queryClient', {
+ get: vi.fn(() => defaultQueryClient),
+ configurable: true,
+ });
+
  mockProp(clerkAny, 'navigate');
  mockProp(clerkAny, 'setActive');
  mockProp(clerkAny, 'redirectWithAuth');

packages/clerk-js/src/ui/components/Checkout/__tests__/Checkout.test.tsx

@@ -316,6 +316,12 @@ describe('Checkout', () => {
  });
 
  const freeTrialEndsAt = new Date('2025-08-19');
+
+ fixtures.clerk.user?.getPaymentMethods.mockResolvedValue({
+ data: [],
+ total_count: 0,
+ });
+
  fixtures.clerk.billing.startCheckout.mockResolvedValue({
  id: 'chk_trial_1',
  status: 'needs_confirmation',
@@ -1033,13 +1039,18 @@ describe('Checkout', () => {
  { wrapper },
  );
 
- await waitFor(async () => {
+ await waitFor(() => {
  expect(getByRole('heading', { name: 'Checkout' })).toBeVisible();
- const addPaymentMethodButton = getByText('Add payment method');
- expect(addPaymentMethodButton).toBeVisible();
- await userEvent.click(addPaymentMethodButton);
  });
 
+ const addPaymentMethodButton = await waitFor(() => {
+ const button = getByText('Add payment method');
+ expect(button).toBeVisible();
+ return button;
+ });
+
+ await userEvent.click(addPaymentMethodButton);
+
  await waitFor(() => {
  expect(getByRole('button', { name: 'Start free trial' })).toBeInTheDocument();
  });

packages/clerk-js/src/ui/components/OrganizationList/__tests__/OrganizationList.test.tsx

@@ -45,7 +45,7 @@ describe('OrganizationList', () => {
  });
  });
 
- fixtures.clerk.user?.getOrganizationMemberships.mockReturnValueOnce(
+ fixtures.clerk.user?.getOrganizationMemberships.mockReturnValue(
  Promise.resolve({
  data: [
  createFakeUserOrganizationMembership({
@@ -117,7 +117,7 @@ describe('OrganizationList', () => {
  });
  });
 
- fixtures.clerk.user?.getOrganizationMemberships.mockReturnValueOnce(
+ fixtures.clerk.user?.getOrganizationMemberships.mockReturnValue(
  Promise.resolve({
  data: [
  createFakeUserOrganizationMembership({
@@ -156,7 +156,7 @@ describe('OrganizationList', () => {
  }),
  );
 
- fixtures.clerk.user?.getOrganizationInvitations.mockReturnValueOnce(
+ fixtures.clerk.user?.getOrganizationInvitations.mockReturnValue(
  Promise.resolve({
  data: [invitation],
  total_count: 1,
@@ -342,7 +342,7 @@ describe('OrganizationList', () => {
  });
 
  await waitFor(async () => {
- fixtures.clerk.setActive.mockReturnValueOnce(Promise.resolve());
+ fixtures.clerk.setActive.mockReturnValue(Promise.resolve());
  await userEvent.click(getByText(/Personal account/i));
 
  expect(fixtures.router.navigate).toHaveBeenCalledWith(`/user/test_user_id`);
@@ -376,7 +376,7 @@ describe('OrganizationList', () => {
  },
  });
 
- fixtures.clerk.user?.getOrganizationMemberships.mockReturnValueOnce(
+ fixtures.clerk.user?.getOrganizationMemberships.mockReturnValue(
  Promise.resolve({
  data: [membership],
  total_count: 1,
@@ -392,7 +392,7 @@ describe('OrganizationList', () => {
  });
 
  await waitFor(async () => {
- fixtures.clerk.setActive.mockReturnValueOnce(Promise.resolve());
+ fixtures.clerk.setActive.mockReturnValue(Promise.resolve());
  await userEvent.click(getByRole('button', { name: /Org1/i }));
  expect(fixtures.clerk.setActive).toHaveBeenCalledWith(
  expect.objectContaining({
@@ -423,7 +423,7 @@ describe('OrganizationList', () => {
  wrapper,
  });
 
- fixtures.clerk.setActive.mockReturnValueOnce(Promise.resolve());
+ fixtures.clerk.setActive.mockReturnValue(Promise.resolve());
  await waitFor(async () =>
  expect(await findByRole('menuitem', { name: 'Create organization' })).toBeInTheDocument(),
  );

.changeset/fuzzy-keys-smell.md

@@ -0,0 +1,5 @@
+---
+'@clerk/shared': patch
+---
+
+Build internal variants of all paginated hooks that use React Query instead of SWR.

.github/workflows/ci.yml

@@ -191,7 +191,7 @@ jobs:
  unit-tests:
  needs: [check-permissions, build-packages]
  if: ${{ github.event_name != 'pull_request' || github.event.pull_request.draft == false }}
- name: Unit Tests
+ name: Unit Tests (${{ matrix.node-version }}, ${{ matrix.filter-label }}${{ matrix.clerk-use-rq == 'true' && ', RQ' || '' }})
  permissions:
  contents: read
  actions: write # needed for actions/upload-artifact
@@ -205,11 +205,17 @@ jobs:
  TURBO_SUMMARIZE: false
 
  strategy:
- fail-fast: true
+ fail-fast: false
  matrix:
  include:
  - node-version: 22
  test-filter: "**"
+ clerk-use-rq: "false"
+ filter-label: "**"
+ - node-version: 22
+ test-filter: "--filter=@clerk/shared --filter=@clerk/clerk-js"
+ clerk-use-rq: "true"
+ filter-label: "shared, clerk-js"
 
  steps:
  - name: Checkout Repo
@@ -229,22 +235,35 @@ jobs:
  turbo-team: ${{ vars.TURBO_TEAM }}
  turbo-token: ${{ secrets.TURBO_TOKEN }}
 
+ - name: Rebuild @clerk/shared with CLERK_USE_RQ=true
+ if: ${{ matrix.clerk-use-rq == 'true' }}
+ run: pnpm turbo build $TURBO_ARGS --filter=@clerk/shared --force
+ env:
+ CLERK_USE_RQ: true
+
+ - name: Rebuild dependent packages with CLERK_USE_RQ=true
+ if: ${{ matrix.clerk-use-rq == 'true' }}
+ run: pnpm turbo build $TURBO_ARGS --filter=@clerk/shared^... --force
+ env:
+ CLERK_USE_RQ: true
+
  - name: Run tests in packages
  run: |
  if [ "${{ matrix.test-filter }}" = "**" ]; then
- echo "Running full test suite on Node ${{ matrix.node-version }}."
+ echo "Running full test suite on Node ${{ matrix.node-version }}"
  pnpm turbo test $TURBO_ARGS
  else
- echo "Running LTS subset on Node ${{ matrix.node-version }}."
+ echo "Running tests: ${{ matrix.filter-label }}"
  pnpm turbo test $TURBO_ARGS ${{ matrix.test-filter }}
  fi
  env:
  NODE_VERSION: ${{ matrix.node-version }}
+ CLERK_USE_RQ: ${{ matrix.clerk-use-rq }}
 
  - name: Run Typedoc tests
  run: |
- # Only run Typedoc tests for one matrix version
- if [ "${{ matrix.node-version }}" == "22" ]; then
+ # Only run Typedoc tests for one matrix version and main test run
+ if [ "${{ matrix.node-version }}" == "22" ] && [ "${{ matrix.test-filter }}" = "**" ]; then
  pnpm test:typedoc
  fi
  env:
@@ -255,14 +274,14 @@ jobs:
  if: ${{ env.TURBO_SUMMARIZE == 'true' }}
  continue-on-error: true
  with:
- name: turbo-summary-report-unit-${{ github.run_id }}-${{ github.run_attempt }}-node-${{ matrix.node-version }}
+ name: turbo-summary-report-unit-${{ github.run_id }}-${{ github.run_attempt }}-node-${{ matrix.node-version }}${{ matrix.clerk-use-rq == 'true' && '-rq' || '' }}
  path: .turbo/runs
  retention-days: 5
 
  integration-tests:
  needs: [check-permissions, build-packages]
  if: ${{ github.event_name != 'pull_request' || github.event.pull_request.draft == false }}
- name: Integration Tests
+ name: Integration Tests (${{ matrix.test-name }}, ${{ matrix.test-project }}${{ matrix.next-version && format(', {0}', matrix.next-version) || '' }}${{ matrix.clerk-use-rq == 'true' && ', RQ' || '' }})
  permissions:
  contents: read
  actions: write # needed for actions/upload-artifact
@@ -291,18 +310,28 @@ jobs:
  'vue',
  'nuxt',
  'react-router',
- 'billing',
  'machine',
  'custom',
  ]
  test-project: ["chrome"]
  include:
+ - test-name: 'billing'
+ test-project: 'chrome'
+ clerk-use-rq: 'false'
+ - test-name: 'billing'
+ test-project: 'chrome'
+ clerk-use-rq: 'true'
  - test-name: 'nextjs'
  test-project: 'chrome'
  next-version: '14'
  - test-name: 'nextjs'
  test-project: 'chrome'
  next-version: '15'
+ clerk-use-rq: 'false'
+ - test-name: 'nextjs'
+ test-project: 'chrome'
+ next-version: '15'
+ clerk-use-rq: 'true'
  - test-name: 'nextjs'
  test-project: 'chrome'
  next-version: '16'
@@ -360,12 +389,24 @@ jobs:
  echo "affected=${AFFECTED}"
  echo "affected=${AFFECTED}" >> $GITHUB_OUTPUT
 
+ - name: Rebuild @clerk/shared with CLERK_USE_RQ=true
+ if: ${{ steps.task-status.outputs.affected == '1' && matrix.clerk-use-rq == 'true' }}
+ run: pnpm turbo build $TURBO_ARGS --filter=@clerk/shared --force
+ env:
+ CLERK_USE_RQ: true
+
+ - name: Rebuild dependent packages with CLERK_USE_RQ=true
+ if: ${{ steps.task-status.outputs.affected == '1' && matrix.clerk-use-rq == 'true' }}
+ run: pnpm turbo build $TURBO_ARGS --filter=@clerk/shared^... --force
+ env:
+ CLERK_USE_RQ: true
+
  - name: Verdaccio
  if: ${{ steps.task-status.outputs.affected == '1' }}
  uses: ./.github/actions/verdaccio
  with:
  publish-cmd: |
- if [ "$(pnpm config get registry)" = "https://registry.npmjs.org/" ]; then echo 'Error: Using default registry' && exit 1; else pnpm turbo build $TURBO_ARGS --only && pnpm changeset publish --no-git-tag; fi
+ if [ "$(pnpm config get registry)" = "https://registry.npmjs.org/" ]; then echo 'Error: Using default registry' && exit 1; else CLERK_USE_RQ=${{ matrix.clerk-use-rq }} pnpm turbo build $TURBO_ARGS --only && pnpm changeset publish --no-git-tag; fi
 
  - name: Edit .npmrc [link-workspace-packages=false]
  run: sed -i -E 's/link-workspace-packages=(deep|true)/link-workspace-packages=false/' .npmrc
@@ -425,6 +466,7 @@ jobs:
  E2E_NEXTJS_VERSION: ${{ matrix.next-version }}
  E2E_PROJECT: ${{ matrix.test-project }}
  E2E_CLERK_ENCRYPTION_KEY: ${{ matrix.clerk-encryption-key }}
+ CLERK_USE_RQ: ${{ matrix.clerk-use-rq }}
  INTEGRATION_INSTANCE_KEYS: ${{ secrets.INTEGRATION_INSTANCE_KEYS }}
  MAILSAC_API_KEY: ${{ secrets.MAILSAC_API_KEY }}
  NODE_EXTRA_CA_CERTS: ${{ github.workspace }}/integration/certs/rootCA.pem
@@ -433,7 +475,7 @@ jobs:
  if: ${{ cancelled() || failure() }}
  uses: actions/upload-artifact@v4
  with:
- name: playwright-traces-${{ github.run_id }}-${{ github.run_attempt }}-${{ matrix.test-name }}
+ name: playwright-traces-${{ github.run_id }}-${{ github.run_attempt }}-${{ matrix.test-name }}${{ matrix.next-version && format('-next{0}', matrix.next-version) || '' }}${{ matrix.clerk-use-rq == 'true' && '-rq' || '' }}
  path: integration/test-results
  retention-days: 1
 

packages/clerk-js/src/test/mock-helpers.ts

@@ -1,6 +1,7 @@
 import type { ActiveSessionResource, LoadedClerk } from '@clerk/shared/types';
 import { type Mocked, vi } from 'vitest';
 
+import { QueryClient } from '../core/query-core';
 import type { RouteContextValue } from '../ui/router';
 
 type FunctionLike = (...args: any) => any;
@@ -45,6 +46,20 @@ export const mockClerkMethods = (clerk: LoadedClerk): DeepVitestMocked<LoadedCle
  // Cast clerk to any to allow mocking properties
  const clerkAny = clerk as any;
 
+ const defaultQueryClient = {
+ __tag: 'clerk-rq-client' as const,
+ client: new QueryClient({
+ defaultOptions: {
+ queries: {
+ retry: false,
+ // Setting staleTime to Infinity will not cause issues between tests as long as each test
+ // case has its own wrapper that initializes a Clerk instance with a new QueryClient.
+ staleTime: Infinity,
+ },
+ },
+ }),
+ };
+
  mockMethodsOf(clerkAny);
  if (clerkAny.client) {
  mockMethodsOf(clerkAny.client.signIn);
@@ -76,6 +91,13 @@ export const mockClerkMethods = (clerk: LoadedClerk): DeepVitestMocked<LoadedCle
  if (clerkAny.billing) {
  mockMethodsOf(clerkAny.billing);
  }
+
+ // Mock the __internal_queryClient getter property
+ Object.defineProperty(clerkAny, '__internal_queryClient', {
+ get: vi.fn(() => defaultQueryClient),
+ configurable: true,
+ });
+
  mockProp(clerkAny, 'navigate');
  mockProp(clerkAny, 'setActive');
  mockProp(clerkAny, 'redirectWithAuth');

packages/clerk-js/src/ui/components/Checkout/__tests__/Checkout.test.tsx

@@ -316,6 +316,12 @@ describe('Checkout', () => {
  });
 
  const freeTrialEndsAt = new Date('2025-08-19');
+
+ fixtures.clerk.user?.getPaymentMethods.mockResolvedValue({
+ data: [],
+ total_count: 0,
+ });
+
  fixtures.clerk.billing.startCheckout.mockResolvedValue({
  id: 'chk_trial_1',
  status: 'needs_confirmation',
@@ -1033,13 +1039,18 @@ describe('Checkout', () => {
  { wrapper },
  );
 
- await waitFor(async () => {
+ await waitFor(() => {
  expect(getByRole('heading', { name: 'Checkout' })).toBeVisible();
- const addPaymentMethodButton = getByText('Add payment method');
- expect(addPaymentMethodButton).toBeVisible();
- await userEvent.click(addPaymentMethodButton);
  });
 
+ const addPaymentMethodButton = await waitFor(() => {
+ const button = getByText('Add payment method');
+ expect(button).toBeVisible();
+ return button;
+ });
+
+ await userEvent.click(addPaymentMethodButton);
+
  await waitFor(() => {
  expect(getByRole('button', { name: 'Start free trial' })).toBeInTheDocument();
  });

packages/clerk-js/src/ui/components/OrganizationList/__tests__/OrganizationList.test.tsx

@@ -45,7 +45,7 @@ describe('OrganizationList', () => {
  });
  });
 
- fixtures.clerk.user?.getOrganizationMemberships.mockReturnValueOnce(
+ fixtures.clerk.user?.getOrganizationMemberships.mockReturnValue(
  Promise.resolve({
  data: [
  createFakeUserOrganizationMembership({
@@ -117,7 +117,7 @@ describe('OrganizationList', () => {
  });
  });
 
- fixtures.clerk.user?.getOrganizationMemberships.mockReturnValueOnce(
+ fixtures.clerk.user?.getOrganizationMemberships.mockReturnValue(
  Promise.resolve({
  data: [
  createFakeUserOrganizationMembership({
@@ -156,7 +156,7 @@ describe('OrganizationList', () => {
  }),
  );
 
- fixtures.clerk.user?.getOrganizationInvitations.mockReturnValueOnce(
+ fixtures.clerk.user?.getOrganizationInvitations.mockReturnValue(
  Promise.resolve({
  data: [invitation],
  total_count: 1,
@@ -342,7 +342,7 @@ describe('OrganizationList', () => {
  });
 
  await waitFor(async () => {
- fixtures.clerk.setActive.mockReturnValueOnce(Promise.resolve());
+ fixtures.clerk.setActive.mockReturnValue(Promise.resolve());
  await userEvent.click(getByText(/Personal account/i));
 
  expect(fixtures.router.navigate).toHaveBeenCalledWith(`/user/test_user_id`);
@@ -376,7 +376,7 @@ describe('OrganizationList', () => {
  },
  });
 
- fixtures.clerk.user?.getOrganizationMemberships.mockReturnValueOnce(
+ fixtures.clerk.user?.getOrganizationMemberships.mockReturnValue(
  Promise.resolve({
  data: [membership],
  total_count: 1,
@@ -392,7 +392,7 @@ describe('OrganizationList', () => {
  });
 
  await waitFor(async () => {
- fixtures.clerk.setActive.mockReturnValueOnce(Promise.resolve());
+ fixtures.clerk.setActive.mockReturnValue(Promise.resolve());
  await userEvent.click(getByRole('button', { name: /Org1/i }));
  expect(fixtures.clerk.setActive).toHaveBeenCalledWith(
  expect.objectContaining({
@@ -423,7 +423,7 @@ describe('OrganizationList', () => {
  wrapper,
  });
 
- fixtures.clerk.setActive.mockReturnValueOnce(Promise.resolve());
+ fixtures.clerk.setActive.mockReturnValue(Promise.resolve());
  await waitFor(async () =>
  expect(await findByRole('menuitem', { name: 'Create organization' })).toBeInTheDocument(),
  );

.changeset/fuzzy-keys-smell.md

@@ -0,0 +1,5 @@
+---
+'@clerk/shared': patch
+---
+
+Build internal variants of all paginated hooks that use React Query instead of SWR.

.github/workflows/ci.yml

@@ -191,7 +191,7 @@ jobs:
  unit-tests:
  needs: [check-permissions, build-packages]
  if: ${{ github.event_name != 'pull_request' || github.event.pull_request.draft == false }}
- name: Unit Tests
+ name: Unit Tests (${{ matrix.node-version }}, ${{ matrix.filter-label }}${{ matrix.clerk-use-rq == 'true' && ', RQ' || '' }})
  permissions:
  contents: read
  actions: write # needed for actions/upload-artifact
@@ -205,11 +205,17 @@ jobs:
  TURBO_SUMMARIZE: false
 
  strategy:
- fail-fast: true
+ fail-fast: false
  matrix:
  include:
  - node-version: 22
  test-filter: "**"
+ clerk-use-rq: "false"
+ filter-label: "**"
+ - node-version: 22
+ test-filter: "--filter=@clerk/shared --filter=@clerk/clerk-js"
+ clerk-use-rq: "true"
+ filter-label: "shared, clerk-js"
 
  steps:
  - name: Checkout Repo
@@ -229,22 +235,35 @@ jobs:
  turbo-team: ${{ vars.TURBO_TEAM }}
  turbo-token: ${{ secrets.TURBO_TOKEN }}
 
+ - name: Rebuild @clerk/shared with CLERK_USE_RQ=true
+ if: ${{ matrix.clerk-use-rq == 'true' }}
+ run: pnpm turbo build $TURBO_ARGS --filter=@clerk/shared --force
+ env:
+ CLERK_USE_RQ: true
+
+ - name: Rebuild dependent packages with CLERK_USE_RQ=true
+ if: ${{ matrix.clerk-use-rq == 'true' }}
+ run: pnpm turbo build $TURBO_ARGS --filter=@clerk/shared^... --force
+ env:
+ CLERK_USE_RQ: true
+
  - name: Run tests in packages
  run: |
  if [ "${{ matrix.test-filter }}" = "**" ]; then
- echo "Running full test suite on Node ${{ matrix.node-version }}."
+ echo "Running full test suite on Node ${{ matrix.node-version }}"
  pnpm turbo test $TURBO_ARGS
  else
- echo "Running LTS subset on Node ${{ matrix.node-version }}."
+ echo "Running tests: ${{ matrix.filter-label }}"
  pnpm turbo test $TURBO_ARGS ${{ matrix.test-filter }}
  fi
  env:
  NODE_VERSION: ${{ matrix.node-version }}
+ CLERK_USE_RQ: ${{ matrix.clerk-use-rq }}
 
  - name: Run Typedoc tests
  run: |
- # Only run Typedoc tests for one matrix version
- if [ "${{ matrix.node-version }}" == "22" ]; then
+ # Only run Typedoc tests for one matrix version and main test run
+ if [ "${{ matrix.node-version }}" == "22" ] && [ "${{ matrix.test-filter }}" = "**" ]; then
  pnpm test:typedoc
  fi
  env:
@@ -255,14 +274,14 @@ jobs:
  if: ${{ env.TURBO_SUMMARIZE == 'true' }}
  continue-on-error: true
  with:
- name: turbo-summary-report-unit-${{ github.run_id }}-${{ github.run_attempt }}-node-${{ matrix.node-version }}
+ name: turbo-summary-report-unit-${{ github.run_id }}-${{ github.run_attempt }}-node-${{ matrix.node-version }}${{ matrix.clerk-use-rq == 'true' && '-rq' || '' }}
  path: .turbo/runs
  retention-days: 5
 
  integration-tests:
  needs: [check-permissions, build-packages]
  if: ${{ github.event_name != 'pull_request' || github.event.pull_request.draft == false }}
- name: Integration Tests
+ name: Integration Tests (${{ matrix.test-name }}, ${{ matrix.test-project }}${{ matrix.next-version && format(', {0}', matrix.next-version) || '' }}${{ matrix.clerk-use-rq == 'true' && ', RQ' || '' }})
  permissions:
  contents: read
  actions: write # needed for actions/upload-artifact
@@ -291,18 +310,28 @@ jobs:
  'vue',
  'nuxt',
  'react-router',
- 'billing',
  'machine',
  'custom',
  ]
  test-project: ["chrome"]
  include:
+ - test-name: 'billing'
+ test-project: 'chrome'
+ clerk-use-rq: 'false'
+ - test-name: 'billing'
+ test-project: 'chrome'
+ clerk-use-rq: 'true'
  - test-name: 'nextjs'
  test-project: 'chrome'
  next-version: '14'
  - test-name: 'nextjs'
  test-project: 'chrome'
  next-version: '15'
+ clerk-use-rq: 'false'
+ - test-name: 'nextjs'
+ test-project: 'chrome'
+ next-version: '15'
+ clerk-use-rq: 'true'
  - test-name: 'nextjs'
  test-project: 'chrome'
  next-version: '16'
@@ -360,12 +389,24 @@ jobs:
  echo "affected=${AFFECTED}"
  echo "affected=${AFFECTED}" >> $GITHUB_OUTPUT
 
+ - name: Rebuild @clerk/shared with CLERK_USE_RQ=true
+ if: ${{ steps.task-status.outputs.affected == '1' && matrix.clerk-use-rq == 'true' }}
+ run: pnpm turbo build $TURBO_ARGS --filter=@clerk/shared --force
+ env:
+ CLERK_USE_RQ: true
+
+ - name: Rebuild dependent packages with CLERK_USE_RQ=true
+ if: ${{ steps.task-status.outputs.affected == '1' && matrix.clerk-use-rq == 'true' }}
+ run: pnpm turbo build $TURBO_ARGS --filter=@clerk/shared^... --force
+ env:
+ CLERK_USE_RQ: true
+
  - name: Verdaccio
  if: ${{ steps.task-status.outputs.affected == '1' }}
  uses: ./.github/actions/verdaccio
  with:
  publish-cmd: |
- if [ "$(pnpm config get registry)" = "https://registry.npmjs.org/" ]; then echo 'Error: Using default registry' && exit 1; else pnpm turbo build $TURBO_ARGS --only && pnpm changeset publish --no-git-tag; fi
+ if [ "$(pnpm config get registry)" = "https://registry.npmjs.org/" ]; then echo 'Error: Using default registry' && exit 1; else CLERK_USE_RQ=${{ matrix.clerk-use-rq }} pnpm turbo build $TURBO_ARGS --only && pnpm changeset publish --no-git-tag; fi
 
  - name: Edit .npmrc [link-workspace-packages=false]
  run: sed -i -E 's/link-workspace-packages=(deep|true)/link-workspace-packages=false/' .npmrc
@@ -425,6 +466,7 @@ jobs:
  E2E_NEXTJS_VERSION: ${{ matrix.next-version }}
  E2E_PROJECT: ${{ matrix.test-project }}
  E2E_CLERK_ENCRYPTION_KEY: ${{ matrix.clerk-encryption-key }}
+ CLERK_USE_RQ: ${{ matrix.clerk-use-rq }}
  INTEGRATION_INSTANCE_KEYS: ${{ secrets.INTEGRATION_INSTANCE_KEYS }}
  MAILSAC_API_KEY: ${{ secrets.MAILSAC_API_KEY }}
  NODE_EXTRA_CA_CERTS: ${{ github.workspace }}/integration/certs/rootCA.pem
@@ -433,7 +475,7 @@ jobs:
  if: ${{ cancelled() || failure() }}
  uses: actions/upload-artifact@v4
  with:
- name: playwright-traces-${{ github.run_id }}-${{ github.run_attempt }}-${{ matrix.test-name }}
+ name: playwright-traces-${{ github.run_id }}-${{ github.run_attempt }}-${{ matrix.test-name }}${{ matrix.next-version && format('-next{0}', matrix.next-version) || '' }}${{ matrix.clerk-use-rq == 'true' && '-rq' || '' }}
  path: integration/test-results
  retention-days: 1
 

packages/clerk-js/src/test/mock-helpers.ts

@@ -1,6 +1,7 @@
 import type { ActiveSessionResource, LoadedClerk } from '@clerk/shared/types';
 import { type Mocked, vi } from 'vitest';
 
+import { QueryClient } from '../core/query-core';
 import type { RouteContextValue } from '../ui/router';
 
 type FunctionLike = (...args: any) => any;
@@ -45,6 +46,20 @@ export const mockClerkMethods = (clerk: LoadedClerk): DeepVitestMocked<LoadedCle
  // Cast clerk to any to allow mocking properties
  const clerkAny = clerk as any;
 
+ const defaultQueryClient = {
+ __tag: 'clerk-rq-client' as const,
+ client: new QueryClient({
+ defaultOptions: {
+ queries: {
+ retry: false,
+ // Setting staleTime to Infinity will not cause issues between tests as long as each test
+ // case has its own wrapper that initializes a Clerk instance with a new QueryClient.
+ staleTime: Infinity,
+ },
+ },
+ }),
+ };
+
  mockMethodsOf(clerkAny);
  if (clerkAny.client) {
  mockMethodsOf(clerkAny.client.signIn);
@@ -76,6 +91,13 @@ export const mockClerkMethods = (clerk: LoadedClerk): DeepVitestMocked<LoadedCle
  if (clerkAny.billing) {
  mockMethodsOf(clerkAny.billing);
  }
+
+ // Mock the __internal_queryClient getter property
+ Object.defineProperty(clerkAny, '__internal_queryClient', {
+ get: vi.fn(() => defaultQueryClient),
+ configurable: true,
+ });
+
  mockProp(clerkAny, 'navigate');
  mockProp(clerkAny, 'setActive');
  mockProp(clerkAny, 'redirectWithAuth');

packages/clerk-js/src/ui/components/Checkout/__tests__/Checkout.test.tsx

@@ -316,6 +316,12 @@ describe('Checkout', () => {
  });
 
  const freeTrialEndsAt = new Date('2025-08-19');
+
+ fixtures.clerk.user?.getPaymentMethods.mockResolvedValue({
+ data: [],
+ total_count: 0,
+ });
+
  fixtures.clerk.billing.startCheckout.mockResolvedValue({
  id: 'chk_trial_1',
  status: 'needs_confirmation',
@@ -1033,13 +1039,18 @@ describe('Checkout', () => {
  { wrapper },
  );
 
- await waitFor(async () => {
+ await waitFor(() => {
  expect(getByRole('heading', { name: 'Checkout' })).toBeVisible();
- const addPaymentMethodButton = getByText('Add payment method');
- expect(addPaymentMethodButton).toBeVisible();
- await userEvent.click(addPaymentMethodButton);
  });
 
+ const addPaymentMethodButton = await waitFor(() => {
+ const button = getByText('Add payment method');
+ expect(button).toBeVisible();
+ return button;
+ });
+
+ await userEvent.click(addPaymentMethodButton);
+
  await waitFor(() => {
  expect(getByRole('button', { name: 'Start free trial' })).toBeInTheDocument();
  });

packages/clerk-js/src/ui/components/OrganizationList/__tests__/OrganizationList.test.tsx

@@ -45,7 +45,7 @@ describe('OrganizationList', () => {
  });
  });
 
- fixtures.clerk.user?.getOrganizationMemberships.mockReturnValueOnce(
+ fixtures.clerk.user?.getOrganizationMemberships.mockReturnValue(
  Promise.resolve({
  data: [
  createFakeUserOrganizationMembership({
@@ -117,7 +117,7 @@ describe('OrganizationList', () => {
  });
  });
 
- fixtures.clerk.user?.getOrganizationMemberships.mockReturnValueOnce(
+ fixtures.clerk.user?.getOrganizationMemberships.mockReturnValue(
  Promise.resolve({
  data: [
  createFakeUserOrganizationMembership({
@@ -156,7 +156,7 @@ describe('OrganizationList', () => {
  }),
  );
 
- fixtures.clerk.user?.getOrganizationInvitations.mockReturnValueOnce(
+ fixtures.clerk.user?.getOrganizationInvitations.mockReturnValue(
  Promise.resolve({
  data: [invitation],
  total_count: 1,
@@ -342,7 +342,7 @@ describe('OrganizationList', () => {
  });
 
  await waitFor(async () => {
- fixtures.clerk.setActive.mockReturnValueOnce(Promise.resolve());
+ fixtures.clerk.setActive.mockReturnValue(Promise.resolve());
  await userEvent.click(getByText(/Personal account/i));
 
  expect(fixtures.router.navigate).toHaveBeenCalledWith(`/user/test_user_id`);
@@ -376,7 +376,7 @@ describe('OrganizationList', () => {
  },
  });
 
- fixtures.clerk.user?.getOrganizationMemberships.mockReturnValueOnce(
+ fixtures.clerk.user?.getOrganizationMemberships.mockReturnValue(
  Promise.resolve({
  data: [membership],
  total_count: 1,
@@ -392,7 +392,7 @@ describe('OrganizationList', () => {
  });
 
  await waitFor(async () => {
- fixtures.clerk.setActive.mockReturnValueOnce(Promise.resolve());
+ fixtures.clerk.setActive.mockReturnValue(Promise.resolve());
  await userEvent.click(getByRole('button', { name: /Org1/i }));
  expect(fixtures.clerk.setActive).toHaveBeenCalledWith(
  expect.objectContaining({
@@ -423,7 +423,7 @@ describe('OrganizationList', () => {
  wrapper,
  });
 
- fixtures.clerk.setActive.mockReturnValueOnce(Promise.resolve());
+ fixtures.clerk.setActive.mockReturnValue(Promise.resolve());
  await waitFor(async () =>
  expect(await findByRole('menuitem', { name: 'Create organization' })).toBeInTheDocument(),
  );

.changeset/fuzzy-keys-smell.md

@@ -0,0 +1,5 @@
+---
+'@clerk/shared': patch
+---
+
+Build internal variants of all paginated hooks that use React Query instead of SWR.

.github/workflows/ci.yml

@@ -191,7 +191,7 @@ jobs:
  unit-tests:
  needs: [check-permissions, build-packages]
  if: ${{ github.event_name != 'pull_request' || github.event.pull_request.draft == false }}
- name: Unit Tests
+ name: Unit Tests (${{ matrix.node-version }}, ${{ matrix.filter-label }}${{ matrix.clerk-use-rq == 'true' && ', RQ' || '' }})
  permissions:
  contents: read
  actions: write # needed for actions/upload-artifact
@@ -205,11 +205,17 @@ jobs:
  TURBO_SUMMARIZE: false
 
  strategy:
- fail-fast: true
+ fail-fast: false
  matrix:
  include:
  - node-version: 22
  test-filter: "**"
+ clerk-use-rq: "false"
+ filter-label: "**"
+ - node-version: 22
+ test-filter: "--filter=@clerk/shared --filter=@clerk/clerk-js"
+ clerk-use-rq: "true"
+ filter-label: "shared, clerk-js"
 
  steps:
  - name: Checkout Repo
@@ -229,22 +235,35 @@ jobs:
  turbo-team: ${{ vars.TURBO_TEAM }}
  turbo-token: ${{ secrets.TURBO_TOKEN }}
 
+ - name: Rebuild @clerk/shared with CLERK_USE_RQ=true
+ if: ${{ matrix.clerk-use-rq == 'true' }}
+ run: pnpm turbo build $TURBO_ARGS --filter=@clerk/shared --force
+ env:
+ CLERK_USE_RQ: true
+
+ - name: Rebuild dependent packages with CLERK_USE_RQ=true
+ if: ${{ matrix.clerk-use-rq == 'true' }}
+ run: pnpm turbo build $TURBO_ARGS --filter=@clerk/shared^... --force
+ env:
+ CLERK_USE_RQ: true
+
  - name: Run tests in packages
  run: |
  if [ "${{ matrix.test-filter }}" = "**" ]; then
- echo "Running full test suite on Node ${{ matrix.node-version }}."
+ echo "Running full test suite on Node ${{ matrix.node-version }}"
  pnpm turbo test $TURBO_ARGS
  else
- echo "Running LTS subset on Node ${{ matrix.node-version }}."
+ echo "Running tests: ${{ matrix.filter-label }}"
  pnpm turbo test $TURBO_ARGS ${{ matrix.test-filter }}
  fi
  env:
  NODE_VERSION: ${{ matrix.node-version }}
+ CLERK_USE_RQ: ${{ matrix.clerk-use-rq }}
 
  - name: Run Typedoc tests
  run: |
- # Only run Typedoc tests for one matrix version
- if [ "${{ matrix.node-version }}" == "22" ]; then
+ # Only run Typedoc tests for one matrix version and main test run
+ if [ "${{ matrix.node-version }}" == "22" ] && [ "${{ matrix.test-filter }}" = "**" ]; then
  pnpm test:typedoc
  fi
  env:
@@ -255,14 +274,14 @@ jobs:
  if: ${{ env.TURBO_SUMMARIZE == 'true' }}
  continue-on-error: true
  with:
- name: turbo-summary-report-unit-${{ github.run_id }}-${{ github.run_attempt }}-node-${{ matrix.node-version }}
+ name: turbo-summary-report-unit-${{ github.run_id }}-${{ github.run_attempt }}-node-${{ matrix.node-version }}${{ matrix.clerk-use-rq == 'true' && '-rq' || '' }}
  path: .turbo/runs
  retention-days: 5
 
  integration-tests:
  needs: [check-permissions, build-packages]
  if: ${{ github.event_name != 'pull_request' || github.event.pull_request.draft == false }}
- name: Integration Tests
+ name: Integration Tests (${{ matrix.test-name }}, ${{ matrix.test-project }}${{ matrix.next-version && format(', {0}', matrix.next-version) || '' }}${{ matrix.clerk-use-rq == 'true' && ', RQ' || '' }})
  permissions:
  contents: read
  actions: write # needed for actions/upload-artifact
@@ -291,18 +310,28 @@ jobs:
  'vue',
  'nuxt',
  'react-router',
- 'billing',
  'machine',
  'custom',
  ]
  test-project: ["chrome"]
  include:
+ - test-name: 'billing'
+ test-project: 'chrome'
+ clerk-use-rq: 'false'
+ - test-name: 'billing'
+ test-project: 'chrome'
+ clerk-use-rq: 'true'
  - test-name: 'nextjs'
  test-project: 'chrome'
  next-version: '14'
  - test-name: 'nextjs'
  test-project: 'chrome'
  next-version: '15'
+ clerk-use-rq: 'false'
+ - test-name: 'nextjs'
+ test-project: 'chrome'
+ next-version: '15'
+ clerk-use-rq: 'true'
  - test-name: 'nextjs'
  test-project: 'chrome'
  next-version: '16'
@@ -360,12 +389,24 @@ jobs:
  echo "affected=${AFFECTED}"
  echo "affected=${AFFECTED}" >> $GITHUB_OUTPUT
 
+ - name: Rebuild @clerk/shared with CLERK_USE_RQ=true
+ if: ${{ steps.task-status.outputs.affected == '1' && matrix.clerk-use-rq == 'true' }}
+ run: pnpm turbo build $TURBO_ARGS --filter=@clerk/shared --force
+ env:
+ CLERK_USE_RQ: true
+
+ - name: Rebuild dependent packages with CLERK_USE_RQ=true
+ if: ${{ steps.task-status.outputs.affected == '1' && matrix.clerk-use-rq == 'true' }}
+ run: pnpm turbo build $TURBO_ARGS --filter=@clerk/shared^... --force
+ env:
+ CLERK_USE_RQ: true
+
  - name: Verdaccio
  if: ${{ steps.task-status.outputs.affected == '1' }}
  uses: ./.github/actions/verdaccio
  with:
  publish-cmd: |
- if [ "$(pnpm config get registry)" = "https://registry.npmjs.org/" ]; then echo 'Error: Using default registry' && exit 1; else pnpm turbo build $TURBO_ARGS --only && pnpm changeset publish --no-git-tag; fi
+ if [ "$(pnpm config get registry)" = "https://registry.npmjs.org/" ]; then echo 'Error: Using default registry' && exit 1; else CLERK_USE_RQ=${{ matrix.clerk-use-rq }} pnpm turbo build $TURBO_ARGS --only && pnpm changeset publish --no-git-tag; fi
 
  - name: Edit .npmrc [link-workspace-packages=false]
  run: sed -i -E 's/link-workspace-packages=(deep|true)/link-workspace-packages=false/' .npmrc
@@ -425,6 +466,7 @@ jobs:
  E2E_NEXTJS_VERSION: ${{ matrix.next-version }}
  E2E_PROJECT: ${{ matrix.test-project }}
  E2E_CLERK_ENCRYPTION_KEY: ${{ matrix.clerk-encryption-key }}
+ CLERK_USE_RQ: ${{ matrix.clerk-use-rq }}
  INTEGRATION_INSTANCE_KEYS: ${{ secrets.INTEGRATION_INSTANCE_KEYS }}
  MAILSAC_API_KEY: ${{ secrets.MAILSAC_API_KEY }}
  NODE_EXTRA_CA_CERTS: ${{ github.workspace }}/integration/certs/rootCA.pem
@@ -433,7 +475,7 @@ jobs:
  if: ${{ cancelled() || failure() }}
  uses: actions/upload-artifact@v4
  with:
- name: playwright-traces-${{ github.run_id }}-${{ github.run_attempt }}-${{ matrix.test-name }}
+ name: playwright-traces-${{ github.run_id }}-${{ github.run_attempt }}-${{ matrix.test-name }}${{ matrix.next-version && format('-next{0}', matrix.next-version) || '' }}${{ matrix.clerk-use-rq == 'true' && '-rq' || '' }}
  path: integration/test-results
  retention-days: 1
 

packages/clerk-js/src/test/mock-helpers.ts

@@ -1,6 +1,7 @@
 import type { ActiveSessionResource, LoadedClerk } from '@clerk/shared/types';
 import { type Mocked, vi } from 'vitest';
 
+import { QueryClient } from '../core/query-core';
 import type { RouteContextValue } from '../ui/router';
 
 type FunctionLike = (...args: any) => any;
@@ -45,6 +46,20 @@ export const mockClerkMethods = (clerk: LoadedClerk): DeepVitestMocked<LoadedCle
  // Cast clerk to any to allow mocking properties
  const clerkAny = clerk as any;
 
+ const defaultQueryClient = {
+ __tag: 'clerk-rq-client' as const,
+ client: new QueryClient({
+ defaultOptions: {
+ queries: {
+ retry: false,
+ // Setting staleTime to Infinity will not cause issues between tests as long as each test
+ // case has its own wrapper that initializes a Clerk instance with a new QueryClient.
+ staleTime: Infinity,
+ },
+ },
+ }),
+ };
+
  mockMethodsOf(clerkAny);
  if (clerkAny.client) {
  mockMethodsOf(clerkAny.client.signIn);
@@ -76,6 +91,13 @@ export const mockClerkMethods = (clerk: LoadedClerk): DeepVitestMocked<LoadedCle
  if (clerkAny.billing) {
  mockMethodsOf(clerkAny.billing);
  }
+
+ // Mock the __internal_queryClient getter property
+ Object.defineProperty(clerkAny, '__internal_queryClient', {
+ get: vi.fn(() => defaultQueryClient),
+ configurable: true,
+ });
+
  mockProp(clerkAny, 'navigate');
  mockProp(clerkAny, 'setActive');
  mockProp(clerkAny, 'redirectWithAuth');

packages/clerk-js/src/ui/components/Checkout/__tests__/Checkout.test.tsx

@@ -316,6 +316,12 @@ describe('Checkout', () => {
  });
 
  const freeTrialEndsAt = new Date('2025-08-19');
+
+ fixtures.clerk.user?.getPaymentMethods.mockResolvedValue({
+ data: [],
+ total_count: 0,
+ });
+
  fixtures.clerk.billing.startCheckout.mockResolvedValue({
  id: 'chk_trial_1',
  status: 'needs_confirmation',
@@ -1033,13 +1039,18 @@ describe('Checkout', () => {
  { wrapper },
  );
 
- await waitFor(async () => {
+ await waitFor(() => {
  expect(getByRole('heading', { name: 'Checkout' })).toBeVisible();
- const addPaymentMethodButton = getByText('Add payment method');
- expect(addPaymentMethodButton).toBeVisible();
- await userEvent.click(addPaymentMethodButton);
  });
 
+ const addPaymentMethodButton = await waitFor(() => {
+ const button = getByText('Add payment method');
+ expect(button).toBeVisible();
+ return button;
+ });
+
+ await userEvent.click(addPaymentMethodButton);
+
  await waitFor(() => {
  expect(getByRole('button', { name: 'Start free trial' })).toBeInTheDocument();
  });

packages/clerk-js/src/ui/components/OrganizationList/__tests__/OrganizationList.test.tsx

@@ -45,7 +45,7 @@ describe('OrganizationList', () => {
  });
  });
 
- fixtures.clerk.user?.getOrganizationMemberships.mockReturnValueOnce(
+ fixtures.clerk.user?.getOrganizationMemberships.mockReturnValue(
  Promise.resolve({
  data: [
  createFakeUserOrganizationMembership({
@@ -117,7 +117,7 @@ describe('OrganizationList', () => {
  });
  });
 
- fixtures.clerk.user?.getOrganizationMemberships.mockReturnValueOnce(
+ fixtures.clerk.user?.getOrganizationMemberships.mockReturnValue(
  Promise.resolve({
  data: [
  createFakeUserOrganizationMembership({
@@ -156,7 +156,7 @@ describe('OrganizationList', () => {
  }),
  );
 
- fixtures.clerk.user?.getOrganizationInvitations.mockReturnValueOnce(
+ fixtures.clerk.user?.getOrganizationInvitations.mockReturnValue(
  Promise.resolve({
  data: [invitation],
  total_count: 1,
@@ -342,7 +342,7 @@ describe('OrganizationList', () => {
  });
 
  await waitFor(async () => {
- fixtures.clerk.setActive.mockReturnValueOnce(Promise.resolve());
+ fixtures.clerk.setActive.mockReturnValue(Promise.resolve());
  await userEvent.click(getByText(/Personal account/i));
 
  expect(fixtures.router.navigate).toHaveBeenCalledWith(`/user/test_user_id`);
@@ -376,7 +376,7 @@ describe('OrganizationList', () => {
  },
  });
 
- fixtures.clerk.user?.getOrganizationMemberships.mockReturnValueOnce(
+ fixtures.clerk.user?.getOrganizationMemberships.mockReturnValue(
  Promise.resolve({
  data: [membership],
  total_count: 1,
@@ -392,7 +392,7 @@ describe('OrganizationList', () => {
  });
 
  await waitFor(async () => {
- fixtures.clerk.setActive.mockReturnValueOnce(Promise.resolve());
+ fixtures.clerk.setActive.mockReturnValue(Promise.resolve());
  await userEvent.click(getByRole('button', { name: /Org1/i }));
  expect(fixtures.clerk.setActive).toHaveBeenCalledWith(
  expect.objectContaining({
@@ -423,7 +423,7 @@ describe('OrganizationList', () => {
  wrapper,
  });
 
- fixtures.clerk.setActive.mockReturnValueOnce(Promise.resolve());
+ fixtures.clerk.setActive.mockReturnValue(Promise.resolve());
  await waitFor(async () =>
  expect(await findByRole('menuitem', { name: 'Create organization' })).toBeInTheDocument(),
  );