state-management

state-management

Core principle: server state and client state are different problems. Conflating them is the root cause of most frontend data bugs.

• Server state: data that lives on the server. You don't own it — you cache it. TanStack Query or SWR.
• Client state: data that only exists in the browser. You do own it. Zustand or Jotai.
• URL state: filters, pagination, selected IDs. The URL is the store — nuqs or useSearchParams.

If you put server data into a Zustand store, you are building a second cache on top of TanStack Query. You will invent your own invalidation logic and lose.

1) TanStack Query — server state authority

// lib/query-client.ts — one instance, shared everywhere
import { QueryClient } from "@tanstack/react-query";

export const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 1000 * 60,       // data fresh for 1 min — don't refetch on every focus
      retry: 2,
      refetchOnWindowFocus: false, // usually too aggressive for dashboards
    },
  },
});

// hooks/use-articles.ts
import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
import { api } from "@/lib/client";   // generated from OpenAPI spec (schema-authority)

// ── Query keys: treat them as addresses, not strings ─────────────────────────
export const articleKeys = {
  all:    ()               => ["articles"]              as const,
  list:   (filters: object)=> ["articles", "list", filters] as const,
  detail: (slug: string)   => ["articles", "detail", slug]  as const,
};

// ── Read ──────────────────────────────────────────────────────────────────────
export function useArticles(filters: ArticleFilters) {
  return useQuery({
    queryKey: articleKeys.list(filters),
    queryFn:  () => api.getArticles(filters),
  });
}

export function useArticle(slug: string) {
  return useQuery({
    queryKey: articleKeys.detail(slug),
    queryFn:  () => api.getArticle(slug),
    enabled:  !!slug,
  });
}