RQ primer
React Query (RQ) is the data layer Meridian recommends for any dashboard, console, or live-updating surface that pulls from the gateway. This primer covers the three rules that keep your queries predictable and your bills small: stable keys, sane stale times, and deliberate invalidation. Read it once before you wire your first endpoint and you will save a week of cache debugging.
1. Stable query keys
Every cache entry is keyed by a serialized array. Treat the key as part of your API surface: never inline anonymous objects, never sprinkle Date.now() into a key, and never let a key depend on render-only state. If two components want the same data they must produce identical keys, or you will pay for the request twice.
2. Stale time vs cache time
staleTime is how long the data is trusted; gcTime is how long it lingers after the last subscriber unmounts. The Meridian default is a 60-second stale window with focus refetch off, because the gateway already pushes invalidations over the event stream and double-polling on focus just burns tokens.
3. Deliberate invalidation
After a mutation, invalidate the narrowest prefix that still covers every affected view. Wildcard invalidations feel safe but they cascade refetches across panels the user is not even looking at. Pair every mutation with a written list of the keys it touches; if that list does not fit on one line, the key shape is wrong.
Reference hook
import { useQuery } from "@tanstack/react-query";
async function fetchInsights() {
const res = await fetch("https://api.meridian.dev/v1/insights", {
headers: { Authorization: `Bearer ${process.env.MERIDIAN_KEY}` },
});
if (!res.ok) throw new Error("fetch_failed");
return res.json();
}
export function useInsights() {
return useQuery({
queryKey: ["insights"],
queryFn: fetchInsights,
staleTime: 60_000,
refetchOnWindowFocus: false,
});
}