feat(shared): useSubscription variant with React Query

Author: panteliselef

packages/clerk-js/rspack.config.js

@@ -114,6 +114,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

@@ -95,7 +95,7 @@ import type {
   WaitlistResource,
   Web3Provider,
 } from '@clerk/types';
-import { QueryClient } from '@tanstack/query-core';
+import type { QueryClient } from '@tanstack/query-core';
 
 import { debugLogger, initDebugLogger } from '@/utils/debug';
 
@@ -223,7 +223,7 @@ export class Clerk implements ClerkInterface {
   // converted to protected environment to support `updateEnvironment` type assertion
   protected environment?: EnvironmentResource | null;
 
-  #queryClient: QueryClient | undefined = new QueryClient();
+  #queryClient: QueryClient | undefined;
   #publishableKey = '';
   #domain: DomainOrProxyUrl['domain'];
   #proxyUrl: DomainOrProxyUrl['proxyUrl'];
@@ -243,6 +243,19 @@ export class Clerk implements ClerkInterface {
   #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', // make this a symbol
@@ -251,16 +264,6 @@ export class Clerk implements ClerkInterface {
       : undefined;
   }
 
-  public async getInternalQueryClient(): Promise<QueryClient> {
-    // const QueryClient = await import('./query-core').then(module => module.QueryClient);
-    if (!this.#queryClient) {
-      // this.#queryClient = new QueryClient();
-      // @ts-expect-error - queryClientStatus is not typed
-      this.#publicEventBus.emit('queryClientStatus', 'ready');
-    }
-    return this.#queryClient;
-  }
-
   public __internal_getCachedResources:
     | (() => Promise<{ client: ClientJSONSnapshot | null; environment: EnvironmentJSONSnapshot | null }>)
     | undefined;

packages/react/src/contexts/ClerkContextProvider.tsx

@@ -88,26 +88,6 @@ export function ClerkContextProvider(props: ClerkContextProvider) {
     return { value };
   }, [orgId, organization]);
 
-  // const [queryStatus, setQueryStatus] = React.useState('loading');
-
-  // React.useEffect(() => {
-  //   // @ts-expect-error - queryClientStatus is not typed
-  //   clerk.on('queryClientStatus', (e)=>{
-  //     console.log('on queryClientStatus', e);
-  //     setQueryStatus(e);
-  //   });
-  //   return () => {
-  //     // @ts-expect-error - queryClientStatus is not typed
-  //     clerk.off('queryClientStatus', setQueryStatus);
-  //   };
-  // }, [clerk]);
-
-  // const queryClient = React.useMemo(() => {
-  //   return clerk.__internal_queryClient;
-  // }, [queryStatus, clerkStatus]);
-
-  // console.log('queryStatus', queryStatus, queryClient);
-
   return (
     // @ts-expect-error value passed is of type IsomorphicClerk where the context expects LoadedClerk
     <IsomorphicClerkContext.Provider value={clerkCtx}>

packages/react/src/isomorphicClerk.ts

@@ -115,66 +115,6 @@ type IsomorphicLoadedClerk = Without<
   apiKeys: APIKeysNamespace | undefined;
 };
 
-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 = 'Mock'): 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 true;
-    },
-    set() {
-      return true;
-    },
-  };
-
-  self = new Proxy(callableTarget, handler) as unknown as RecursiveMock;
-  return self;
-}
-
-/**
- * Returns a permissive mock compatible with `QueryClient` usage in tests.
- * It accepts any chain of property accesses and calls without throwing.
- */
-export function createMockQueryClient(): RecursiveMock {
-  return createRecursiveProxy('MockQueryClient') as unknown as RecursiveMock;
-}
-
 export class IsomorphicClerk implements IsomorphicLoadedClerk {
   private readonly mode: 'browser' | 'server';
   private readonly options: IsomorphicClerkOptions;
@@ -224,7 +164,6 @@ export class IsomorphicClerk implements IsomorphicLoadedClerk {
   #publishableKey: string;
   #eventBus = createClerkEventBus();
   #stateProxy: StateProxy;
-  #__internal_queryClient = createMockQueryClient();
 
   get publishableKey(): string {
     return this.#publishableKey;
@@ -348,14 +287,7 @@ export class IsomorphicClerk implements IsomorphicLoadedClerk {
 
   get __internal_queryClient() {
     // @ts-expect-error - __internal_queryClient is not typed
-    if (!this.clerkjs?.__internal_queryClient) {
-      // @ts-expect-error - __internal_queryClient is not typed
-      void this.clerkjs?.getInternalQueryClient?.();
-      this.prefetchQueryClientStatus = true;
-    }
-
-    // @ts-expect-error - __internal_queryClient is not typed
-    return this.clerkjs?.__internal_queryClient || this.#__internal_queryClient;
+    return this.clerkjs?.__internal_queryClient;
   }
 
   get isSatellite() {
@@ -693,10 +625,10 @@ export class IsomorphicClerk implements IsomorphicLoadedClerk {
       clerkjs.openWaitlist(this.preOpenWaitlist);
     }
 
-    if (this.prefetchQueryClientStatus) {
-      // @ts-expect-error - queryClientStatus is not typed
-      this.clerkjs.getInternalQueryClient?.();
-    }
+    // if (this.prefetchQueryClientStatus) {
+    //   // @ts-expect-error - queryClientStatus is not typed
+    //   this.clerkjs.getInternalQueryClient?.();
+    // }
 
     this.premountSignInNodes.forEach((props, node) => {
       clerkjs.mountSignIn(node, props);

packages/shared/package.json

@@ -146,7 +146,6 @@
   },
   "dependencies": {
     "@clerk/types": "workspace:^",
-    "@tanstack/react-query": "^5.87.4",
     "dequal": "2.0.3",
     "glob-to-regexp": "0.4.1",
     "js-cookie": "3.0.5",
@@ -156,6 +155,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,53 @@
+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>;
+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>;