Prefetching
If a user is likely to open a profile next, start loading it before the next screen renders. Prefetching means making an ordinary read early and letting a later consumer reuse its pending request or cached result. It uses the same keys, instance, and freshness rules as any other read.
There is no separate core prefetch method. Use query.query() on the shared instance from Getting Started.
Warm the cache with handled failures
Section titled “Warm the cache with handled failures”For optional work, catch the early read without blocking the current screen:
void query.query('/profile.json').catch((error: unknown) => { console.info('Profile preload did not complete:', error)})For required preparation, await the returned promise and let your workflow handle failure before continuing. Multiple independent keys can run together with Promise.all or Promise.allSettled, depending on whether partial success is useful.
A later ordinary reader reuses the result if it is still valid. An expired entry follows stale-while-revalidate; the awaited prefetch can return stale data before revalidation finishes. Use { stale: false } when preparation must wait on expired data, or { fresh: true } only when you deliberately want to abort and replace pending same-key work. The latter is usually not appropriate for speculative work shared with an active screen.
Prefetching stores data in the instance, not in a global browser cache or another instance. A fresh React resource can intentionally bypass prefetched data on its first selection. Increasing expiration avoids unnecessary immediate revalidation, but also permits older data for longer; choose it according to the screen’s tolerance for age.
Start work from browser intent
Section titled “Start work from browser intent”A pointer entering a link is one possible signal. This fragment assumes an existing HTML anchor named link and your shared query instance:
/** Optional warmup must not produce an unhandled rejection. */function onPointerEnter(): void { void query.query('/profile.json').catch(console.error)}link.addEventListener('pointerenter', onPointerEnter)Remove the listener with link.removeEventListener('pointerenter', onPointerEnter) when its owning view is disposed. Pointer intent is only a hint: it does not cover keyboard navigation, touch interactions, or every accessibility workflow. Do not make correctness depend on prefetch completing. Readers must still handle their own pending and failed reads.
Removing this listener does not cancel an already-started shared request. Avoid aborting speculative work on pointer leave if another consumer might already need it.
Understand the React convenience APIs
Section titled “Understand the React convenience APIs”Import useQueryPrefetch, QueryPrefetch, and QueryPrefetchTags from @studiolambda/query/react. They use the provider’s instance, or an explicit query option/prop. With your React provider installed, a stable list can warm known keys after mount:
These convenience helpers do not expose, await, or catch request promises and do not abort on unmount. A rejected initial request can therefore become an unhandled rejection; observing an error event does not consume the promise rejection. Prefer the explicit, caught query.query() path above when a failure is possible and needs application handling. The following example illustrates the helper’s wiring, not a replacement for that failure policy.
import { QueryPrefetch } from '@studiolambda/query/react'
/** A stable effect dependency shared across renders. */const profileKeys = ['/profile.json']
/** Starts optional client-effect work without delaying the child content. */export function ProfileWarmup() { return <QueryPrefetch keys={profileKeys}>Open a profile to continue.</QueryPrefetch>}QueryPrefetch passes children through without adding a DOM wrapper. useQueryPrefetch(profileKeys) performs the same effect without rendering children. Both start work in a client effect, not during server rendering. Changing the array reference reruns the effect; use a module-level constant for static keys. Do not assume your application has React Compiler enabled.
Add preload hints only for URL keys
Section titled “Add preload hints only for URL keys”QueryPrefetchTags also renders <link rel="preload" href={key} as="fetch" /> for each key and then renders its children. Additional link attributes are forwarded after those defaults, so even rel, href, or as can be overridden.
Use it only when the keys are actual fetch URLs and the hint matches the request’s credentials/CORS requirements. Logical keys such as profile:current are not useful preload URLs. Browser hints and query fetches are independent and can make separate requests; they do not guarantee network deduplication or seed the Query cache during SSR. The client effect has the same unhandled-failure and cleanup limitations as QueryPrefetch.
If the next screen needs server-rendered data rather than a browser hint, prepare a request-scoped instance and hydrate explicit data before rendering instead.