TanStack Query v5: The New API and Why stale-while-revalidate Changes Everything

// v4
const { data } = useQuery(["users", id], () => fetchUser(id), {
  staleTime: 1000 * 60,
  keepPreviousData: true,
});

// v5  -  unified object, new option names
const { data } = useQuery({
  queryKey: ["users", id],
  queryFn: () => fetchUser(id),
  staleTime: 1000 * 60,
  placeholderData: "keepPrevious", // replaces keepPreviousData
});

// lib/queries/tasks.ts
import { queryOptions } from "@tanstack/react-query";

export const taskQueries = {
  list: (projectId: string) =>
    queryOptions({
      queryKey: ["tasks", projectId],
      queryFn: () => api.tasks.list(projectId),
      staleTime: 30_000,
    }),

  detail: (taskId: string) =>
    queryOptions({
      queryKey: ["tasks", "detail", taskId],
      queryFn: () => api.tasks.get(taskId),
    }),
};

// In a component
const { data: tasks } = useQuery(taskQueries.list(projectId));

// In a server component for prefetch
await queryClient.prefetchQuery(taskQueries.list(projectId));

// In a mutation's onSuccess
queryClient.invalidateQueries(taskQueries.list(projectId));

const createTask = useMutation({
  mutationFn: (data: NewTask) => api.tasks.create(data),

  onMutate: async (newTask) => {
    // Cancel in-flight refetches
    await queryClient.cancelQueries(taskQueries.list(projectId));
    // Snapshot current data
    const previous = queryClient.getQueryData(taskQueries.list(projectId).queryKey);
    // Optimistically update
    queryClient.setQueryData(
      taskQueries.list(projectId).queryKey,
      (old: Task[]) => [...old, { ...newTask, id: "temp", status: "pending" }]
    );
    return { previous };
  },

  onError: (err, vars, context) => {
    // Roll back on error
    queryClient.setQueryData(
      taskQueries.list(projectId).queryKey,
      context?.previous
    );
  },

  onSettled: () => {
    queryClient.invalidateQueries(taskQueries.list(projectId));
  },
});

import { useSuspenseQuery } from "@tanstack/react-query";

function TaskList({ projectId }: { projectId: string }) {
  // Throws a promise while loading  -  caught by parent Suspense
  const { data: tasks } = useSuspenseQuery(taskQueries.list(projectId));

  return <ul>{tasks.map(t => <li key={t.id}>{t.title}</li>)}</ul>;
}

// Parent
<Suspense fallback={<Skeleton />}>
  <ErrorBoundary fallback={<Error />}>
    <TaskList projectId={id} />
  </ErrorBoundary>
</Suspense>

// app/projects/[id]/page.tsx
import { dehydrate, HydrationBoundary, QueryClient } from "@tanstack/react-query";
import { taskQueries } from "@/lib/queries/tasks";

export default async function ProjectPage({ params }: { params: { id: string } }) {
  const queryClient = new QueryClient();
  await queryClient.prefetchQuery(taskQueries.list(params.id));

  return (
    <HydrationBoundary state={dehydrate(queryClient)}>
      <TaskList projectId={params.id} />
    </HydrationBoundary>
  );
}