fix(clerk-js): Restore internal queryClient for backward compat with older SDKs (#8562)

Co-authored-by: Jacek <jacek@clerk.dev>

Author: wobsoriano

.changeset/restore-internal-query-client.md

@@ -0,0 +1,5 @@
+---
+'@clerk/clerk-js': patch
+---
+
+Restore the `clerk.__internal_queryClient` getter as a backward-compatibility shim so apps still on `@clerk/shared < 4.10.0` can hydrate their query client and continue to render paginated hooks (e.g. `useOrganizationList`, `useOrganization`). The getter lazily imports `@tanstack/query-core` only when accessed, so apps on `@clerk/shared >= 4.10.0` (which use the singleton in `@clerk/shared`) pay zero runtime cost.

packages/clerk-js/bundlewatch.config.json

@@ -1,14 +1,15 @@
 {
   "files": [
-    { "path": "./dist/clerk.js", "maxSize": "543KB" },
+    { "path": "./dist/clerk.js", "maxSize": "549KB" },
     { "path": "./dist/clerk.browser.js", "maxSize": "70KB" },
     { "path": "./dist/clerk.legacy.browser.js", "maxSize": "112KB" },
-    { "path": "./dist/clerk.no-rhc.js", "maxSize": "311KB" },
+    { "path": "./dist/clerk.no-rhc.js", "maxSize": "316KB" },
     { "path": "./dist/clerk.native.js", "maxSize": "70KB" },
     { "path": "./dist/vendors*.js", "maxSize": "7KB" },
     { "path": "./dist/coinbase*.js", "maxSize": "36KB" },
     { "path": "./dist/base-account-sdk*.js", "maxSize": "203KB" },
     { "path": "./dist/stripe-vendors*.js", "maxSize": "1KB" },
+    { "path": "./dist/query-core-vendors*.js", "maxSize": "11KB" },
     { "path": "./dist/zxcvbn-ts-core*.js", "maxSize": "12KB" },
     { "path": "./dist/zxcvbn-common*.js", "maxSize": "226KB" }
   ]

packages/clerk-js/package.json

@@ -91,6 +91,7 @@
     "@solana/wallet-standard": "catalog:module-manager",
     "@stripe/stripe-js": "5.6.0",
     "@swc/helpers": "catalog:repo",
+    "@tanstack/query-core": "catalog:repo",
     "@wallet-standard/core": "catalog:module-manager",
     "@zxcvbn-ts/core": "catalog:module-manager",
     "@zxcvbn-ts/language-common": "catalog:module-manager",

packages/clerk-js/rspack.config.js

@@ -110,6 +110,12 @@ const common = ({ mode, variant, disableRHC = false }) => {
             chunks: 'all',
             enforce: true,
           },
+          queryCoreVendor: {
+            test: /[\\/]node_modules[\\/](@tanstack\/query-core)[\\/]/,
+            name: 'query-core-vendors',
+            chunks: 'all',
+            enforce: true,
+          },
           defaultVendors: {
             minChunks: 1,
             test: module => {

packages/clerk-js/src/core/__tests__/clerk.internal-query-client.test.ts

@@ -0,0 +1,75 @@
+import { QueryClient } from '@tanstack/query-core';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { Clerk } from '../clerk';
+import { Client, Environment } from '../resources/internal';
+
+vi.mock('../resources/Client');
+vi.mock('../resources/Environment');
+
+vi.mock('../auth/devBrowser', () => ({
+  createDevBrowser: () => ({
+    clear: vi.fn(),
+    setup: vi.fn(),
+    getDevBrowser: vi.fn(() => 'deadbeef'),
+    setDevBrowser: vi.fn(),
+    removeDevBrowser: vi.fn(),
+    refreshCookies: vi.fn(),
+  }),
+}));
+
+Client.getOrCreateInstance = vi.fn().mockImplementation(() => ({ fetch: vi.fn() }));
+Environment.getInstance = vi.fn().mockImplementation(() => ({ fetch: vi.fn(() => Promise.resolve({})) }));
+
+const publishableKey = 'pk_test_Y2xlcmsuYWJjZWYuMTIzNDUuZGV2LmxjbGNsZXJrLmNvbSQ';
+
+describe('Clerk __internal_queryClient (backward compat shim)', () => {
+  let clerk: Clerk;
+
+  beforeEach(() => {
+    clerk = new Clerk(publishableKey);
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('returns undefined before the lazy import resolves', () => {
+    expect(clerk.__internal_queryClient).toBeUndefined();
+  });
+
+  it('returns a tagged QueryClient after the lazy import resolves', async () => {
+    // Trigger the getter (fires the lazy import)
+    void clerk.__internal_queryClient;
+
+    // Wait for the dynamic import and QueryClient construction to settle
+    await vi.dynamicImportSettled();
+
+    const result = clerk.__internal_queryClient;
+    expect(result).toBeDefined();
+    expect(result!.__tag).toBe('clerk-rq-client');
+    expect(result!.client).toBeInstanceOf(QueryClient);
+  });
+
+  it('returns the same QueryClient instance on repeated access', async () => {
+    void clerk.__internal_queryClient;
+    await vi.dynamicImportSettled();
+
+    const first = clerk.__internal_queryClient;
+    const second = clerk.__internal_queryClient;
+    expect(first!.client).toBe(second!.client);
+  });
+
+  it('emits queryClientStatus event when the client is ready', async () => {
+    const listener = vi.fn();
+    // @ts-expect-error - queryClientStatus is not typed on clerk.on
+    clerk.on('queryClientStatus', listener);
+
+    void clerk.__internal_queryClient;
+    await vi.dynamicImportSettled();
+
+    expect(listener).toHaveBeenCalledWith('ready');
+    // @ts-expect-error
+    clerk.off('queryClientStatus', listener);
+  });
+});

packages/clerk-js/src/core/clerk.ts

@@ -140,6 +140,7 @@ import type {
 import type { ClerkUI } from '@clerk/shared/ui';
 import { addClerkPrefix, isAbsoluteUrl, stripScheme } from '@clerk/shared/url';
 import { allSettled, handleValueOrFn, noop } from '@clerk/shared/utils';
+import type { QueryClient } from '@tanstack/query-core';
 
 import { debugLogger, initDebugLogger } from '@/utils/debug';
 import { ModuleManager } from '@/utils/moduleManager';
@@ -252,6 +253,7 @@ export class Clerk implements ClerkInterface {
   // converted to protected environment to support `updateEnvironment` type assertion
   protected environment?: EnvironmentResource | null;
 
+  #queryClient: QueryClient | undefined;
   #publishableKey = '';
   #domain: DomainOrProxyUrl['domain'];
   #proxyUrl: DomainOrProxyUrl['proxyUrl'];
@@ -271,6 +273,28 @@ export class Clerk implements ClerkInterface {
   #touchThrottledUntil = 0;
   #publicEventBus = createClerkEventBus();
 
+  get __internal_queryClient(): { __tag: 'clerk-rq-client'; client: QueryClient } | undefined {
+    if (!this.#queryClient) {
+      void import('./query-core')
+        .then(module => module.QueryClient)
+        .then(QueryClient => {
+          if (this.#queryClient) {
+            return;
+          }
+          this.#queryClient = new QueryClient();
+          // @ts-expect-error - queryClientStatus is not typed
+          this.#publicEventBus.emit('queryClientStatus', 'ready');
+        });
+    }
+
+    return this.#queryClient
+      ? {
+          __tag: 'clerk-rq-client',
+          client: this.#queryClient,
+        }
+      : undefined;
+  }
+
   public __internal_getCachedResources:
     | (() => Promise<{ client: ClientJSONSnapshot | null; environment: EnvironmentJSONSnapshot | null }>)
     | undefined;

packages/clerk-js/src/core/query-core.ts

@@ -0,0 +1 @@
+export { QueryClient } from '@tanstack/query-core';