react-query

npm install @tanstack/react-query

// app/providers.tsx — Query client setup
'use client'
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import { ReactQueryDevtools } from '@tanstack/react-query-devtools'
import { useState } from 'react'

export function Providers({ children }) {
  const [queryClient] = useState(() => new QueryClient({
    defaultOptions: {
      queries: {
        staleTime: 60 * 1000,         // data is fresh for 1 minute
        gcTime: 5 * 60 * 1000,        // garbage collect after 5 minutes
        retry: 2,                      // retry failed requests twice
        refetchOnWindowFocus: false,   // don't refetch on tab switch
      },
    },
  }))

  return (
    <QueryClientProvider client={queryClient}>
      {children}
      <ReactQueryDevtools />
    </QueryClientProvider>
  )
}

// hooks/useProjects.ts — Data fetching hooks
import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'

// Fetch projects
export function useProjects(status?: string) {
  return useQuery({
    queryKey: ['projects', { status }],
    queryFn: async () => {
      const params = new URLSearchParams()
      if (status) params.set('status', status)
      const res = await fetch(`/api/projects?${params}`)
      if (!res.ok) throw new Error('Failed to fetch projects')
      return res.json() as Promise<{ data: Project[]; pagination: Pagination }>
    },
  })
}

// Fetch single project
export function useProject(id: string) {
  return useQuery({
    queryKey: ['projects', id],
    queryFn: async () => {
      const res = await fetch(`/api/projects/${id}`)
      if (!res.ok) throw new Error('Project not found')
      return res.json() as Promise<Project>
    },
    enabled: !!id,    // don't fetch if id is empty
  })
}

// Usage in component
function ProjectList() {
  const { data, isLoading, error } = useProjects('active')

  if (isLoading) return <Skeleton />
  if (error) return <ErrorMessage error={error} />

  return (
    <ul>
      {data.data.map(project => (
        <li key={project.id}>{project.name}</li>
      ))}
    </ul>
  )
}

// hooks/useCreateProject.ts — Optimistic mutation
export function useCreateProject() {
  const queryClient = useQueryClient()

  return useMutation({
    mutationFn: async (input: CreateProjectInput) => {
      const res = await fetch('/api/projects', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(input),
      })
      if (!res.ok) throw new Error('Failed to create project')
      return res.json()
    },

    // Optimistic update — show new project immediately
    onMutate: async (newProject) => {
      await queryClient.cancelQueries({ queryKey: ['projects'] })

      const previous = queryClient.getQueryData(['projects', { status: 'active' }])

      queryClient.setQueryData(['projects', { status: 'active' }], (old: any) => ({
        ...old,
        data: [{ id: 'temp', ...newProject, status: 'active' }, ...(old?.data || [])],
      }))

      return { previous }
    },

    // Rollback on error
    onError: (err, newProject, context) => {
      queryClient.setQueryData(['projects', { status: 'active' }], context?.previous)
    },

    // Refetch to get real data
    onSettled: () => {
      queryClient.invalidateQueries({ queryKey: ['projects'] })
    },
  })
}

// hooks/useInfiniteProjects.ts — Cursor-based pagination
import { useInfiniteQuery } from '@tanstack/react-query'

export function useInfiniteProjects() {
  return useInfiniteQuery({
    queryKey: ['projects', 'infinite'],
    queryFn: async ({ pageParam }) => {
      const params = new URLSearchParams({ limit: '20' })
      if (pageParam) params.set('cursor', pageParam)
      const res = await fetch(`/api/projects?${params}`)
      return res.json()
    },
    initialPageParam: undefined as string | undefined,
    getNextPageParam: (lastPage) => lastPage.pagination.nextCursor,
  })
}