feat(clerk-js): Lazy query client

Author: panteliselef

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/src/core/clerk.ts

@@ -95,6 +95,7 @@ import type {
   WaitlistResource,
   Web3Provider,
 } from '@clerk/types';
+import type { QueryClient } from '@tanstack/query-core';
 
 import { debugLogger, initDebugLogger } from '@/utils/debug';
 
@@ -222,6 +223,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'];
@@ -240,6 +242,20 @@ export class Clerk implements ClerkInterface {
   #touchThrottledUntil = 0;
   #publicEventBus = createClerkEventBus();
 
+  get __internal_queryClient(): QueryClient | undefined {
+    return this.#queryClient;
+  }
+
+  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/clerk-js/src/core/query-core.ts

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

packages/clerk-js/src/ui/contexts/CoreClerkContextWrapper.tsx

@@ -52,6 +52,8 @@ export function CoreClerkContextWrapper(props: CoreClerkContextWrapperProps): JS
       <ClientContext.Provider value={clientCtx}>
         <SessionContext.Provider value={sessionCtx}>
           <OrganizationProvider
+            // @ts-expect-error - __internal_queryClient is not typed
+            queryClient={clerk.__internal_queryClient}
             {...organizationCtx.value}
             swrConfig={props.swrConfig}
           >

packages/react/src/contexts/ClerkContextProvider.tsx

@@ -88,12 +88,33 @@ 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', setQueryStatus);
+    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}>
       <ClientContext.Provider value={clientCtx}>
         <SessionContext.Provider value={sessionCtx}>
-          <OrganizationProvider {...organizationCtx.value}>
+          <OrganizationProvider
+            key={clerkStatus + queryStatus}
+            {...organizationCtx.value}
+            queryClient={queryClient}
+          >
             <AuthContext.Provider value={authCtx}>
               <UserContext.Provider value={userCtx}>
                 <CheckoutProvider

packages/react/src/isomorphicClerk.ts

@@ -115,6 +115,66 @@ 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;
@@ -146,6 +206,8 @@ 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>();
+  private prefetchQueryClientStatus = false;
+
   // A separate Map of `addListener` method calls to handle multiple listeners.
   private premountAddListenerCalls = new Map<
     ListenerCallback,
@@ -162,6 +224,7 @@ export class IsomorphicClerk implements IsomorphicLoadedClerk {
   #publishableKey: string;
   #eventBus = createClerkEventBus();
   #stateProxy: StateProxy;
+  #__internal_queryClient = createMockQueryClient();
 
   get publishableKey(): string {
     return this.#publishableKey;
@@ -283,6 +346,18 @@ export class IsomorphicClerk implements IsomorphicLoadedClerk {
     return this.clerkjs?.isStandardBrowser || this.options.standardBrowser || false;
   }
 
+  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;
+  }
+
   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 +642,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('status', listener)`
+      // @ts-expect-error - queryClientStatus is not typed
+      this.on('queryClientStatus', listener, { notify: true });
+    });
+
     if (this.preopenSignIn !== null) {
       clerkjs.openSignIn(this.preopenSignIn);
     }
@@ -611,6 +693,11 @@ export class IsomorphicClerk implements IsomorphicLoadedClerk {
       clerkjs.openWaitlist(this.preOpenWaitlist);
     }
 
+    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,6 +146,7 @@
   },
   "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",

packages/shared/src/react/contexts.tsx

@@ -10,6 +10,7 @@ import type {
   SignedInSessionResource,
   UserResource,
 } from '@clerk/types';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
 import type { PropsWithChildren } from 'react';
 import React from 'react';
 
@@ -59,22 +60,27 @@ const OrganizationProvider = ({
   children,
   organization,
   swrConfig,
+  queryClient,
 }: PropsWithChildren<
   OrganizationContextProps & {
     // Exporting inferred types  directly from SWR will result in error while building declarations
     swrConfig?: any;
+    queryClient?: QueryClient;
   }
 >) => {
+  const [defaultClient] = React.useState(() => new QueryClient());
   return (
-    <SWRConfig value={swrConfig}>
-      <OrganizationContextInternal.Provider
-        value={{
-          value: { organization },
-        }}
-      >
-        {children}
-      </OrganizationContextInternal.Provider>
-    </SWRConfig>
+    <QueryClientProvider client={queryClient || defaultClient}>
+      <SWRConfig value={swrConfig}>
+        <OrganizationContextInternal.Provider
+          value={{
+            value: { organization },
+          }}
+        >
+          {children}
+        </OrganizationContextInternal.Provider>
+      </SWRConfig>
+    </QueryClientProvider>
   );
 };
 

packages/shared/src/react/hooks/useSubscription.tsx

@@ -1,5 +1,6 @@
 import type { EnvironmentResource, ForPayerType } from '@clerk/types';
-import { useCallback } from 'react';
+import { useQuery, useQueryClient } from '@tanstack/react-query';
+import { useCallback, useMemo } from 'react';
 
 import { eventMethodCalled } from '../../telemetry/events';
 import { useSWR } from '../clerk-swr';
@@ -29,7 +30,7 @@ type UseSubscriptionParams = {
  *
  * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to [pin](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.
  */
-export const useSubscription = (params?: UseSubscriptionParams) => {
+export const useSubscriptionPrev = (params?: UseSubscriptionParams) => {
   useAssertWrappedByClerkProvider(hookName);
 
   const clerk = useClerkInstanceContext();
@@ -78,3 +79,60 @@ export const useSubscription = (params?: UseSubscriptionParams) => {
     revalidate,
   };
 };
+
+export const useSubscription = (params?: UseSubscriptionParams) => {
+  useAssertWrappedByClerkProvider(hookName);
+
+  const clerk = useClerkInstanceContext();
+  const user = useUserContext();
+  const { organization } = useOrganizationContext();
+
+  // console.log('cache', cache);
+
+  // @ts-expect-error `__unstable__environment` is not typed
+  const environment = clerk.__unstable__environment as unknown as EnvironmentResource | null | undefined;
+
+  clerk.telemetry?.record(eventMethodCalled(hookName));
+
+  const isOrganization = params?.for === 'organization';
+  const billingEnabled = isOrganization
+    ? environment?.commerceSettings.billing.organization.enabled
+    : environment?.commerceSettings.billing.user.enabled;
+
+  const queryClient = useQueryClient();
+
+  const queryKey = useMemo(() => {
+    return [
+      'commerce-subscription',
+      {
+        userId: user?.id,
+        args: { orgId: isOrganization ? organization?.id : undefined },
+      },
+    ];
+  }, [user?.id, isOrganization, organization?.id]);
+
+  const query = useQuery({
+    queryKey,
+    queryFn: ({ queryKey }) => {
+      const obj = queryKey[1] as {
+        args: {
+          orgId?: string;
+        };
+      };
+      return clerk.billing.getSubscription(obj.args);
+    },
+    staleTime: 1_0000 * 60,
+    enabled: Boolean(user?.id && billingEnabled) && clerk.status === 'ready',
+    // placeholderData
+  });
+
+  const revalidate = useCallback(() => queryClient.invalidateQueries({ queryKey }), [queryClient, queryKey]);
+
+  return {
+    data: query.data,
+    error: query.error,
+    isLoading: query.isLoading,
+    isFetching: query.isFetching,
+    revalidate,
+  };
+};