## What is the fuss about? Let's be honest here – if you've been writing React apps for more than five minutes, you've probably found yourself in this delightful situation what I call the "I'll just quickly fetch some data" starter pack: ```javascript // 1. A state for the data itself. const [todos, setTodos] = useState([]); // 2. A state to track the initial loading. const [loading, setLoading] = useState(false); // 3. A state to hold any potential errors. const [error, setError] = useState(null); // 4. And maybe even ANOTHER state for subsequent fetches... it gets messy. const [refetching, setRefetching] = useState(false); // 5. The classic data-fetching effect hook. useEffect(() => { // Set loading to true before we start the fetch. setLoading(true); fetch('/api/todos') .then(res => res.json()) .then(data => { // On success, we update our data and stop loading. setTodos(data); setLoading(false); }) .catch(err => { // On failure, we store the error and stop loading. setError(err); setLoading(false); }); // The empty dependency array means this runs only once on mount. }, []); // 6. Now we need a separate function for refetching, often repeating logic. const refetchTodos = () => { setRefetching(true); // ... and we'd have to copy-paste the same fetch logic again 🤦‍♂️ }; ``` While there is nothing inherently anything wrong about this approach, I have to concur that we can do better, way better! This is where Tanstack Query comes to rescue. ## What Exactly Is TanStack Query? Think of TanStack Query as your personal data-fetching butler. It's sophisticated, it handles all the messy details. It's a querying and state management library that takes all the painful parts of data fetching and wraps them up in a neat little package with a bow on top. In the most basic terms, TanStack Query provides hooks that come with: - Reactive state management - Built-in loading states - Error handling that doesn't make you cry - Automatic refetching capabilities - Caching that's so smart, it might be plotting world domination Under the hood, it uses a query client that keeps track of all your queries and automatically caches them, making subsequent requests faster than your morning coffee kicks in. TLDR; it's a querying and state management library that turns this: ```jsx // The old way: Pain and suffering const [data, setData] = useState(null); const [loading, setLoading] = useState(false); const [error, setError] = useState(null); useEffect(() => { // 15 lines of fetch logic... }, [dependency1, dependency2, dependency3]); ``` Into this: ```jsx // The TanStack Query way: Pure bliss const { data, // Our data will be here isLoading, // A boolean for the loading state error // An object for the error state } = useQuery({ // A unique key to identify and cache this query. queryKey: ['todos'], // The function that will fetch the data. It must return a promise. queryFn: fetchTodos }); ``` It's like magic, but the kind that actually works in production. Please be mindful of the word I used: "cached" state management because henceforth we will be managing not the state but the "cached" version of it! ## Let's Begin In this blog, we will be using React and build a simple todo app. If you want to use Nextjs, you can just adjust the setup as stated below, otherwise feel free to skip. For further reading regarding Nextjs and SSR please refer to: [Tanstack query docs](https://tanstack.com/query/latest/docs/framework/react/guides/advanced-ssr "Tanstack query docs") ## Getting Started: The Setup Ritual First things first, let's get this library into your project: ```bash npm install @tanstack/react-query ``` Now, before we can start querying, we need to wrap our app in a query client provider. This is like introducing TanStack Query to your app and saying, "These two need to be friends." ```jsx import { QueryClient, QueryClientProvider } from '@tanstack/react-query'; // 1. Create a new instance of the QueryClient. // It's crucial to create this OUTSIDE the component to prevent it // from being recreated on every re-render. const queryClient = new QueryClient(); function App() { return ( // 2. Wrap your application with the QueryClientProvider. // Pass the client instance you created to the `client` prop. {/* 3. Now, any component inside this provider can use TanStack Query hooks. */} ); } ``` **Pro tip**: Make sure that queryClient lives outside of your React component. We don't want it getting recreated every time React decides to re-render. ## The useQuery Hook: Your New Best Friend The heart and soul of TanStack Query is the useQuery hook. This little beauty is going to replace all those messy combinations of useState, useEffect, and tears. Here's how it works: ```jsx import { useQuery } from '@tanstack/react-query'; // This is our actual data fetching function. // It's just a standard async function that returns a promise. async function fetchTodos() { const response = await fetch('https://jsonplaceholder.typicode.com/todos'); if (!response.ok) { throw new Error('Network response was not ok'); } return response.json(); } function TodoList() { // 1. Call the useQuery hook with a unique key and your fetch function. const { data, isLoading, error } = useQuery({ queryKey: ['todos'], queryFn: fetchTodos, }); // 2. TanStack Query provides a simple boolean for the initial loading state. if (isLoading) { return

Loading your life away...

; } // 3. It also provides a dedicated state for handling errors. if (error) { return

Something went wrong: {error.message}

; } // 4. If not loading and no error, `data` is available and typed! // We use optional chaining `data?.map` as a good practice. return (

{data?.map(todo => (

{todo.title}

))}

); } ``` ## The Anatomy of useQuery Let's break this down: ### Query Key: The Unique Identifier The queryKey is like a name tag for your query. It needs to be unique because that's how TanStack Query knows which query is which. Think of it as the difference between calling your friend "John" and calling your other friend "John from accounting"—specificity matters. If you shout "John" in a room full of Johns, people get confused. This is exactly why we need queryKey, it lets the Tanstack know which data to cache. Do not worry, we will talk about caching, stale and so on in the future. ### Query Function: Where the Magic Happens The queryFn is where you put your actual API call. This is your fetch, axios, or whatever HTTP client you're using to grab your data. ## The Beauty of Built-in State Management Remember the days when you had to manually track loading states, error states, and data states? Those days are over. TanStack Query gives you all of this out of the box: ```jsx const { data, // Your actual data, once successfully fetched. isPending, // The new, recommended state. True if the query has no data and is fetching for the first time. isLoading, // An alias for `isPending`. Kept for backward compatibility. Use this for a full-page skeleton loader. isFetching, // True anytime the query function is running, including background refetches. // Perfect for a subtle loading spinner that doesn't block the UI. isError, // A boolean flag, true if the query encountered an error. error, // The actual error object itself, so you can display a message. refetch, // A function you can call to manually trigger a refetch of the data. } = useQuery({ queryKey: ['todos'], queryFn: fetchTodos, }); ``` Want to add a loading spinner? Use isPending. Want to handle errors gracefully? Use isError and error. Want to refetch data when the user clicks a button? Just call refetch(). It's that simple. ## Parameters and Dynamic Queries Real-world applications rarely deal with static data. You'll often need to pass parameters to your queries. Here's how you handle that: ```jsx async function fetchComments(postId) { const response = await fetch(`https://jsonplaceholder.typicode.com/posts/${postId}/comments`); return response.json(); } function PostComments({ postId }) { const { data: comments, isLoading } = useQuery({ // 1. **CRITICAL**: The query key is now an array that includes the dynamic `postId`. // This tells TanStack Query that `['comments', 1]` is a different query // from `['comments', 2]`, and it will cache them separately. queryKey: ['comments', postId], // 2. The query function is now an anonymous function so we can pass the `postId`. queryFn: () => fetchComments(postId), }); // ... rest of your component } ``` **Critical point**: Always include your parameters in the query key! If you don't, TanStack Query won't be able to differentiate between different parameter combinations, and you'll end up with cached data when you shouldn't. ## Conditional Querying: The "enabled" Option Sometimes you don't want a query to run automatically. Maybe you want to wait for user input, or maybe you need data from another query first. This is where the enabled option comes in handy: ```jsx function UserProfile({ userId }) { // 1. We have a local state to control when the query should be active. const [shouldFetchPosts, setShouldFetchPosts] = useState(false); const { data: posts } = useQuery({ queryKey: ['posts', userId], queryFn: () => fetchUserPosts(userId), // 2. The magic `enabled` option. The query will NOT run as long as this is false. // It will automatically trigger once it becomes true. enabled: shouldFetchPosts, }); return (

{/* 3. A user action, like clicking a button, can change the state and enable the query. */} {/* 4. Render the posts once they are fetched. */} {posts && }

); } ``` ## Modularity! ### Organizing Your Queries: The Query Options Pattern For the past couple of years, I have worked on some big apps, like millions of citizens with hundreds of different fetch requests, mutations and so on. As your app grows, you'll want to keep your query options organized. It will keep you sane, trust me: ```jsx import { queryOptions } from '@tanstack/react-query'; // This is our standard fetch function. async function fetchTodos() { const response = await fetch('https://jsonplaceholder.typicode.com/todos'); return response.json(); } // 1. We create a factory function that returns a pre-configured query object. // The `queryOptions` helper provides type-safety and autocompletion. export function createTodoQueryOptions() { return queryOptions({ // 2. Define the query key here. It's now co-located with its fetching logic. queryKey: ['todos'], // 3. Define the query function. queryFn: fetchTodos, // 4. You can add any other shared options here, like `staleTime` or `gcTime`. // staleTime: 5 * 60 * 1000, // e.g., data is fresh for 5 minutes }); } ``` Now, using this in a component becomes incredibly clean and reusable. ```jsx import { createTodoQueryOptions } from './queries/todoQueries'; function TodoList() { // 1. Simply call our factory function to get the query options. const todoQueryOptions = createTodoQueryOptions(); // 2. Pass the entire options object directly to `useQuery`. // This is clean, reusable, and ensures consistency across your app. const { data, isLoading } = useQuery(todoQueryOptions); // ... rest of your component } ``` This pattern makes your queries reusable across your entire app and keeps things organized. ## TypeScript Integration: Because Types Are Your Friends If you're using TypeScript (and you should be, you beautiful, organized developer), you'll want to add types to your query functions: You can use Zod here, but I will talk about it in the future. ```typescript // 1. Define the shape of a single 'Todo' item. interface Todo { userId: number; id: number; title: string; completed: boolean; } // 2. Type the return value of your fetch function as a Promise that resolves to an array of Todos. async function fetchTodos(): Promise { const response = await fetch('https://jsonplaceholder.typicode.com/todos'); return response.json(); } function MyComponent() { const { data, isLoading } = useQuery({ queryKey: ['todos'], queryFn: fetchTodos, }); // 3. Magic! Because `fetchTodos` returns `Promise`, TypeScript now knows // that `data` is of type `Todo[] | undefined`. You get full autocompletion! data?.forEach(todo => { console.log(todo.title); // Autocomplete for .title, .id, etc. }); } ``` Now your data will be properly typed, and TypeScript will catch any property access errors before they reach production. ## useSuspenseQuery: For the Suspense Lovers If you're using React Suspense (and you should consider it), TanStack Query has you covered with useSuspenseQuery: ```jsx import { Suspense } from 'react'; import { useSuspenseQuery } from '@tanstack/react-query'; function TodoList() { // 1. Use `useSuspenseQuery` instead of `useQuery`. const { data } = useSuspenseQuery({ queryKey: ['todos'], queryFn: fetchTodos }); // 2. **Key difference**: `data` is GUARANTEED to be defined here. // The hook doesn't return `isLoading` or `error` because Suspense handles it. // If the query is loading, the component suspends, and the fallback is shown. // If it errors, the nearest catches it. return (

{data.map(todo => (

{todo.title}

))}

); } // Wrap your component in a Suspense boundary function App() { return ( // 3. The `fallback` prop defines what to render while `TodoList` (or any child) is suspended. Loading with Suspense...}> ); } ``` The key difference is that useSuspenseQuery guarantees that data will never be undefined, making your code cleaner and more predictable. ## Multiple Queries: Because Sometimes You Need More Sometimes you need to run multiple queries in the same component. TanStack Query has a couple of approaches for this: ### Independent Queries with useQueries When you have multiple queries that don't depend on each other: ```jsx function Dashboard() { // 1. `useQueries` takes an object with a `queries` property, which is an array of query options. const results = useQueries({ queries: [ { queryKey: ['todos'], queryFn: fetchTodos }, { queryKey: ['users'], queryFn: fetchUsers }, { queryKey: ['posts'], queryFn: fetchPosts } ] }); // 2. It returns an array of query results, in the same order as the options you provided. const [todosQuery, usersQuery, postsQuery] = results; // 3. Now you can check the status of each query individually and render its data. return (

{todosQuery.isSuccess && } {usersQuery.isSuccess && } {postsQuery.isSuccess && }

); } ``` ### Dependent Queries with Conditional Fetching When one query depends on another: ```jsx function UserPosts({ userId }) { // 1. First, we fetch the user's data. const { data: user } = useQuery({ queryKey: ['user', userId], queryFn: () => fetchUser(userId) }); // 2. Then, we fetch the user's posts. const { data: posts } = useQuery({ queryKey: ['posts', userId], queryFn: () => fetchUserPosts(userId), // 3. This query is only enabled if the `user` object from the first query exists. // `!!user` converts the `user` object (or undefined) to a boolean. // The query will wait until the first one succeeds. enabled: !!user }); return (

{user && } {posts && }

); } ``` ## The Caching Magic: Why Your App Feels Lightning Fast Here's where TanStack Query really shines. Remember how I mentioned it caches your queries? This means: 1. **No duplicate requests**: If two components need the same data, only one request is made 2. **Instant subsequent loads**: Data is served from cache while being refreshed in the background 3. **Smart invalidation**: You can selectively invalidate cached data when needed The caching happens automatically based on your query keys. It's like having a really smart assistant who remembers everything and knows exactly when to refresh information. ## Common Patterns and Best Practices ### 1. Always Include Dynamic Values in Query Keys ```jsx // Good ✅: The query key uniquely identifies this specific data request. // TanStack Query knows that ['posts', 5, 'published'] is different from ['posts', 5, 'draft']. const { data } = useQuery({ queryKey: ['posts', userId, status], queryFn: () => fetchPosts(userId, status) }); // Bad ❌: This will cause problems! // If `userId` or `status` changes, TanStack Query will think it's the same query // because the key is static. It will likely return stale, incorrect cached data. const { data } = useQuery({ queryKey: ['posts'], queryFn: () => fetchPosts(userId, status) }); ``` ### 2. Keep Query Functions Pure ```jsx // Good ✅: This function only fetches and returns data. It's predictable and testable. const fetchTodos = async () => { const response = await fetch('/api/todos'); return response.json(); }; // Questionable ❓: This function has a "side effect." const fetchTodos = async () => { const response = await fetch('/api/todos'); const data = await response.json(); // This is a side effect. It modifies state outside of its own scope. // This makes the function less predictable and harder to reuse. // Use the `onSuccess` callback in `useQuery` for this instead. setGlobalState(data); return data; }; ``` ### 3. Use Suspense Boundaries Wisely ```jsx function App() { return ( // 1. This boundary will catch any suspending components inside it. // 2. It will show a single if the entire suspends, // or if any component inside the dashboard suspends. }> ); } ``` ## Conclusion TanStack Query isn't just a library—it's a paradigm shift. It takes the complexity of data fetching and state management and makes it feel almost... easy? Before I started using it, I was always thinking about managing the state but after using it, it has completely changed the way I perceive data. I am contantly making decisions to how to manage the "cached" state. For the next part of this blog, I will deep-dive into Tanstack Query and explore some more advanced topics like State and Fresh data, Mutations, Infinite Queries, Pagination, Placeholder Data so on and on! Stay tuned! ---

Blog

Understanding JavaScript Callbacks: A Comprehensive Guide

How I Learned to Stop Worrying and Love the Tanstack Query - Part 1