TanStack Query

All new web-app backend requests go through TanStack Query. Imperative Api.foo.bar() in loaders, generated tuple hooks (Api.foo.useBar()), and Pages.useRefresh() are the old pattern.

When you add a feature or fix on an existing page, hook, or model module, migrate that surface's queries and mutations to TanStack in the same change. Do not leave a mixed loader (one TanStack query plus one raw Api.* fetch) on the file you just edited.

For copy-paste skeletons and old→new mappings, see reference.md.

When to migrate

Situation	Do
New page, loader, or mutation	TanStack from the start
Feature or fix on an existing page/module	Migrate that surface's API calls too
Typeahead / search-as-you-type (People.usePeopleSearch, Api.*.search as a search fn)	Leave imperative
Unrelated sibling page	Do not expand the PR
ProjectPage	Only when that page is the requested work

ProjectPage is the last project-page migration. A one-line copy fix there does not require rewriting its loader.

How it works

Generated helpers live next to each endpoint in app/assets/js/api/index.tsx:

Helper	Role
fooQuery(input)	Prefetch in the router loader (staleTime: Infinity)
fooQueryOptions(input)	queryKey + queryFn for useQuery / useLoadedQuery
fooQueryKey(input)	Invalidate one cached input
fooQueryKeyPrefix()	Invalidate every cached input for that endpoint
fooMutationOptions()	mutationFn for useMutation

The shared client is app/assets/js/api/queryClient.ts.

flowchart LR
  loader["router loader: fooQuery"] --> cache["TanStack cache"]
  cache --> hook["useLoadedQuery / useQuery"]
  mutate["mutateAsync"] --> invalidate["invalidateQueries"]
  invalidate --> cache

Page loaders

Router loader prefetches and returns inputs, not payload:

1. Build queryInput (same shape the API already used).
2. await Api.namespace.fooQuery(queryInput) (parallelize with Promise.all).
3. return { queryInput }.
4. useLoadedData reads Pages.useLoadedData(), then useLoadedQuery(Api.namespace.fooQueryOptions(queryInput)).
5. Check the declared types: do not assert fields that are already non-nullable. For nullable data, prefer safe defaults (for example, items ?? [] or permissions?.canCreateSpace ?? false), or hide optional UI when valid. Use assertPresent(value, message) only for data that may be absent but is essential and has no safe fallback, rather than an inline null check that throws.

Use useLoadedQuery, not useQuery, when the loader prefetched. It uses loaderBackedQueryOptions so the page does not refetch on mount unless the query was invalidated.

Replace Pages.useRefresh() with a local useRefresh that invalidateQueries on the page's query keys.

Canonical: ProjectPausePage/loader.tsx, ProjectDiscussionPage/loader.tsx.

Optional queries (URL may omit space/goal, or a parent fetch may fail): always call useLoadedQuery, pass enabled: input != null, and fall back in JS. See reference.md.

Mutations

Put wrappers in app/assets/js/models/<resource>/<resource>Lifecycle.ts (or projectDiscussionLifecycle.ts when the resource already has a sibling file).

export function useCreateProjectDiscussion() {
  const queryClient = useQueryClient();

  return useMutation({
    ...Api.projects.createDiscussionMutationOptions(),
    onSuccess: () => {
      void invalidateProjectDiscussionQueries(queryClient);
    },
  });
}

Pages call mutateAsync. Invalidate with *QueryKeyPrefix() so every cached input for that endpoint refreshes. Re-export from the model's index.tsx.

Do not switch every remaining call site of a generated tuple hook when you add a lifecycle wrapper. Update the surface you are on; leave others (for example WorkMap's Api.projects.useCreate()) until that file is migrated.

Canonical: projectDiscussionLifecycle.ts, projectLifecycle.ts.

Layout and non-prefetched queries

If the query is not prefetched in a router loader (company layout getMe), wrap with useQuery(fooQueryOptions(input)), not useLoadedQuery.

Canonical: models/people/index.tsx useGetMe.

Tests

Colocate Jest next to the lifecycle file (fooLifecycle.test.ts). Seed queryClient.setQueryData(key, {}), run the invalidate helper, assert getQueryState(key)?.isInvalidated. Cover the intended prefixes and one unrelated key that must stay clean.

Run make test FILE=assets/js/models/.../fooLifecycle.test.ts.

Existing feature tests for the page are the behavior net; run the ones that visit the migrated route.

Do not

• Prefetch with raw Api.foo.bar(input) or Projects.getProject(...).
• Return fetched records from the loader (return { project }). Return inputs.
• Use Pages.useRefresh() after a TanStack loader — it will not update cache.
• Introduce PageCache.fetch on new work.
• Extract a shared loader helper for two similar pages unless duplication is already painful. Include flags and parent APIs usually differ.
• Use ! to bypass missing query data, or assertPresent for non-nullable fields or data with a safe fallback.

Navigation and hover preloading

• pageRoute runs route.loader for navigation: authentication, progress, synchronous onNavigate, then the page loader. Hover/focus runs only handle.dataLoader after 150 ms; the shared company loader stays navigation-only.
• Keep page loaders read-only and reuse the same generated query inputs/options in useLoadedQuery. Use emptyLoader when no data is needed. Put navigation-only effects in synchronous onNavigate; never change headers in a preloadable loader.
• auth defaults to true. Set preload: false for mutating reads, redirects with browser effects, context changes, and mandatory fresh checks. Do not relax freshness or company isolation for preloading. Individual links can opt out with data-preload="false"; cross-company links are skipped automatically.
• Cached-query transport has no toast/reload effects. Navigation and active query observers report errors centrally. Imperative cached queries without an observer keep local error handling; delayed stale-client detection is an accepted tradeoff.
• See the minimal route example.