frontend-state-management

Frontend State Management

State management in the user frontend follows a strict split: server state lives in TanStack Query, client-only state lives in Zustand. Never mix the two.

TanStack Query Patterns

Query Key Factory

All query keys are centralized in src/api/query-keys.ts:

export const queryKeys = {
  me: ["me"] as const,
  entitlements: ["entitlements"] as const,
  likesIncoming: ["likes", "incoming"] as const,
  matches: ["matches"] as const,
  notifications: ["notifications"] as const,
  privacySettings: ["settings", "privacy"] as const,
  notificationSettings: ["settings", "notifications"] as const,
  profile: ["profile"] as const,
  blockedUsers: ["blocked"] as const,
  blockedContacts: ["blockedContacts"] as const,
  travel: ["travel"] as const,
  feed: ["feed"] as const,
  storeCatalog: ["store", "catalog"] as const,
};

Rules:

• Always use queryKeys.xxx — never inline string arrays
• Keys use as const for type-safe matching in invalidateQueries
• Hierarchical keys: ["settings", "privacy"] lets you invalidate all settings with { queryKey: ["settings"] }
• Add new keys here when adding new API endpoints — keep alphabetical within groups

Query Client Config

Location: src/api/query-client.ts

export const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 30_000,       // 30s — data considered fresh
      gcTime: 24 * 60 * 60_000, // 24h — keep in memory/IDB across sessions
      retry: 1,                 // single retry on failure
      refetchOnWindowFocus: false, // TG mini app manages own lifecycle
    },
  },
});

Cache Invalidation After Mutations

Pattern: API function performs mutation, then invalidates related queries.

// src/api/profile.ts
export async function updateProfile(payload: ProfileCoreRequest): Promise<ProfileCoreResponse> {
  const result = await requestJSON<ProfileCoreResponse, ProfileCoreRequest>("/v1/profile/core", {
    method: "POST",
    body: payload,
  });
  // Invalidate stale caches — profile data changed, /me might too
  void queryClient.invalidateQueries({ queryKey: queryKeys.profile });
  void queryClient.invalidateQueries({ queryKey: queryKeys.me });
  return result;
}