React Query Patterns | Bootspring Docs

Server state management with TanStack Query.

Overview#

React Query handles caching, synchronization, and server state. This pattern covers:

Query client setup
Basic queries
Mutations with cache updates
Optimistic updates
Infinite queries
Prefetching

Prerequisites#

npm install @tanstack/react-query @tanstack/react-query-devtools

Setup#

Configure the query client and provider.

// app/providers.tsx
'use client'

import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import { ReactQueryDevtools } from '@tanstack/react-query-devtools'
import { useState } from 'react'

export function Providers({ children }: { children: React.ReactNode }) {
  const [queryClient] = useState(() => new QueryClient({
    defaultOptions: {
      queries: {
        staleTime: 60 * 1000, // 1 minute
        refetchOnWindowFocus: false
      }
    }
  }))

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

// app/layout.tsx
import { Providers } from './providers'

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html>
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  )
}

Basic Query#

Fetch and cache data with useQuery.

// hooks/useUsers.ts
import { useQuery } from '@tanstack/react-query'

interface User {
  id: string
  name: string
  email: string
}

async function fetchUsers(): Promise<User[]> {
  const response = await fetch('/api/users')
  if (!response.ok) throw new Error('Failed to fetch users')
  return response.json()
}

export function useUsers() {
  return useQuery({
    queryKey: ['users'],
    queryFn: fetchUsers
  })
}

// Usage
function UserList() {
  const { data: users, isLoading, error } = useUsers()

  if (isLoading) return <Skeleton />
  if (error) return <Error message={error.message} />

  return (
    <ul>
      {users?.map(user => (
        <li key={user.id}>{user.name}</li>
      ))}
    </ul>
  )
}

Parameterized Query#

Query with dynamic parameters.

// hooks/useUser.ts
import { useQuery } from '@tanstack/react-query'

async function fetchUser(id: string): Promise<User> {
  const response = await fetch(`/api/users/${id}`)
  if (!response.ok) throw new Error('User not found')
  return response.json()
}

export function useUser(id: string | undefined) {
  return useQuery({
    queryKey: ['users', id],
    queryFn: () => fetchUser(id!),
    enabled: !!id // Only fetch when id exists
  })
}

// With options
export function useUserWithOptions(id: string, options?: { enabled?: boolean }) {
  return useQuery({
    queryKey: ['users', id],
    queryFn: () => fetchUser(id),
    enabled: options?.enabled !== false && !!id,
    staleTime: 5 * 60 * 1000, // 5 minutes
    gcTime: 10 * 60 * 1000 // 10 minutes (formerly cacheTime)
  })
}

Mutations#

Create, update, and delete data.

// hooks/useCreateUser.ts
import { useMutation, useQueryClient } from '@tanstack/react-query'

interface CreateUserData {
  name: string
  email: string
}

async function createUser(data: CreateUserData): Promise<User> {
  const response = await fetch('/api/users', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(data)
  })
  if (!response.ok) throw new Error('Failed to create user')
  return response.json()
}

export function useCreateUser() {
  const queryClient = useQueryClient()

  return useMutation({
    mutationFn: createUser,
    onSuccess: (newUser) => {
      // Invalidate and refetch users list
      queryClient.invalidateQueries({ queryKey: ['users'] })

      // Or optimistically add to cache
      queryClient.setQueryData(['users'], (old: User[] | undefined) =>
        old ? [...old, newUser] : [newUser]
      )
    },
    onError: (error) => {
      console.error('Failed to create user:', error)
    }
  })
}

// Usage
function CreateUserForm() {
  const createUser = useCreateUser()

  const handleSubmit = (data: CreateUserData) => {
    createUser.mutate(data, {
      onSuccess: () => {
        toast.success('User created!')
      }
    })
  }

  return (
    <form onSubmit={handleSubmit}>
      {/* ... */}
      <button disabled={createUser.isPending}>
        {createUser.isPending ? 'Creating...' : 'Create'}
      </button>
    </form>
  )
}

Optimistic Updates#

Update UI immediately before server confirmation.

// hooks/useUpdateUser.ts
import { useMutation, useQueryClient } from '@tanstack/react-query'

export function useUpdateUser() {
  const queryClient = useQueryClient()

  return useMutation({
    mutationFn: updateUser,
    onMutate: async (updatedUser) => {
      // Cancel outgoing refetches
      await queryClient.cancelQueries({ queryKey: ['users', updatedUser.id] })

      // Snapshot previous value
      const previousUser = queryClient.getQueryData(['users', updatedUser.id])

      // Optimistically update
      queryClient.setQueryData(['users', updatedUser.id], updatedUser)

      // Return context with snapshot
      return { previousUser }
    },
    onError: (err, updatedUser, context) => {
      // Rollback on error
      queryClient.setQueryData(
        ['users', updatedUser.id],
        context?.previousUser
      )
    },
    onSettled: (data, error, variables) => {
      // Always refetch to ensure cache is in sync
      queryClient.invalidateQueries({ queryKey: ['users', variables.id] })
    }
  })
}

Infinite Query#

Load paginated data with infinite scroll.

// hooks/usePosts.ts
import { useInfiniteQuery } from '@tanstack/react-query'

interface PostsResponse {
  posts: Post[]
  nextCursor: string | null
}

async function fetchPosts({ pageParam }: { pageParam?: string }): Promise<PostsResponse> {
  const url = pageParam
    ? `/api/posts?cursor=${pageParam}`
    : '/api/posts'

  const response = await fetch(url)
  return response.json()
}

export function useInfinitePosts() {
  return useInfiniteQuery({
    queryKey: ['posts'],
    queryFn: fetchPosts,
    initialPageParam: undefined,
    getNextPageParam: (lastPage) => lastPage.nextCursor
  })
}

// Usage
function PostFeed() {
  const {
    data,
    fetchNextPage,
    hasNextPage,
    isFetchingNextPage
  } = useInfinitePosts()

  return (
    <div>
      {data?.pages.map((page, i) => (
        <Fragment key={i}>
          {page.posts.map(post => (
            <PostCard key={post.id} post={post} />
          ))}
        </Fragment>
      ))}

      <button
        onClick={() => fetchNextPage()}
        disabled={!hasNextPage || isFetchingNextPage}
      >
        {isFetchingNextPage ? 'Loading...' : hasNextPage ? 'Load More' : 'No more posts'}
      </button>
    </div>
  )
}

Prefetching#

Load data before it's needed.

// Prefetch on hover
function UserLink({ userId }: { userId: string }) {
  const queryClient = useQueryClient()

  const prefetchUser = () => {
    queryClient.prefetchQuery({
      queryKey: ['users', userId],
      queryFn: () => fetchUser(userId)
    })
  }

  return (
    <Link href={`/users/${userId}`} onMouseEnter={prefetchUser}>
      View User
    </Link>
  )
}

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

async function UserPage({ params }: { params: { id: string } }) {
  const queryClient = new QueryClient()

  await queryClient.prefetchQuery({
    queryKey: ['users', params.id],
    queryFn: () => fetchUser(params.id)
  })

  return (
    <HydrationBoundary state={dehydrate(queryClient)}>
      <UserProfile userId={params.id} />
    </HydrationBoundary>
  )
}

Best Practices#

Use consistent query keys - Establish naming conventions for cache keys
Set appropriate stale times - Balance freshness vs performance
Handle loading and error states - Always provide feedback
Invalidate strategically - Don't over-invalidate, be specific
Combine with Zustand - Use React Query for server state, Zustand for UI state

Zustand - Client state management
Tables - Data tables with React Query
Forms - Form submission with mutations