TanStack Query

# TaskFlow query key catalog

- ["tasks"] - Task resource family
- ["tasks", "list", query] - one normalized collection view
- ["tasks", "detail", taskId] - one Task detail

Rules:
1. Include every variable used by queryFn that changes returned data.
2. Keep keys JSON-serializable.
3. Never include access/refresh tokens or secrets.
4. Use prefixes for intentional invalidation families.

# TaskFlow Phase 22 reference snapshot

This snapshot demonstrates TanStack Query v5.103.1 integration with the existing Next.js App Router, Supabase-authenticated API client and NestJS Task API. It is a teaching reference, not a wholesale replacement for earlier phase files.

Key rule: TanStack Query owns remote server-state lifecycle; URL state, form state, local UI state, authentication and backend business rules keep their existing owners.

{
  "dependencies": {
    "@tanstack/react-query": "5.103.1"
  },
  "devDependencies": {
    "@tanstack/react-query-devtools": "5.103.1"
  }
}

import { dehydrate, HydrationBoundary } from "@tanstack/react-query";
import { getQueryClient } from "@/lib/query/get-query-client";
import { taskListOptions } from "@/lib/query/task-options";
import { normalizeTaskSearchParams } from "@/lib/tasks/normalize-task-search-params";
import { TasksScreen } from "@/components/tasks/tasks-screen";

export default async function TasksPage({ searchParams }: { searchParams: Promise<Record<string, string | string[] | undefined>> }) {
  const query = normalizeTaskSearchParams(await searchParams);
  const queryClient = getQueryClient();
  await queryClient.prefetchQuery(taskListOptions(query));

  return (
    <HydrationBoundary state={dehydrate(queryClient)}>
      <TasksScreen query={query} />
    </HydrationBoundary>
  );
}

"use client";

import { QueryClientProvider } from "@tanstack/react-query";
import { ReactQueryDevtools } from "@tanstack/react-query-devtools";
import { getQueryClient } from "@/lib/query/get-query-client";

export function Providers({ children }: { children: React.ReactNode }) {
  const queryClient = getQueryClient();
  return (
    <QueryClientProvider client={queryClient}>
      {children}
      <ReactQueryDevtools initialIsOpen={false} />
    </QueryClientProvider>
  );
}

"use client";

import { keepPreviousData, useQuery } from "@tanstack/react-query";
import { taskListOptions } from "@/lib/query/task-options";
import type { TaskListQuery } from "@/lib/api/tasks";
import { TaskTable } from "./task-table";
import { EmptyState } from "@/components/ui/empty-state";

export function TasksScreen({ query }: { query: TaskListQuery }) {
  const result = useQuery({
    ...taskListOptions(query),
    placeholderData: keepPreviousData,
  });

  if (result.isPending) return <p>Loading tasks...</p>;
  if (result.isError) return <p role="alert">Unable to load tasks.</p>;
  if (result.data.data.length === 0) return <EmptyState title="No tasks found" />;

  return (
    <>

"use client";

import { useMutation, useQueryClient } from "@tanstack/react-query";
import { createTask, updateTask, type CreateTaskInput, type UpdateTaskInput } from "@/lib/api/task-mutations";
import { taskKeys } from "@/lib/query/task-keys";

export function useCreateTask() {
  const queryClient = useQueryClient();
  return useMutation({
    mutationFn: (input: CreateTaskInput) => createTask(input),
    onSuccess: async () => {
      await queryClient.invalidateQueries({ queryKey: taskKeys.lists() });
    },
  });
}

export function useUpdateTask(taskId: string) {
  const queryClient = useQueryClient();
  return useMutation({
    mutationFn: (input: UpdateTaskInput) => updateTask(taskId, input),

"use client";

import type { QueryClient } from "@tanstack/react-query";
import { createClient } from "@/lib/supabase/client";

export async function signOutWithCacheClear(queryClient: QueryClient) {
  const supabase = createClient();
  await supabase.auth.signOut({ scope: "local" });
  queryClient.clear();
  window.location.assign("/sign-in");
}

import { environmentManager, QueryClient } from "@tanstack/react-query";
import { ApiClientError } from "@/lib/api/api-error";

function shouldRetry(failureCount: number, error: unknown) {
  if (error instanceof ApiClientError && [400, 401, 403, 404, 409].includes(error.status)) {
    return false;
  }
  return failureCount < 2;
}

function makeQueryClient() {
  return new QueryClient({
    defaultOptions: {
      queries: { staleTime: 30_000, retry: shouldRetry },
      mutations: { retry: 0 },
    },
  });
}

let browserQueryClient: QueryClient | undefined;

import type { TaskListQuery } from "@/lib/api/tasks";

export const taskKeys = {
  all: ["tasks"] as const,
  lists: () => [...taskKeys.all, "list"] as const,
  list: (query: TaskListQuery) => [...taskKeys.lists(), query] as const,
  details: () => [...taskKeys.all, "detail"] as const,
  detail: (id: string) => [...taskKeys.details(), id] as const,
};

import { queryOptions } from "@tanstack/react-query";
import { fetchTask, fetchTasks, type TaskListQuery } from "@/lib/api/tasks";
import { taskKeys } from "./task-keys";

export function taskListOptions(query: TaskListQuery) {
  return queryOptions({
    queryKey: taskKeys.list(query),
    queryFn: () => fetchTasks(query),
    staleTime: 30_000,
  });
}

export function taskDetailOptions(id: string) {
  return queryOptions({
    queryKey: taskKeys.detail(id),
    queryFn: () => fetchTask(id),
    staleTime: 30_000,
  });
}

# Phase 22 test matrix

- First Task list visit -> pending state, then successful table.
- Return to a still-fresh page -> cached data reused without unnecessary fetch.
- Let staleTime expire, refocus window -> background refetch while table remains visible.
- Change page -> URL changes, query key changes, previous page remains as placeholder while next loads.
- Change search/status -> page resets to 1 and a distinct list key is used.
- Create Task -> mutation succeeds, Task list key family invalidated, active list refreshes.
- Update Task -> detail cache receives saved Task and list family invalidates.
- 401/403/409 -> query/mutation does not loop retries.
- User A sign-out -> queryClient.clear(); User B sign-in starts with no User A cached Task data.
- Devtools -> keys show no bearer token or secret values.