Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
TypeScript agentaiai-agentsall-in-onecrmcrm-systememaillinearmcpmessagingnotesnotionofficerustslackslack-alternativestartupstartup-toolstypescriptworkspace
description: "Queries, caching, and where data is fetched." paths: - "apps/web/" - "packages/" globs: "apps/web/,packages/" alwaysApply: false
Frontend data fetching
Queries, caching, and where data is fetched.
- FE-01 Never call a service client outside the
queriespackage — UI code calling an endpoint directly is usually re-fetching data an existing query already caches. Enforced by ast-grepts-no-service-client-outside-queries+tsx-no-service-client-outside-queries, warning. - FE-02 Every query module has a
keys.tsstructured like the existing ones. - FE-03 Conditional fetching uses a debounced signal passed to TanStack
Query's
enabled, not a custom resource. - FE-04 Pre-populating data means exposing a cache-seeding method on the query, not an ad hoc manual cache.
- FE-05 Data-dependent UI that must not suspend uses
queryReadyGate. - FE-06 Extend
QUERY_FILTERS_BASEinstead of re-deriving filter exclusions per query, and prefer explicit include lists — exclude lists silently break when a new entity type is added. - FE-07 Don't hardcode backend-owned config in the frontend (e.g. system bot config) — fetch it dynamically or generate types from the backend source of truth.
- FE-57 Never hardcode a
provider/modelid. Pick AI models from@core/component/AI/constantby plan:FREE_DEFAULT_MODELfor AI every plan runs,defaultModelForPlan/modelsForPlanfor user choices.FREE_MODELSis generated from the backend'sFreeTierModelschema, and the backend 403s anything outside the user's plan. Enforced by ast-grepts-no-hardcoded-model-id+tsx-no-hardcoded-model-id, error. - FE-29 Every new query call site (
useQuery/useInfiniteQueryor a hook fromsrc/lib/queries/**) needs a deliberateSuspenseboundary: readingquery.datasuspends to the nearest ancestor boundary. When reviewing, walk up the component tree from the call site and determine which boundary would catch it. If none exists below the app root, or the nearest one is far outside the component's own UI scope (e.g. the route-level boundary inapps/web/src/routes/Root.tsx, whose fallback blanks unrelated UI), flag it and ask which boundary is intended.
Query callback lifetimes
Query options can remain cached after their UI unmounts, including for disabled
queries: for gcTime, and indefinitely on a query other views still observe,
which keeps its last observer's options. Callbacks created inside hooks can
retain component accessors, Solid owners, and detached DOM through shared closure
environments—even when a callback only references a locally resolved ID. This
does not mean every closure captures every local variable.
- FE-69 Create cached callbacks in module-scope query factories accepting
resolved IDs, flags, and plain data. Resolve reactive inputs inside the
useQuery/useInfiniteQueryoptions accessor, e.g.useQuery(() => itemQueryOptions(id())), so inputs still update reactively. Enforced by ast-grepts-/tsx-no-inline-query-callbacks, CI error, for functions written in a query hook's options, and inqueryOptionsor clientfetchQuery-family options inside ause*,create*, or component function or an object method. Names ending inOptionscount as factories. The rule does not see references to hook-local functions or wrapper-hook arguments (below). - Keep pure selectors and polling policies at module scope, or inside those
factories. Check all retained callbacks:
queryFn,select,refetchInterval, pagination, placeholder callbacks, and functions inmeta. - Do not pass component accessors, props getters, or query proxies into the factory. For reactive selection, pass plain snapshots of the needed values (such as channel names or a resolved document ID). Naming a function or copying an ID inside the hook does not isolate its closure from the hook.
- Use
keepPreviousDatafrom@tanstack/solid-queryinstead of an inlineplaceholderData: (p) => p. - The same rule applies to callers of wrapper hooks such as
useSoupAstItemsQueryandcreateGroupedSoupQueries:meta.itemFilter/meta.insertFilterpassed from a component or view context are cached too, so build them with a module-scope factory over plain snapshots (see drive-data-source). - Query hooks in
src/lib/urql-solidare exempt: their observers are created per mount and destroyed on cleanup, so nothing outlives the component.
Examples: session query factory and search query factories.
- FE-48 Keep cached data on screen through refetch errors: gate on
isPending, neverisSuccess/isError. Every query view handles pending, error, empty, and nothing-selected separately. - FE-49 Refetches and optimistic updates never wipe local state (drafts,
anchors, selections), and a refetch started before a mutation can't overwrite
its result. Optimistic rollback state lives in
onMutate; temporary ids are never openable. Solid Query returns new objects on every refetch, so a query that polls or refetches under open lists and pickers setsreconcile: 'id'; otherwise rows remount and drop focus. - FE-50 Scope invalidation to what changed, but update every reader of it. Query keys hold exactly the fetch inputs.
- FE-58 With the GraphQL normalized cache, a mutation never refetches the
lists the cache maintains: its optimistic write and returned records update
them, and they re-evaluate locally. A refetch reads a replica that can lag the
write and puts stale state back. Read again only lists the cache cannot keep
current (
unmaintainedOnly), everything without the cache, or as a failure fallback; a write the server answers only in part writes the confirmed rest into the cache itself. - FE-51 State moved into the URL round-trips every field. Removed or renamed routes and route ids get redirects, and saved split layouts keep working.