feat(shared): React Query variant for useSubscription (#6913)

Co-authored-by: Nikos Douvlis <[email protected]>

Author: 2 people

.changeset/tricky-badgers-post.md

@@ -0,0 +1,7 @@
+---
+'@clerk/clerk-js': patch
+'@clerk/shared': patch
+'@clerk/clerk-react': patch
+---
+
+Experimental: Ground work for fixing stale data between hooks and components by sharing a single cache. 

packages/clerk-js/package.json

@@ -71,6 +71,7 @@
     "@formkit/auto-animate": "^0.8.2",
     "@stripe/stripe-js": "5.6.0",
     "@swc/helpers": "^0.5.17",
+    "@tanstack/query-core": "5.87.4",
     "@zxcvbn-ts/core": "3.0.4",
     "@zxcvbn-ts/language-common": "3.0.4",
     "alien-signals": "2.0.6",

packages/clerk-js/rspack.config.js

@@ -117,6 +117,12 @@ const common = ({ mode, variant, disableRHC = false }) => {
             chunks: 'all',
             enforce: true,
           },
+          queryCoreVendor: {
+            test: /[\\/]node_modules[\\/](@tanstack\/query-core)[\\/]/,
+            name: 'query-core-vendors',
+            chunks: 'all',
+            enforce: true,
+          },
           /**
            * Sign up is shared between the SignUp component and the SignIn component.
            */

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

@@ -94,6 +94,7 @@ import type {
 } from '@clerk/shared/types';
 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';
 
@@ -219,6 +220,7 @@ export class Clerk implements ClerkInterface {
   // converted to protected environment to support `updateEnvironment` type assertion
   protected environment?: EnvironmentResource | null;
 
+  #queryClient: QueryClient | undefined;
   #publishableKey = '';
   #domain: DomainOrProxyUrl['domain'];
   #proxyUrl: DomainOrProxyUrl['proxyUrl'];
@@ -237,6 +239,28 @@ export class Clerk implements ClerkInterface {
   #touchThrottledUntil = 0;
   #publicEventBus = createClerkEventBus();
 
+  get __internal_queryClient(): { __tag: 'clerk-rq-client'; client: QueryClient } | undefined {
+    if (!this.#queryClient) {
+      void import('./query-core')
+        .then(module => module.QueryClient)
+        .then(QueryClient => {
+          if (this.#queryClient) {
+            return;
+          }
+          this.#queryClient = new QueryClient();
+          // @ts-expect-error - queryClientStatus is not typed
+          this.#publicEventBus.emit('queryClientStatus', 'ready');
+        });
+    }
+
+    return this.#queryClient
+      ? {
+          __tag: 'clerk-rq-client',
+          client: this.#queryClient,
+        }
+      : undefined;
+  }
+
   public __internal_getCachedResources:
     | (() => Promise<{ client: ClientJSONSnapshot | null; environment: EnvironmentJSONSnapshot | null }>)
     | undefined;

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

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

packages/react/src/isomorphicClerk.ts

@@ -146,6 +146,7 @@ export class IsomorphicClerk implements IsomorphicLoadedClerk {
   private premountApiKeysNodes = new Map<HTMLDivElement, APIKeysProps | undefined>();
   private premountOAuthConsentNodes = new Map<HTMLDivElement, __internal_OAuthConsentProps | undefined>();
   private premountTaskChooseOrganizationNodes = new Map<HTMLDivElement, TaskChooseOrganizationProps | undefined>();
+
   // A separate Map of `addListener` method calls to handle multiple listeners.
   private premountAddListenerCalls = new Map<
     ListenerCallback,
@@ -283,6 +284,11 @@ 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
@@ -567,6 +573,13 @@ 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/package.json

@@ -163,6 +163,7 @@
   "devDependencies": {
     "@stripe/react-stripe-js": "3.1.1",
     "@stripe/stripe-js": "5.6.0",
+    "@tanstack/query-core": "5.87.4",
     "@types/glob-to-regexp": "0.4.4",
     "@types/js-cookie": "3.0.6",
     "cross-fetch": "^4.1.0",

packages/shared/src/react/clerk-rq/queryOptions.ts

@@ -0,0 +1,80 @@
+import type {
+  DataTag,
+  DefaultError,
+  InitialDataFunction,
+  NonUndefinedGuard,
+  OmitKeyof,
+  QueryFunction,
+  QueryKey,
+  SkipToken,
+} from '@tanstack/query-core';
+
+import type { UseQueryOptions } from './types';
+
+export type UndefinedInitialDataOptions<
+  TQueryFnData = unknown,
+  TError = DefaultError,
+  TData = TQueryFnData,
+  TQueryKey extends QueryKey = QueryKey,
+> = UseQueryOptions<TQueryFnData, TError, TData, TQueryKey> & {
+  initialData?: undefined | InitialDataFunction<NonUndefinedGuard<TQueryFnData>> | NonUndefinedGuard<TQueryFnData>;
+};
+
+export type UnusedSkipTokenOptions<
+  TQueryFnData = unknown,
+  TError = DefaultError,
+  TData = TQueryFnData,
+  TQueryKey extends QueryKey = QueryKey,
+> = OmitKeyof<UseQueryOptions<TQueryFnData, TError, TData, TQueryKey>, 'queryFn'> & {
+  queryFn?: Exclude<UseQueryOptions<TQueryFnData, TError, TData, TQueryKey>['queryFn'], SkipToken | undefined>;
+};
+
+export type DefinedInitialDataOptions<
+  TQueryFnData = unknown,
+  TError = DefaultError,
+  TData = TQueryFnData,
+  TQueryKey extends QueryKey = QueryKey,
+> = Omit<UseQueryOptions<TQueryFnData, TError, TData, TQueryKey>, 'queryFn'> & {
+  initialData: NonUndefinedGuard<TQueryFnData> | (() => NonUndefinedGuard<TQueryFnData>);
+  queryFn?: QueryFunction<TQueryFnData, TQueryKey>;
+};
+
+export function queryOptions<
+  TQueryFnData = unknown,
+  TError = DefaultError,
+  TData = TQueryFnData,
+  TQueryKey extends QueryKey = QueryKey,
+>(
+  options: DefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>,
+): DefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey> & {
+  queryKey: DataTag<TQueryKey, TQueryFnData, TError>;
+};
+
+export function queryOptions<
+  TQueryFnData = unknown,
+  TError = DefaultError,
+  TData = TQueryFnData,
+  TQueryKey extends QueryKey = QueryKey,
+>(
+  options: UnusedSkipTokenOptions<TQueryFnData, TError, TData, TQueryKey>,
+): UnusedSkipTokenOptions<TQueryFnData, TError, TData, TQueryKey> & {
+  queryKey: DataTag<TQueryKey, TQueryFnData, TError>;
+};
+
+export function queryOptions<
+  TQueryFnData = unknown,
+  TError = DefaultError,
+  TData = TQueryFnData,
+  TQueryKey extends QueryKey = QueryKey,
+>(
+  options: UndefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>,
+): UndefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey> & {
+  queryKey: DataTag<TQueryKey, TQueryFnData, TError>;
+};
+
+/**
+ *
+ */
+export function queryOptions(options: unknown) {
+  return options;
+}

packages/shared/src/react/clerk-rq/types.ts

@@ -0,0 +1,54 @@
+import type {
+  DefaultError,
+  DefinedQueryObserverResult,
+  InfiniteQueryObserverOptions,
+  OmitKeyof,
+  QueryKey,
+  QueryObserverOptions,
+  QueryObserverResult,
+} from '@tanstack/query-core';
+
+export type AnyUseBaseQueryOptions = UseBaseQueryOptions<any, any, any, any, any>;
+export interface UseBaseQueryOptions<
+  TQueryFnData = unknown,
+  TError = DefaultError,
+  TData = TQueryFnData,
+  TQueryData = TQueryFnData,
+  TQueryKey extends QueryKey = QueryKey,
+> extends QueryObserverOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey> {
+  /**
+   * Set this to `false` to unsubscribe this observer from updates to the query cache.
+   * Defaults to `true`.
+   */
+  subscribed?: boolean;
+}
+
+export type AnyUseQueryOptions = UseQueryOptions<any, any, any, any>;
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface UseQueryOptions<
+  TQueryFnData = unknown,
+  TError = DefaultError,
+  TData = TQueryFnData,
+  TQueryKey extends QueryKey = QueryKey,
+> extends OmitKeyof<UseBaseQueryOptions<TQueryFnData, TError, TData, TQueryFnData, TQueryKey>, 'suspense'> {}
+
+export type AnyUseInfiniteQueryOptions = UseInfiniteQueryOptions<any, any, any, any, any>;
+export interface UseInfiniteQueryOptions<
+  TQueryFnData = unknown,
+  TError = DefaultError,
+  TData = TQueryFnData,
+  TQueryKey extends QueryKey = QueryKey,
+  TPageParam = unknown,
+> extends OmitKeyof<InfiniteQueryObserverOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>, 'suspense'> {
+  /**
+   * Set this to `false` to unsubscribe this observer from updates to the query cache.
+   * Defaults to `true`.
+   */
+  subscribed?: boolean;
+}
+
+export type UseBaseQueryResult<TData = unknown, TError = DefaultError> = QueryObserverResult<TData, TError>;
+
+export type UseQueryResult<TData = unknown, TError = DefaultError> = UseBaseQueryResult<TData, TError>;
+
+export type DefinedUseQueryResult<TData = unknown, TError = DefaultError> = DefinedQueryObserverResult<TData, TError>;

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

@@ -0,0 +1,84 @@
+import type { QueryClient } from '@tanstack/query-core';
+import { useEffect, useState } from 'react';
+
+import { useClerkInstanceContext } from '../contexts';
+
+export type RecursiveMock = {
+  (...args: unknown[]): RecursiveMock;
+} & {
+  readonly [key in string | symbol]: RecursiveMock;
+};
+
+/**
+ * Creates a recursively self-referential Proxy that safely handles:
+ * - Arbitrary property access (e.g., obj.any.prop.path)
+ * - Function calls at any level (e.g., obj.a().b.c())
+ * - Construction (e.g., new obj.a.b())
+ *
+ * Always returns itself to allow infinite chaining without throwing.
+ */
+function createRecursiveProxy(label: string): RecursiveMock {
+  // The callable target for the proxy so that `apply` works
+  const callableTarget = function noop(): void {};
+
+  // eslint-disable-next-line prefer-const
+  let self: RecursiveMock;
+  const handler: ProxyHandler<typeof callableTarget> = {
+    get(_target, prop) {
+      // Avoid being treated as a Promise/thenable by test runners or frameworks
+      if (prop === 'then') {
+        return undefined;
+      }
+      if (prop === 'toString') {
+        return () => `[${label}]`;
+      }
+      if (prop === Symbol.toPrimitive) {
+        return () => 0;
+      }
+      return self;
+    },
+    apply() {
+      return self;
+    },
+    construct() {
+      return self as unknown as object;
+    },
+    has() {
+      return false;
+    },
+    set() {
+      return false;
+    },
+  };
+
+  self = new Proxy(callableTarget, handler) as unknown as RecursiveMock;
+  return self;
+}
+
+const mockQueryClient = createRecursiveProxy('ClerkMockQueryClient') as unknown as QueryClient;
+
+const useClerkQueryClient = (): [QueryClient, boolean] => {
+  const clerk = useClerkInstanceContext();
+
+  // @ts-expect-error - __internal_queryClient is not typed
+  const queryClient = clerk.__internal_queryClient as { __tag: 'clerk-rq-client'; client: QueryClient } | undefined;
+  const [, setQueryClientLoaded] = useState(
+    typeof queryClient === 'object' && '__tag' in queryClient && queryClient.__tag === 'clerk-rq-client',
+  );
+
+  useEffect(() => {
+    const _setQueryClientLoaded = () => setQueryClientLoaded(true);
+    // @ts-expect-error - queryClientStatus is not typed
+    clerk.on('queryClientStatus', _setQueryClientLoaded);
+    return () => {
+      // @ts-expect-error - queryClientStatus is not typed
+      clerk.off('queryClientStatus', _setQueryClientLoaded);
+    };
+  }, [clerk, setQueryClientLoaded]);
+
+  const isLoaded = typeof queryClient === 'object' && '__tag' in queryClient && queryClient.__tag === 'clerk-rq-client';
+
+  return [queryClient?.client || mockQueryClient, isLoaded];
+};
+
+export { useClerkQueryClient };