Understanding TanStack Query: The Missing Piece for Modern React Applications | Monir Hossain

Frontend Development

Understanding TanStack Query: The Missing Piece for Modern React Applications

Learn how TanStack Query simplifies data fetching, caching, background synchronization, and server-state management in modern React and Next.js applications. Perfect for developers building scalable web apps.

Written byMonir Hossain

Aug 28, 2026

6 min read

Understanding TanStack Query: The Missing Piece for Modern React Applications

When I first started building React applications, fetching data from APIs felt simple.

A useEffect, a few state variables, and everything worked.

const [users, setUsers] = useState([]);
const [loading, setLoading] = useState(false);
const [error, setError] = useState(null);

useEffect(() => {
  setLoading(true);

  fetch('/api/users')
    .then((res) => res.json())
    .then(setUsers)
    .catch(setError)
    .finally(() => setLoading(false));
}, []);

For a small application, this approach is perfectly reasonable.

But as applications grow, the same problems start appearing everywhere:

Loading states
Error handling
Refetching
Caching
Data synchronization
Duplicate requests
Stale data
Mutation updates

You solve the same problem in one component, then again on another page, and eventually your application becomes full of repetitive API-state logic.

That's when I discovered TanStack Query.

Today, it has become one of my favorite tools for building React and Next.js applications that depend heavily on server data.

In this article, we'll look at what TanStack Query is, why it exists, how server state differs from client state, how caching works, how mutations work, and where TanStack Query fits into modern Next.js applications.

Continue exploring

Related projects

View all projects

BD Geo — Bangladesh Geography API & Console

Explore the implementation, architecture, and technologies behind this project.

Quran Web Application

Explore the implementation, architecture, and technologies behind this project.

Let's build something

Have a project or idea in mind?

Explore my work or get in touch to discuss a web application, backend system, or product idea.

Start a conversation Explore projects

const {
  data,
  isPending,
  error,
} = useQuery({
  queryKey: ['users'],
  queryFn: getUsers,
});

users
loading
error

const [users, setUsers] = useState([]);
const [loading, setLoading] = useState(false);
const [error, setError] = useState(null);

useEffect(() => {
  setLoading(true);

  fetch('/api/users')
    .then((res) => res.json())
    .then(setUsers)
    .catch(setError)
    .finally(() => setLoading(false));
}, []);

Fetch data
      ↓
Store data
      ↓
Show loading state
      ↓
Handle errors
      ↓
Refetch data
      ↓
Cache results
      ↓
Detect stale data
      ↓
Update after mutation

API request
     ↓
Loading state
     ↓
Error state
     ↓
Local data state
     ↓
Refetching
     ↓
Cache logic
     ↓
Synchronization

Admin Product Page
       ↓
Product List
       ↓
Product Details
       ↓
Search Results
       ↓
Dashboard

const isSidebarOpen = useUiStore(
  (state) => state.isSidebarOpen
);

                    Server
                       |
                       v
                  Product Data
                       |
         +-------------+-------------+
         |             |             |
         v             v             v
      Browser A     Browser B      Admin

"How do I fetch this API?"

"What server data does this screen need,
and how should that data be cached and synchronized?"

Users Query
     |
     +--- Fetch
     +--- Cache
     +--- Track freshness
     +--- Refetch
     +--- Update
     +--- Invalidate

async function getUsers() {
  const response = await fetch('/api/users');

  if (!response.ok) {
    throw new Error('Failed to fetch users');
  }

  return response.json();
}

const {
  data,
  isPending,
  error,
} = useQuery({
  queryKey: ['users'],
  queryFn: getUsers,
});

useQuery()
    |
    +---- data
    +---- loading state
    +---- error state
    +---- cache
    +---- refetching
    +---- synchronization

queryKey: ['users']

queryKey: ['users', userId]

queryKey: [
  'products',
  {
    category: 'shirts',
    page: 1,
  },
]

['users']
      ↓
Users collection

['users', 42]
      ↓
User #42

['products', { category: 'shirts', page: 1 }]
      ↓
Filtered product list

Products Page
      |
      v
API Request
      |
      v
Server Data
      |
      v
Query Cache

Products Page
      |
      v
Query Cache
      |
      +---- Cached data available
      |
      v
UI

Cached Data
     |
     +---- Display immediately
     |
     +---- Background request
                  |
                  v
             Fresh data
                  |
                  v
              Update UI

staleTime: 60 * 1000

gcTime: 10 * 60 * 1000

staleTime
    ↓
How long is this data considered fresh?

gcTime
    ↓
How long can unused cached data remain in memory?

useQuery({
  queryKey: ['products'],
  queryFn: getProducts,
  staleTime: 60 * 1000,
  gcTime: 10 * 60 * 1000,
});

0 min
  |
  |------ Fresh ------|
  |      1 minute      |
  |
  |------ Stale --------------------------|
         Cache can still exist
  |
  |-----------------------|
                         10 min
                         Potential GC

const mutation = useMutation({
  mutationFn: createUser,
});

mutation.mutate({
  name: 'Monir',
  email: 'monir@example.com',
});

Pending
Success
Error

Create User
     |
     v
API
     |
     v
Success

queryClient.invalidateQueries({
  queryKey: ['users'],
});

Create User
     |
     v
Mutation Success
     |
     v
Invalidate ['users']
     |
     v
Users Query Becomes Stale
     |
     v
Refetch When Appropriate
     |
     v
Fresh User List

Server Mutation
      |
      v
Success
      |
      +---- Invalidate query
      |
      +---- Update cache directly

const [loading, setLoading] = useState(false);
const [error, setError] = useState(null);
const [users, setUsers] = useState([]);

const {
  data,
  isPending,
  error,
} = useQuery({
  queryKey: ['users'],
  queryFn: getUsers,
});

if (isPending) {
  return <UsersSkeleton />;
}

if (error) {
  return <ErrorMessage />;
}

return <UsersList users={data} />;

async function ProductsPage() {
  const response = await fetch(
    'https://example.com/api/products',
  );

  const products = await response.json();

  return <ProductList products={products} />;
}

Admin Dashboard
       |
       +---- Users Query
       +---- Orders Query
       +---- Analytics Query
       +---- Notifications Query
       +---- Products Query

                    Next.js App
                         |
          +--------------+--------------+
          |                             |
          v                             v
   Server-side data              Client-side data
          |                             |
          v                             v
    Next.js fetching              TanStack Query
          |                             |
          v                             v
   SEO / initial page          Interactive UI

loading
error
data
refetch
cache

Static website
      |
      v
Next.js

Theme
Sidebar
Modal
UI preferences
Temporary state

Users
Products
Orders
Notifications
Analytics

React Application
       |
       +-------------------+
       |                   |
       v                   v
   Zustand            TanStack Query
       |                   |
  Client State         Server State

src/
├── components/
├── features/
│   ├── users/
│   ├── products/
│   └── orders/
│
├── lib/
│   ├── api/
│   └── query-client/
│
├── stores/
│   └── ui-store.ts
│
└── app/

UI
 |
 +---- Zustand
 |       |
 |       +---- Client State
 |
 +---- TanStack Query
         |
         +---- Server State
                |
                +---- API

API
 ↓
useEffect
 ↓
useState
 ↓
UI

API
 ↓
Query
 ↓
Cache
 ↓
Synchronization
 ↓
UI

fetch('/api/users');

Related projects

BD Geo — Bangladesh Geography API & Console

Quran Web Application

Have a project or idea in mind?

2. Why Was TanStack Query Created?

3. The Problem It Solves

4. Understanding Server State

Client State

5. Server State

6. TanStack Query's Mental Model

7. Fetching Data With TanStack Query

8. Query Keys

9. Automatic Caching

10. Stale Data and Background Refetching

11. Understanding staleTime

12. Understanding gcTime

Simple Example

13. Mutations: Creating, Updating, and Deleting Data

14. Keeping Related Data in Sync

15. Invalidation vs Manual Cache Updates

16. Automatic Refetching

17. Loading and Error States

18. TanStack Query With Next.js

19. When Next.js Native Fetching May Be Enough

20. When TanStack Query Becomes More Valuable

21. A Hybrid Next.js Architecture

Server-side

Client-side

22. Advantages of TanStack Query

Cleaner Code

Automatic Caching

Data Synchronization

Mutation Management

Better Developer Experience

23. Potential Drawbacks

Learning Curve

Overkill for Small Applications

Additional Dependency

24. TanStack Query vs Zustand

Zustand

TanStack Query

25. A Practical Architecture

26. The Bigger Picture

Conclusion

Monir Hossain

Ayra

11. Understanding `staleTime`

12. Understanding `gcTime`