chore(shared): Improve cache key creation

.changeset/lemon-facts-stare.md

@@ -0,0 +1,5 @@
+---
+'@clerk/shared': patch
+---
+
+Update how cache keys are created in SWR/RQ hooks.

packages/clerk-js/bundlewatch.config.json

@@ -6,7 +6,7 @@
  { "path": "./dist/clerk.legacy.browser.js", "maxSize": "123KB" },
  { "path": "./dist/clerk.headless*.js", "maxSize": "63.2KB" },
  { "path": "./dist/ui-common*.js", "maxSize": "117.1KB" },
- { "path": "./dist/ui-common*.legacy.*.js", "maxSize": "120KB" },
+ { "path": "./dist/ui-common*.legacy.*.js", "maxSize": "120.1KB" },
  { "path": "./dist/vendors*.js", "maxSize": "47KB" },
  { "path": "./dist/coinbase*.js", "maxSize": "38KB" },
  { "path": "./dist/stripe-vendors*.js", "maxSize": "1KB" },

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

@@ -7,6 +7,7 @@ import {
  useUserContext,
 } from '../contexts';
 import type { PagesOrInfiniteOptions, PaginatedHookConfig, PaginatedResources } from '../types';
+import { createCacheKeys } from './createCacheKeys';
 import { usePagesOrInfinite, useWithSafeValues } from './usePagesOrInfinite';
 
 /**
@@ -35,6 +36,16 @@ export interface HookParams
  * @default true
  */
  enabled?: boolean;
+ /**
+ * On `cache` mode, no request will be triggered when the hook is mounted and the data will be fetched from the cache.
+ *
+ * @default undefined
+ *
+ * @hidden
+ *
+ * @experimental
+ */
+ __experimental_mode?: 'cache';
  }
  > {
  /**
@@ -110,28 +121,31 @@ export function createBillingPaginatedHook<TResource extends ClerkResource, TPar
 
  const isEnabled = !!hookParams && clerk.loaded && !!billingEnabled && (externalEnabled ?? true);
 
- const result = usePagesOrInfinite<TParams, ClerkPaginatedResponse<TResource>>(
- (hookParams || {}) as TParams,
- fetchFn,
- {
- ...({
- keepPreviousData: safeValues.keepPreviousData,
- infinite: safeValues.infinite,
- } as PaginatedHookConfig<unknown>),
+ const result = usePagesOrInfinite({
+ fetcher: fetchFn,
+ config: {
+ keepPreviousData: safeValues.keepPreviousData,
+ infinite: safeValues.infinite,
  enabled: isEnabled,
  ...(options?.unauthenticated ? {} : { isSignedIn: Boolean(user) }),
  __experimental_mode: safeValues.__experimental_mode,
+ initialPage: safeValues.initialPage,
+ pageSize: safeValues.pageSize,
  },
- {
- type: resourceType,
- ...(options?.unauthenticated
- ? { for: safeFor }
- : {
+ keys: createCacheKeys({
+ stablePrefix: resourceType,
+ authenticated: !options?.unauthenticated,
+ tracked: options?.unauthenticated
+ ? ({ for: safeFor } as const)
+ : ({
  userId: user?.id,
- ...(isForOrganization ? { orgId: organization?.id } : {}),
- }),
- },
- );
+ ...(isForOrganization ? { [__CLERK_USE_RQ__ ? 'orgId' : '_orgId']: organization?.id } : {}),
+ } as const),
+ untracked: {
+ args: hookParams as TParams,
+ },
+ }),
+ });
 
  return result;
  };

packages/shared/src/react/hooks/createCacheKeys.ts

@@ -0,0 +1,21 @@
+/**
+ * @internal
+ */
+export function createCacheKeys<
+ Params,
+ StableKey extends string,
+ T extends Record<string, unknown> = Record<string, unknown>,
+ U extends Record<string, unknown> | undefined = undefined,
+>(params: {
+ stablePrefix: StableKey;
+ authenticated: boolean;
+ tracked: T;
+ untracked: U extends { args: Params } ? U : never;
+}) {
+ return {
+ queryKey: [params.stablePrefix, params.authenticated, params.tracked, params.untracked] as const,
+ invalidationKey: [params.stablePrefix, params.authenticated, params.tracked] as const,
+ stableKey: params.stablePrefix,
+ authenticated: params.authenticated,
+ };
+}

packages/shared/src/react/hooks/useAPIKeys.ts

@@ -1,9 +1,10 @@
 'use client';
 
 import { eventMethodCalled } from '../../telemetry/events/method-called';
-import type { APIKeyResource, ClerkPaginatedResponse, GetAPIKeysParams } from '../../types';
+import type { APIKeyResource, GetAPIKeysParams } from '../../types';
 import { useAssertWrappedByClerkProvider, useClerkInstanceContext } from '../contexts';
 import type { PaginatedHookConfig, PaginatedResources } from '../types';
+import { createCacheKeys } from './createCacheKeys';
 import { usePagesOrInfinite, useWithSafeValues } from './usePagesOrInfinite';
 
 /**
@@ -92,17 +93,25 @@ export function useAPIKeys<T extends UseAPIKeysParams>(params?: T): UseAPIKeysRe
 
  const isEnabled = (safeValues.enabled ?? true) && clerk.loaded;
 
- return usePagesOrInfinite<GetAPIKeysParams, ClerkPaginatedResponse<APIKeyResource>>(
- hookParams,
- clerk.apiKeys?.getAll ? (params: GetAPIKeysParams) => clerk.apiKeys.getAll(params) : undefined,
- {
+ return usePagesOrInfinite({
+ fetcher: clerk.apiKeys?.getAll ? (params: GetAPIKeysParams) => clerk.apiKeys.getAll(params) : undefined,
+ config: {
  keepPreviousData: safeValues.keepPreviousData,
  infinite: safeValues.infinite,
  enabled: isEnabled,
+ isSignedIn: Boolean(clerk.user),
+ initialPage: safeValues.initialPage,
+ pageSize: safeValues.pageSize,
  },
- {
- type: 'apiKeys',
- subject: safeValues.subject || '',
- },
- ) as UseAPIKeysReturn<T>;
+ keys: createCacheKeys({
+ stablePrefix: 'apiKeys',
+ authenticated: Boolean(clerk.user),
+ tracked: {
+ subject: safeValues.subject,
+ },
+ untracked: {
+ args: hookParams,
+ },
+ }),
+ }) as UseAPIKeysReturn<T>;
 }

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

@@ -1,7 +1,6 @@
 import { getCurrentOrganizationMembership } from '../../organization';
 import { eventMethodCalled } from '../../telemetry/events/method-called';
 import type {
- ClerkPaginatedResponse,
  GetDomainsParams,
  GetInvitationsParams,
  GetMembershipRequestParams,
@@ -19,6 +18,7 @@ import {
  useSessionContext,
 } from '../contexts';
 import type { PaginatedHookConfig, PaginatedResources, PaginatedResourcesWithDefault } from '../types';
+import { createCacheKeys } from './createCacheKeys';
 import { usePagesOrInfinite, useWithSafeValues } from './usePagesOrInfinite';
 
 /**
@@ -357,70 +357,93 @@ export function useOrganization<T extends UseOrganizationParams>(params?: T): Us
  status: invitationsSafeValues.status,
  };
 
- const domains = usePagesOrInfinite<GetDomainsParams, ClerkPaginatedResponse<OrganizationDomainResource>>(
- {
- ...domainParams,
- },
- organization?.getDomains,
- {
+ const domains = usePagesOrInfinite({
+ fetcher: organization?.getDomains,
+ config: {
  keepPreviousData: domainSafeValues.keepPreviousData,
  infinite: domainSafeValues.infinite,
  enabled: !!domainParams,
+ isSignedIn: Boolean(organization),
+ initialPage: domainSafeValues.initialPage,
+ pageSize: domainSafeValues.pageSize,
  },
- {
- type: 'domains',
- organizationId: organization?.id,
- },
- );
+ keys: createCacheKeys({
+ stablePrefix: 'domains',
+ authenticated: Boolean(organization),
+ tracked: {
+ organizationId: organization?.id,
+ },
+ untracked: {
+ args: domainParams,
+ },
+ }),
+ });
 
- const membershipRequests = usePagesOrInfinite<
- GetMembershipRequestParams,
- ClerkPaginatedResponse<OrganizationMembershipRequestResource>
- >(
- {
- ...membershipRequestParams,
- },
- organization?.getMembershipRequests,
- {
+ const membershipRequests = usePagesOrInfinite({
+ fetcher: organization?.getMembershipRequests,
+ config: {
  keepPreviousData: membershipRequestSafeValues.keepPreviousData,
  infinite: membershipRequestSafeValues.infinite,
  enabled: !!membershipRequestParams,
+ isSignedIn: Boolean(organization),
+ initialPage: membershipRequestSafeValues.initialPage,
+ pageSize: membershipRequestSafeValues.pageSize,
  },
- {
- type: 'membershipRequests',
- organizationId: organization?.id,
- },
- );
+ keys: createCacheKeys({
+ stablePrefix: 'membershipRequests',
+ authenticated: Boolean(organization),
+ tracked: {
+ organizationId: organization?.id,
+ },
+ untracked: {
+ args: membershipRequestParams,
+ },
+ }),
+ });
 
- const memberships = usePagesOrInfinite<GetMembersParams, ClerkPaginatedResponse<OrganizationMembershipResource>>(
- membersParams || {},
- organization?.getMemberships,
- {
+ const memberships = usePagesOrInfinite({
+ fetcher: organization?.getMemberships,
+ config: {
  keepPreviousData: membersSafeValues.keepPreviousData,
  infinite: membersSafeValues.infinite,
  enabled: !!membersParams,
+ isSignedIn: Boolean(organization),
+ initialPage: membersSafeValues.initialPage,
+ pageSize: membersSafeValues.pageSize,
  },
- {
- type: 'members',
- organizationId: organization?.id,
- },
- );
+ keys: createCacheKeys({
+ stablePrefix: 'members',
+ authenticated: Boolean(organization),
+ tracked: {
+ organizationId: organization?.id,
+ },
+ untracked: {
+ args: membersParams,
+ },
+ }),
+ });
 
- const invitations = usePagesOrInfinite<GetInvitationsParams, ClerkPaginatedResponse<OrganizationInvitationResource>>(
- {
- ...invitationsParams,
- },
- organization?.getInvitations,
- {
+ const invitations = usePagesOrInfinite({
+ fetcher: organization?.getInvitations,
+ config: {
  keepPreviousData: invitationsSafeValues.keepPreviousData,
  infinite: invitationsSafeValues.infinite,
  enabled: !!invitationsParams,
+ isSignedIn: Boolean(organization),
+ initialPage: invitationsSafeValues.initialPage,
+ pageSize: invitationsSafeValues.pageSize,
  },
- {
- type: 'invitations',
- organizationId: organization?.id,
- },
- );
+ keys: createCacheKeys({
+ stablePrefix: 'invitations',
+ authenticated: Boolean(organization),
+ tracked: {
+ organizationId: organization?.id,
+ },
+ untracked: {
+ args: invitationsParams,
+ },
+ }),
+ });
 
  if (organization === undefined) {
  return {

.changeset/lemon-facts-stare.md

@@ -0,0 +1,5 @@
+---
+'@clerk/shared': patch
+---
+
+Update how cache keys are created in SWR/RQ hooks.

packages/clerk-js/bundlewatch.config.json

@@ -6,7 +6,7 @@
  { "path": "./dist/clerk.legacy.browser.js", "maxSize": "123KB" },
  { "path": "./dist/clerk.headless*.js", "maxSize": "63.2KB" },
  { "path": "./dist/ui-common*.js", "maxSize": "117.1KB" },
- { "path": "./dist/ui-common*.legacy.*.js", "maxSize": "120KB" },
+ { "path": "./dist/ui-common*.legacy.*.js", "maxSize": "120.1KB" },
  { "path": "./dist/vendors*.js", "maxSize": "47KB" },
  { "path": "./dist/coinbase*.js", "maxSize": "38KB" },
  { "path": "./dist/stripe-vendors*.js", "maxSize": "1KB" },

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

@@ -7,6 +7,7 @@ import {
  useUserContext,
 } from '../contexts';
 import type { PagesOrInfiniteOptions, PaginatedHookConfig, PaginatedResources } from '../types';
+import { createCacheKeys } from './createCacheKeys';
 import { usePagesOrInfinite, useWithSafeValues } from './usePagesOrInfinite';
 
 /**
@@ -35,6 +36,16 @@ export interface HookParams
  * @default true
  */
  enabled?: boolean;
+ /**
+ * On `cache` mode, no request will be triggered when the hook is mounted and the data will be fetched from the cache.
+ *
+ * @default undefined
+ *
+ * @hidden
+ *
+ * @experimental
+ */
+ __experimental_mode?: 'cache';
  }
  > {
  /**
@@ -110,28 +121,31 @@ export function createBillingPaginatedHook<TResource extends ClerkResource, TPar
 
  const isEnabled = !!hookParams && clerk.loaded && !!billingEnabled && (externalEnabled ?? true);
 
- const result = usePagesOrInfinite<TParams, ClerkPaginatedResponse<TResource>>(
- (hookParams || {}) as TParams,
- fetchFn,
- {
- ...({
- keepPreviousData: safeValues.keepPreviousData,
- infinite: safeValues.infinite,
- } as PaginatedHookConfig<unknown>),
+ const result = usePagesOrInfinite({
+ fetcher: fetchFn,
+ config: {
+ keepPreviousData: safeValues.keepPreviousData,
+ infinite: safeValues.infinite,
  enabled: isEnabled,
  ...(options?.unauthenticated ? {} : { isSignedIn: Boolean(user) }),
  __experimental_mode: safeValues.__experimental_mode,
+ initialPage: safeValues.initialPage,
+ pageSize: safeValues.pageSize,
  },
- {
- type: resourceType,
- ...(options?.unauthenticated
- ? { for: safeFor }
- : {
+ keys: createCacheKeys({
+ stablePrefix: resourceType,
+ authenticated: !options?.unauthenticated,
+ tracked: options?.unauthenticated
+ ? ({ for: safeFor } as const)
+ : ({
  userId: user?.id,
- ...(isForOrganization ? { orgId: organization?.id } : {}),
- }),
- },
- );
+ ...(isForOrganization ? { [__CLERK_USE_RQ__ ? 'orgId' : '_orgId']: organization?.id } : {}),
+ } as const),
+ untracked: {
+ args: hookParams as TParams,
+ },
+ }),
+ });
 
  return result;
  };

packages/shared/src/react/hooks/createCacheKeys.ts

@@ -0,0 +1,21 @@
+/**
+ * @internal
+ */
+export function createCacheKeys<
+ Params,
+ StableKey extends string,
+ T extends Record<string, unknown> = Record<string, unknown>,
+ U extends Record<string, unknown> | undefined = undefined,
+>(params: {
+ stablePrefix: StableKey;
+ authenticated: boolean;
+ tracked: T;
+ untracked: U extends { args: Params } ? U : never;
+}) {
+ return {
+ queryKey: [params.stablePrefix, params.authenticated, params.tracked, params.untracked] as const,
+ invalidationKey: [params.stablePrefix, params.authenticated, params.tracked] as const,
+ stableKey: params.stablePrefix,
+ authenticated: params.authenticated,
+ };
+}

packages/shared/src/react/hooks/useAPIKeys.ts

@@ -1,9 +1,10 @@
 'use client';
 
 import { eventMethodCalled } from '../../telemetry/events/method-called';
-import type { APIKeyResource, ClerkPaginatedResponse, GetAPIKeysParams } from '../../types';
+import type { APIKeyResource, GetAPIKeysParams } from '../../types';
 import { useAssertWrappedByClerkProvider, useClerkInstanceContext } from '../contexts';
 import type { PaginatedHookConfig, PaginatedResources } from '../types';
+import { createCacheKeys } from './createCacheKeys';
 import { usePagesOrInfinite, useWithSafeValues } from './usePagesOrInfinite';
 
 /**
@@ -92,17 +93,25 @@ export function useAPIKeys<T extends UseAPIKeysParams>(params?: T): UseAPIKeysRe
 
  const isEnabled = (safeValues.enabled ?? true) && clerk.loaded;
 
- return usePagesOrInfinite<GetAPIKeysParams, ClerkPaginatedResponse<APIKeyResource>>(
- hookParams,
- clerk.apiKeys?.getAll ? (params: GetAPIKeysParams) => clerk.apiKeys.getAll(params) : undefined,
- {
+ return usePagesOrInfinite({
+ fetcher: clerk.apiKeys?.getAll ? (params: GetAPIKeysParams) => clerk.apiKeys.getAll(params) : undefined,
+ config: {
  keepPreviousData: safeValues.keepPreviousData,
  infinite: safeValues.infinite,
  enabled: isEnabled,
+ isSignedIn: Boolean(clerk.user),
+ initialPage: safeValues.initialPage,
+ pageSize: safeValues.pageSize,
  },
- {
- type: 'apiKeys',
- subject: safeValues.subject || '',
- },
- ) as UseAPIKeysReturn<T>;
+ keys: createCacheKeys({
+ stablePrefix: 'apiKeys',
+ authenticated: Boolean(clerk.user),
+ tracked: {
+ subject: safeValues.subject,
+ },
+ untracked: {
+ args: hookParams,
+ },
+ }),
+ }) as UseAPIKeysReturn<T>;
 }

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

@@ -1,7 +1,6 @@
 import { getCurrentOrganizationMembership } from '../../organization';
 import { eventMethodCalled } from '../../telemetry/events/method-called';
 import type {
- ClerkPaginatedResponse,
  GetDomainsParams,
  GetInvitationsParams,
  GetMembershipRequestParams,
@@ -19,6 +18,7 @@ import {
  useSessionContext,
 } from '../contexts';
 import type { PaginatedHookConfig, PaginatedResources, PaginatedResourcesWithDefault } from '../types';
+import { createCacheKeys } from './createCacheKeys';
 import { usePagesOrInfinite, useWithSafeValues } from './usePagesOrInfinite';
 
 /**
@@ -357,70 +357,93 @@ export function useOrganization<T extends UseOrganizationParams>(params?: T): Us
  status: invitationsSafeValues.status,
  };
 
- const domains = usePagesOrInfinite<GetDomainsParams, ClerkPaginatedResponse<OrganizationDomainResource>>(
- {
- ...domainParams,
- },
- organization?.getDomains,
- {
+ const domains = usePagesOrInfinite({
+ fetcher: organization?.getDomains,
+ config: {
  keepPreviousData: domainSafeValues.keepPreviousData,
  infinite: domainSafeValues.infinite,
  enabled: !!domainParams,
+ isSignedIn: Boolean(organization),
+ initialPage: domainSafeValues.initialPage,
+ pageSize: domainSafeValues.pageSize,
  },
- {
- type: 'domains',
- organizationId: organization?.id,
- },
- );
+ keys: createCacheKeys({
+ stablePrefix: 'domains',
+ authenticated: Boolean(organization),
+ tracked: {
+ organizationId: organization?.id,
+ },
+ untracked: {
+ args: domainParams,
+ },
+ }),
+ });
 
- const membershipRequests = usePagesOrInfinite<
- GetMembershipRequestParams,
- ClerkPaginatedResponse<OrganizationMembershipRequestResource>
- >(
- {
- ...membershipRequestParams,
- },
- organization?.getMembershipRequests,
- {
+ const membershipRequests = usePagesOrInfinite({
+ fetcher: organization?.getMembershipRequests,
+ config: {
  keepPreviousData: membershipRequestSafeValues.keepPreviousData,
  infinite: membershipRequestSafeValues.infinite,
  enabled: !!membershipRequestParams,
+ isSignedIn: Boolean(organization),
+ initialPage: membershipRequestSafeValues.initialPage,
+ pageSize: membershipRequestSafeValues.pageSize,
  },
- {
- type: 'membershipRequests',
- organizationId: organization?.id,
- },
- );
+ keys: createCacheKeys({
+ stablePrefix: 'membershipRequests',
+ authenticated: Boolean(organization),
+ tracked: {
+ organizationId: organization?.id,
+ },
+ untracked: {
+ args: membershipRequestParams,
+ },
+ }),
+ });
 
- const memberships = usePagesOrInfinite<GetMembersParams, ClerkPaginatedResponse<OrganizationMembershipResource>>(
- membersParams || {},
- organization?.getMemberships,
- {
+ const memberships = usePagesOrInfinite({
+ fetcher: organization?.getMemberships,
+ config: {
  keepPreviousData: membersSafeValues.keepPreviousData,
  infinite: membersSafeValues.infinite,
  enabled: !!membersParams,
+ isSignedIn: Boolean(organization),
+ initialPage: membersSafeValues.initialPage,
+ pageSize: membersSafeValues.pageSize,
  },
- {
- type: 'members',
- organizationId: organization?.id,
- },
- );
+ keys: createCacheKeys({
+ stablePrefix: 'members',
+ authenticated: Boolean(organization),
+ tracked: {
+ organizationId: organization?.id,
+ },
+ untracked: {
+ args: membersParams,
+ },
+ }),
+ });
 
- const invitations = usePagesOrInfinite<GetInvitationsParams, ClerkPaginatedResponse<OrganizationInvitationResource>>(
- {
- ...invitationsParams,
- },
- organization?.getInvitations,
- {
+ const invitations = usePagesOrInfinite({
+ fetcher: organization?.getInvitations,
+ config: {
  keepPreviousData: invitationsSafeValues.keepPreviousData,
  infinite: invitationsSafeValues.infinite,
  enabled: !!invitationsParams,
+ isSignedIn: Boolean(organization),
+ initialPage: invitationsSafeValues.initialPage,
+ pageSize: invitationsSafeValues.pageSize,
  },
- {
- type: 'invitations',
- organizationId: organization?.id,
- },
- );
+ keys: createCacheKeys({
+ stablePrefix: 'invitations',
+ authenticated: Boolean(organization),
+ tracked: {
+ organizationId: organization?.id,
+ },
+ untracked: {
+ args: invitationsParams,
+ },
+ }),
+ });
 
  if (organization === undefined) {
  return {

.changeset/lemon-facts-stare.md

@@ -0,0 +1,5 @@
+---
+'@clerk/shared': patch
+---
+
+Update how cache keys are created in SWR/RQ hooks.

packages/clerk-js/bundlewatch.config.json

@@ -6,7 +6,7 @@
  { "path": "./dist/clerk.legacy.browser.js", "maxSize": "123KB" },
  { "path": "./dist/clerk.headless*.js", "maxSize": "63.2KB" },
  { "path": "./dist/ui-common*.js", "maxSize": "117.1KB" },
- { "path": "./dist/ui-common*.legacy.*.js", "maxSize": "120KB" },
+ { "path": "./dist/ui-common*.legacy.*.js", "maxSize": "120.1KB" },
  { "path": "./dist/vendors*.js", "maxSize": "47KB" },
  { "path": "./dist/coinbase*.js", "maxSize": "38KB" },
  { "path": "./dist/stripe-vendors*.js", "maxSize": "1KB" },

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

@@ -7,6 +7,7 @@ import {
  useUserContext,
 } from '../contexts';
 import type { PagesOrInfiniteOptions, PaginatedHookConfig, PaginatedResources } from '../types';
+import { createCacheKeys } from './createCacheKeys';
 import { usePagesOrInfinite, useWithSafeValues } from './usePagesOrInfinite';
 
 /**
@@ -35,6 +36,16 @@ export interface HookParams
  * @default true
  */
  enabled?: boolean;
+ /**
+ * On `cache` mode, no request will be triggered when the hook is mounted and the data will be fetched from the cache.
+ *
+ * @default undefined
+ *
+ * @hidden
+ *
+ * @experimental
+ */
+ __experimental_mode?: 'cache';
  }
  > {
  /**
@@ -110,28 +121,31 @@ export function createBillingPaginatedHook<TResource extends ClerkResource, TPar
 
  const isEnabled = !!hookParams && clerk.loaded && !!billingEnabled && (externalEnabled ?? true);
 
- const result = usePagesOrInfinite<TParams, ClerkPaginatedResponse<TResource>>(
- (hookParams || {}) as TParams,
- fetchFn,
- {
- ...({
- keepPreviousData: safeValues.keepPreviousData,
- infinite: safeValues.infinite,
- } as PaginatedHookConfig<unknown>),
+ const result = usePagesOrInfinite({
+ fetcher: fetchFn,
+ config: {
+ keepPreviousData: safeValues.keepPreviousData,
+ infinite: safeValues.infinite,
  enabled: isEnabled,
  ...(options?.unauthenticated ? {} : { isSignedIn: Boolean(user) }),
  __experimental_mode: safeValues.__experimental_mode,
+ initialPage: safeValues.initialPage,
+ pageSize: safeValues.pageSize,
  },
- {
- type: resourceType,
- ...(options?.unauthenticated
- ? { for: safeFor }
- : {
+ keys: createCacheKeys({
+ stablePrefix: resourceType,
+ authenticated: !options?.unauthenticated,
+ tracked: options?.unauthenticated
+ ? ({ for: safeFor } as const)
+ : ({
  userId: user?.id,
- ...(isForOrganization ? { orgId: organization?.id } : {}),
- }),
- },
- );
+ ...(isForOrganization ? { [__CLERK_USE_RQ__ ? 'orgId' : '_orgId']: organization?.id } : {}),
+ } as const),
+ untracked: {
+ args: hookParams as TParams,
+ },
+ }),
+ });
 
  return result;
  };

packages/shared/src/react/hooks/createCacheKeys.ts

@@ -0,0 +1,21 @@
+/**
+ * @internal
+ */
+export function createCacheKeys<
+ Params,
+ StableKey extends string,
+ T extends Record<string, unknown> = Record<string, unknown>,
+ U extends Record<string, unknown> | undefined = undefined,
+>(params: {
+ stablePrefix: StableKey;
+ authenticated: boolean;
+ tracked: T;
+ untracked: U extends { args: Params } ? U : never;
+}) {
+ return {
+ queryKey: [params.stablePrefix, params.authenticated, params.tracked, params.untracked] as const,
+ invalidationKey: [params.stablePrefix, params.authenticated, params.tracked] as const,
+ stableKey: params.stablePrefix,
+ authenticated: params.authenticated,
+ };
+}

packages/shared/src/react/hooks/useAPIKeys.ts

@@ -1,9 +1,10 @@
 'use client';
 
 import { eventMethodCalled } from '../../telemetry/events/method-called';
-import type { APIKeyResource, ClerkPaginatedResponse, GetAPIKeysParams } from '../../types';
+import type { APIKeyResource, GetAPIKeysParams } from '../../types';
 import { useAssertWrappedByClerkProvider, useClerkInstanceContext } from '../contexts';
 import type { PaginatedHookConfig, PaginatedResources } from '../types';
+import { createCacheKeys } from './createCacheKeys';
 import { usePagesOrInfinite, useWithSafeValues } from './usePagesOrInfinite';
 
 /**
@@ -92,17 +93,25 @@ export function useAPIKeys<T extends UseAPIKeysParams>(params?: T): UseAPIKeysRe
 
  const isEnabled = (safeValues.enabled ?? true) && clerk.loaded;
 
- return usePagesOrInfinite<GetAPIKeysParams, ClerkPaginatedResponse<APIKeyResource>>(
- hookParams,
- clerk.apiKeys?.getAll ? (params: GetAPIKeysParams) => clerk.apiKeys.getAll(params) : undefined,
- {
+ return usePagesOrInfinite({
+ fetcher: clerk.apiKeys?.getAll ? (params: GetAPIKeysParams) => clerk.apiKeys.getAll(params) : undefined,
+ config: {
  keepPreviousData: safeValues.keepPreviousData,
  infinite: safeValues.infinite,
  enabled: isEnabled,
+ isSignedIn: Boolean(clerk.user),
+ initialPage: safeValues.initialPage,
+ pageSize: safeValues.pageSize,
  },
- {
- type: 'apiKeys',
- subject: safeValues.subject || '',
- },
- ) as UseAPIKeysReturn<T>;
+ keys: createCacheKeys({
+ stablePrefix: 'apiKeys',
+ authenticated: Boolean(clerk.user),
+ tracked: {
+ subject: safeValues.subject,
+ },
+ untracked: {
+ args: hookParams,
+ },
+ }),
+ }) as UseAPIKeysReturn<T>;
 }

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

@@ -1,7 +1,6 @@
 import { getCurrentOrganizationMembership } from '../../organization';
 import { eventMethodCalled } from '../../telemetry/events/method-called';
 import type {
- ClerkPaginatedResponse,
  GetDomainsParams,
  GetInvitationsParams,
  GetMembershipRequestParams,
@@ -19,6 +18,7 @@ import {
  useSessionContext,
 } from '../contexts';
 import type { PaginatedHookConfig, PaginatedResources, PaginatedResourcesWithDefault } from '../types';
+import { createCacheKeys } from './createCacheKeys';
 import { usePagesOrInfinite, useWithSafeValues } from './usePagesOrInfinite';
 
 /**
@@ -357,70 +357,93 @@ export function useOrganization<T extends UseOrganizationParams>(params?: T): Us
  status: invitationsSafeValues.status,
  };
 
- const domains = usePagesOrInfinite<GetDomainsParams, ClerkPaginatedResponse<OrganizationDomainResource>>(
- {
- ...domainParams,
- },
- organization?.getDomains,
- {
+ const domains = usePagesOrInfinite({
+ fetcher: organization?.getDomains,
+ config: {
  keepPreviousData: domainSafeValues.keepPreviousData,
  infinite: domainSafeValues.infinite,
  enabled: !!domainParams,
+ isSignedIn: Boolean(organization),
+ initialPage: domainSafeValues.initialPage,
+ pageSize: domainSafeValues.pageSize,
  },
- {
- type: 'domains',
- organizationId: organization?.id,
- },
- );
+ keys: createCacheKeys({
+ stablePrefix: 'domains',
+ authenticated: Boolean(organization),
+ tracked: {
+ organizationId: organization?.id,
+ },
+ untracked: {
+ args: domainParams,
+ },
+ }),
+ });
 
- const membershipRequests = usePagesOrInfinite<
- GetMembershipRequestParams,
- ClerkPaginatedResponse<OrganizationMembershipRequestResource>
- >(
- {
- ...membershipRequestParams,
- },
- organization?.getMembershipRequests,
- {
+ const membershipRequests = usePagesOrInfinite({
+ fetcher: organization?.getMembershipRequests,
+ config: {
  keepPreviousData: membershipRequestSafeValues.keepPreviousData,
  infinite: membershipRequestSafeValues.infinite,
  enabled: !!membershipRequestParams,
+ isSignedIn: Boolean(organization),
+ initialPage: membershipRequestSafeValues.initialPage,
+ pageSize: membershipRequestSafeValues.pageSize,
  },
- {
- type: 'membershipRequests',
- organizationId: organization?.id,
- },
- );
+ keys: createCacheKeys({
+ stablePrefix: 'membershipRequests',
+ authenticated: Boolean(organization),
+ tracked: {
+ organizationId: organization?.id,
+ },
+ untracked: {
+ args: membershipRequestParams,
+ },
+ }),
+ });
 
- const memberships = usePagesOrInfinite<GetMembersParams, ClerkPaginatedResponse<OrganizationMembershipResource>>(
- membersParams || {},
- organization?.getMemberships,
- {
+ const memberships = usePagesOrInfinite({
+ fetcher: organization?.getMemberships,
+ config: {
  keepPreviousData: membersSafeValues.keepPreviousData,
  infinite: membersSafeValues.infinite,
  enabled: !!membersParams,
+ isSignedIn: Boolean(organization),
+ initialPage: membersSafeValues.initialPage,
+ pageSize: membersSafeValues.pageSize,
  },
- {
- type: 'members',
- organizationId: organization?.id,
- },
- );
+ keys: createCacheKeys({
+ stablePrefix: 'members',
+ authenticated: Boolean(organization),
+ tracked: {
+ organizationId: organization?.id,
+ },
+ untracked: {
+ args: membersParams,
+ },
+ }),
+ });
 
- const invitations = usePagesOrInfinite<GetInvitationsParams, ClerkPaginatedResponse<OrganizationInvitationResource>>(
- {
- ...invitationsParams,
- },
- organization?.getInvitations,
- {
+ const invitations = usePagesOrInfinite({
+ fetcher: organization?.getInvitations,
+ config: {
  keepPreviousData: invitationsSafeValues.keepPreviousData,
  infinite: invitationsSafeValues.infinite,
  enabled: !!invitationsParams,
+ isSignedIn: Boolean(organization),
+ initialPage: invitationsSafeValues.initialPage,
+ pageSize: invitationsSafeValues.pageSize,
  },
- {
- type: 'invitations',
- organizationId: organization?.id,
- },
- );
+ keys: createCacheKeys({
+ stablePrefix: 'invitations',
+ authenticated: Boolean(organization),
+ tracked: {
+ organizationId: organization?.id,
+ },
+ untracked: {
+ args: invitationsParams,
+ },
+ }),
+ });
 
  if (organization === undefined) {
  return {

.changeset/lemon-facts-stare.md

@@ -0,0 +1,5 @@
+---
+'@clerk/shared': patch
+---
+
+Update how cache keys are created in SWR/RQ hooks.

packages/clerk-js/bundlewatch.config.json

@@ -6,7 +6,7 @@
  { "path": "./dist/clerk.legacy.browser.js", "maxSize": "123KB" },
  { "path": "./dist/clerk.headless*.js", "maxSize": "63.2KB" },
  { "path": "./dist/ui-common*.js", "maxSize": "117.1KB" },
- { "path": "./dist/ui-common*.legacy.*.js", "maxSize": "120KB" },
+ { "path": "./dist/ui-common*.legacy.*.js", "maxSize": "120.1KB" },
  { "path": "./dist/vendors*.js", "maxSize": "47KB" },
  { "path": "./dist/coinbase*.js", "maxSize": "38KB" },
  { "path": "./dist/stripe-vendors*.js", "maxSize": "1KB" },

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

@@ -7,6 +7,7 @@ import {
  useUserContext,
 } from '../contexts';
 import type { PagesOrInfiniteOptions, PaginatedHookConfig, PaginatedResources } from '../types';
+import { createCacheKeys } from './createCacheKeys';
 import { usePagesOrInfinite, useWithSafeValues } from './usePagesOrInfinite';
 
 /**
@@ -35,6 +36,16 @@ export interface HookParams
  * @default true
  */
  enabled?: boolean;
+ /**
+ * On `cache` mode, no request will be triggered when the hook is mounted and the data will be fetched from the cache.
+ *
+ * @default undefined
+ *
+ * @hidden
+ *
+ * @experimental
+ */
+ __experimental_mode?: 'cache';
  }
  > {
  /**
@@ -110,28 +121,31 @@ export function createBillingPaginatedHook<TResource extends ClerkResource, TPar
 
  const isEnabled = !!hookParams && clerk.loaded && !!billingEnabled && (externalEnabled ?? true);
 
- const result = usePagesOrInfinite<TParams, ClerkPaginatedResponse<TResource>>(
- (hookParams || {}) as TParams,
- fetchFn,
- {
- ...({
- keepPreviousData: safeValues.keepPreviousData,
- infinite: safeValues.infinite,
- } as PaginatedHookConfig<unknown>),
+ const result = usePagesOrInfinite({
+ fetcher: fetchFn,
+ config: {
+ keepPreviousData: safeValues.keepPreviousData,
+ infinite: safeValues.infinite,
  enabled: isEnabled,
  ...(options?.unauthenticated ? {} : { isSignedIn: Boolean(user) }),
  __experimental_mode: safeValues.__experimental_mode,
+ initialPage: safeValues.initialPage,
+ pageSize: safeValues.pageSize,
  },
- {
- type: resourceType,
- ...(options?.unauthenticated
- ? { for: safeFor }
- : {
+ keys: createCacheKeys({
+ stablePrefix: resourceType,
+ authenticated: !options?.unauthenticated,
+ tracked: options?.unauthenticated
+ ? ({ for: safeFor } as const)
+ : ({
  userId: user?.id,
- ...(isForOrganization ? { orgId: organization?.id } : {}),
- }),
- },
- );
+ ...(isForOrganization ? { [__CLERK_USE_RQ__ ? 'orgId' : '_orgId']: organization?.id } : {}),
+ } as const),
+ untracked: {
+ args: hookParams as TParams,
+ },
+ }),
+ });
 
  return result;
  };

packages/shared/src/react/hooks/createCacheKeys.ts

@@ -0,0 +1,21 @@
+/**
+ * @internal
+ */
+export function createCacheKeys<
+ Params,
+ StableKey extends string,
+ T extends Record<string, unknown> = Record<string, unknown>,
+ U extends Record<string, unknown> | undefined = undefined,
+>(params: {
+ stablePrefix: StableKey;
+ authenticated: boolean;
+ tracked: T;
+ untracked: U extends { args: Params } ? U : never;
+}) {
+ return {
+ queryKey: [params.stablePrefix, params.authenticated, params.tracked, params.untracked] as const,
+ invalidationKey: [params.stablePrefix, params.authenticated, params.tracked] as const,
+ stableKey: params.stablePrefix,
+ authenticated: params.authenticated,
+ };
+}

packages/shared/src/react/hooks/useAPIKeys.ts

@@ -1,9 +1,10 @@
 'use client';
 
 import { eventMethodCalled } from '../../telemetry/events/method-called';
-import type { APIKeyResource, ClerkPaginatedResponse, GetAPIKeysParams } from '../../types';
+import type { APIKeyResource, GetAPIKeysParams } from '../../types';
 import { useAssertWrappedByClerkProvider, useClerkInstanceContext } from '../contexts';
 import type { PaginatedHookConfig, PaginatedResources } from '../types';
+import { createCacheKeys } from './createCacheKeys';
 import { usePagesOrInfinite, useWithSafeValues } from './usePagesOrInfinite';
 
 /**
@@ -92,17 +93,25 @@ export function useAPIKeys<T extends UseAPIKeysParams>(params?: T): UseAPIKeysRe
 
  const isEnabled = (safeValues.enabled ?? true) && clerk.loaded;
 
- return usePagesOrInfinite<GetAPIKeysParams, ClerkPaginatedResponse<APIKeyResource>>(
- hookParams,
- clerk.apiKeys?.getAll ? (params: GetAPIKeysParams) => clerk.apiKeys.getAll(params) : undefined,
- {
+ return usePagesOrInfinite({
+ fetcher: clerk.apiKeys?.getAll ? (params: GetAPIKeysParams) => clerk.apiKeys.getAll(params) : undefined,
+ config: {
  keepPreviousData: safeValues.keepPreviousData,
  infinite: safeValues.infinite,
  enabled: isEnabled,
+ isSignedIn: Boolean(clerk.user),
+ initialPage: safeValues.initialPage,
+ pageSize: safeValues.pageSize,
  },
- {
- type: 'apiKeys',
- subject: safeValues.subject || '',
- },
- ) as UseAPIKeysReturn<T>;
+ keys: createCacheKeys({
+ stablePrefix: 'apiKeys',
+ authenticated: Boolean(clerk.user),
+ tracked: {
+ subject: safeValues.subject,
+ },
+ untracked: {
+ args: hookParams,
+ },
+ }),
+ }) as UseAPIKeysReturn<T>;
 }

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

@@ -1,7 +1,6 @@
 import { getCurrentOrganizationMembership } from '../../organization';
 import { eventMethodCalled } from '../../telemetry/events/method-called';
 import type {
- ClerkPaginatedResponse,
  GetDomainsParams,
  GetInvitationsParams,
  GetMembershipRequestParams,
@@ -19,6 +18,7 @@ import {
  useSessionContext,
 } from '../contexts';
 import type { PaginatedHookConfig, PaginatedResources, PaginatedResourcesWithDefault } from '../types';
+import { createCacheKeys } from './createCacheKeys';
 import { usePagesOrInfinite, useWithSafeValues } from './usePagesOrInfinite';
 
 /**
@@ -357,70 +357,93 @@ export function useOrganization<T extends UseOrganizationParams>(params?: T): Us
  status: invitationsSafeValues.status,
  };
 
- const domains = usePagesOrInfinite<GetDomainsParams, ClerkPaginatedResponse<OrganizationDomainResource>>(
- {
- ...domainParams,
- },
- organization?.getDomains,
- {
+ const domains = usePagesOrInfinite({
+ fetcher: organization?.getDomains,
+ config: {
  keepPreviousData: domainSafeValues.keepPreviousData,
  infinite: domainSafeValues.infinite,
  enabled: !!domainParams,
+ isSignedIn: Boolean(organization),
+ initialPage: domainSafeValues.initialPage,
+ pageSize: domainSafeValues.pageSize,
  },
- {
- type: 'domains',
- organizationId: organization?.id,
- },
- );
+ keys: createCacheKeys({
+ stablePrefix: 'domains',
+ authenticated: Boolean(organization),
+ tracked: {
+ organizationId: organization?.id,
+ },
+ untracked: {
+ args: domainParams,
+ },
+ }),
+ });
 
- const membershipRequests = usePagesOrInfinite<
- GetMembershipRequestParams,
- ClerkPaginatedResponse<OrganizationMembershipRequestResource>
- >(
- {
- ...membershipRequestParams,
- },
- organization?.getMembershipRequests,
- {
+ const membershipRequests = usePagesOrInfinite({
+ fetcher: organization?.getMembershipRequests,
+ config: {
  keepPreviousData: membershipRequestSafeValues.keepPreviousData,
  infinite: membershipRequestSafeValues.infinite,
  enabled: !!membershipRequestParams,
+ isSignedIn: Boolean(organization),
+ initialPage: membershipRequestSafeValues.initialPage,
+ pageSize: membershipRequestSafeValues.pageSize,
  },
- {
- type: 'membershipRequests',
- organizationId: organization?.id,
- },
- );
+ keys: createCacheKeys({
+ stablePrefix: 'membershipRequests',
+ authenticated: Boolean(organization),
+ tracked: {
+ organizationId: organization?.id,
+ },
+ untracked: {
+ args: membershipRequestParams,
+ },
+ }),
+ });
 
- const memberships = usePagesOrInfinite<GetMembersParams, ClerkPaginatedResponse<OrganizationMembershipResource>>(
- membersParams || {},
- organization?.getMemberships,
- {
+ const memberships = usePagesOrInfinite({
+ fetcher: organization?.getMemberships,
+ config: {
  keepPreviousData: membersSafeValues.keepPreviousData,
  infinite: membersSafeValues.infinite,
  enabled: !!membersParams,
+ isSignedIn: Boolean(organization),
+ initialPage: membersSafeValues.initialPage,
+ pageSize: membersSafeValues.pageSize,
  },
- {
- type: 'members',
- organizationId: organization?.id,
- },
- );
+ keys: createCacheKeys({
+ stablePrefix: 'members',
+ authenticated: Boolean(organization),
+ tracked: {
+ organizationId: organization?.id,
+ },
+ untracked: {
+ args: membersParams,
+ },
+ }),
+ });
 
- const invitations = usePagesOrInfinite<GetInvitationsParams, ClerkPaginatedResponse<OrganizationInvitationResource>>(
- {
- ...invitationsParams,
- },
- organization?.getInvitations,
- {
+ const invitations = usePagesOrInfinite({
+ fetcher: organization?.getInvitations,
+ config: {
  keepPreviousData: invitationsSafeValues.keepPreviousData,
  infinite: invitationsSafeValues.infinite,
  enabled: !!invitationsParams,
+ isSignedIn: Boolean(organization),
+ initialPage: invitationsSafeValues.initialPage,
+ pageSize: invitationsSafeValues.pageSize,
  },
- {
- type: 'invitations',
- organizationId: organization?.id,
- },
- );
+ keys: createCacheKeys({
+ stablePrefix: 'invitations',
+ authenticated: Boolean(organization),
+ tracked: {
+ organizationId: organization?.id,
+ },
+ untracked: {
+ args: invitationsParams,
+ },
+ }),
+ });
 
  if (organization === undefined) {
  return {

.changeset/lemon-facts-stare.md

@@ -0,0 +1,5 @@
+---
+'@clerk/shared': patch
+---
+
+Update how cache keys are created in SWR/RQ hooks.

packages/clerk-js/bundlewatch.config.json

@@ -6,7 +6,7 @@
  { "path": "./dist/clerk.legacy.browser.js", "maxSize": "123KB" },
  { "path": "./dist/clerk.headless*.js", "maxSize": "63.2KB" },
  { "path": "./dist/ui-common*.js", "maxSize": "117.1KB" },
- { "path": "./dist/ui-common*.legacy.*.js", "maxSize": "120KB" },
+ { "path": "./dist/ui-common*.legacy.*.js", "maxSize": "120.1KB" },
  { "path": "./dist/vendors*.js", "maxSize": "47KB" },
  { "path": "./dist/coinbase*.js", "maxSize": "38KB" },
  { "path": "./dist/stripe-vendors*.js", "maxSize": "1KB" },

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

@@ -7,6 +7,7 @@ import {
  useUserContext,
 } from '../contexts';
 import type { PagesOrInfiniteOptions, PaginatedHookConfig, PaginatedResources } from '../types';
+import { createCacheKeys } from './createCacheKeys';
 import { usePagesOrInfinite, useWithSafeValues } from './usePagesOrInfinite';
 
 /**
@@ -35,6 +36,16 @@ export interface HookParams
  * @default true
  */
  enabled?: boolean;
+ /**
+ * On `cache` mode, no request will be triggered when the hook is mounted and the data will be fetched from the cache.
+ *
+ * @default undefined
+ *
+ * @hidden
+ *
+ * @experimental
+ */
+ __experimental_mode?: 'cache';
  }
  > {
  /**
@@ -110,28 +121,31 @@ export function createBillingPaginatedHook<TResource extends ClerkResource, TPar
 
  const isEnabled = !!hookParams && clerk.loaded && !!billingEnabled && (externalEnabled ?? true);
 
- const result = usePagesOrInfinite<TParams, ClerkPaginatedResponse<TResource>>(
- (hookParams || {}) as TParams,
- fetchFn,
- {
- ...({
- keepPreviousData: safeValues.keepPreviousData,
- infinite: safeValues.infinite,
- } as PaginatedHookConfig<unknown>),
+ const result = usePagesOrInfinite({
+ fetcher: fetchFn,
+ config: {
+ keepPreviousData: safeValues.keepPreviousData,
+ infinite: safeValues.infinite,
  enabled: isEnabled,
  ...(options?.unauthenticated ? {} : { isSignedIn: Boolean(user) }),
  __experimental_mode: safeValues.__experimental_mode,
+ initialPage: safeValues.initialPage,
+ pageSize: safeValues.pageSize,
  },
- {
- type: resourceType,
- ...(options?.unauthenticated
- ? { for: safeFor }
- : {
+ keys: createCacheKeys({
+ stablePrefix: resourceType,
+ authenticated: !options?.unauthenticated,
+ tracked: options?.unauthenticated
+ ? ({ for: safeFor } as const)
+ : ({
  userId: user?.id,
- ...(isForOrganization ? { orgId: organization?.id } : {}),
- }),
- },
- );
+ ...(isForOrganization ? { [__CLERK_USE_RQ__ ? 'orgId' : '_orgId']: organization?.id } : {}),
+ } as const),
+ untracked: {
+ args: hookParams as TParams,
+ },
+ }),
+ });
 
  return result;
  };

packages/shared/src/react/hooks/createCacheKeys.ts

@@ -0,0 +1,21 @@
+/**
+ * @internal
+ */
+export function createCacheKeys<
+ Params,
+ StableKey extends string,
+ T extends Record<string, unknown> = Record<string, unknown>,
+ U extends Record<string, unknown> | undefined = undefined,
+>(params: {
+ stablePrefix: StableKey;
+ authenticated: boolean;
+ tracked: T;
+ untracked: U extends { args: Params } ? U : never;
+}) {
+ return {
+ queryKey: [params.stablePrefix, params.authenticated, params.tracked, params.untracked] as const,
+ invalidationKey: [params.stablePrefix, params.authenticated, params.tracked] as const,
+ stableKey: params.stablePrefix,
+ authenticated: params.authenticated,
+ };
+}

packages/shared/src/react/hooks/useAPIKeys.ts

@@ -1,9 +1,10 @@
 'use client';
 
 import { eventMethodCalled } from '../../telemetry/events/method-called';
-import type { APIKeyResource, ClerkPaginatedResponse, GetAPIKeysParams } from '../../types';
+import type { APIKeyResource, GetAPIKeysParams } from '../../types';
 import { useAssertWrappedByClerkProvider, useClerkInstanceContext } from '../contexts';
 import type { PaginatedHookConfig, PaginatedResources } from '../types';
+import { createCacheKeys } from './createCacheKeys';
 import { usePagesOrInfinite, useWithSafeValues } from './usePagesOrInfinite';
 
 /**
@@ -92,17 +93,25 @@ export function useAPIKeys<T extends UseAPIKeysParams>(params?: T): UseAPIKeysRe
 
  const isEnabled = (safeValues.enabled ?? true) && clerk.loaded;
 
- return usePagesOrInfinite<GetAPIKeysParams, ClerkPaginatedResponse<APIKeyResource>>(
- hookParams,
- clerk.apiKeys?.getAll ? (params: GetAPIKeysParams) => clerk.apiKeys.getAll(params) : undefined,
- {
+ return usePagesOrInfinite({
+ fetcher: clerk.apiKeys?.getAll ? (params: GetAPIKeysParams) => clerk.apiKeys.getAll(params) : undefined,
+ config: {
  keepPreviousData: safeValues.keepPreviousData,
  infinite: safeValues.infinite,
  enabled: isEnabled,
+ isSignedIn: Boolean(clerk.user),
+ initialPage: safeValues.initialPage,
+ pageSize: safeValues.pageSize,
  },
- {
- type: 'apiKeys',
- subject: safeValues.subject || '',
- },
- ) as UseAPIKeysReturn<T>;
+ keys: createCacheKeys({
+ stablePrefix: 'apiKeys',
+ authenticated: Boolean(clerk.user),
+ tracked: {
+ subject: safeValues.subject,
+ },
+ untracked: {
+ args: hookParams,
+ },
+ }),
+ }) as UseAPIKeysReturn<T>;
 }

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

@@ -1,7 +1,6 @@
 import { getCurrentOrganizationMembership } from '../../organization';
 import { eventMethodCalled } from '../../telemetry/events/method-called';
 import type {
- ClerkPaginatedResponse,
  GetDomainsParams,
  GetInvitationsParams,
  GetMembershipRequestParams,
@@ -19,6 +18,7 @@ import {
  useSessionContext,
 } from '../contexts';
 import type { PaginatedHookConfig, PaginatedResources, PaginatedResourcesWithDefault } from '../types';
+import { createCacheKeys } from './createCacheKeys';
 import { usePagesOrInfinite, useWithSafeValues } from './usePagesOrInfinite';
 
 /**
@@ -357,70 +357,93 @@ export function useOrganization<T extends UseOrganizationParams>(params?: T): Us
  status: invitationsSafeValues.status,
  };
 
- const domains = usePagesOrInfinite<GetDomainsParams, ClerkPaginatedResponse<OrganizationDomainResource>>(
- {
- ...domainParams,
- },
- organization?.getDomains,
- {
+ const domains = usePagesOrInfinite({
+ fetcher: organization?.getDomains,
+ config: {
  keepPreviousData: domainSafeValues.keepPreviousData,
  infinite: domainSafeValues.infinite,
  enabled: !!domainParams,
+ isSignedIn: Boolean(organization),
+ initialPage: domainSafeValues.initialPage,
+ pageSize: domainSafeValues.pageSize,
  },
- {
- type: 'domains',
- organizationId: organization?.id,
- },
- );
+ keys: createCacheKeys({
+ stablePrefix: 'domains',
+ authenticated: Boolean(organization),
+ tracked: {
+ organizationId: organization?.id,
+ },
+ untracked: {
+ args: domainParams,
+ },
+ }),
+ });
 
- const membershipRequests = usePagesOrInfinite<
- GetMembershipRequestParams,
- ClerkPaginatedResponse<OrganizationMembershipRequestResource>
- >(
- {
- ...membershipRequestParams,
- },
- organization?.getMembershipRequests,
- {
+ const membershipRequests = usePagesOrInfinite({
+ fetcher: organization?.getMembershipRequests,
+ config: {
  keepPreviousData: membershipRequestSafeValues.keepPreviousData,
  infinite: membershipRequestSafeValues.infinite,
  enabled: !!membershipRequestParams,
+ isSignedIn: Boolean(organization),
+ initialPage: membershipRequestSafeValues.initialPage,
+ pageSize: membershipRequestSafeValues.pageSize,
  },
- {
- type: 'membershipRequests',
- organizationId: organization?.id,
- },
- );
+ keys: createCacheKeys({
+ stablePrefix: 'membershipRequests',
+ authenticated: Boolean(organization),
+ tracked: {
+ organizationId: organization?.id,
+ },
+ untracked: {
+ args: membershipRequestParams,
+ },
+ }),
+ });
 
- const memberships = usePagesOrInfinite<GetMembersParams, ClerkPaginatedResponse<OrganizationMembershipResource>>(
- membersParams || {},
- organization?.getMemberships,
- {
+ const memberships = usePagesOrInfinite({
+ fetcher: organization?.getMemberships,
+ config: {
  keepPreviousData: membersSafeValues.keepPreviousData,
  infinite: membersSafeValues.infinite,
  enabled: !!membersParams,
+ isSignedIn: Boolean(organization),
+ initialPage: membersSafeValues.initialPage,
+ pageSize: membersSafeValues.pageSize,
  },
- {
- type: 'members',
- organizationId: organization?.id,
- },
- );
+ keys: createCacheKeys({
+ stablePrefix: 'members',
+ authenticated: Boolean(organization),
+ tracked: {
+ organizationId: organization?.id,
+ },
+ untracked: {
+ args: membersParams,
+ },
+ }),
+ });
 
- const invitations = usePagesOrInfinite<GetInvitationsParams, ClerkPaginatedResponse<OrganizationInvitationResource>>(
- {
- ...invitationsParams,
- },
- organization?.getInvitations,
- {
+ const invitations = usePagesOrInfinite({
+ fetcher: organization?.getInvitations,
+ config: {
  keepPreviousData: invitationsSafeValues.keepPreviousData,
  infinite: invitationsSafeValues.infinite,
  enabled: !!invitationsParams,
+ isSignedIn: Boolean(organization),
+ initialPage: invitationsSafeValues.initialPage,
+ pageSize: invitationsSafeValues.pageSize,
  },
- {
- type: 'invitations',
- organizationId: organization?.id,
- },
- );
+ keys: createCacheKeys({
+ stablePrefix: 'invitations',
+ authenticated: Boolean(organization),
+ tracked: {
+ organizationId: organization?.id,
+ },
+ untracked: {
+ args: invitationsParams,
+ },
+ }),
+ });
 
  if (organization === undefined) {
  return {

.changeset/lemon-facts-stare.md

@@ -0,0 +1,5 @@
+---
+'@clerk/shared': patch
+---
+
+Update how cache keys are created in SWR/RQ hooks.

packages/clerk-js/bundlewatch.config.json

@@ -6,7 +6,7 @@
  { "path": "./dist/clerk.legacy.browser.js", "maxSize": "123KB" },
  { "path": "./dist/clerk.headless*.js", "maxSize": "63.2KB" },
  { "path": "./dist/ui-common*.js", "maxSize": "117.1KB" },
- { "path": "./dist/ui-common*.legacy.*.js", "maxSize": "120KB" },
+ { "path": "./dist/ui-common*.legacy.*.js", "maxSize": "120.1KB" },
  { "path": "./dist/vendors*.js", "maxSize": "47KB" },
  { "path": "./dist/coinbase*.js", "maxSize": "38KB" },
  { "path": "./dist/stripe-vendors*.js", "maxSize": "1KB" },

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

@@ -7,6 +7,7 @@ import {
  useUserContext,
 } from '../contexts';
 import type { PagesOrInfiniteOptions, PaginatedHookConfig, PaginatedResources } from '../types';
+import { createCacheKeys } from './createCacheKeys';
 import { usePagesOrInfinite, useWithSafeValues } from './usePagesOrInfinite';
 
 /**
@@ -35,6 +36,16 @@ export interface HookParams
  * @default true
  */
  enabled?: boolean;
+ /**
+ * On `cache` mode, no request will be triggered when the hook is mounted and the data will be fetched from the cache.
+ *
+ * @default undefined
+ *
+ * @hidden
+ *
+ * @experimental
+ */
+ __experimental_mode?: 'cache';
  }
  > {
  /**
@@ -110,28 +121,31 @@ export function createBillingPaginatedHook<TResource extends ClerkResource, TPar
 
  const isEnabled = !!hookParams && clerk.loaded && !!billingEnabled && (externalEnabled ?? true);
 
- const result = usePagesOrInfinite<TParams, ClerkPaginatedResponse<TResource>>(
- (hookParams || {}) as TParams,
- fetchFn,
- {
- ...({
- keepPreviousData: safeValues.keepPreviousData,
- infinite: safeValues.infinite,
- } as PaginatedHookConfig<unknown>),
+ const result = usePagesOrInfinite({
+ fetcher: fetchFn,
+ config: {
+ keepPreviousData: safeValues.keepPreviousData,
+ infinite: safeValues.infinite,
  enabled: isEnabled,
  ...(options?.unauthenticated ? {} : { isSignedIn: Boolean(user) }),
  __experimental_mode: safeValues.__experimental_mode,
+ initialPage: safeValues.initialPage,
+ pageSize: safeValues.pageSize,
  },
- {
- type: resourceType,
- ...(options?.unauthenticated
- ? { for: safeFor }
- : {
+ keys: createCacheKeys({
+ stablePrefix: resourceType,
+ authenticated: !options?.unauthenticated,
+ tracked: options?.unauthenticated
+ ? ({ for: safeFor } as const)
+ : ({
  userId: user?.id,
- ...(isForOrganization ? { orgId: organization?.id } : {}),
- }),
- },
- );
+ ...(isForOrganization ? { [__CLERK_USE_RQ__ ? 'orgId' : '_orgId']: organization?.id } : {}),
+ } as const),
+ untracked: {
+ args: hookParams as TParams,
+ },
+ }),
+ });
 
  return result;
  };

packages/shared/src/react/hooks/createCacheKeys.ts

@@ -0,0 +1,21 @@
+/**
+ * @internal
+ */
+export function createCacheKeys<
+ Params,
+ StableKey extends string,
+ T extends Record<string, unknown> = Record<string, unknown>,
+ U extends Record<string, unknown> | undefined = undefined,
+>(params: {
+ stablePrefix: StableKey;
+ authenticated: boolean;
+ tracked: T;
+ untracked: U extends { args: Params } ? U : never;
+}) {
+ return {
+ queryKey: [params.stablePrefix, params.authenticated, params.tracked, params.untracked] as const,
+ invalidationKey: [params.stablePrefix, params.authenticated, params.tracked] as const,
+ stableKey: params.stablePrefix,
+ authenticated: params.authenticated,
+ };
+}

packages/shared/src/react/hooks/useAPIKeys.ts

@@ -1,9 +1,10 @@
 'use client';
 
 import { eventMethodCalled } from '../../telemetry/events/method-called';
-import type { APIKeyResource, ClerkPaginatedResponse, GetAPIKeysParams } from '../../types';
+import type { APIKeyResource, GetAPIKeysParams } from '../../types';
 import { useAssertWrappedByClerkProvider, useClerkInstanceContext } from '../contexts';
 import type { PaginatedHookConfig, PaginatedResources } from '../types';
+import { createCacheKeys } from './createCacheKeys';
 import { usePagesOrInfinite, useWithSafeValues } from './usePagesOrInfinite';
 
 /**
@@ -92,17 +93,25 @@ export function useAPIKeys<T extends UseAPIKeysParams>(params?: T): UseAPIKeysRe
 
  const isEnabled = (safeValues.enabled ?? true) && clerk.loaded;
 
- return usePagesOrInfinite<GetAPIKeysParams, ClerkPaginatedResponse<APIKeyResource>>(
- hookParams,
- clerk.apiKeys?.getAll ? (params: GetAPIKeysParams) => clerk.apiKeys.getAll(params) : undefined,
- {
+ return usePagesOrInfinite({
+ fetcher: clerk.apiKeys?.getAll ? (params: GetAPIKeysParams) => clerk.apiKeys.getAll(params) : undefined,
+ config: {
  keepPreviousData: safeValues.keepPreviousData,
  infinite: safeValues.infinite,
  enabled: isEnabled,
+ isSignedIn: Boolean(clerk.user),
+ initialPage: safeValues.initialPage,
+ pageSize: safeValues.pageSize,
  },
- {
- type: 'apiKeys',
- subject: safeValues.subject || '',
- },
- ) as UseAPIKeysReturn<T>;
+ keys: createCacheKeys({
+ stablePrefix: 'apiKeys',
+ authenticated: Boolean(clerk.user),
+ tracked: {
+ subject: safeValues.subject,
+ },
+ untracked: {
+ args: hookParams,
+ },
+ }),
+ }) as UseAPIKeysReturn<T>;
 }

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

@@ -1,7 +1,6 @@
 import { getCurrentOrganizationMembership } from '../../organization';
 import { eventMethodCalled } from '../../telemetry/events/method-called';
 import type {
- ClerkPaginatedResponse,
  GetDomainsParams,
  GetInvitationsParams,
  GetMembershipRequestParams,
@@ -19,6 +18,7 @@ import {
  useSessionContext,
 } from '../contexts';
 import type { PaginatedHookConfig, PaginatedResources, PaginatedResourcesWithDefault } from '../types';
+import { createCacheKeys } from './createCacheKeys';
 import { usePagesOrInfinite, useWithSafeValues } from './usePagesOrInfinite';
 
 /**
@@ -357,70 +357,93 @@ export function useOrganization<T extends UseOrganizationParams>(params?: T): Us
  status: invitationsSafeValues.status,
  };
 
- const domains = usePagesOrInfinite<GetDomainsParams, ClerkPaginatedResponse<OrganizationDomainResource>>(
- {
- ...domainParams,
- },
- organization?.getDomains,
- {
+ const domains = usePagesOrInfinite({
+ fetcher: organization?.getDomains,
+ config: {
  keepPreviousData: domainSafeValues.keepPreviousData,
  infinite: domainSafeValues.infinite,
  enabled: !!domainParams,
+ isSignedIn: Boolean(organization),
+ initialPage: domainSafeValues.initialPage,
+ pageSize: domainSafeValues.pageSize,
  },
- {
- type: 'domains',
- organizationId: organization?.id,
- },
- );
+ keys: createCacheKeys({
+ stablePrefix: 'domains',
+ authenticated: Boolean(organization),
+ tracked: {
+ organizationId: organization?.id,
+ },
+ untracked: {
+ args: domainParams,
+ },
+ }),
+ });
 
- const membershipRequests = usePagesOrInfinite<
- GetMembershipRequestParams,
- ClerkPaginatedResponse<OrganizationMembershipRequestResource>
- >(
- {
- ...membershipRequestParams,
- },
- organization?.getMembershipRequests,
- {
+ const membershipRequests = usePagesOrInfinite({
+ fetcher: organization?.getMembershipRequests,
+ config: {
  keepPreviousData: membershipRequestSafeValues.keepPreviousData,
  infinite: membershipRequestSafeValues.infinite,
  enabled: !!membershipRequestParams,
+ isSignedIn: Boolean(organization),
+ initialPage: membershipRequestSafeValues.initialPage,
+ pageSize: membershipRequestSafeValues.pageSize,
  },
- {
- type: 'membershipRequests',
- organizationId: organization?.id,
- },
- );
+ keys: createCacheKeys({
+ stablePrefix: 'membershipRequests',
+ authenticated: Boolean(organization),
+ tracked: {
+ organizationId: organization?.id,
+ },
+ untracked: {
+ args: membershipRequestParams,
+ },
+ }),
+ });
 
- const memberships = usePagesOrInfinite<GetMembersParams, ClerkPaginatedResponse<OrganizationMembershipResource>>(
- membersParams || {},
- organization?.getMemberships,
- {
+ const memberships = usePagesOrInfinite({
+ fetcher: organization?.getMemberships,
+ config: {
  keepPreviousData: membersSafeValues.keepPreviousData,
  infinite: membersSafeValues.infinite,
  enabled: !!membersParams,
+ isSignedIn: Boolean(organization),
+ initialPage: membersSafeValues.initialPage,
+ pageSize: membersSafeValues.pageSize,
  },
- {
- type: 'members',
- organizationId: organization?.id,
- },
- );
+ keys: createCacheKeys({
+ stablePrefix: 'members',
+ authenticated: Boolean(organization),
+ tracked: {
+ organizationId: organization?.id,
+ },
+ untracked: {
+ args: membersParams,
+ },
+ }),
+ });
 
- const invitations = usePagesOrInfinite<GetInvitationsParams, ClerkPaginatedResponse<OrganizationInvitationResource>>(
- {
- ...invitationsParams,
- },
- organization?.getInvitations,
- {
+ const invitations = usePagesOrInfinite({
+ fetcher: organization?.getInvitations,
+ config: {
  keepPreviousData: invitationsSafeValues.keepPreviousData,
  infinite: invitationsSafeValues.infinite,
  enabled: !!invitationsParams,
+ isSignedIn: Boolean(organization),
+ initialPage: invitationsSafeValues.initialPage,
+ pageSize: invitationsSafeValues.pageSize,
  },
- {
- type: 'invitations',
- organizationId: organization?.id,
- },
- );
+ keys: createCacheKeys({
+ stablePrefix: 'invitations',
+ authenticated: Boolean(organization),
+ tracked: {
+ organizationId: organization?.id,
+ },
+ untracked: {
+ args: invitationsParams,
+ },
+ }),
+ });
 
  if (organization === undefined) {
  return {

.changeset/lemon-facts-stare.md

@@ -0,0 +1,5 @@
+---
+'@clerk/shared': patch
+---
+
+Update how cache keys are created in SWR/RQ hooks.

packages/clerk-js/bundlewatch.config.json

@@ -6,7 +6,7 @@
  { "path": "./dist/clerk.legacy.browser.js", "maxSize": "123KB" },
  { "path": "./dist/clerk.headless*.js", "maxSize": "63.2KB" },
  { "path": "./dist/ui-common*.js", "maxSize": "117.1KB" },
- { "path": "./dist/ui-common*.legacy.*.js", "maxSize": "120KB" },
+ { "path": "./dist/ui-common*.legacy.*.js", "maxSize": "120.1KB" },
  { "path": "./dist/vendors*.js", "maxSize": "47KB" },
  { "path": "./dist/coinbase*.js", "maxSize": "38KB" },
  { "path": "./dist/stripe-vendors*.js", "maxSize": "1KB" },

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

@@ -7,6 +7,7 @@ import {
  useUserContext,
 } from '../contexts';
 import type { PagesOrInfiniteOptions, PaginatedHookConfig, PaginatedResources } from '../types';
+import { createCacheKeys } from './createCacheKeys';
 import { usePagesOrInfinite, useWithSafeValues } from './usePagesOrInfinite';
 
 /**
@@ -35,6 +36,16 @@ export interface HookParams
  * @default true
  */
  enabled?: boolean;
+ /**
+ * On `cache` mode, no request will be triggered when the hook is mounted and the data will be fetched from the cache.
+ *
+ * @default undefined
+ *
+ * @hidden
+ *
+ * @experimental
+ */
+ __experimental_mode?: 'cache';
  }
  > {
  /**
@@ -110,28 +121,31 @@ export function createBillingPaginatedHook<TResource extends ClerkResource, TPar
 
  const isEnabled = !!hookParams && clerk.loaded && !!billingEnabled && (externalEnabled ?? true);
 
- const result = usePagesOrInfinite<TParams, ClerkPaginatedResponse<TResource>>(
- (hookParams || {}) as TParams,
- fetchFn,
- {
- ...({
- keepPreviousData: safeValues.keepPreviousData,
- infinite: safeValues.infinite,
- } as PaginatedHookConfig<unknown>),
+ const result = usePagesOrInfinite({
+ fetcher: fetchFn,
+ config: {
+ keepPreviousData: safeValues.keepPreviousData,
+ infinite: safeValues.infinite,
  enabled: isEnabled,
  ...(options?.unauthenticated ? {} : { isSignedIn: Boolean(user) }),
  __experimental_mode: safeValues.__experimental_mode,
+ initialPage: safeValues.initialPage,
+ pageSize: safeValues.pageSize,
  },
- {
- type: resourceType,
- ...(options?.unauthenticated
- ? { for: safeFor }
- : {
+ keys: createCacheKeys({
+ stablePrefix: resourceType,
+ authenticated: !options?.unauthenticated,
+ tracked: options?.unauthenticated
+ ? ({ for: safeFor } as const)
+ : ({
  userId: user?.id,
- ...(isForOrganization ? { orgId: organization?.id } : {}),
- }),
- },
- );
+ ...(isForOrganization ? { [__CLERK_USE_RQ__ ? 'orgId' : '_orgId']: organization?.id } : {}),
+ } as const),
+ untracked: {
+ args: hookParams as TParams,
+ },
+ }),
+ });
 
  return result;
  };

packages/shared/src/react/hooks/createCacheKeys.ts

@@ -0,0 +1,21 @@
+/**
+ * @internal
+ */
+export function createCacheKeys<
+ Params,
+ StableKey extends string,
+ T extends Record<string, unknown> = Record<string, unknown>,
+ U extends Record<string, unknown> | undefined = undefined,
+>(params: {
+ stablePrefix: StableKey;
+ authenticated: boolean;
+ tracked: T;
+ untracked: U extends { args: Params } ? U : never;
+}) {
+ return {
+ queryKey: [params.stablePrefix, params.authenticated, params.tracked, params.untracked] as const,
+ invalidationKey: [params.stablePrefix, params.authenticated, params.tracked] as const,
+ stableKey: params.stablePrefix,
+ authenticated: params.authenticated,
+ };
+}

packages/shared/src/react/hooks/useAPIKeys.ts

@@ -1,9 +1,10 @@
 'use client';
 
 import { eventMethodCalled } from '../../telemetry/events/method-called';
-import type { APIKeyResource, ClerkPaginatedResponse, GetAPIKeysParams } from '../../types';
+import type { APIKeyResource, GetAPIKeysParams } from '../../types';
 import { useAssertWrappedByClerkProvider, useClerkInstanceContext } from '../contexts';
 import type { PaginatedHookConfig, PaginatedResources } from '../types';
+import { createCacheKeys } from './createCacheKeys';
 import { usePagesOrInfinite, useWithSafeValues } from './usePagesOrInfinite';
 
 /**
@@ -92,17 +93,25 @@ export function useAPIKeys<T extends UseAPIKeysParams>(params?: T): UseAPIKeysRe
 
  const isEnabled = (safeValues.enabled ?? true) && clerk.loaded;
 
- return usePagesOrInfinite<GetAPIKeysParams, ClerkPaginatedResponse<APIKeyResource>>(
- hookParams,
- clerk.apiKeys?.getAll ? (params: GetAPIKeysParams) => clerk.apiKeys.getAll(params) : undefined,
- {
+ return usePagesOrInfinite({
+ fetcher: clerk.apiKeys?.getAll ? (params: GetAPIKeysParams) => clerk.apiKeys.getAll(params) : undefined,
+ config: {
  keepPreviousData: safeValues.keepPreviousData,
  infinite: safeValues.infinite,
  enabled: isEnabled,
+ isSignedIn: Boolean(clerk.user),
+ initialPage: safeValues.initialPage,
+ pageSize: safeValues.pageSize,
  },
- {
- type: 'apiKeys',
- subject: safeValues.subject || '',
- },
- ) as UseAPIKeysReturn<T>;
+ keys: createCacheKeys({
+ stablePrefix: 'apiKeys',
+ authenticated: Boolean(clerk.user),
+ tracked: {
+ subject: safeValues.subject,
+ },
+ untracked: {
+ args: hookParams,
+ },
+ }),
+ }) as UseAPIKeysReturn<T>;
 }

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

@@ -1,7 +1,6 @@
 import { getCurrentOrganizationMembership } from '../../organization';
 import { eventMethodCalled } from '../../telemetry/events/method-called';
 import type {
- ClerkPaginatedResponse,
  GetDomainsParams,
  GetInvitationsParams,
  GetMembershipRequestParams,
@@ -19,6 +18,7 @@ import {
  useSessionContext,
 } from '../contexts';
 import type { PaginatedHookConfig, PaginatedResources, PaginatedResourcesWithDefault } from '../types';
+import { createCacheKeys } from './createCacheKeys';
 import { usePagesOrInfinite, useWithSafeValues } from './usePagesOrInfinite';
 
 /**
@@ -357,70 +357,93 @@ export function useOrganization<T extends UseOrganizationParams>(params?: T): Us
  status: invitationsSafeValues.status,
  };
 
- const domains = usePagesOrInfinite<GetDomainsParams, ClerkPaginatedResponse<OrganizationDomainResource>>(
- {
- ...domainParams,
- },
- organization?.getDomains,
- {
+ const domains = usePagesOrInfinite({
+ fetcher: organization?.getDomains,
+ config: {
  keepPreviousData: domainSafeValues.keepPreviousData,
  infinite: domainSafeValues.infinite,
  enabled: !!domainParams,
+ isSignedIn: Boolean(organization),
+ initialPage: domainSafeValues.initialPage,
+ pageSize: domainSafeValues.pageSize,
  },
- {
- type: 'domains',
- organizationId: organization?.id,
- },
- );
+ keys: createCacheKeys({
+ stablePrefix: 'domains',
+ authenticated: Boolean(organization),
+ tracked: {
+ organizationId: organization?.id,
+ },
+ untracked: {
+ args: domainParams,
+ },
+ }),
+ });
 
- const membershipRequests = usePagesOrInfinite<
- GetMembershipRequestParams,
- ClerkPaginatedResponse<OrganizationMembershipRequestResource>
- >(
- {
- ...membershipRequestParams,
- },
- organization?.getMembershipRequests,
- {
+ const membershipRequests = usePagesOrInfinite({
+ fetcher: organization?.getMembershipRequests,
+ config: {
  keepPreviousData: membershipRequestSafeValues.keepPreviousData,
  infinite: membershipRequestSafeValues.infinite,
  enabled: !!membershipRequestParams,
+ isSignedIn: Boolean(organization),
+ initialPage: membershipRequestSafeValues.initialPage,
+ pageSize: membershipRequestSafeValues.pageSize,
  },
- {
- type: 'membershipRequests',
- organizationId: organization?.id,
- },
- );
+ keys: createCacheKeys({
+ stablePrefix: 'membershipRequests',
+ authenticated: Boolean(organization),
+ tracked: {
+ organizationId: organization?.id,
+ },
+ untracked: {
+ args: membershipRequestParams,
+ },
+ }),
+ });
 
- const memberships = usePagesOrInfinite<GetMembersParams, ClerkPaginatedResponse<OrganizationMembershipResource>>(
- membersParams || {},
- organization?.getMemberships,
- {
+ const memberships = usePagesOrInfinite({
+ fetcher: organization?.getMemberships,
+ config: {
  keepPreviousData: membersSafeValues.keepPreviousData,
  infinite: membersSafeValues.infinite,
  enabled: !!membersParams,
+ isSignedIn: Boolean(organization),
+ initialPage: membersSafeValues.initialPage,
+ pageSize: membersSafeValues.pageSize,
  },
- {
- type: 'members',
- organizationId: organization?.id,
- },
- );
+ keys: createCacheKeys({
+ stablePrefix: 'members',
+ authenticated: Boolean(organization),
+ tracked: {
+ organizationId: organization?.id,
+ },
+ untracked: {
+ args: membersParams,
+ },
+ }),
+ });
 
- const invitations = usePagesOrInfinite<GetInvitationsParams, ClerkPaginatedResponse<OrganizationInvitationResource>>(
- {
- ...invitationsParams,
- },
- organization?.getInvitations,
- {
+ const invitations = usePagesOrInfinite({
+ fetcher: organization?.getInvitations,
+ config: {
  keepPreviousData: invitationsSafeValues.keepPreviousData,
  infinite: invitationsSafeValues.infinite,
  enabled: !!invitationsParams,
+ isSignedIn: Boolean(organization),
+ initialPage: invitationsSafeValues.initialPage,
+ pageSize: invitationsSafeValues.pageSize,
  },
- {
- type: 'invitations',
- organizationId: organization?.id,
- },
- );
+ keys: createCacheKeys({
+ stablePrefix: 'invitations',
+ authenticated: Boolean(organization),
+ tracked: {
+ organizationId: organization?.id,
+ },
+ untracked: {
+ args: invitationsParams,
+ },
+ }),
+ });
 
  if (organization === undefined) {
  return {

.changeset/lemon-facts-stare.md

@@ -0,0 +1,5 @@
+---
+'@clerk/shared': patch
+---
+
+Update how cache keys are created in SWR/RQ hooks.

packages/clerk-js/bundlewatch.config.json

@@ -6,7 +6,7 @@
  { "path": "./dist/clerk.legacy.browser.js", "maxSize": "123KB" },
  { "path": "./dist/clerk.headless*.js", "maxSize": "63.2KB" },
  { "path": "./dist/ui-common*.js", "maxSize": "117.1KB" },
- { "path": "./dist/ui-common*.legacy.*.js", "maxSize": "120KB" },
+ { "path": "./dist/ui-common*.legacy.*.js", "maxSize": "120.1KB" },
  { "path": "./dist/vendors*.js", "maxSize": "47KB" },
  { "path": "./dist/coinbase*.js", "maxSize": "38KB" },
  { "path": "./dist/stripe-vendors*.js", "maxSize": "1KB" },

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

@@ -7,6 +7,7 @@ import {
  useUserContext,
 } from '../contexts';
 import type { PagesOrInfiniteOptions, PaginatedHookConfig, PaginatedResources } from '../types';
+import { createCacheKeys } from './createCacheKeys';
 import { usePagesOrInfinite, useWithSafeValues } from './usePagesOrInfinite';
 
 /**
@@ -35,6 +36,16 @@ export interface HookParams
  * @default true
  */
  enabled?: boolean;
+ /**
+ * On `cache` mode, no request will be triggered when the hook is mounted and the data will be fetched from the cache.
+ *
+ * @default undefined
+ *
+ * @hidden
+ *
+ * @experimental
+ */
+ __experimental_mode?: 'cache';
  }
  > {
  /**
@@ -110,28 +121,31 @@ export function createBillingPaginatedHook<TResource extends ClerkResource, TPar
 
  const isEnabled = !!hookParams && clerk.loaded && !!billingEnabled && (externalEnabled ?? true);
 
- const result = usePagesOrInfinite<TParams, ClerkPaginatedResponse<TResource>>(
- (hookParams || {}) as TParams,
- fetchFn,
- {
- ...({
- keepPreviousData: safeValues.keepPreviousData,
- infinite: safeValues.infinite,
- } as PaginatedHookConfig<unknown>),
+ const result = usePagesOrInfinite({
+ fetcher: fetchFn,
+ config: {
+ keepPreviousData: safeValues.keepPreviousData,
+ infinite: safeValues.infinite,
  enabled: isEnabled,
  ...(options?.unauthenticated ? {} : { isSignedIn: Boolean(user) }),
  __experimental_mode: safeValues.__experimental_mode,
+ initialPage: safeValues.initialPage,
+ pageSize: safeValues.pageSize,
  },
- {
- type: resourceType,
- ...(options?.unauthenticated
- ? { for: safeFor }
- : {
+ keys: createCacheKeys({
+ stablePrefix: resourceType,
+ authenticated: !options?.unauthenticated,
+ tracked: options?.unauthenticated
+ ? ({ for: safeFor } as const)
+ : ({
  userId: user?.id,
- ...(isForOrganization ? { orgId: organization?.id } : {}),
- }),
- },
- );
+ ...(isForOrganization ? { [__CLERK_USE_RQ__ ? 'orgId' : '_orgId']: organization?.id } : {}),
+ } as const),
+ untracked: {
+ args: hookParams as TParams,
+ },
+ }),
+ });
 
  return result;
  };

packages/shared/src/react/hooks/createCacheKeys.ts

@@ -0,0 +1,21 @@
+/**
+ * @internal
+ */
+export function createCacheKeys<
+ Params,
+ StableKey extends string,
+ T extends Record<string, unknown> = Record<string, unknown>,
+ U extends Record<string, unknown> | undefined = undefined,
+>(params: {
+ stablePrefix: StableKey;
+ authenticated: boolean;
+ tracked: T;
+ untracked: U extends { args: Params } ? U : never;
+}) {
+ return {
+ queryKey: [params.stablePrefix, params.authenticated, params.tracked, params.untracked] as const,
+ invalidationKey: [params.stablePrefix, params.authenticated, params.tracked] as const,
+ stableKey: params.stablePrefix,
+ authenticated: params.authenticated,
+ };
+}

packages/shared/src/react/hooks/useAPIKeys.ts

@@ -1,9 +1,10 @@
 'use client';
 
 import { eventMethodCalled } from '../../telemetry/events/method-called';
-import type { APIKeyResource, ClerkPaginatedResponse, GetAPIKeysParams } from '../../types';
+import type { APIKeyResource, GetAPIKeysParams } from '../../types';
 import { useAssertWrappedByClerkProvider, useClerkInstanceContext } from '../contexts';
 import type { PaginatedHookConfig, PaginatedResources } from '../types';
+import { createCacheKeys } from './createCacheKeys';
 import { usePagesOrInfinite, useWithSafeValues } from './usePagesOrInfinite';
 
 /**
@@ -92,17 +93,25 @@ export function useAPIKeys<T extends UseAPIKeysParams>(params?: T): UseAPIKeysRe
 
  const isEnabled = (safeValues.enabled ?? true) && clerk.loaded;
 
- return usePagesOrInfinite<GetAPIKeysParams, ClerkPaginatedResponse<APIKeyResource>>(
- hookParams,
- clerk.apiKeys?.getAll ? (params: GetAPIKeysParams) => clerk.apiKeys.getAll(params) : undefined,
- {
+ return usePagesOrInfinite({
+ fetcher: clerk.apiKeys?.getAll ? (params: GetAPIKeysParams) => clerk.apiKeys.getAll(params) : undefined,
+ config: {
  keepPreviousData: safeValues.keepPreviousData,
  infinite: safeValues.infinite,
  enabled: isEnabled,
+ isSignedIn: Boolean(clerk.user),
+ initialPage: safeValues.initialPage,
+ pageSize: safeValues.pageSize,
  },
- {
- type: 'apiKeys',
- subject: safeValues.subject || '',
- },
- ) as UseAPIKeysReturn<T>;
+ keys: createCacheKeys({
+ stablePrefix: 'apiKeys',
+ authenticated: Boolean(clerk.user),
+ tracked: {
+ subject: safeValues.subject,
+ },
+ untracked: {
+ args: hookParams,
+ },
+ }),
+ }) as UseAPIKeysReturn<T>;
 }

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

@@ -1,7 +1,6 @@
 import { getCurrentOrganizationMembership } from '../../organization';
 import { eventMethodCalled } from '../../telemetry/events/method-called';
 import type {
- ClerkPaginatedResponse,
  GetDomainsParams,
  GetInvitationsParams,
  GetMembershipRequestParams,
@@ -19,6 +18,7 @@ import {
  useSessionContext,
 } from '../contexts';
 import type { PaginatedHookConfig, PaginatedResources, PaginatedResourcesWithDefault } from '../types';
+import { createCacheKeys } from './createCacheKeys';
 import { usePagesOrInfinite, useWithSafeValues } from './usePagesOrInfinite';
 
 /**
@@ -357,70 +357,93 @@ export function useOrganization<T extends UseOrganizationParams>(params?: T): Us
  status: invitationsSafeValues.status,
  };
 
- const domains = usePagesOrInfinite<GetDomainsParams, ClerkPaginatedResponse<OrganizationDomainResource>>(
- {
- ...domainParams,
- },
- organization?.getDomains,
- {
+ const domains = usePagesOrInfinite({
+ fetcher: organization?.getDomains,
+ config: {
  keepPreviousData: domainSafeValues.keepPreviousData,
  infinite: domainSafeValues.infinite,
  enabled: !!domainParams,
+ isSignedIn: Boolean(organization),
+ initialPage: domainSafeValues.initialPage,
+ pageSize: domainSafeValues.pageSize,
  },
- {
- type: 'domains',
- organizationId: organization?.id,
- },
- );
+ keys: createCacheKeys({
+ stablePrefix: 'domains',
+ authenticated: Boolean(organization),
+ tracked: {
+ organizationId: organization?.id,
+ },
+ untracked: {
+ args: domainParams,
+ },
+ }),
+ });
 
- const membershipRequests = usePagesOrInfinite<
- GetMembershipRequestParams,
- ClerkPaginatedResponse<OrganizationMembershipRequestResource>
- >(
- {
- ...membershipRequestParams,
- },
- organization?.getMembershipRequests,
- {
+ const membershipRequests = usePagesOrInfinite({
+ fetcher: organization?.getMembershipRequests,
+ config: {
  keepPreviousData: membershipRequestSafeValues.keepPreviousData,
  infinite: membershipRequestSafeValues.infinite,
  enabled: !!membershipRequestParams,
+ isSignedIn: Boolean(organization),
+ initialPage: membershipRequestSafeValues.initialPage,
+ pageSize: membershipRequestSafeValues.pageSize,
  },
- {
- type: 'membershipRequests',
- organizationId: organization?.id,
- },
- );
+ keys: createCacheKeys({
+ stablePrefix: 'membershipRequests',
+ authenticated: Boolean(organization),
+ tracked: {
+ organizationId: organization?.id,
+ },
+ untracked: {
+ args: membershipRequestParams,
+ },
+ }),
+ });
 
- const memberships = usePagesOrInfinite<GetMembersParams, ClerkPaginatedResponse<OrganizationMembershipResource>>(
- membersParams || {},
- organization?.getMemberships,
- {
+ const memberships = usePagesOrInfinite({
+ fetcher: organization?.getMemberships,
+ config: {
  keepPreviousData: membersSafeValues.keepPreviousData,
  infinite: membersSafeValues.infinite,
  enabled: !!membersParams,
+ isSignedIn: Boolean(organization),
+ initialPage: membersSafeValues.initialPage,
+ pageSize: membersSafeValues.pageSize,
  },
- {
- type: 'members',
- organizationId: organization?.id,
- },
- );
+ keys: createCacheKeys({
+ stablePrefix: 'members',
+ authenticated: Boolean(organization),
+ tracked: {
+ organizationId: organization?.id,
+ },
+ untracked: {
+ args: membersParams,
+ },
+ }),
+ });
 
- const invitations = usePagesOrInfinite<GetInvitationsParams, ClerkPaginatedResponse<OrganizationInvitationResource>>(
- {
- ...invitationsParams,
- },
- organization?.getInvitations,
- {
+ const invitations = usePagesOrInfinite({
+ fetcher: organization?.getInvitations,
+ config: {
  keepPreviousData: invitationsSafeValues.keepPreviousData,
  infinite: invitationsSafeValues.infinite,
  enabled: !!invitationsParams,
+ isSignedIn: Boolean(organization),
+ initialPage: invitationsSafeValues.initialPage,
+ pageSize: invitationsSafeValues.pageSize,
  },
- {
- type: 'invitations',
- organizationId: organization?.id,
- },
- );
+ keys: createCacheKeys({
+ stablePrefix: 'invitations',
+ authenticated: Boolean(organization),
+ tracked: {
+ organizationId: organization?.id,
+ },
+ untracked: {
+ args: invitationsParams,
+ },
+ }),
+ });
 
  if (organization === undefined) {
  return {