Keeping TanStack Query v5 Cache Consistency Intact — Invalidation Boundaries, Optimistic Updates, and SSR Traps, Worked Through with Antigravity

Place 1: invalidation boundary — express "how far it reaches" through query keys

Invalidate too widely and refetches fire on unrelated screens. Too narrowly and the display never changes after an update. The only way to make this boundary readable is to layer query keys and route everything through a factory rather than scattering string literals.

// queryKeys.ts — resource -> scope -> identifier -> subresource, four layers
export const queryKeys = {
  users: {
    all: ["users"] as const,
    lists: () => [...queryKeys.users.all, "list"] as const,
    list: (filters: UserFilters) => [...queryKeys.users.lists(), filters] as const,
    detail: (id: string) => [...queryKeys.users.all, "detail", id] as const,
    profile: (id: string) => [...queryKeys.users.detail(id), "profile"] as const,
    posts: (id: string) => [...queryKeys.users.detail(id), "posts"] as const,
  },
} as const;

With this factory, the intent of invalidation survives as code. After a profile update, writing queryClient.invalidateQueries({ queryKey: queryKeys.users.detail(id) }) invalidates the profile and posts hanging beneath it together. If you only want to change a list's filter, scope it under queryKeys.users.lists(). The advantage is that the boundary becomes visible as "key depth."

What pays off in practice is that this convention propagates to AI generation too. Use the queryKeys.users.detail(id) pattern two or three times in the project, and Antigravity's agent references the existing code and starts matching this shape on its own. Which is exactly why writing the first few hooks carefully by hand is worth it. Don't forget to apply as const at every level; drop it and the key type received in callbacks loosens, breaking silently during refactors.

One more judgment call: don't substitute removeQueries for invalidation. removeQueries drops the cache entirely, so the old data still on screen blanks out in an instant and the skeleton reappears. invalidateQueries keeps the old data visible while refetching behind it, so the seam never shows. "Remove" and "invalidate" are different things; holding that distinction sharpens your boundary design.

Place 2: optimistic updates — template the five steps so rollback is guarded by structure

The reverting-heart problem lived here. An optimistic update rewrites the cache as if the mutation succeeded, without waiting for the response. The perceived speed jumps, but drop even one rollback step and you get "the display changed even though it didn't succeed" or "it doesn't revert on failure."

I've decided to always write optimistic updates in these five steps: stop in-flight fetches with cancelQueries, take a snapshot, update the cache ahead, restore on failure, and finally sync regardless of outcome. The order has meaning.

import { useMutation, useQueryClient } from "@tanstack/react-query";
import { queryKeys } from "@/lib/queryKeys";
 
type Ctx = { previous: PostDetail | undefined };
 
export function useToggleLike(postId: string) {
  const qc = useQueryClient();
  const key = queryKeys.posts.detail(postId);
 
  return useMutation<PostDetail, Error, void, Ctx>({
    mutationFn: async () => {
      const res = await fetch(`/api/posts/${postId}/like`, { method: "POST" });
      if (!res.ok) throw new Error(`Like failed: ${res.status}`);
      return (await res.json()) as PostDetail;
    },
    onMutate: async () => {
      await qc.cancelQueries({ queryKey: key }); // (1) stop the competing fetch
      const previous = qc.getQueryData<PostDetail>(key); // (2) snapshot
      if (previous) {
        qc.setQueryData<PostDetail>(key, { // (3) update ahead
          ...previous,
          liked: !previous.liked,
          likeCount: previous.likeCount + (previous.liked ? -1 : 1),
        });
      }
      return { previous };
    },
    onError: (_e, _v, ctx) => {
      if (ctx?.previous) qc.setQueryData(key, ctx.previous); // (4) restore
    },
    onSettled: () => {
      qc.invalidateQueries({ queryKey: key }); // (5) final sync with server
    },
  });
}

The culprit behind the revert was the absence of (1). Without cancelQueries, a useQuery fetch that had started just before the mutation overwrites the cache slightly later with "the old server response." The value you just updated ahead gets repainted with that old one and snaps back. The server returns a correct 200, yet only the display lies — because of this collision. After hitting it twice, I turned my optimistic-update snippet into a fixed template that begins at (1).

Many people wonder whether (5) can be replaced by a success-path setQueryData. But to pull the server's normalized values into your hands — the assigned id, the final related counts — you ultimately need a fetch. The principle here is: don't try to finish with local state alone. When Antigravity writes optimistic updates, it tends to drop either (1) or (5), so after generation I check for those two steps first.

Place 3: SSR hydration — create the QueryClient per request

When combined with the Next.js App Router, this is the quietest and most dangerous place. Bridging server-component prefetch results to the client through HydrationBoundary is the proper v5 approach.

// app/users/[id]/page.tsx — server component
import { dehydrate, HydrationBoundary, QueryClient } from "@tanstack/react-query";
import { UserPageClient } from "./UserPageClient";
import { queryKeys } from "@/lib/queryKeys";
 
export default async function Page({ params }: { params: { id: string } }) {
  const qc = new QueryClient(); // <- always create a fresh one per request
 
  await qc.prefetchQuery({
    queryKey: queryKeys.users.profile(params.id),
    queryFn: () => fetchUserProfileServer(params.id),
  });
 
  return (
    <HydrationBoundary state={dehydrate(qc)}>
      <UserPageClient userId={params.id} />
    </HydrationBoundary>
  );
}

Calling new QueryClient() inside the function is the crux. On the Next.js server, multiple users' requests are processed in the same process. Place a QueryClient as a module-top singleton and one user's profile lingers in the cache, bleeding into the next user's render. That is, another person's personal data appears on screen. This isn't a performance topic; it's a design accident that can become a real data leak in production. When Antigravity writes SSR integration, it sometimes proposes a singleton for convenience, so a human must stop it here.

One more point: keep fetchUserProfileServer on the server and fetchUserProfile on the client sharing only the return type, with separate implementations. The server may need to reconstruct an auth cookie or call an internal RPC directly; cram both into one function and you get a thicket of isServer branches. Share the type, split the implementation. That line makes later debugging far easier.

Split Suspense boundaries "narrow and many"

useSuspenseQuery, stabilized in v5, hands loading to the parent <Suspense> and failure to <ErrorBoundary>. Erasing the if (isPending) branch from components is a big win, but misplacing the boundary causes "the whole screen vanishes when one half loads" or "the error persists even after pressing recover."

// cut boundaries narrowly, per child component
<ErrorBoundary FallbackComponent={ErrorFallback}>
  <Suspense fallback={<UserHeaderSkeleton />}>
    <UserHeader userId={id} />
  </Suspense>
</ErrorBoundary>
 
<ErrorBoundary FallbackComponent={ErrorFallback}>
  <Suspense fallback={<UserPostsSkeleton />}>
    <UserPosts userId={id} />
  </Suspense>
</ErrorBoundary>

Put one giant boundary at the top and the entire screen sinks into a skeleton when either the header or the posts wait. Cut it per child and the header stays visible while the posts appear later, with failure kept local. I adopt the convention that "a component that fetches data is responsible for wrapping itself in <Suspense>." Add a single line to the component-generation prompt — "do not expect a <Suspense> from the parent" — and the consistency of generated code visibly improves.

Guard the invalidation boundary through "operations" — injecting conventions into the AI

Even with a correct design, boundaries erode gradually as a team or an AI grows. The practical way to prevent this is to embed the convention in code and prompts, not in documentation. In my case I fix four points in the .antigravity/rules equivalent: query keys always go through the queryKeys factory; queryFn receives signal and passes it to fetch; mutations hold both cancelQueries and onSettled.invalidateQueries; components using useSuspenseQuery sit inside a Suspense boundary.

With these four in the AI's rules, generated code comes out conforming from the start, so review shifts from "hunting for convention violations" to "confirming design decisions." What you can leave to the AI is boilerplate and following existing patterns. What you must hold yourself is the design judgment: the invalidation boundary, the Suspense placement, the optimistic rollback path, and whether to propagate signal. Keep that line and you can raise generation speed while preserving consistency.

One next step

If you touch only one thing tomorrow, add a queryKeys factory in a single file and rewrite just one existing useQuery to go through it. That alone makes invalidation granularity visible as "key depth," and revert bugs like the opening one become answerable as "which of the three places." Consistency design begins quietly, from that first file.