React Query: QueryClient Setup Tips & Mistakes

The Two Approaches

Let's examine two common approaches to initializing QueryClient:

// Approach 1: Using useState
const [queryClient] = useState(() => new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 60 * 1000, // 1 minute
    },
  },
}));

// Approach 2: Direct instantiation
const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 60 * 1000, // 1 minute
    },
  },
});

Why useState Matters

1. Component Lifecycle Management

React components re-render for various reasons: state changes, prop updates, or parent component re-renders. With direct instantiation (Approach 2), each re-render creates a new QueryClient instance. This leads to several problems:

Cache clearing on every re-render
Loss of in-flight queries
Unnecessary network requests
Potential memory leaks

Using useState (Approach 1) ensures the QueryClient instance persists across re-renders, maintaining a stable reference throughout the component's lifecycle.

2. Performance Implications

Creating a new QueryClient instance is not a heavy operation by itself. However, the implications of creating new instances can be significant:

Each new instance maintains its own cache
Previous queries are abandoned
Ongoing background updates are interrupted
Cache invalidation triggers unnecessarily

3. Cache Consistency

React Query's power comes from its intelligent caching mechanism. When you create new QueryClient instances frequently:

Cache becomes ineffective
Stale-while-revalidate patterns break
Background updates might conflict
Optimistic updates could be lost

Best Practices

1. Proper Initialization

function Providers({ children }) {
  const [queryClient] = useState(() => new QueryClient({
    defaultOptions: {
      queries: {
        staleTime: 60 * 1000,
        retry: 2,
        refetchOnWindowFocus: false,
      },
    },
  }));

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

2. Configuration Considerations

When initializing QueryClient, consider:

Setting appropriate staleTime for your use case
Configuring retry behavior
Managing cache lifetime
Setting up default error handling

3. Testing Implications

When writing tests, you might need to reset the QueryClient between tests. With the useState approach, you can:

beforeEach(() => {
  queryClient.clear();
});

Common Pitfalls to Avoid

Creating Multiple Providers: Avoid nesting QueryClientProvider components. Use a single provider at the root level.
Dynamic Configuration: Don't change QueryClient configuration after initialization. Set up defaults that work for most cases.
Missing Error Boundaries: Always wrap your React Query implementation with error boundaries to handle query failures gracefully.

Impact on Real-World Applications

In production applications, proper QueryClient initialization can affect:

User experience through consistent data presentation
Server load by preventing unnecessary requests
Application performance through proper cache utilization
Memory usage patterns
Network bandwidth consumption

Conclusion

While both approaches to initializing QueryClient will work, using useState is clearly the superior choice for production applications. It provides better performance, more predictable behavior, and aligns with React's component lifecycle management.

Remember:

Always use useState for QueryClient initialization
Configure sensible defaults upfront
Maintain a single QueryClient instance per application
Consider the implications for testing and error handling

By following these guidelines, you'll ensure your React Query implementation remains efficient, predictable, and maintainable as your application grows.

Understanding QueryClient Initialization in React Query: Best Practices and Pitfalls

Table of contents