data-fetching

Data Fetching Conventions

Decision Matrix

Context	Pattern
Server Component (initial load)	Direct Supabase/Prisma query
Client Component (read)	TanStack Query useQuery
Client Component (mutation)	TanStack Query useMutation or Server Action
Form submission	Server Action with useActionState
Real-time updates	Supabase Realtime subscription
URL-driven state	nuqs useQueryStates

TanStack Query Patterns

// Query with proper key factory
const queryKeys = {
  all: ['features'] as const,
  lists: () => [...queryKeys.all, 'list'] as const,
  list: (filters: Filters) => [...queryKeys.lists(), filters] as const,
  details: () => [...queryKeys.all, 'detail'] as const,
  detail: (id: string) => [...queryKeys.details(), id] as const,
}

// Hook
export function useFeatures(filters: Filters) {
  return useQuery({
    queryKey: queryKeys.list(filters),
    queryFn: () => fetchFeatures(filters),
    staleTime: 5 * 60 * 1000, // 5 minutes
  })
}

Next.js 16 caching

Caching is explicit: 'use cache' + cacheComponents (static shell / dynamic holes). Do not assume implicit fetch caching. Turbopack is default for dev and build. React Compiler: reactCompiler: true.

Server Component Prefetching

// Prefetch in Server Component, hydrate in Client
import { HydrationBoundary, dehydrate } from '@tanstack/react-query'

export default async function Page() {
  const queryClient = new QueryClient()
  await queryClient.prefetchQuery({
    queryKey: ['features'],
    queryFn: fetchFeatures,
  })

  return (
    <HydrationBoundary state={dehydrate(queryClient)}>
      <FeatureList />
    </HydrationBoundary>
  )
}

Error Handling

• Always handle error state from useQuery
• Show <ErrorState> component with retry button
• Mutations: use onSuccess for cache invalidation, onError for toast

Caching

• Set staleTime based on data freshness needs
• Use queryClient.invalidateQueries after mutations
• Use revalidatePath / revalidateTag in Server Actions