Optimizing Your React Query Performance with TanStack Config

Anton Ioffe - April 7th 2024 - 10 minutes read

In the dynamic realm of modern web development, optimizing data fetching and state management represents a battleground where performance often dictates the user experience. This article peels back the layers of React Query, revealing how the strategic application of TanStack Config can transform your approach to managing server-state in React applications. From the nuanced control of render triggers to the automatic finesse of tracked queries, and the clever utilization of structural sharing and selectors, we dive deep into advanced techniques and common pitfalls. Armed with real-world code examples and best practices, you're on the brink of mastering how to fine-tune your React Query setups for noteworthy performance gains. Whether you're looking to reduce unnecessary re-renders or streamline your data fetching strategies, this guide promises to equip you with the insights needed to elevate your applications to the next level.

Understanding the Core of React Query and TanStack Config

React Query, often heralded as the missing piece for fetching, caching, and managing server state in web applications, simplifies complex state management that previously depended on libraries like Redux. This simplification comes by automating the process of fetching, caching, and updating data without the need for verbose code, enabling developers to focus more on building out the UI rather than managing state. At its core, React Query provides hooks such as useQuery and useMutation which handle the data fetching and synchronization with the server state, significantly reducing the potential for errors and boilerplate code.

The introduction of TanStack Config into React Query elevates this simplification by offering advanced configuration options that afford developers granular control over query behaviors and caching strategies. This aspect of TanStack Query enables performance optimization at a level previously unattainable with React Query alone. Through TanStack Config, developers can tailor the behavior of queries and mutations to fit the specific needs of their application, optimizing both the speed and efficiency with which data is fetched, cached, and updated.

One of the key benefits of using TanStack Config with React Query is the ability to customize caching mechanisms to suit specific application needs. By fine-tuning how data is cached, applications can reduce redundant network requests, thereby saving on precious bandwidth and improving user experience through faster load times. Caching strategies can range from simple time-based invalidation to complex custom logic that determines when and how data should be refetched from the server.

Additionally, TanStack Config allows for the adjustment of query refetching behaviors, providing the ability to specify exactly how and when data should be synchronized with the server. This includes configuring queries to refetch on window focus, network reconnect, or at specific intervals, ensuring that the application data remains fresh without manual intervention. This level of control is particularly useful in applications where data changes frequently and needs to be kept up-to-date in real-time.

Lastly, the utilization of TanStack Config in conjunction with React Query facilitates the optimization of application performance by minimizing unnecessary renders and reducing memory usage. Through precise configuration, developers can ensure that components only re-render when absolutely necessary, and that stale data is efficiently cleared from the cache, freeing up memory. This attention to detail in configuration results in a smoother, more responsive application, providing an enhanced user experience.

Delving into notifyOnChangeProps for Render Optimization

One of React Query's standout features for performance optimization is notifyOnChangeProps, which empowers developers to tailor component re-renders more precisely in response to specific query state changes. The traditional approach without this feature often leads to excess re-renders because every state update, whether relevant to the displayed content or not, triggers a component update. By defining notifyOnChangeProps, developers can specify an array of properties (e.g., ['data', 'error']) that, when changed, should cause a rerender. This selective update mechanism notably conserves resources by avoiding unnecessary render cycles, improving application efficiency without compromising responsiveness.

To implement this optimization, consider a scenario where a component displays data returned from a query and also shows a loading indicator while fetching. Without notifyOnChangeProps, changes in fetch status or error information would unnecessarily cause the component to rerender, even if such information isn't used in the UI. By setting notifyOnChangeProps to ['data'], React Query is instructed to trigger a rerender only when the fetched data changes. This finer control over re-renders enhances performance, especially in complex components or applications with numerous simultaneous queries.

export const useTodosQuery = (select, notifyOnChangeProps) => 
        queryKey: ['todos'],
        queryFn: fetchTodos,

In the code snippet above, notifyOnChangeProps is set to focus only on changes to the data property. This setup ensures that components consuming this query do not unnecessarily rerender due to irrelevant query state updates, like isFetching flag flips. As a result, users experience smoother interactions as the UI updates more efficiently, reflecting only meaningful changes.

Moreover, setting notifyOnChangeProps to 'tracked' enables a dynamic optimization strategy where React Query automatically tracks which query properties the component actually uses during render. This auto-tracking alleviates the developer's burden of manually listing properties, ensuring the component rerenders only when relevant observed properties change. This smart tracking further streamlines component updates, enhancing performance without adding extra complexity to the development process.

In summary, notifyOnChangeProps presents a vital tool in the optimization toolkit provided by React Query. By facilitating more granular control over component re-renders based on query state changes, it helps prevent unnecessary updates, thereby boosting application performance. This feature, combined with a thoughtful implementation strategy, enables developers to create responsive, efficient web applications that scale well and provide a smooth user experience.

Leveraging Tracked Queries for Intuitive Performance Gains

In the realm of modern web development, React Query's tracked queries feature stands out as a powerful tool for optimizing performance through intuitive re-render strategies. By monitoring the specific query data utilized in a component and limiting re-renders to only when that data changes, this feature introduces an unprecedented level of efficiency. Developers can enable tracked queries either globally or on a per-query basis using TanStack Config, ensuring that their applications benefit from reduced unnecessary re-renders and, consequently, smooth and fast user experiences.

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      notifyOnChangeProps: 'tracked',

Deploying tracked queries across an application requires a thoughtful approach to balance automatic tracking with the need for explicit control. While the automatic aspect significantly reduces the burden of manually specifying which query data changes should trigger re-renders, it's crucial for developers to remain cautious of potential overheads. For instance, automatic tracking inherently involves some computational cost, albeit minor, that comes with monitoring data usage patterns. Therefore, understanding the trade-offs between automatic tracking and explicit management plays a pivotal role in harnessing tracked queries effectively.

A common mistake when leveraging tracked queries is the indiscriminate tracking of all query fields, particularly through the unintended use of object rest destructuring. This approach can lead to excessive tracking and, by extension, unnecessary re-renders whenever any piece of the query data changes, negating the performance optimizations sought through tracked queries.

// Correct usage avoiding tracking all fields
const { data } = useQuery(...);
// Incorrect usage that leads to tracking all fields
const { isLoading, ...queryInfo } = useQuery(...);

To navigate this, developers should employ destructuring judiciously, focusing on extracting only the specific pieces of data that are genuinely needed for rendering. This disciplined approach ensures that the application leverages tracked queries' efficiency without falling into common pitfalls that could inadvertently degrade performance.

In conclusion, tracked queries offered by React Query and configured via TanStack present a significant opportunity for developers to enhance application performance through intelligent re-render optimizations. By carefully balancing the benefits of automatic tracking with the nuances of explicit control and staying mindful of common mistakes, developers can achieve substantial performance gains. This empowers them to build highly responsive, efficient, and user-friendly web applications that stand the test of time in the ever-evolving landscape of web development.

Structural Sharing and Selectors: A Deep Dive

React Query's innovative approach to data synchronization and performance optimization centres around the concept of structural sharing. This technique ensures that data retains its referential integrity across component re-renders, essentially meaning that unchanged data between re-renders maintains the same memory reference. This is particularly beneficial when dealing with large datasets or complex data structures, as it minimizes the unnecessary creation of new references, consequently reducing memory footprint and enhancing performance. Structural sharing operates on the principle that if a data object hasn't changed since the last render, its memory reference should remain the same. This optimization cleverly leverages JavaScript's innate handling of object and array references, thus leading to more efficient memory usage and quicker component updates.

To further illustrate, consider a scenario where data fetched from the network undergoes JSON parsing, typically resulting in a completely new object reference. React Query, however, compares this newly fetched data with the existing data, retaining references for any unchanged segments. This mechanism is immensely advantageous for preserving the unchanged parts of your application's state, particularly in scenarios involving deeply nested data structures. It means that components relying on unchanged data do not needlessly re-render, which significantly improves the application's responsiveness and performance.

Selectors play an integral role in conjunction with structural sharing by providing a way to derive or transform data without negating the performance gains achieved through structural sharing. By using selectors, developers can apply transformations or filters to query data, preparing it for rendering or further processing. For example, a selector could extract a subset of an array or reshape an object's structure to make it more conducive to display. The beauty of selectors within React Query lies in their ability to implement these transformations while still preserving the underlying optimization of structural sharing. They ensure that the transformation logic does not inadvertently force re-renders through the creation of new references to unchanged data.

Here's a concrete example demonstrating how to utilize selectors with React Query to achieve data transformation without compromising on performance:

const { data: todos } = useQuery(['todos'], fetchTodos, {
  select: data => data.map(todo => ({ ...todo, isChecked: todo.status === 'done' })),

In the above snippet, useQuery fetches a list of todos, and the select option is used to transform the fetched data. Each todo item is augmented with an isChecked property derived from its status. Importantly, this transformation respects structural sharing for any data that remains unchanged, ensuring that React Query's performance optimization is not impaired.

A common mistake, however, is neglecting the impact of selectors on structural sharing. An improperly used selector that returns a new reference every time, even if the input data hasn't changed, undermines the optimization gains. Thus, it is crucial to design selectors that are mindful of structural sharing - they should only return new references when the input data genuinely changes. Here's a corrected approach:

const { data: todos } = useQuery(['todos'], fetchTodos, {
  select: data => data.map(todo => todo.status === 'done' ? { ...todo, isChecked: true } : todo),

This adjusted selector mitigates unnecessary reference changes by only generating a new object when a todo's status is done, otherwise returning the original todo. Such cautious application of selectors ensures that React Query's structural sharing can operate effectively, maintaining the application's performance and responsiveness.

In essence, the interplay between structural sharing and selectors within React Query exemplifies a sophisticated approach to state management and performance optimization in modern web development. It highlights the importance of understanding the underlying mechanisms to leverage these features effectively, ensuring that data integrity and application efficiency are upheld. This deep dive should prompt developers to consider: How can we further optimize data handling in our projects through strategic use of structural sharing and selectors?

Common Pitfalls and Best Practices in React Query Optimization

Common pitfalls in integrating React Query often revolve around over-fetching data, improper design of query keys, and mishandling cache settings, inadvertently leading to reduced application performance. For instance, over-fetching data occurs when developers subscribe to more data updates than necessary. The incorrect approach might look like using a broad query that fetches large datasets for displaying only a small fraction of that data. The optimized counterpart involves utilizing specific query keys and leveraging the select option to fetch and render only the needed data.

// Less optimized code
const { data } = useQuery('largeDataset', fetchLargeDataset);

// Optimized with select
const { data } = useQuery('largeDataset', fetchLargeDataset, {
  select: data => data.slice(0, 10) // fetching only the needed portion

Another common mistake is the improper design of query keys, which directly impacts the efficiency of caching and re-fetching strategies. A poorly structured query key, such as using unspecific or constantly changing values, can lead to cache misses and unnecessary re-fetches. A well-thought-out query key structure that reflects the uniqueness and hierarchy of the data can drastically improve cache hits and application performance.

// Non-optimal query key usage
const { data } = useQuery([userId, 'profile'], fetchUserProfile);

// More effectively structured query keys
const { data } = useQuery(['user', userId, 'profile'], fetchUserProfile);

Mismanagement of cache settings is another area where developers often stumble, either by setting overly aggressive cache time, leading to stale data, or by setting it too short, causing frequent re-fetches. Fine-tuning the cache times based on the actual data lifecycle and usage patterns ensures that the application strikes the right balance between data freshness and minimizing network requests.

React Query offers a powerful toolkit for handling server state, but it also demands a strategic approach to leverage its full potential. It's vital to continuously reflect on and adapt data fetching strategies, query key design, and cache management practices to the evolving needs of your application.

To conclude, React Query, when integrated with mindfulness towards data specificity, query key granularity, and cache policy optimization, stands as a robust solution for enhancing the performance and scalability of React applications. Developers are encouraged to explore the capabilities of TanStack Config within React Query to tailor their applications' data management practices, pushing the boundaries of what's achievable in modern web development.


This article explores how to optimize your React Query performance using TanStack Config. It delves into the benefits of using TanStack Config for customizing caching mechanisms, adjusting query refetching behaviors, and optimizing rendering and memory usage. Key takeaways include the importance of using notifyOnChangeProps for precise render optimization, leveraging tracked queries for intuitive performance gains, understanding structural sharing and selectors for efficient data handling, and avoiding common pitfalls in React Query optimization. A challenging task for readers is to implement and fine-tune caching strategies based on the specific needs of their applications, ensuring a balance between data freshness and minimizing network requests.

Don't Get Left Behind:
The Top 5 Career-Ending Mistakes Software Developers Make
FREE Cheat Sheet for Software Developers