refactor(react-query): hoist every staleTime into a named exported constant (#5427)

* refactor(react-query): hoist every staleTime into a named exported constant

Adds a repo-wide convention (documented in .claude/rules/sim-queries.md,
CLAUDE.md, and the react-query-best-practices skill/command) that every
staleTime value must come from a named exported constant instead of an
inline numeric literal. This prevents a server-side prefetch and its
client hook from independently duplicating the same duration and
drifting out of sync, which Greptile caught on PR #5426.

Applies the convention across all of hooks/queries/** and their
prefetch.ts consumers.

* refactor(react-query): use FOLDER_LIST_STALE_TIME in folders.ts hooks

useFolders and useFolderMap still used inline 60 * 1000 despite folders.ts
already exporting FOLDER_LIST_STALE_TIME — the same prefetch-drift gap this
refactor closes everywhere else. Same value, no behavior change.

Author: waleedlatif1

.agents/skills/react-query-best-practices/SKILL.md

@@ -31,7 +31,7 @@ Read these before analyzing:
 
 ### Query hooks
 - Every `queryFn` must forward `signal` for request cancellation
-- Every query must have an explicit `staleTime` (default 0 is almost never correct)
+- Every query must have an explicit `staleTime` (default 0 is almost never correct), assigned from a named exported constant — never an inline numeric literal. A server-side prefetch hydrating the same query key must import and reuse that constant instead of restating the number
 - `keepPreviousData` / `placeholderData` only on variable-key queries (where params change), never on static keys
 - Use `enabled` to prevent queries from running without required params
 

.claude/commands/react-query-best-practices.md

@@ -31,7 +31,7 @@ Read these before analyzing:
 
 ### Query hooks
 - Every `queryFn` must forward `signal` for request cancellation
-- Every query must have an explicit `staleTime` (default 0 is almost never correct)
+- Every query must have an explicit `staleTime` (default 0 is almost never correct), assigned from a named exported constant — never an inline numeric literal. A server-side prefetch hydrating the same query key must import and reuse that constant instead of restating the number
 - `keepPreviousData` / `placeholderData` only on variable-key queries (where params change), never on static keys
 - Use `enabled` to prevent queries from running without required params
 

.claude/rules/sim-queries.md

@@ -50,14 +50,16 @@ The `'use client'` hook module then imports these back for its hooks. **Never**
 ## Query Hook
 
 - Every `queryFn` must destructure and forward `signal` for request cancellation
-- Every query must have an explicit `staleTime`
+- Every query must have an explicit `staleTime`, assigned from a named exported constant (`ENTITY_LIST_STALE_TIME`), never an inline numeric literal. A server-side prefetch (`prefetch.ts`) hydrating the same query key must import and reuse that constant, not restate the number — this is what keeps a prefetched cache entry from going stale out of sync with the client hook that reads it
 - Use `keepPreviousData` only on variable-key queries (where params change), never on static keys
 - Same-origin JSON calls must go through `requestJson(contract, ...)` from `@/lib/api/client/request` against the contract in `@/lib/api/contracts/**`
 
 ```typescript
 import { requestJson } from '@/lib/api/client/request'
 import { listEntitiesContract, type EntityList } from '@/lib/api/contracts/entities'
 
+export const ENTITY_LIST_STALE_TIME = 60 * 1000
+
 async function fetchEntities(workspaceId: string, signal?: AbortSignal): Promise<EntityList> {
   const data = await requestJson(listEntitiesContract, {
     query: { workspaceId },
@@ -71,7 +73,7 @@ export function useEntityList(workspaceId?: string, options?: { enabled?: boolea
     queryKey: entityKeys.list(workspaceId),
     queryFn: ({ signal }) => fetchEntities(workspaceId as string, signal),
     enabled: Boolean(workspaceId) && (options?.enabled ?? true),
-    staleTime: 60 * 1000,
+    staleTime: ENTITY_LIST_STALE_TIME,
     placeholderData: keepPreviousData, // OK: workspaceId varies
   })
 }

.cursor/commands/react-query-best-practices.md

@@ -26,7 +26,7 @@ Read these before analyzing:
 
 ### Query hooks
 - Every `queryFn` must forward `signal` for request cancellation
-- Every query must have an explicit `staleTime` (default 0 is almost never correct)
+- Every query must have an explicit `staleTime` (default 0 is almost never correct), assigned from a named exported constant — never an inline numeric literal. A server-side prefetch hydrating the same query key must import and reuse that constant instead of restating the number
 - `keepPreviousData` / `placeholderData` only on variable-key queries (where params change), never on static keys
 - Use `enabled` to prevent queries from running without required params
 

CLAUDE.md

@@ -290,6 +290,8 @@ import { keepPreviousData, useQuery } from '@tanstack/react-query'
 import { requestJson } from '@/lib/api/client/request'
 import { listEntitiesContract, type EntityList } from '@/lib/api/contracts/entities'
 
+export const ENTITY_LIST_STALE_TIME = 60 * 1000
+
 async function fetchEntities(workspaceId: string, signal?: AbortSignal): Promise<EntityList> {
   const data = await requestJson(listEntitiesContract, {
     query: { workspaceId },
@@ -303,7 +305,7 @@ export function useEntityList(workspaceId?: string) {
     queryKey: entityKeys.list(workspaceId),
     queryFn: ({ signal }) => fetchEntities(workspaceId as string, signal),
     enabled: Boolean(workspaceId),
-    staleTime: 60 * 1000,
+    staleTime: ENTITY_LIST_STALE_TIME,
     placeholderData: keepPreviousData,
   })
 }
@@ -326,7 +328,7 @@ export const entityKeys = {
 ### Query Hooks
 
 - Every `queryFn` must forward `signal` for request cancellation
-- Every query must have an explicit `staleTime`
+- Every query must have an explicit `staleTime`, assigned from a named exported constant, never an inline numeric literal — a server-side prefetch hydrating the same query key must import and reuse that constant so the two never drift out of sync
 - Use `keepPreviousData` only on variable-key queries (where params change), never on static keys
 
 ```typescript
@@ -335,7 +337,7 @@ export function useEntityList(workspaceId?: string) {
     queryKey: entityKeys.list(workspaceId),
     queryFn: ({ signal }) => fetchEntities(workspaceId as string, signal),
     enabled: Boolean(workspaceId),
-    staleTime: 60 * 1000,
+    staleTime: ENTITY_LIST_STALE_TIME,
     placeholderData: keepPreviousData, // OK: workspaceId varies
   })
 }

apps/sim/app/workspace/[workspaceId]/files/prefetch.ts

@@ -2,8 +2,14 @@ import type { QueryClient } from '@tanstack/react-query'
 import type { WorkspaceFileFolderApi } from '@/lib/api/contracts/workspace-file-folders'
 import type { ListWorkspaceFilesResponse } from '@/lib/api/contracts/workspace-files'
 import { prefetchInternalJson } from '@/app/workspace/[workspaceId]/lib/prefetch-internal-fetch'
-import { workspaceFileFolderKeys } from '@/hooks/queries/workspace-file-folders'
-import { workspaceFilesKeys } from '@/hooks/queries/workspace-files'
+import {
+  WORKSPACE_FILE_FOLDERS_STALE_TIME,
+  workspaceFileFolderKeys,
+} from '@/hooks/queries/workspace-file-folders'
+import {
+  WORKSPACE_FILES_LIST_STALE_TIME,
+  workspaceFilesKeys,
+} from '@/hooks/queries/workspace-files'
 
 /**
  * Prefetches the Files browser's two lists — workspace files and file folders —
@@ -27,7 +33,7 @@ export async function prefetchFilesBrowser(
         )
         return data.success ? data.files : []
       },
-      staleTime: 30 * 1000,
+      staleTime: WORKSPACE_FILES_LIST_STALE_TIME,
     }),
     queryClient.prefetchQuery({
       queryKey: workspaceFileFolderKeys.list(workspaceId, 'active'),
@@ -37,7 +43,7 @@ export async function prefetchFilesBrowser(
         )
         return data.folders ?? []
       },
-      staleTime: 30 * 1000,
+      staleTime: WORKSPACE_FILE_FOLDERS_STALE_TIME,
     }),
   ])
 }

apps/sim/app/workspace/[workspaceId]/home/prefetch.ts

@@ -4,7 +4,10 @@ import type { ListWorkspaceFilesResponse } from '@/lib/api/contracts/workspace-f
 import { prefetchInternalJson } from '@/app/workspace/[workspaceId]/lib/prefetch-internal-fetch'
 import { FOLDER_LIST_STALE_TIME, mapFolder } from '@/hooks/queries/folders'
 import { folderKeys } from '@/hooks/queries/utils/folder-keys'
-import { workspaceFilesKeys } from '@/hooks/queries/workspace-files'
+import {
+  WORKSPACE_FILES_LIST_STALE_TIME,
+  workspaceFilesKeys,
+} from '@/hooks/queries/workspace-files'
 
 /**
  * Prefetches the home page's secondary lists — folders and workspace files —
@@ -42,7 +45,7 @@ export async function prefetchHomeLists(
         )
         return data.success ? data.files : []
       },
-      staleTime: 30 * 1000,
+      staleTime: WORKSPACE_FILES_LIST_STALE_TIME,
     }),
   ])
 }

apps/sim/app/workspace/[workspaceId]/knowledge/prefetch.ts

@@ -1,7 +1,7 @@
 import type { QueryClient } from '@tanstack/react-query'
 import type { KnowledgeBaseData } from '@/lib/api/contracts/knowledge'
 import { prefetchInternalJson } from '@/app/workspace/[workspaceId]/lib/prefetch-internal-fetch'
-import { knowledgeKeys } from '@/hooks/queries/kb/knowledge'
+import { KNOWLEDGE_BASE_LIST_STALE_TIME, knowledgeKeys } from '@/hooks/queries/kb/knowledge'
 
 /**
  * Prefetches the workspace's knowledge-bases list under the same query key the
@@ -23,6 +23,6 @@ export async function prefetchKnowledgeBases(
       )
       return result.data
     },
-    staleTime: 60 * 1000,
+    staleTime: KNOWLEDGE_BASE_LIST_STALE_TIME,
   })
 }

apps/sim/app/workspace/[workspaceId]/settings/[section]/prefetch.ts

@@ -3,9 +3,17 @@ import { headers } from 'next/headers'
 import { getSession } from '@/lib/auth'
 import { getInternalApiBaseUrl } from '@/lib/core/utils/urls'
 import { getUserProfile, getUserSettings } from '@/lib/users/queries'
-import { generalSettingsKeys, mapGeneralSettingsResponse } from '@/hooks/queries/general-settings'
-import { subscriptionKeys } from '@/hooks/queries/subscription'
-import { mapUserProfileResponse, userProfileKeys } from '@/hooks/queries/user-profile'
+import {
+  GENERAL_SETTINGS_STALE_TIME,
+  generalSettingsKeys,
+  mapGeneralSettingsResponse,
+} from '@/hooks/queries/general-settings'
+import { SUBSCRIPTION_DATA_STALE_TIME, subscriptionKeys } from '@/hooks/queries/subscription'
+import {
+  mapUserProfileResponse,
+  USER_PROFILE_STALE_TIME,
+  userProfileKeys,
+} from '@/hooks/queries/user-profile'
 
 /**
  * Prefetch general settings server-side via the shared data layer.
@@ -20,7 +28,7 @@ export function prefetchGeneralSettings(queryClient: QueryClient) {
       const data = await getUserSettings(session?.user?.id ?? null)
       return mapGeneralSettingsResponse(data)
     },
-    staleTime: 60 * 60 * 1000,
+    staleTime: GENERAL_SETTINGS_STALE_TIME,
   })
 }
 
@@ -46,7 +54,7 @@ export function prefetchSubscriptionData(queryClient: QueryClient) {
       if (!response.ok) throw new Error(`Subscription prefetch failed: ${response.status}`)
       return response.json()
     },
-    staleTime: 5 * 60 * 1000,
+    staleTime: SUBSCRIPTION_DATA_STALE_TIME,
   })
 }
 
@@ -65,6 +73,6 @@ export function prefetchUserProfile(queryClient: QueryClient) {
       if (!user) throw new Error('User not found')
       return mapUserProfileResponse(user)
     },
-    staleTime: 5 * 60 * 1000,
+    staleTime: USER_PROFILE_STALE_TIME,
   })
 }

apps/sim/app/workspace/[workspaceId]/tables/prefetch.ts

@@ -1,7 +1,7 @@
 import type { QueryClient } from '@tanstack/react-query'
 import type { TableDefinition } from '@/lib/table'
 import { prefetchInternalJson } from '@/app/workspace/[workspaceId]/lib/prefetch-internal-fetch'
-import { tableKeys } from '@/hooks/queries/utils/table-keys'
+import { TABLE_LIST_STALE_TIME, tableKeys } from '@/hooks/queries/utils/table-keys'
 
 /**
  * Prefetches the workspace's tables list under the same query key the client
@@ -21,6 +21,6 @@ export async function prefetchTables(queryClient: QueryClient, workspaceId: stri
       )
       return response.data.tables
     },
-    staleTime: 30 * 1000,
+    staleTime: TABLE_LIST_STALE_TIME,
   })
 }