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

.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';

.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';

.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';

.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';

.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';

.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';

.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';