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(),
         );