refactor(shared,clerk-js,react): move QueryClient ownership into @clerk/shared

.changeset/invert-clerk-rq-ownership.md

@@ -0,0 +1,11 @@
+---
+'@clerk/shared': patch
+'@clerk/clerk-js': patch
+'@clerk/react': patch
+---
+
+Move ownership of the clerk-rq `QueryClient` from `@clerk/clerk-js` into `@clerk/shared`. The `QueryObserver` (constructed in `@clerk/shared`) and the `Query` objects it observes now always come from a single `@tanstack/query-core` resolution — the cross-bundle API contract that produced #8428 (`Query.isFetched is not a function`) no longer exists.
+
+This removes the undocumented `clerk.__internal_queryClient` getter from both `@clerk/clerk-js` and `@clerk/react`'s `IsomorphicClerk`. The `QueryClient` is owned by an internal singleton in `@clerk/shared`, lazily instantiated on the browser only — server renders return `undefined`, preserving SSR safety and avoiding cross-request cache sharing.
+
+`@tanstack/query-core` is no longer a direct dependency of `@clerk/clerk-js`; it remains a dep of `@clerk/shared` and resolves consumer-side as before.

packages/clerk-js/bundlewatch.config.json

@@ -9,7 +9,6 @@
  { "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,7 +91,6 @@
  "@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,12 +110,6 @@ 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/clerk.ts

@@ -138,7 +138,6 @@ 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';
@@ -248,7 +247,6 @@ 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'];
@@ -268,28 +266,6 @@ 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/test/mock-helpers.ts

@@ -1,7 +1,7 @@
+import { __createClerkTestQueryClient } from '@clerk/shared/react';
 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;
@@ -46,19 +46,7 @@ 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,
- },
- },
- }),
- };
+ __createClerkTestQueryClient();
 
  mockMethodsOf(clerkAny);
  if (clerkAny.client) {
@@ -92,12 +80,6 @@ export const mockClerkMethods = (clerk: LoadedClerk): DeepVitestMocked<LoadedCle
  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/react/src/isomorphicClerk.ts

@@ -344,11 +344,6 @@ export class IsomorphicClerk implements IsomorphicLoadedClerk {
  return this.clerkjs?.isStandardBrowser || this.options.standardBrowser || false;
  }
 
- get __internal_queryClient() {
- // @ts-expect-error - __internal_queryClient is not typed
- return this.clerkjs?.__internal_queryClient;
- }
-
  get isSatellite() {
  // This getter can run in environments where window is not available.
  // In those cases we should expect and use domain as a string
@@ -656,13 +651,6 @@ export class IsomorphicClerk implements IsomorphicLoadedClerk {
  this.on('status', listener, { notify: true });
  });
 
- // @ts-expect-error - queryClientStatus is not typed
- this.#eventBus.internal.retrieveListeners('queryClientStatus')?.forEach(listener => {
- // Since clerkjs exists it will call `this.clerkjs.on('queryClientStatus', listener)`
- // @ts-expect-error - queryClientStatus is not typed
- this.on('queryClientStatus', listener, { notify: true });
- });
-
  if (this.preopenSignIn !== null) {
  clerkjs.openSignIn(this.preopenSignIn);
  }

packages/shared/src/react/clerk-rq/__tests__/clerk-query-client.spec.ts

@@ -0,0 +1,84 @@
+import { QueryClient } from '@tanstack/query-core';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import {
+ __createClerkTestQueryClient,
+ __resetClerkQueryClientForTest,
+ __setClerkQueryClientForTest,
+ getClerkQueryClient,
+} from '../clerk-query-client';
+
+afterEach(() => {
+ vi.unstubAllGlobals();
+ __resetClerkQueryClientForTest();
+});
+
+describe('getClerkQueryClient', () => {
+ it('returns undefined when window is not defined (SSR)', () => {
+ vi.stubGlobal('window', undefined);
+
+ expect(getClerkQueryClient()).toBeUndefined();
+ });
+
+ it('does not cache the SSR undefined — a later browser call still creates a client', () => {
+ vi.stubGlobal('window', undefined);
+ expect(getClerkQueryClient()).toBeUndefined();
+
+ vi.unstubAllGlobals();
+ const client = getClerkQueryClient();
+ expect(client).toBeInstanceOf(QueryClient);
+ });
+
+ it('lazy-creates a singleton on the browser and returns the same instance on repeated calls', () => {
+ const first = getClerkQueryClient();
+ const second = getClerkQueryClient();
+
+ expect(first).toBeInstanceOf(QueryClient);
+ expect(second).toBe(first);
+ });
+});
+
+describe('__resetClerkQueryClientForTest', () => {
+ it('clears the singleton so the next read lazy-creates a fresh client', () => {
+ const original = getClerkQueryClient();
+ expect(original).toBeInstanceOf(QueryClient);
+
+ __resetClerkQueryClientForTest();
+
+ const next = getClerkQueryClient();
+ expect(next).toBeInstanceOf(QueryClient);
+ expect(next).not.toBe(original);
+ });
+});
+
+describe('__setClerkQueryClientForTest', () => {
+ it('installs a caller-supplied client and returns it from getClerkQueryClient', () => {
+ const custom = new QueryClient();
+ __setClerkQueryClientForTest(custom);
+
+ expect(getClerkQueryClient()).toBe(custom);
+ });
+
+ it('installs the "no client" state without triggering lazy creation on subsequent reads', () => {
+ __setClerkQueryClientForTest(undefined);
+
+ expect(getClerkQueryClient()).toBeUndefined();
+ expect(getClerkQueryClient()).toBeUndefined();
+ });
+});
+
+describe('__createClerkTestQueryClient', () => {
+ it('returns a QueryClient with deterministic defaults and installs it as the singleton', () => {
+ const client = __createClerkTestQueryClient();
+
+ expect(client).toBeInstanceOf(QueryClient);
+ expect(getClerkQueryClient()).toBe(client);
+
+ const defaults = client.getDefaultOptions().queries;
+ expect(defaults?.retry).toBe(false);
+ expect(defaults?.staleTime).toBe(Infinity);
+ expect(defaults?.refetchOnWindowFocus).toBe(false);
+ expect(defaults?.refetchOnReconnect).toBe(false);
+ expect(defaults?.refetchOnMount).toBe(false);
+ });
+});

packages/shared/src/react/clerk-rq/__tests__/useBaseQuery.spec.tsx

@@ -3,6 +3,7 @@ import React from 'react';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
 import { createMockClerk, createMockQueryClient } from '../../hooks/__tests__/mocks/clerk';
+import { __resetClerkQueryClientForTest, __setClerkQueryClientForTest } from '../clerk-query-client';
 import { useClerkInfiniteQuery } from '../useInfiniteQuery';
 import { useClerkQuery } from '../useQuery';
 
@@ -16,22 +17,15 @@ vi.mock('../../contexts', () => ({
 
 const wrapper = ({ children }: { children: React.ReactNode }) => <>{children}</>;
 
-const makeClerkWithoutQueryClient = () => {
- const mockClerk = createMockClerk({ queryClient: null });
- Object.defineProperty(mockClerk, '__internal_queryClient', {
- get: () => undefined,
- configurable: true,
- });
- return mockClerk;
-};
-
 afterEach(() => {
  vi.clearAllMocks();
+ __resetClerkQueryClientForTest();
 });
 
 describe('useBaseQuery - dummy result while query client is not attached', () => {
  beforeEach(() => {
- activeClerk = makeClerkWithoutQueryClient();
+ activeClerk = createMockClerk({ queryClient: null });
+ __setClerkQueryClientForTest(undefined);
  });
 
  it('reports isLoading: true when the query would be enabled', () => {
@@ -109,8 +103,8 @@ describe('useBaseQuery - dummy result while query client is not attached', () =>
 
 describe('useBaseQuery - normal behavior once query client attaches', () => {
  it('delegates to the real observer when the query client is loaded', async () => {
-const queryClient = createMockQueryClient();
- activeClerk = createMockClerk({ queryClient });
+ createMockQueryClient();
+ activeClerk = createMockClerk({ queryClient: undefined });
 
  const queryFn = vi.fn(async () => 'result');
  const { result } = renderHook(

packages/shared/src/react/clerk-rq/clerk-query-client.ts

@@ -0,0 +1,66 @@
+import { QueryClient } from '@tanstack/query-core';
+
+/**
+ * The QueryClient backing every clerk-rq hook. Owned by `@clerk/shared` so the
+ * `QueryObserver` that observes it and the `Query` objects inside it always
+ * resolve to the same `@tanstack/query-core` (no cross-bundle drift between
+ * the consumer-side `@clerk/shared` and the production CDN `clerk-js` bundle).
+ *
+ * Lazily instantiated on the client only. Server-side renders return
+ * `undefined` so per-request renders never share a cache across requests.
+ */
+let clerkQueryClient: QueryClient | undefined;
+let initialized = false;
+
+export function getClerkQueryClient(): QueryClient | undefined {
+ if (typeof window === 'undefined') {
+ return undefined;
+ }
+ if (!initialized) {
+ clerkQueryClient = new QueryClient();
+ initialized = true;
+ }
+ return clerkQueryClient;
+}
+
+/**
+ * Test-only: install a custom client (for deterministic defaults like
+ * `staleTime: Infinity`) or pass `undefined` to simulate the "no client"
+ * state without triggering lazy creation on subsequent reads.
+ */
+export function __setClerkQueryClientForTest(client: QueryClient | undefined): void {
+ clerkQueryClient = client;
+ initialized = true;
+}
+
+/**
+ * Test-only: build and install a fresh `QueryClient` with deterministic
+ * defaults (no retries, infinite stale time, no refetching). Returns the
+ * client so the spec can read/write its cache directly.
+ *
+ * Avoids forcing every test consumer to depend on `@tanstack/query-core`.
+ */
+export function __createClerkTestQueryClient(): QueryClient {
+ const client = new QueryClient({
+ defaultOptions: {
+ queries: {
+ retry: false,
+ staleTime: Infinity,
+ refetchOnWindowFocus: false,
+ refetchOnReconnect: false,
+ refetchOnMount: false,
+ },
+ },
+ });
+ __setClerkQueryClientForTest(client);
+ return client;
+}
+
+/**
+ * Test-only: clear both the override and the initialization flag so the
+ * next read lazy-creates a fresh client.
+ */
+export function __resetClerkQueryClientForTest(): void {
+ clerkQueryClient = undefined;
+ initialized = false;
+}

.changeset/invert-clerk-rq-ownership.md

@@ -0,0 +1,11 @@
+---
+'@clerk/shared': patch
+'@clerk/clerk-js': patch
+'@clerk/react': patch
+---
+
+Move ownership of the clerk-rq `QueryClient` from `@clerk/clerk-js` into `@clerk/shared`. The `QueryObserver` (constructed in `@clerk/shared`) and the `Query` objects it observes now always come from a single `@tanstack/query-core` resolution — the cross-bundle API contract that produced #8428 (`Query.isFetched is not a function`) no longer exists.
+
+This removes the undocumented `clerk.__internal_queryClient` getter from both `@clerk/clerk-js` and `@clerk/react`'s `IsomorphicClerk`. The `QueryClient` is owned by an internal singleton in `@clerk/shared`, lazily instantiated on the browser only — server renders return `undefined`, preserving SSR safety and avoiding cross-request cache sharing.
+
+`@tanstack/query-core` is no longer a direct dependency of `@clerk/clerk-js`; it remains a dep of `@clerk/shared` and resolves consumer-side as before.

packages/clerk-js/bundlewatch.config.json

@@ -9,7 +9,6 @@
  { "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,7 +91,6 @@
  "@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,12 +110,6 @@ 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/clerk.ts

@@ -138,7 +138,6 @@ 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';
@@ -248,7 +247,6 @@ 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'];
@@ -268,28 +266,6 @@ 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/test/mock-helpers.ts

@@ -1,7 +1,7 @@
+import { __createClerkTestQueryClient } from '@clerk/shared/react';
 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;
@@ -46,19 +46,7 @@ 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,
- },
- },
- }),
- };
+ __createClerkTestQueryClient();
 
  mockMethodsOf(clerkAny);
  if (clerkAny.client) {
@@ -92,12 +80,6 @@ export const mockClerkMethods = (clerk: LoadedClerk): DeepVitestMocked<LoadedCle
  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/react/src/isomorphicClerk.ts

@@ -344,11 +344,6 @@ export class IsomorphicClerk implements IsomorphicLoadedClerk {
  return this.clerkjs?.isStandardBrowser || this.options.standardBrowser || false;
  }
 
- get __internal_queryClient() {
- // @ts-expect-error - __internal_queryClient is not typed
- return this.clerkjs?.__internal_queryClient;
- }
-
  get isSatellite() {
  // This getter can run in environments where window is not available.
  // In those cases we should expect and use domain as a string
@@ -656,13 +651,6 @@ export class IsomorphicClerk implements IsomorphicLoadedClerk {
  this.on('status', listener, { notify: true });
  });
 
- // @ts-expect-error - queryClientStatus is not typed
- this.#eventBus.internal.retrieveListeners('queryClientStatus')?.forEach(listener => {
- // Since clerkjs exists it will call `this.clerkjs.on('queryClientStatus', listener)`
- // @ts-expect-error - queryClientStatus is not typed
- this.on('queryClientStatus', listener, { notify: true });
- });
-
  if (this.preopenSignIn !== null) {
  clerkjs.openSignIn(this.preopenSignIn);
  }

packages/shared/src/react/clerk-rq/__tests__/clerk-query-client.spec.ts

@@ -0,0 +1,84 @@
+import { QueryClient } from '@tanstack/query-core';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import {
+ __createClerkTestQueryClient,
+ __resetClerkQueryClientForTest,
+ __setClerkQueryClientForTest,
+ getClerkQueryClient,
+} from '../clerk-query-client';
+
+afterEach(() => {
+ vi.unstubAllGlobals();
+ __resetClerkQueryClientForTest();
+});
+
+describe('getClerkQueryClient', () => {
+ it('returns undefined when window is not defined (SSR)', () => {
+ vi.stubGlobal('window', undefined);
+
+ expect(getClerkQueryClient()).toBeUndefined();
+ });
+
+ it('does not cache the SSR undefined — a later browser call still creates a client', () => {
+ vi.stubGlobal('window', undefined);
+ expect(getClerkQueryClient()).toBeUndefined();
+
+ vi.unstubAllGlobals();
+ const client = getClerkQueryClient();
+ expect(client).toBeInstanceOf(QueryClient);
+ });
+
+ it('lazy-creates a singleton on the browser and returns the same instance on repeated calls', () => {
+ const first = getClerkQueryClient();
+ const second = getClerkQueryClient();
+
+ expect(first).toBeInstanceOf(QueryClient);
+ expect(second).toBe(first);
+ });
+});
+
+describe('__resetClerkQueryClientForTest', () => {
+ it('clears the singleton so the next read lazy-creates a fresh client', () => {
+ const original = getClerkQueryClient();
+ expect(original).toBeInstanceOf(QueryClient);
+
+ __resetClerkQueryClientForTest();
+
+ const next = getClerkQueryClient();
+ expect(next).toBeInstanceOf(QueryClient);
+ expect(next).not.toBe(original);
+ });
+});
+
+describe('__setClerkQueryClientForTest', () => {
+ it('installs a caller-supplied client and returns it from getClerkQueryClient', () => {
+ const custom = new QueryClient();
+ __setClerkQueryClientForTest(custom);
+
+ expect(getClerkQueryClient()).toBe(custom);
+ });
+
+ it('installs the "no client" state without triggering lazy creation on subsequent reads', () => {
+ __setClerkQueryClientForTest(undefined);
+
+ expect(getClerkQueryClient()).toBeUndefined();
+ expect(getClerkQueryClient()).toBeUndefined();
+ });
+});
+
+describe('__createClerkTestQueryClient', () => {
+ it('returns a QueryClient with deterministic defaults and installs it as the singleton', () => {
+ const client = __createClerkTestQueryClient();
+
+ expect(client).toBeInstanceOf(QueryClient);
+ expect(getClerkQueryClient()).toBe(client);
+
+ const defaults = client.getDefaultOptions().queries;
+ expect(defaults?.retry).toBe(false);
+ expect(defaults?.staleTime).toBe(Infinity);
+ expect(defaults?.refetchOnWindowFocus).toBe(false);
+ expect(defaults?.refetchOnReconnect).toBe(false);
+ expect(defaults?.refetchOnMount).toBe(false);
+ });
+});

packages/shared/src/react/clerk-rq/__tests__/useBaseQuery.spec.tsx

@@ -3,6 +3,7 @@ import React from 'react';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
 import { createMockClerk, createMockQueryClient } from '../../hooks/__tests__/mocks/clerk';
+import { __resetClerkQueryClientForTest, __setClerkQueryClientForTest } from '../clerk-query-client';
 import { useClerkInfiniteQuery } from '../useInfiniteQuery';
 import { useClerkQuery } from '../useQuery';
 
@@ -16,22 +17,15 @@ vi.mock('../../contexts', () => ({
 
 const wrapper = ({ children }: { children: React.ReactNode }) => <>{children}</>;
 
-const makeClerkWithoutQueryClient = () => {
- const mockClerk = createMockClerk({ queryClient: null });
- Object.defineProperty(mockClerk, '__internal_queryClient', {
- get: () => undefined,
- configurable: true,
- });
- return mockClerk;
-};
-
 afterEach(() => {
  vi.clearAllMocks();
+ __resetClerkQueryClientForTest();
 });
 
 describe('useBaseQuery - dummy result while query client is not attached', () => {
  beforeEach(() => {
- activeClerk = makeClerkWithoutQueryClient();
+ activeClerk = createMockClerk({ queryClient: null });
+ __setClerkQueryClientForTest(undefined);
  });
 
  it('reports isLoading: true when the query would be enabled', () => {
@@ -109,8 +103,8 @@ describe('useBaseQuery - dummy result while query client is not attached', () =>
 
 describe('useBaseQuery - normal behavior once query client attaches', () => {
  it('delegates to the real observer when the query client is loaded', async () => {
-const queryClient = createMockQueryClient();
- activeClerk = createMockClerk({ queryClient });
+ createMockQueryClient();
+ activeClerk = createMockClerk({ queryClient: undefined });
 
  const queryFn = vi.fn(async () => 'result');
  const { result } = renderHook(

packages/shared/src/react/clerk-rq/clerk-query-client.ts

@@ -0,0 +1,66 @@
+import { QueryClient } from '@tanstack/query-core';
+
+/**
+ * The QueryClient backing every clerk-rq hook. Owned by `@clerk/shared` so the
+ * `QueryObserver` that observes it and the `Query` objects inside it always
+ * resolve to the same `@tanstack/query-core` (no cross-bundle drift between
+ * the consumer-side `@clerk/shared` and the production CDN `clerk-js` bundle).
+ *
+ * Lazily instantiated on the client only. Server-side renders return
+ * `undefined` so per-request renders never share a cache across requests.
+ */
+let clerkQueryClient: QueryClient | undefined;
+let initialized = false;
+
+export function getClerkQueryClient(): QueryClient | undefined {
+ if (typeof window === 'undefined') {
+ return undefined;
+ }
+ if (!initialized) {
+ clerkQueryClient = new QueryClient();
+ initialized = true;
+ }
+ return clerkQueryClient;
+}
+
+/**
+ * Test-only: install a custom client (for deterministic defaults like
+ * `staleTime: Infinity`) or pass `undefined` to simulate the "no client"
+ * state without triggering lazy creation on subsequent reads.
+ */
+export function __setClerkQueryClientForTest(client: QueryClient | undefined): void {
+ clerkQueryClient = client;
+ initialized = true;
+}
+
+/**
+ * Test-only: build and install a fresh `QueryClient` with deterministic
+ * defaults (no retries, infinite stale time, no refetching). Returns the
+ * client so the spec can read/write its cache directly.
+ *
+ * Avoids forcing every test consumer to depend on `@tanstack/query-core`.
+ */
+export function __createClerkTestQueryClient(): QueryClient {
+ const client = new QueryClient({
+ defaultOptions: {
+ queries: {
+ retry: false,
+ staleTime: Infinity,
+ refetchOnWindowFocus: false,
+ refetchOnReconnect: false,
+ refetchOnMount: false,
+ },
+ },
+ });
+ __setClerkQueryClientForTest(client);
+ return client;
+}
+
+/**
+ * Test-only: clear both the override and the initialization flag so the
+ * next read lazy-creates a fresh client.
+ */
+export function __resetClerkQueryClientForTest(): void {
+ clerkQueryClient = undefined;
+ initialized = false;
+}

.changeset/invert-clerk-rq-ownership.md

@@ -0,0 +1,11 @@
+---
+'@clerk/shared': patch
+'@clerk/clerk-js': patch
+'@clerk/react': patch
+---
+
+Move ownership of the clerk-rq `QueryClient` from `@clerk/clerk-js` into `@clerk/shared`. The `QueryObserver` (constructed in `@clerk/shared`) and the `Query` objects it observes now always come from a single `@tanstack/query-core` resolution — the cross-bundle API contract that produced #8428 (`Query.isFetched is not a function`) no longer exists.
+
+This removes the undocumented `clerk.__internal_queryClient` getter from both `@clerk/clerk-js` and `@clerk/react`'s `IsomorphicClerk`. The `QueryClient` is owned by an internal singleton in `@clerk/shared`, lazily instantiated on the browser only — server renders return `undefined`, preserving SSR safety and avoiding cross-request cache sharing.
+
+`@tanstack/query-core` is no longer a direct dependency of `@clerk/clerk-js`; it remains a dep of `@clerk/shared` and resolves consumer-side as before.

packages/clerk-js/bundlewatch.config.json

@@ -9,7 +9,6 @@
  { "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,7 +91,6 @@
  "@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,12 +110,6 @@ 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/clerk.ts

@@ -138,7 +138,6 @@ 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';
@@ -248,7 +247,6 @@ 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'];
@@ -268,28 +266,6 @@ 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/test/mock-helpers.ts

@@ -1,7 +1,7 @@
+import { __createClerkTestQueryClient } from '@clerk/shared/react';
 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;
@@ -46,19 +46,7 @@ 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,
- },
- },
- }),
- };
+ __createClerkTestQueryClient();
 
  mockMethodsOf(clerkAny);
  if (clerkAny.client) {
@@ -92,12 +80,6 @@ export const mockClerkMethods = (clerk: LoadedClerk): DeepVitestMocked<LoadedCle
  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/react/src/isomorphicClerk.ts

@@ -344,11 +344,6 @@ export class IsomorphicClerk implements IsomorphicLoadedClerk {
  return this.clerkjs?.isStandardBrowser || this.options.standardBrowser || false;
  }
 
- get __internal_queryClient() {
- // @ts-expect-error - __internal_queryClient is not typed
- return this.clerkjs?.__internal_queryClient;
- }
-
  get isSatellite() {
  // This getter can run in environments where window is not available.
  // In those cases we should expect and use domain as a string
@@ -656,13 +651,6 @@ export class IsomorphicClerk implements IsomorphicLoadedClerk {
  this.on('status', listener, { notify: true });
  });
 
- // @ts-expect-error - queryClientStatus is not typed
- this.#eventBus.internal.retrieveListeners('queryClientStatus')?.forEach(listener => {
- // Since clerkjs exists it will call `this.clerkjs.on('queryClientStatus', listener)`
- // @ts-expect-error - queryClientStatus is not typed
- this.on('queryClientStatus', listener, { notify: true });
- });
-
  if (this.preopenSignIn !== null) {
  clerkjs.openSignIn(this.preopenSignIn);
  }

packages/shared/src/react/clerk-rq/__tests__/clerk-query-client.spec.ts

@@ -0,0 +1,84 @@
+import { QueryClient } from '@tanstack/query-core';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import {
+ __createClerkTestQueryClient,
+ __resetClerkQueryClientForTest,
+ __setClerkQueryClientForTest,
+ getClerkQueryClient,
+} from '../clerk-query-client';
+
+afterEach(() => {
+ vi.unstubAllGlobals();
+ __resetClerkQueryClientForTest();
+});
+
+describe('getClerkQueryClient', () => {
+ it('returns undefined when window is not defined (SSR)', () => {
+ vi.stubGlobal('window', undefined);
+
+ expect(getClerkQueryClient()).toBeUndefined();
+ });
+
+ it('does not cache the SSR undefined — a later browser call still creates a client', () => {
+ vi.stubGlobal('window', undefined);
+ expect(getClerkQueryClient()).toBeUndefined();
+
+ vi.unstubAllGlobals();
+ const client = getClerkQueryClient();
+ expect(client).toBeInstanceOf(QueryClient);
+ });
+
+ it('lazy-creates a singleton on the browser and returns the same instance on repeated calls', () => {
+ const first = getClerkQueryClient();
+ const second = getClerkQueryClient();
+
+ expect(first).toBeInstanceOf(QueryClient);
+ expect(second).toBe(first);
+ });
+});
+
+describe('__resetClerkQueryClientForTest', () => {
+ it('clears the singleton so the next read lazy-creates a fresh client', () => {
+ const original = getClerkQueryClient();
+ expect(original).toBeInstanceOf(QueryClient);
+
+ __resetClerkQueryClientForTest();
+
+ const next = getClerkQueryClient();
+ expect(next).toBeInstanceOf(QueryClient);
+ expect(next).not.toBe(original);
+ });
+});
+
+describe('__setClerkQueryClientForTest', () => {
+ it('installs a caller-supplied client and returns it from getClerkQueryClient', () => {
+ const custom = new QueryClient();
+ __setClerkQueryClientForTest(custom);
+
+ expect(getClerkQueryClient()).toBe(custom);
+ });
+
+ it('installs the "no client" state without triggering lazy creation on subsequent reads', () => {
+ __setClerkQueryClientForTest(undefined);
+
+ expect(getClerkQueryClient()).toBeUndefined();
+ expect(getClerkQueryClient()).toBeUndefined();
+ });
+});
+
+describe('__createClerkTestQueryClient', () => {
+ it('returns a QueryClient with deterministic defaults and installs it as the singleton', () => {
+ const client = __createClerkTestQueryClient();
+
+ expect(client).toBeInstanceOf(QueryClient);
+ expect(getClerkQueryClient()).toBe(client);
+
+ const defaults = client.getDefaultOptions().queries;
+ expect(defaults?.retry).toBe(false);
+ expect(defaults?.staleTime).toBe(Infinity);
+ expect(defaults?.refetchOnWindowFocus).toBe(false);
+ expect(defaults?.refetchOnReconnect).toBe(false);
+ expect(defaults?.refetchOnMount).toBe(false);
+ });
+});

packages/shared/src/react/clerk-rq/__tests__/useBaseQuery.spec.tsx

@@ -3,6 +3,7 @@ import React from 'react';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
 import { createMockClerk, createMockQueryClient } from '../../hooks/__tests__/mocks/clerk';
+import { __resetClerkQueryClientForTest, __setClerkQueryClientForTest } from '../clerk-query-client';
 import { useClerkInfiniteQuery } from '../useInfiniteQuery';
 import { useClerkQuery } from '../useQuery';
 
@@ -16,22 +17,15 @@ vi.mock('../../contexts', () => ({
 
 const wrapper = ({ children }: { children: React.ReactNode }) => <>{children}</>;
 
-const makeClerkWithoutQueryClient = () => {
- const mockClerk = createMockClerk({ queryClient: null });
- Object.defineProperty(mockClerk, '__internal_queryClient', {
- get: () => undefined,
- configurable: true,
- });
- return mockClerk;
-};
-
 afterEach(() => {
  vi.clearAllMocks();
+ __resetClerkQueryClientForTest();
 });
 
 describe('useBaseQuery - dummy result while query client is not attached', () => {
  beforeEach(() => {
- activeClerk = makeClerkWithoutQueryClient();
+ activeClerk = createMockClerk({ queryClient: null });
+ __setClerkQueryClientForTest(undefined);
  });
 
  it('reports isLoading: true when the query would be enabled', () => {
@@ -109,8 +103,8 @@ describe('useBaseQuery - dummy result while query client is not attached', () =>
 
 describe('useBaseQuery - normal behavior once query client attaches', () => {
  it('delegates to the real observer when the query client is loaded', async () => {
-const queryClient = createMockQueryClient();
- activeClerk = createMockClerk({ queryClient });
+ createMockQueryClient();
+ activeClerk = createMockClerk({ queryClient: undefined });
 
  const queryFn = vi.fn(async () => 'result');
  const { result } = renderHook(

packages/shared/src/react/clerk-rq/clerk-query-client.ts

@@ -0,0 +1,66 @@
+import { QueryClient } from '@tanstack/query-core';
+
+/**
+ * The QueryClient backing every clerk-rq hook. Owned by `@clerk/shared` so the
+ * `QueryObserver` that observes it and the `Query` objects inside it always
+ * resolve to the same `@tanstack/query-core` (no cross-bundle drift between
+ * the consumer-side `@clerk/shared` and the production CDN `clerk-js` bundle).
+ *
+ * Lazily instantiated on the client only. Server-side renders return
+ * `undefined` so per-request renders never share a cache across requests.
+ */
+let clerkQueryClient: QueryClient | undefined;
+let initialized = false;
+
+export function getClerkQueryClient(): QueryClient | undefined {
+ if (typeof window === 'undefined') {
+ return undefined;
+ }
+ if (!initialized) {
+ clerkQueryClient = new QueryClient();
+ initialized = true;
+ }
+ return clerkQueryClient;
+}
+
+/**
+ * Test-only: install a custom client (for deterministic defaults like
+ * `staleTime: Infinity`) or pass `undefined` to simulate the "no client"
+ * state without triggering lazy creation on subsequent reads.
+ */
+export function __setClerkQueryClientForTest(client: QueryClient | undefined): void {
+ clerkQueryClient = client;
+ initialized = true;
+}
+
+/**
+ * Test-only: build and install a fresh `QueryClient` with deterministic
+ * defaults (no retries, infinite stale time, no refetching). Returns the
+ * client so the spec can read/write its cache directly.
+ *
+ * Avoids forcing every test consumer to depend on `@tanstack/query-core`.
+ */
+export function __createClerkTestQueryClient(): QueryClient {
+ const client = new QueryClient({
+ defaultOptions: {
+ queries: {
+ retry: false,
+ staleTime: Infinity,
+ refetchOnWindowFocus: false,
+ refetchOnReconnect: false,
+ refetchOnMount: false,
+ },
+ },
+ });
+ __setClerkQueryClientForTest(client);
+ return client;
+}
+
+/**
+ * Test-only: clear both the override and the initialization flag so the
+ * next read lazy-creates a fresh client.
+ */
+export function __resetClerkQueryClientForTest(): void {
+ clerkQueryClient = undefined;
+ initialized = false;
+}

.changeset/invert-clerk-rq-ownership.md

@@ -0,0 +1,11 @@
+---
+'@clerk/shared': patch
+'@clerk/clerk-js': patch
+'@clerk/react': patch
+---
+
+Move ownership of the clerk-rq `QueryClient` from `@clerk/clerk-js` into `@clerk/shared`. The `QueryObserver` (constructed in `@clerk/shared`) and the `Query` objects it observes now always come from a single `@tanstack/query-core` resolution — the cross-bundle API contract that produced #8428 (`Query.isFetched is not a function`) no longer exists.
+
+This removes the undocumented `clerk.__internal_queryClient` getter from both `@clerk/clerk-js` and `@clerk/react`'s `IsomorphicClerk`. The `QueryClient` is owned by an internal singleton in `@clerk/shared`, lazily instantiated on the browser only — server renders return `undefined`, preserving SSR safety and avoiding cross-request cache sharing.
+
+`@tanstack/query-core` is no longer a direct dependency of `@clerk/clerk-js`; it remains a dep of `@clerk/shared` and resolves consumer-side as before.

packages/clerk-js/bundlewatch.config.json

@@ -9,7 +9,6 @@
  { "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,7 +91,6 @@
  "@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,12 +110,6 @@ 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/clerk.ts

@@ -138,7 +138,6 @@ 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';
@@ -248,7 +247,6 @@ 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'];
@@ -268,28 +266,6 @@ 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/test/mock-helpers.ts

@@ -1,7 +1,7 @@
+import { __createClerkTestQueryClient } from '@clerk/shared/react';
 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;
@@ -46,19 +46,7 @@ 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,
- },
- },
- }),
- };
+ __createClerkTestQueryClient();
 
  mockMethodsOf(clerkAny);
  if (clerkAny.client) {
@@ -92,12 +80,6 @@ export const mockClerkMethods = (clerk: LoadedClerk): DeepVitestMocked<LoadedCle
  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/react/src/isomorphicClerk.ts

@@ -344,11 +344,6 @@ export class IsomorphicClerk implements IsomorphicLoadedClerk {
  return this.clerkjs?.isStandardBrowser || this.options.standardBrowser || false;
  }
 
- get __internal_queryClient() {
- // @ts-expect-error - __internal_queryClient is not typed
- return this.clerkjs?.__internal_queryClient;
- }
-
  get isSatellite() {
  // This getter can run in environments where window is not available.
  // In those cases we should expect and use domain as a string
@@ -656,13 +651,6 @@ export class IsomorphicClerk implements IsomorphicLoadedClerk {
  this.on('status', listener, { notify: true });
  });
 
- // @ts-expect-error - queryClientStatus is not typed
- this.#eventBus.internal.retrieveListeners('queryClientStatus')?.forEach(listener => {
- // Since clerkjs exists it will call `this.clerkjs.on('queryClientStatus', listener)`
- // @ts-expect-error - queryClientStatus is not typed
- this.on('queryClientStatus', listener, { notify: true });
- });
-
  if (this.preopenSignIn !== null) {
  clerkjs.openSignIn(this.preopenSignIn);
  }

packages/shared/src/react/clerk-rq/__tests__/clerk-query-client.spec.ts

@@ -0,0 +1,84 @@
+import { QueryClient } from '@tanstack/query-core';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import {
+ __createClerkTestQueryClient,
+ __resetClerkQueryClientForTest,
+ __setClerkQueryClientForTest,
+ getClerkQueryClient,
+} from '../clerk-query-client';
+
+afterEach(() => {
+ vi.unstubAllGlobals();
+ __resetClerkQueryClientForTest();
+});
+
+describe('getClerkQueryClient', () => {
+ it('returns undefined when window is not defined (SSR)', () => {
+ vi.stubGlobal('window', undefined);
+
+ expect(getClerkQueryClient()).toBeUndefined();
+ });
+
+ it('does not cache the SSR undefined — a later browser call still creates a client', () => {
+ vi.stubGlobal('window', undefined);
+ expect(getClerkQueryClient()).toBeUndefined();
+
+ vi.unstubAllGlobals();
+ const client = getClerkQueryClient();
+ expect(client).toBeInstanceOf(QueryClient);
+ });
+
+ it('lazy-creates a singleton on the browser and returns the same instance on repeated calls', () => {
+ const first = getClerkQueryClient();
+ const second = getClerkQueryClient();
+
+ expect(first).toBeInstanceOf(QueryClient);
+ expect(second).toBe(first);
+ });
+});
+
+describe('__resetClerkQueryClientForTest', () => {
+ it('clears the singleton so the next read lazy-creates a fresh client', () => {
+ const original = getClerkQueryClient();
+ expect(original).toBeInstanceOf(QueryClient);
+
+ __resetClerkQueryClientForTest();
+
+ const next = getClerkQueryClient();
+ expect(next).toBeInstanceOf(QueryClient);
+ expect(next).not.toBe(original);
+ });
+});
+
+describe('__setClerkQueryClientForTest', () => {
+ it('installs a caller-supplied client and returns it from getClerkQueryClient', () => {
+ const custom = new QueryClient();
+ __setClerkQueryClientForTest(custom);
+
+ expect(getClerkQueryClient()).toBe(custom);
+ });
+
+ it('installs the "no client" state without triggering lazy creation on subsequent reads', () => {
+ __setClerkQueryClientForTest(undefined);
+
+ expect(getClerkQueryClient()).toBeUndefined();
+ expect(getClerkQueryClient()).toBeUndefined();
+ });
+});
+
+describe('__createClerkTestQueryClient', () => {
+ it('returns a QueryClient with deterministic defaults and installs it as the singleton', () => {
+ const client = __createClerkTestQueryClient();
+
+ expect(client).toBeInstanceOf(QueryClient);
+ expect(getClerkQueryClient()).toBe(client);
+
+ const defaults = client.getDefaultOptions().queries;
+ expect(defaults?.retry).toBe(false);
+ expect(defaults?.staleTime).toBe(Infinity);
+ expect(defaults?.refetchOnWindowFocus).toBe(false);
+ expect(defaults?.refetchOnReconnect).toBe(false);
+ expect(defaults?.refetchOnMount).toBe(false);
+ });
+});

packages/shared/src/react/clerk-rq/__tests__/useBaseQuery.spec.tsx

@@ -3,6 +3,7 @@ import React from 'react';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
 import { createMockClerk, createMockQueryClient } from '../../hooks/__tests__/mocks/clerk';
+import { __resetClerkQueryClientForTest, __setClerkQueryClientForTest } from '../clerk-query-client';
 import { useClerkInfiniteQuery } from '../useInfiniteQuery';
 import { useClerkQuery } from '../useQuery';
 
@@ -16,22 +17,15 @@ vi.mock('../../contexts', () => ({
 
 const wrapper = ({ children }: { children: React.ReactNode }) => <>{children}</>;
 
-const makeClerkWithoutQueryClient = () => {
- const mockClerk = createMockClerk({ queryClient: null });
- Object.defineProperty(mockClerk, '__internal_queryClient', {
- get: () => undefined,
- configurable: true,
- });
- return mockClerk;
-};
-
 afterEach(() => {
  vi.clearAllMocks();
+ __resetClerkQueryClientForTest();
 });
 
 describe('useBaseQuery - dummy result while query client is not attached', () => {
  beforeEach(() => {
- activeClerk = makeClerkWithoutQueryClient();
+ activeClerk = createMockClerk({ queryClient: null });
+ __setClerkQueryClientForTest(undefined);
  });
 
  it('reports isLoading: true when the query would be enabled', () => {
@@ -109,8 +103,8 @@ describe('useBaseQuery - dummy result while query client is not attached', () =>
 
 describe('useBaseQuery - normal behavior once query client attaches', () => {
  it('delegates to the real observer when the query client is loaded', async () => {
-const queryClient = createMockQueryClient();
- activeClerk = createMockClerk({ queryClient });
+ createMockQueryClient();
+ activeClerk = createMockClerk({ queryClient: undefined });
 
  const queryFn = vi.fn(async () => 'result');
  const { result } = renderHook(

packages/shared/src/react/clerk-rq/clerk-query-client.ts

@@ -0,0 +1,66 @@
+import { QueryClient } from '@tanstack/query-core';
+
+/**
+ * The QueryClient backing every clerk-rq hook. Owned by `@clerk/shared` so the
+ * `QueryObserver` that observes it and the `Query` objects inside it always
+ * resolve to the same `@tanstack/query-core` (no cross-bundle drift between
+ * the consumer-side `@clerk/shared` and the production CDN `clerk-js` bundle).
+ *
+ * Lazily instantiated on the client only. Server-side renders return
+ * `undefined` so per-request renders never share a cache across requests.
+ */
+let clerkQueryClient: QueryClient | undefined;
+let initialized = false;
+
+export function getClerkQueryClient(): QueryClient | undefined {
+ if (typeof window === 'undefined') {
+ return undefined;
+ }
+ if (!initialized) {
+ clerkQueryClient = new QueryClient();
+ initialized = true;
+ }
+ return clerkQueryClient;
+}
+
+/**
+ * Test-only: install a custom client (for deterministic defaults like
+ * `staleTime: Infinity`) or pass `undefined` to simulate the "no client"
+ * state without triggering lazy creation on subsequent reads.
+ */
+export function __setClerkQueryClientForTest(client: QueryClient | undefined): void {
+ clerkQueryClient = client;
+ initialized = true;
+}
+
+/**
+ * Test-only: build and install a fresh `QueryClient` with deterministic
+ * defaults (no retries, infinite stale time, no refetching). Returns the
+ * client so the spec can read/write its cache directly.
+ *
+ * Avoids forcing every test consumer to depend on `@tanstack/query-core`.
+ */
+export function __createClerkTestQueryClient(): QueryClient {
+ const client = new QueryClient({
+ defaultOptions: {
+ queries: {
+ retry: false,
+ staleTime: Infinity,
+ refetchOnWindowFocus: false,
+ refetchOnReconnect: false,
+ refetchOnMount: false,
+ },
+ },
+ });
+ __setClerkQueryClientForTest(client);
+ return client;
+}
+
+/**
+ * Test-only: clear both the override and the initialization flag so the
+ * next read lazy-creates a fresh client.
+ */
+export function __resetClerkQueryClientForTest(): void {
+ clerkQueryClient = undefined;
+ initialized = false;
+}

.changeset/invert-clerk-rq-ownership.md

@@ -0,0 +1,11 @@
+---
+'@clerk/shared': patch
+'@clerk/clerk-js': patch
+'@clerk/react': patch
+---
+
+Move ownership of the clerk-rq `QueryClient` from `@clerk/clerk-js` into `@clerk/shared`. The `QueryObserver` (constructed in `@clerk/shared`) and the `Query` objects it observes now always come from a single `@tanstack/query-core` resolution — the cross-bundle API contract that produced #8428 (`Query.isFetched is not a function`) no longer exists.
+
+This removes the undocumented `clerk.__internal_queryClient` getter from both `@clerk/clerk-js` and `@clerk/react`'s `IsomorphicClerk`. The `QueryClient` is owned by an internal singleton in `@clerk/shared`, lazily instantiated on the browser only — server renders return `undefined`, preserving SSR safety and avoiding cross-request cache sharing.
+
+`@tanstack/query-core` is no longer a direct dependency of `@clerk/clerk-js`; it remains a dep of `@clerk/shared` and resolves consumer-side as before.

packages/clerk-js/bundlewatch.config.json

@@ -9,7 +9,6 @@
  { "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,7 +91,6 @@
  "@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,12 +110,6 @@ 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/clerk.ts

@@ -138,7 +138,6 @@ 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';
@@ -248,7 +247,6 @@ 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'];
@@ -268,28 +266,6 @@ 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/test/mock-helpers.ts

@@ -1,7 +1,7 @@
+import { __createClerkTestQueryClient } from '@clerk/shared/react';
 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;
@@ -46,19 +46,7 @@ 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,
- },
- },
- }),
- };
+ __createClerkTestQueryClient();
 
  mockMethodsOf(clerkAny);
  if (clerkAny.client) {
@@ -92,12 +80,6 @@ export const mockClerkMethods = (clerk: LoadedClerk): DeepVitestMocked<LoadedCle
  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/react/src/isomorphicClerk.ts

@@ -344,11 +344,6 @@ export class IsomorphicClerk implements IsomorphicLoadedClerk {
  return this.clerkjs?.isStandardBrowser || this.options.standardBrowser || false;
  }
 
- get __internal_queryClient() {
- // @ts-expect-error - __internal_queryClient is not typed
- return this.clerkjs?.__internal_queryClient;
- }
-
  get isSatellite() {
  // This getter can run in environments where window is not available.
  // In those cases we should expect and use domain as a string
@@ -656,13 +651,6 @@ export class IsomorphicClerk implements IsomorphicLoadedClerk {
  this.on('status', listener, { notify: true });
  });
 
- // @ts-expect-error - queryClientStatus is not typed
- this.#eventBus.internal.retrieveListeners('queryClientStatus')?.forEach(listener => {
- // Since clerkjs exists it will call `this.clerkjs.on('queryClientStatus', listener)`
- // @ts-expect-error - queryClientStatus is not typed
- this.on('queryClientStatus', listener, { notify: true });
- });
-
  if (this.preopenSignIn !== null) {
  clerkjs.openSignIn(this.preopenSignIn);
  }

packages/shared/src/react/clerk-rq/__tests__/clerk-query-client.spec.ts

@@ -0,0 +1,84 @@
+import { QueryClient } from '@tanstack/query-core';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import {
+ __createClerkTestQueryClient,
+ __resetClerkQueryClientForTest,
+ __setClerkQueryClientForTest,
+ getClerkQueryClient,
+} from '../clerk-query-client';
+
+afterEach(() => {
+ vi.unstubAllGlobals();
+ __resetClerkQueryClientForTest();
+});
+
+describe('getClerkQueryClient', () => {
+ it('returns undefined when window is not defined (SSR)', () => {
+ vi.stubGlobal('window', undefined);
+
+ expect(getClerkQueryClient()).toBeUndefined();
+ });
+
+ it('does not cache the SSR undefined — a later browser call still creates a client', () => {
+ vi.stubGlobal('window', undefined);
+ expect(getClerkQueryClient()).toBeUndefined();
+
+ vi.unstubAllGlobals();
+ const client = getClerkQueryClient();
+ expect(client).toBeInstanceOf(QueryClient);
+ });
+
+ it('lazy-creates a singleton on the browser and returns the same instance on repeated calls', () => {
+ const first = getClerkQueryClient();
+ const second = getClerkQueryClient();
+
+ expect(first).toBeInstanceOf(QueryClient);
+ expect(second).toBe(first);
+ });
+});
+
+describe('__resetClerkQueryClientForTest', () => {
+ it('clears the singleton so the next read lazy-creates a fresh client', () => {
+ const original = getClerkQueryClient();
+ expect(original).toBeInstanceOf(QueryClient);
+
+ __resetClerkQueryClientForTest();
+
+ const next = getClerkQueryClient();
+ expect(next).toBeInstanceOf(QueryClient);
+ expect(next).not.toBe(original);
+ });
+});
+
+describe('__setClerkQueryClientForTest', () => {
+ it('installs a caller-supplied client and returns it from getClerkQueryClient', () => {
+ const custom = new QueryClient();
+ __setClerkQueryClientForTest(custom);
+
+ expect(getClerkQueryClient()).toBe(custom);
+ });
+
+ it('installs the "no client" state without triggering lazy creation on subsequent reads', () => {
+ __setClerkQueryClientForTest(undefined);
+
+ expect(getClerkQueryClient()).toBeUndefined();
+ expect(getClerkQueryClient()).toBeUndefined();
+ });
+});
+
+describe('__createClerkTestQueryClient', () => {
+ it('returns a QueryClient with deterministic defaults and installs it as the singleton', () => {
+ const client = __createClerkTestQueryClient();
+
+ expect(client).toBeInstanceOf(QueryClient);
+ expect(getClerkQueryClient()).toBe(client);
+
+ const defaults = client.getDefaultOptions().queries;
+ expect(defaults?.retry).toBe(false);
+ expect(defaults?.staleTime).toBe(Infinity);
+ expect(defaults?.refetchOnWindowFocus).toBe(false);
+ expect(defaults?.refetchOnReconnect).toBe(false);
+ expect(defaults?.refetchOnMount).toBe(false);
+ });
+});

packages/shared/src/react/clerk-rq/__tests__/useBaseQuery.spec.tsx

@@ -3,6 +3,7 @@ import React from 'react';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
 import { createMockClerk, createMockQueryClient } from '../../hooks/__tests__/mocks/clerk';
+import { __resetClerkQueryClientForTest, __setClerkQueryClientForTest } from '../clerk-query-client';
 import { useClerkInfiniteQuery } from '../useInfiniteQuery';
 import { useClerkQuery } from '../useQuery';
 
@@ -16,22 +17,15 @@ vi.mock('../../contexts', () => ({
 
 const wrapper = ({ children }: { children: React.ReactNode }) => <>{children}</>;
 
-const makeClerkWithoutQueryClient = () => {
- const mockClerk = createMockClerk({ queryClient: null });
- Object.defineProperty(mockClerk, '__internal_queryClient', {
- get: () => undefined,
- configurable: true,
- });
- return mockClerk;
-};
-
 afterEach(() => {
  vi.clearAllMocks();
+ __resetClerkQueryClientForTest();
 });
 
 describe('useBaseQuery - dummy result while query client is not attached', () => {
  beforeEach(() => {
- activeClerk = makeClerkWithoutQueryClient();
+ activeClerk = createMockClerk({ queryClient: null });
+ __setClerkQueryClientForTest(undefined);
  });
 
  it('reports isLoading: true when the query would be enabled', () => {
@@ -109,8 +103,8 @@ describe('useBaseQuery - dummy result while query client is not attached', () =>
 
 describe('useBaseQuery - normal behavior once query client attaches', () => {
  it('delegates to the real observer when the query client is loaded', async () => {
-const queryClient = createMockQueryClient();
- activeClerk = createMockClerk({ queryClient });
+ createMockQueryClient();
+ activeClerk = createMockClerk({ queryClient: undefined });
 
  const queryFn = vi.fn(async () => 'result');
  const { result } = renderHook(

packages/shared/src/react/clerk-rq/clerk-query-client.ts

@@ -0,0 +1,66 @@
+import { QueryClient } from '@tanstack/query-core';
+
+/**
+ * The QueryClient backing every clerk-rq hook. Owned by `@clerk/shared` so the
+ * `QueryObserver` that observes it and the `Query` objects inside it always
+ * resolve to the same `@tanstack/query-core` (no cross-bundle drift between
+ * the consumer-side `@clerk/shared` and the production CDN `clerk-js` bundle).
+ *
+ * Lazily instantiated on the client only. Server-side renders return
+ * `undefined` so per-request renders never share a cache across requests.
+ */
+let clerkQueryClient: QueryClient | undefined;
+let initialized = false;
+
+export function getClerkQueryClient(): QueryClient | undefined {
+ if (typeof window === 'undefined') {
+ return undefined;
+ }
+ if (!initialized) {
+ clerkQueryClient = new QueryClient();
+ initialized = true;
+ }
+ return clerkQueryClient;
+}
+
+/**
+ * Test-only: install a custom client (for deterministic defaults like
+ * `staleTime: Infinity`) or pass `undefined` to simulate the "no client"
+ * state without triggering lazy creation on subsequent reads.
+ */
+export function __setClerkQueryClientForTest(client: QueryClient | undefined): void {
+ clerkQueryClient = client;
+ initialized = true;
+}
+
+/**
+ * Test-only: build and install a fresh `QueryClient` with deterministic
+ * defaults (no retries, infinite stale time, no refetching). Returns the
+ * client so the spec can read/write its cache directly.
+ *
+ * Avoids forcing every test consumer to depend on `@tanstack/query-core`.
+ */
+export function __createClerkTestQueryClient(): QueryClient {
+ const client = new QueryClient({
+ defaultOptions: {
+ queries: {
+ retry: false,
+ staleTime: Infinity,
+ refetchOnWindowFocus: false,
+ refetchOnReconnect: false,
+ refetchOnMount: false,
+ },
+ },
+ });
+ __setClerkQueryClientForTest(client);
+ return client;
+}
+
+/**
+ * Test-only: clear both the override and the initialization flag so the
+ * next read lazy-creates a fresh client.
+ */
+export function __resetClerkQueryClientForTest(): void {
+ clerkQueryClient = undefined;
+ initialized = false;
+}

.changeset/invert-clerk-rq-ownership.md

@@ -0,0 +1,11 @@
+---
+'@clerk/shared': patch
+'@clerk/clerk-js': patch
+'@clerk/react': patch
+---
+
+Move ownership of the clerk-rq `QueryClient` from `@clerk/clerk-js` into `@clerk/shared`. The `QueryObserver` (constructed in `@clerk/shared`) and the `Query` objects it observes now always come from a single `@tanstack/query-core` resolution — the cross-bundle API contract that produced #8428 (`Query.isFetched is not a function`) no longer exists.
+
+This removes the undocumented `clerk.__internal_queryClient` getter from both `@clerk/clerk-js` and `@clerk/react`'s `IsomorphicClerk`. The `QueryClient` is owned by an internal singleton in `@clerk/shared`, lazily instantiated on the browser only — server renders return `undefined`, preserving SSR safety and avoiding cross-request cache sharing.
+
+`@tanstack/query-core` is no longer a direct dependency of `@clerk/clerk-js`; it remains a dep of `@clerk/shared` and resolves consumer-side as before.

packages/clerk-js/bundlewatch.config.json

@@ -9,7 +9,6 @@
  { "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,7 +91,6 @@
  "@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,12 +110,6 @@ 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/clerk.ts

@@ -138,7 +138,6 @@ 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';
@@ -248,7 +247,6 @@ 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'];
@@ -268,28 +266,6 @@ 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/test/mock-helpers.ts

@@ -1,7 +1,7 @@
+import { __createClerkTestQueryClient } from '@clerk/shared/react';
 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;
@@ -46,19 +46,7 @@ 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,
- },
- },
- }),
- };
+ __createClerkTestQueryClient();
 
  mockMethodsOf(clerkAny);
  if (clerkAny.client) {
@@ -92,12 +80,6 @@ export const mockClerkMethods = (clerk: LoadedClerk): DeepVitestMocked<LoadedCle
  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/react/src/isomorphicClerk.ts

@@ -344,11 +344,6 @@ export class IsomorphicClerk implements IsomorphicLoadedClerk {
  return this.clerkjs?.isStandardBrowser || this.options.standardBrowser || false;
  }
 
- get __internal_queryClient() {
- // @ts-expect-error - __internal_queryClient is not typed
- return this.clerkjs?.__internal_queryClient;
- }
-
  get isSatellite() {
  // This getter can run in environments where window is not available.
  // In those cases we should expect and use domain as a string
@@ -656,13 +651,6 @@ export class IsomorphicClerk implements IsomorphicLoadedClerk {
  this.on('status', listener, { notify: true });
  });
 
- // @ts-expect-error - queryClientStatus is not typed
- this.#eventBus.internal.retrieveListeners('queryClientStatus')?.forEach(listener => {
- // Since clerkjs exists it will call `this.clerkjs.on('queryClientStatus', listener)`
- // @ts-expect-error - queryClientStatus is not typed
- this.on('queryClientStatus', listener, { notify: true });
- });
-
  if (this.preopenSignIn !== null) {
  clerkjs.openSignIn(this.preopenSignIn);
  }

packages/shared/src/react/clerk-rq/__tests__/clerk-query-client.spec.ts

@@ -0,0 +1,84 @@
+import { QueryClient } from '@tanstack/query-core';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import {
+ __createClerkTestQueryClient,
+ __resetClerkQueryClientForTest,
+ __setClerkQueryClientForTest,
+ getClerkQueryClient,
+} from '../clerk-query-client';
+
+afterEach(() => {
+ vi.unstubAllGlobals();
+ __resetClerkQueryClientForTest();
+});
+
+describe('getClerkQueryClient', () => {
+ it('returns undefined when window is not defined (SSR)', () => {
+ vi.stubGlobal('window', undefined);
+
+ expect(getClerkQueryClient()).toBeUndefined();
+ });
+
+ it('does not cache the SSR undefined — a later browser call still creates a client', () => {
+ vi.stubGlobal('window', undefined);
+ expect(getClerkQueryClient()).toBeUndefined();
+
+ vi.unstubAllGlobals();
+ const client = getClerkQueryClient();
+ expect(client).toBeInstanceOf(QueryClient);
+ });
+
+ it('lazy-creates a singleton on the browser and returns the same instance on repeated calls', () => {
+ const first = getClerkQueryClient();
+ const second = getClerkQueryClient();
+
+ expect(first).toBeInstanceOf(QueryClient);
+ expect(second).toBe(first);
+ });
+});
+
+describe('__resetClerkQueryClientForTest', () => {
+ it('clears the singleton so the next read lazy-creates a fresh client', () => {
+ const original = getClerkQueryClient();
+ expect(original).toBeInstanceOf(QueryClient);
+
+ __resetClerkQueryClientForTest();
+
+ const next = getClerkQueryClient();
+ expect(next).toBeInstanceOf(QueryClient);
+ expect(next).not.toBe(original);
+ });
+});
+
+describe('__setClerkQueryClientForTest', () => {
+ it('installs a caller-supplied client and returns it from getClerkQueryClient', () => {
+ const custom = new QueryClient();
+ __setClerkQueryClientForTest(custom);
+
+ expect(getClerkQueryClient()).toBe(custom);
+ });
+
+ it('installs the "no client" state without triggering lazy creation on subsequent reads', () => {
+ __setClerkQueryClientForTest(undefined);
+
+ expect(getClerkQueryClient()).toBeUndefined();
+ expect(getClerkQueryClient()).toBeUndefined();
+ });
+});
+
+describe('__createClerkTestQueryClient', () => {
+ it('returns a QueryClient with deterministic defaults and installs it as the singleton', () => {
+ const client = __createClerkTestQueryClient();
+
+ expect(client).toBeInstanceOf(QueryClient);
+ expect(getClerkQueryClient()).toBe(client);
+
+ const defaults = client.getDefaultOptions().queries;
+ expect(defaults?.retry).toBe(false);
+ expect(defaults?.staleTime).toBe(Infinity);
+ expect(defaults?.refetchOnWindowFocus).toBe(false);
+ expect(defaults?.refetchOnReconnect).toBe(false);
+ expect(defaults?.refetchOnMount).toBe(false);
+ });
+});

packages/shared/src/react/clerk-rq/__tests__/useBaseQuery.spec.tsx

@@ -3,6 +3,7 @@ import React from 'react';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
 import { createMockClerk, createMockQueryClient } from '../../hooks/__tests__/mocks/clerk';
+import { __resetClerkQueryClientForTest, __setClerkQueryClientForTest } from '../clerk-query-client';
 import { useClerkInfiniteQuery } from '../useInfiniteQuery';
 import { useClerkQuery } from '../useQuery';
 
@@ -16,22 +17,15 @@ vi.mock('../../contexts', () => ({
 
 const wrapper = ({ children }: { children: React.ReactNode }) => <>{children}</>;
 
-const makeClerkWithoutQueryClient = () => {
- const mockClerk = createMockClerk({ queryClient: null });
- Object.defineProperty(mockClerk, '__internal_queryClient', {
- get: () => undefined,
- configurable: true,
- });
- return mockClerk;
-};
-
 afterEach(() => {
  vi.clearAllMocks();
+ __resetClerkQueryClientForTest();
 });
 
 describe('useBaseQuery - dummy result while query client is not attached', () => {
  beforeEach(() => {
- activeClerk = makeClerkWithoutQueryClient();
+ activeClerk = createMockClerk({ queryClient: null });
+ __setClerkQueryClientForTest(undefined);
  });
 
  it('reports isLoading: true when the query would be enabled', () => {
@@ -109,8 +103,8 @@ describe('useBaseQuery - dummy result while query client is not attached', () =>
 
 describe('useBaseQuery - normal behavior once query client attaches', () => {
  it('delegates to the real observer when the query client is loaded', async () => {
-const queryClient = createMockQueryClient();
- activeClerk = createMockClerk({ queryClient });
+ createMockQueryClient();
+ activeClerk = createMockClerk({ queryClient: undefined });
 
  const queryFn = vi.fn(async () => 'result');
  const { result } = renderHook(

packages/shared/src/react/clerk-rq/clerk-query-client.ts

@@ -0,0 +1,66 @@
+import { QueryClient } from '@tanstack/query-core';
+
+/**
+ * The QueryClient backing every clerk-rq hook. Owned by `@clerk/shared` so the
+ * `QueryObserver` that observes it and the `Query` objects inside it always
+ * resolve to the same `@tanstack/query-core` (no cross-bundle drift between
+ * the consumer-side `@clerk/shared` and the production CDN `clerk-js` bundle).
+ *
+ * Lazily instantiated on the client only. Server-side renders return
+ * `undefined` so per-request renders never share a cache across requests.
+ */
+let clerkQueryClient: QueryClient | undefined;
+let initialized = false;
+
+export function getClerkQueryClient(): QueryClient | undefined {
+ if (typeof window === 'undefined') {
+ return undefined;
+ }
+ if (!initialized) {
+ clerkQueryClient = new QueryClient();
+ initialized = true;
+ }
+ return clerkQueryClient;
+}
+
+/**
+ * Test-only: install a custom client (for deterministic defaults like
+ * `staleTime: Infinity`) or pass `undefined` to simulate the "no client"
+ * state without triggering lazy creation on subsequent reads.
+ */
+export function __setClerkQueryClientForTest(client: QueryClient | undefined): void {
+ clerkQueryClient = client;
+ initialized = true;
+}
+
+/**
+ * Test-only: build and install a fresh `QueryClient` with deterministic
+ * defaults (no retries, infinite stale time, no refetching). Returns the
+ * client so the spec can read/write its cache directly.
+ *
+ * Avoids forcing every test consumer to depend on `@tanstack/query-core`.
+ */
+export function __createClerkTestQueryClient(): QueryClient {
+ const client = new QueryClient({
+ defaultOptions: {
+ queries: {
+ retry: false,
+ staleTime: Infinity,
+ refetchOnWindowFocus: false,
+ refetchOnReconnect: false,
+ refetchOnMount: false,
+ },
+ },
+ });
+ __setClerkQueryClientForTest(client);
+ return client;
+}
+
+/**
+ * Test-only: clear both the override and the initialization flag so the
+ * next read lazy-creates a fresh client.
+ */
+export function __resetClerkQueryClientForTest(): void {
+ clerkQueryClient = undefined;
+ initialized = false;
+}

.changeset/invert-clerk-rq-ownership.md

@@ -0,0 +1,11 @@
+---
+'@clerk/shared': patch
+'@clerk/clerk-js': patch
+'@clerk/react': patch
+---
+
+Move ownership of the clerk-rq `QueryClient` from `@clerk/clerk-js` into `@clerk/shared`. The `QueryObserver` (constructed in `@clerk/shared`) and the `Query` objects it observes now always come from a single `@tanstack/query-core` resolution — the cross-bundle API contract that produced #8428 (`Query.isFetched is not a function`) no longer exists.
+
+This removes the undocumented `clerk.__internal_queryClient` getter from both `@clerk/clerk-js` and `@clerk/react`'s `IsomorphicClerk`. The `QueryClient` is owned by an internal singleton in `@clerk/shared`, lazily instantiated on the browser only — server renders return `undefined`, preserving SSR safety and avoiding cross-request cache sharing.
+
+`@tanstack/query-core` is no longer a direct dependency of `@clerk/clerk-js`; it remains a dep of `@clerk/shared` and resolves consumer-side as before.

packages/clerk-js/bundlewatch.config.json

@@ -9,7 +9,6 @@
  { "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,7 +91,6 @@
  "@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,12 +110,6 @@ 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/clerk.ts

@@ -138,7 +138,6 @@ 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';
@@ -248,7 +247,6 @@ 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'];
@@ -268,28 +266,6 @@ 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/test/mock-helpers.ts

@@ -1,7 +1,7 @@
+import { __createClerkTestQueryClient } from '@clerk/shared/react';
 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;
@@ -46,19 +46,7 @@ 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,
- },
- },
- }),
- };
+ __createClerkTestQueryClient();
 
  mockMethodsOf(clerkAny);
  if (clerkAny.client) {
@@ -92,12 +80,6 @@ export const mockClerkMethods = (clerk: LoadedClerk): DeepVitestMocked<LoadedCle
  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/react/src/isomorphicClerk.ts

@@ -344,11 +344,6 @@ export class IsomorphicClerk implements IsomorphicLoadedClerk {
  return this.clerkjs?.isStandardBrowser || this.options.standardBrowser || false;
  }
 
- get __internal_queryClient() {
- // @ts-expect-error - __internal_queryClient is not typed
- return this.clerkjs?.__internal_queryClient;
- }
-
  get isSatellite() {
  // This getter can run in environments where window is not available.
  // In those cases we should expect and use domain as a string
@@ -656,13 +651,6 @@ export class IsomorphicClerk implements IsomorphicLoadedClerk {
  this.on('status', listener, { notify: true });
  });
 
- // @ts-expect-error - queryClientStatus is not typed
- this.#eventBus.internal.retrieveListeners('queryClientStatus')?.forEach(listener => {
- // Since clerkjs exists it will call `this.clerkjs.on('queryClientStatus', listener)`
- // @ts-expect-error - queryClientStatus is not typed
- this.on('queryClientStatus', listener, { notify: true });
- });
-
  if (this.preopenSignIn !== null) {
  clerkjs.openSignIn(this.preopenSignIn);
  }

packages/shared/src/react/clerk-rq/__tests__/clerk-query-client.spec.ts

@@ -0,0 +1,84 @@
+import { QueryClient } from '@tanstack/query-core';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import {
+ __createClerkTestQueryClient,
+ __resetClerkQueryClientForTest,
+ __setClerkQueryClientForTest,
+ getClerkQueryClient,
+} from '../clerk-query-client';
+
+afterEach(() => {
+ vi.unstubAllGlobals();
+ __resetClerkQueryClientForTest();
+});
+
+describe('getClerkQueryClient', () => {
+ it('returns undefined when window is not defined (SSR)', () => {
+ vi.stubGlobal('window', undefined);
+
+ expect(getClerkQueryClient()).toBeUndefined();
+ });
+
+ it('does not cache the SSR undefined — a later browser call still creates a client', () => {
+ vi.stubGlobal('window', undefined);
+ expect(getClerkQueryClient()).toBeUndefined();
+
+ vi.unstubAllGlobals();
+ const client = getClerkQueryClient();
+ expect(client).toBeInstanceOf(QueryClient);
+ });
+
+ it('lazy-creates a singleton on the browser and returns the same instance on repeated calls', () => {
+ const first = getClerkQueryClient();
+ const second = getClerkQueryClient();
+
+ expect(first).toBeInstanceOf(QueryClient);
+ expect(second).toBe(first);
+ });
+});
+
+describe('__resetClerkQueryClientForTest', () => {
+ it('clears the singleton so the next read lazy-creates a fresh client', () => {
+ const original = getClerkQueryClient();
+ expect(original).toBeInstanceOf(QueryClient);
+
+ __resetClerkQueryClientForTest();
+
+ const next = getClerkQueryClient();
+ expect(next).toBeInstanceOf(QueryClient);
+ expect(next).not.toBe(original);
+ });
+});
+
+describe('__setClerkQueryClientForTest', () => {
+ it('installs a caller-supplied client and returns it from getClerkQueryClient', () => {
+ const custom = new QueryClient();
+ __setClerkQueryClientForTest(custom);
+
+ expect(getClerkQueryClient()).toBe(custom);
+ });
+
+ it('installs the "no client" state without triggering lazy creation on subsequent reads', () => {
+ __setClerkQueryClientForTest(undefined);
+
+ expect(getClerkQueryClient()).toBeUndefined();
+ expect(getClerkQueryClient()).toBeUndefined();
+ });
+});
+
+describe('__createClerkTestQueryClient', () => {
+ it('returns a QueryClient with deterministic defaults and installs it as the singleton', () => {
+ const client = __createClerkTestQueryClient();
+
+ expect(client).toBeInstanceOf(QueryClient);
+ expect(getClerkQueryClient()).toBe(client);
+
+ const defaults = client.getDefaultOptions().queries;
+ expect(defaults?.retry).toBe(false);
+ expect(defaults?.staleTime).toBe(Infinity);
+ expect(defaults?.refetchOnWindowFocus).toBe(false);
+ expect(defaults?.refetchOnReconnect).toBe(false);
+ expect(defaults?.refetchOnMount).toBe(false);
+ });
+});

packages/shared/src/react/clerk-rq/__tests__/useBaseQuery.spec.tsx

@@ -3,6 +3,7 @@ import React from 'react';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
 import { createMockClerk, createMockQueryClient } from '../../hooks/__tests__/mocks/clerk';
+import { __resetClerkQueryClientForTest, __setClerkQueryClientForTest } from '../clerk-query-client';
 import { useClerkInfiniteQuery } from '../useInfiniteQuery';
 import { useClerkQuery } from '../useQuery';
 
@@ -16,22 +17,15 @@ vi.mock('../../contexts', () => ({
 
 const wrapper = ({ children }: { children: React.ReactNode }) => <>{children}</>;
 
-const makeClerkWithoutQueryClient = () => {
- const mockClerk = createMockClerk({ queryClient: null });
- Object.defineProperty(mockClerk, '__internal_queryClient', {
- get: () => undefined,
- configurable: true,
- });
- return mockClerk;
-};
-
 afterEach(() => {
  vi.clearAllMocks();
+ __resetClerkQueryClientForTest();
 });
 
 describe('useBaseQuery - dummy result while query client is not attached', () => {
  beforeEach(() => {
- activeClerk = makeClerkWithoutQueryClient();
+ activeClerk = createMockClerk({ queryClient: null });
+ __setClerkQueryClientForTest(undefined);
  });
 
  it('reports isLoading: true when the query would be enabled', () => {
@@ -109,8 +103,8 @@ describe('useBaseQuery - dummy result while query client is not attached', () =>
 
 describe('useBaseQuery - normal behavior once query client attaches', () => {
  it('delegates to the real observer when the query client is loaded', async () => {
-const queryClient = createMockQueryClient();
- activeClerk = createMockClerk({ queryClient });
+ createMockQueryClient();
+ activeClerk = createMockClerk({ queryClient: undefined });
 
  const queryFn = vi.fn(async () => 'result');
  const { result } = renderHook(

packages/shared/src/react/clerk-rq/clerk-query-client.ts

@@ -0,0 +1,66 @@
+import { QueryClient } from '@tanstack/query-core';
+
+/**
+ * The QueryClient backing every clerk-rq hook. Owned by `@clerk/shared` so the
+ * `QueryObserver` that observes it and the `Query` objects inside it always
+ * resolve to the same `@tanstack/query-core` (no cross-bundle drift between
+ * the consumer-side `@clerk/shared` and the production CDN `clerk-js` bundle).
+ *
+ * Lazily instantiated on the client only. Server-side renders return
+ * `undefined` so per-request renders never share a cache across requests.
+ */
+let clerkQueryClient: QueryClient | undefined;
+let initialized = false;
+
+export function getClerkQueryClient(): QueryClient | undefined {
+ if (typeof window === 'undefined') {
+ return undefined;
+ }
+ if (!initialized) {
+ clerkQueryClient = new QueryClient();
+ initialized = true;
+ }
+ return clerkQueryClient;
+}
+
+/**
+ * Test-only: install a custom client (for deterministic defaults like
+ * `staleTime: Infinity`) or pass `undefined` to simulate the "no client"
+ * state without triggering lazy creation on subsequent reads.
+ */
+export function __setClerkQueryClientForTest(client: QueryClient | undefined): void {
+ clerkQueryClient = client;
+ initialized = true;
+}
+
+/**
+ * Test-only: build and install a fresh `QueryClient` with deterministic
+ * defaults (no retries, infinite stale time, no refetching). Returns the
+ * client so the spec can read/write its cache directly.
+ *
+ * Avoids forcing every test consumer to depend on `@tanstack/query-core`.
+ */
+export function __createClerkTestQueryClient(): QueryClient {
+ const client = new QueryClient({
+ defaultOptions: {
+ queries: {
+ retry: false,
+ staleTime: Infinity,
+ refetchOnWindowFocus: false,
+ refetchOnReconnect: false,
+ refetchOnMount: false,
+ },
+ },
+ });
+ __setClerkQueryClientForTest(client);
+ return client;
+}
+
+/**
+ * Test-only: clear both the override and the initialization flag so the
+ * next read lazy-creates a fresh client.
+ */
+export function __resetClerkQueryClientForTest(): void {
+ clerkQueryClient = undefined;
+ initialized = false;
+}

.changeset/invert-clerk-rq-ownership.md

@@ -0,0 +1,11 @@
+---
+'@clerk/shared': patch
+'@clerk/clerk-js': patch
+'@clerk/react': patch
+---
+
+Move ownership of the clerk-rq `QueryClient` from `@clerk/clerk-js` into `@clerk/shared`. The `QueryObserver` (constructed in `@clerk/shared`) and the `Query` objects it observes now always come from a single `@tanstack/query-core` resolution — the cross-bundle API contract that produced #8428 (`Query.isFetched is not a function`) no longer exists.
+
+This removes the undocumented `clerk.__internal_queryClient` getter from both `@clerk/clerk-js` and `@clerk/react`'s `IsomorphicClerk`. The `QueryClient` is owned by an internal singleton in `@clerk/shared`, lazily instantiated on the browser only — server renders return `undefined`, preserving SSR safety and avoiding cross-request cache sharing.
+
+`@tanstack/query-core` is no longer a direct dependency of `@clerk/clerk-js`; it remains a dep of `@clerk/shared` and resolves consumer-side as before.

packages/clerk-js/bundlewatch.config.json

@@ -9,7 +9,6 @@
  { "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,7 +91,6 @@
  "@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,12 +110,6 @@ 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/clerk.ts

@@ -138,7 +138,6 @@ 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';
@@ -248,7 +247,6 @@ 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'];
@@ -268,28 +266,6 @@ 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/test/mock-helpers.ts

@@ -1,7 +1,7 @@
+import { __createClerkTestQueryClient } from '@clerk/shared/react';
 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;
@@ -46,19 +46,7 @@ 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,
- },
- },
- }),
- };
+ __createClerkTestQueryClient();
 
  mockMethodsOf(clerkAny);
  if (clerkAny.client) {
@@ -92,12 +80,6 @@ export const mockClerkMethods = (clerk: LoadedClerk): DeepVitestMocked<LoadedCle
  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/react/src/isomorphicClerk.ts

@@ -344,11 +344,6 @@ export class IsomorphicClerk implements IsomorphicLoadedClerk {
  return this.clerkjs?.isStandardBrowser || this.options.standardBrowser || false;
  }
 
- get __internal_queryClient() {
- // @ts-expect-error - __internal_queryClient is not typed
- return this.clerkjs?.__internal_queryClient;
- }
-
  get isSatellite() {
  // This getter can run in environments where window is not available.
  // In those cases we should expect and use domain as a string
@@ -656,13 +651,6 @@ export class IsomorphicClerk implements IsomorphicLoadedClerk {
  this.on('status', listener, { notify: true });
  });
 
- // @ts-expect-error - queryClientStatus is not typed
- this.#eventBus.internal.retrieveListeners('queryClientStatus')?.forEach(listener => {
- // Since clerkjs exists it will call `this.clerkjs.on('queryClientStatus', listener)`
- // @ts-expect-error - queryClientStatus is not typed
- this.on('queryClientStatus', listener, { notify: true });
- });
-
  if (this.preopenSignIn !== null) {
  clerkjs.openSignIn(this.preopenSignIn);
  }

packages/shared/src/react/clerk-rq/__tests__/clerk-query-client.spec.ts

@@ -0,0 +1,84 @@
+import { QueryClient } from '@tanstack/query-core';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import {
+ __createClerkTestQueryClient,
+ __resetClerkQueryClientForTest,
+ __setClerkQueryClientForTest,
+ getClerkQueryClient,
+} from '../clerk-query-client';
+
+afterEach(() => {
+ vi.unstubAllGlobals();
+ __resetClerkQueryClientForTest();
+});
+
+describe('getClerkQueryClient', () => {
+ it('returns undefined when window is not defined (SSR)', () => {
+ vi.stubGlobal('window', undefined);
+
+ expect(getClerkQueryClient()).toBeUndefined();
+ });
+
+ it('does not cache the SSR undefined — a later browser call still creates a client', () => {
+ vi.stubGlobal('window', undefined);
+ expect(getClerkQueryClient()).toBeUndefined();
+
+ vi.unstubAllGlobals();
+ const client = getClerkQueryClient();
+ expect(client).toBeInstanceOf(QueryClient);
+ });
+
+ it('lazy-creates a singleton on the browser and returns the same instance on repeated calls', () => {
+ const first = getClerkQueryClient();
+ const second = getClerkQueryClient();
+
+ expect(first).toBeInstanceOf(QueryClient);
+ expect(second).toBe(first);
+ });
+});
+
+describe('__resetClerkQueryClientForTest', () => {
+ it('clears the singleton so the next read lazy-creates a fresh client', () => {
+ const original = getClerkQueryClient();
+ expect(original).toBeInstanceOf(QueryClient);
+
+ __resetClerkQueryClientForTest();
+
+ const next = getClerkQueryClient();
+ expect(next).toBeInstanceOf(QueryClient);
+ expect(next).not.toBe(original);
+ });
+});
+
+describe('__setClerkQueryClientForTest', () => {
+ it('installs a caller-supplied client and returns it from getClerkQueryClient', () => {
+ const custom = new QueryClient();
+ __setClerkQueryClientForTest(custom);
+
+ expect(getClerkQueryClient()).toBe(custom);
+ });
+
+ it('installs the "no client" state without triggering lazy creation on subsequent reads', () => {
+ __setClerkQueryClientForTest(undefined);
+
+ expect(getClerkQueryClient()).toBeUndefined();
+ expect(getClerkQueryClient()).toBeUndefined();
+ });
+});
+
+describe('__createClerkTestQueryClient', () => {
+ it('returns a QueryClient with deterministic defaults and installs it as the singleton', () => {
+ const client = __createClerkTestQueryClient();
+
+ expect(client).toBeInstanceOf(QueryClient);
+ expect(getClerkQueryClient()).toBe(client);
+
+ const defaults = client.getDefaultOptions().queries;
+ expect(defaults?.retry).toBe(false);
+ expect(defaults?.staleTime).toBe(Infinity);
+ expect(defaults?.refetchOnWindowFocus).toBe(false);
+ expect(defaults?.refetchOnReconnect).toBe(false);
+ expect(defaults?.refetchOnMount).toBe(false);
+ });
+});

packages/shared/src/react/clerk-rq/__tests__/useBaseQuery.spec.tsx

@@ -3,6 +3,7 @@ import React from 'react';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
 import { createMockClerk, createMockQueryClient } from '../../hooks/__tests__/mocks/clerk';
+import { __resetClerkQueryClientForTest, __setClerkQueryClientForTest } from '../clerk-query-client';
 import { useClerkInfiniteQuery } from '../useInfiniteQuery';
 import { useClerkQuery } from '../useQuery';
 
@@ -16,22 +17,15 @@ vi.mock('../../contexts', () => ({
 
 const wrapper = ({ children }: { children: React.ReactNode }) => <>{children}</>;
 
-const makeClerkWithoutQueryClient = () => {
- const mockClerk = createMockClerk({ queryClient: null });
- Object.defineProperty(mockClerk, '__internal_queryClient', {
- get: () => undefined,
- configurable: true,
- });
- return mockClerk;
-};
-
 afterEach(() => {
  vi.clearAllMocks();
+ __resetClerkQueryClientForTest();
 });
 
 describe('useBaseQuery - dummy result while query client is not attached', () => {
  beforeEach(() => {
- activeClerk = makeClerkWithoutQueryClient();
+ activeClerk = createMockClerk({ queryClient: null });
+ __setClerkQueryClientForTest(undefined);
  });
 
  it('reports isLoading: true when the query would be enabled', () => {
@@ -109,8 +103,8 @@ describe('useBaseQuery - dummy result while query client is not attached', () =>
 
 describe('useBaseQuery - normal behavior once query client attaches', () => {
  it('delegates to the real observer when the query client is loaded', async () => {
-const queryClient = createMockQueryClient();
- activeClerk = createMockClerk({ queryClient });
+ createMockQueryClient();
+ activeClerk = createMockClerk({ queryClient: undefined });
 
  const queryFn = vi.fn(async () => 'result');
  const { result } = renderHook(

packages/shared/src/react/clerk-rq/clerk-query-client.ts

@@ -0,0 +1,66 @@
+import { QueryClient } from '@tanstack/query-core';
+
+/**
+ * The QueryClient backing every clerk-rq hook. Owned by `@clerk/shared` so the
+ * `QueryObserver` that observes it and the `Query` objects inside it always
+ * resolve to the same `@tanstack/query-core` (no cross-bundle drift between
+ * the consumer-side `@clerk/shared` and the production CDN `clerk-js` bundle).
+ *
+ * Lazily instantiated on the client only. Server-side renders return
+ * `undefined` so per-request renders never share a cache across requests.
+ */
+let clerkQueryClient: QueryClient | undefined;
+let initialized = false;
+
+export function getClerkQueryClient(): QueryClient | undefined {
+ if (typeof window === 'undefined') {
+ return undefined;
+ }
+ if (!initialized) {
+ clerkQueryClient = new QueryClient();
+ initialized = true;
+ }
+ return clerkQueryClient;
+}
+
+/**
+ * Test-only: install a custom client (for deterministic defaults like
+ * `staleTime: Infinity`) or pass `undefined` to simulate the "no client"
+ * state without triggering lazy creation on subsequent reads.
+ */
+export function __setClerkQueryClientForTest(client: QueryClient | undefined): void {
+ clerkQueryClient = client;
+ initialized = true;
+}
+
+/**
+ * Test-only: build and install a fresh `QueryClient` with deterministic
+ * defaults (no retries, infinite stale time, no refetching). Returns the
+ * client so the spec can read/write its cache directly.
+ *
+ * Avoids forcing every test consumer to depend on `@tanstack/query-core`.
+ */
+export function __createClerkTestQueryClient(): QueryClient {
+ const client = new QueryClient({
+ defaultOptions: {
+ queries: {
+ retry: false,
+ staleTime: Infinity,
+ refetchOnWindowFocus: false,
+ refetchOnReconnect: false,
+ refetchOnMount: false,
+ },
+ },
+ });
+ __setClerkQueryClientForTest(client);
+ return client;
+}
+
+/**
+ * Test-only: clear both the override and the initialization flag so the
+ * next read lazy-creates a fresh client.
+ */
+export function __resetClerkQueryClientForTest(): void {
+ clerkQueryClient = undefined;
+ initialized = false;
+}