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;
+}