103 lines
4.7 KiB
Markdown
103 lines
4.7 KiB
Markdown
---
|
|
id: overview
|
|
title: Overview
|
|
---
|
|
|
|
TanStack Query (formerly known as React Query) is often described as the missing data-fetching library for web applications, but in more technical terms, it makes **fetching, caching, synchronizing and updating server state** in your web applications a breeze.
|
|
|
|
## Motivation
|
|
|
|
Most core web frameworks **do not** come with an opinionated way of fetching or updating data in a holistic way. Because of this developers end up building either meta-frameworks which encapsulate strict opinions about data-fetching, or they invent their own ways of fetching data. This usually means cobbling together component-based state and side-effects, or using more general purpose state management libraries to store and provide asynchronous data throughout their apps.
|
|
|
|
While most traditional state management libraries are great for working with client state, they are **not so great at working with async or server state**. This is because **server state is totally different**. For starters, server state:
|
|
|
|
- Is persisted remotely in a location you may not control or own
|
|
- Requires asynchronous APIs for fetching and updating
|
|
- Implies shared ownership and can be changed by other people without your knowledge
|
|
- Can potentially become "out of date" in your applications if you're not careful
|
|
|
|
Once you grasp the nature of server state in your application, **even more challenges will arise** as you go, for example:
|
|
|
|
- Caching... (possibly the hardest thing to do in programming)
|
|
- Deduping multiple requests for the same data into a single request
|
|
- Updating "out of date" data in the background
|
|
- Knowing when data is "out of date"
|
|
- Reflecting updates to data as quickly as possible
|
|
- Performance optimizations like pagination and lazy loading data
|
|
- Managing memory and garbage collection of server state
|
|
- Memoizing query results with structural sharing
|
|
|
|
If you're not overwhelmed by that list, then that must mean that you've probably solved all of your server state problems already and deserve an award. However, if you are like a vast majority of people, you either have yet to tackle all or most of these challenges and we're only scratching the surface!
|
|
|
|
TanStack Query is hands down one of the _best_ libraries for managing server state. It works amazingly well **out-of-the-box, with zero-config, and can be customized** to your liking as your application grows.
|
|
|
|
TanStack Query allows you to defeat and overcome the tricky challenges and hurdles of _server state_ and control your app data before it starts to control you.
|
|
|
|
On a more technical note, TanStack Query will likely:
|
|
|
|
- Help you remove **many** lines of complicated and misunderstood code from your application and replace with just a handful of lines of TanStack Query logic
|
|
- Make your application more maintainable and easier to build new features without worrying about wiring up new server state data sources
|
|
- Have a direct impact on your end-users by making your application feel faster and more responsive than ever before
|
|
- Potentially help you save on bandwidth and increase memory performance
|
|
|
|
[//]: # 'Example'
|
|
|
|
## Enough talk, show me some code already!
|
|
|
|
In the example below, you can see TanStack Query in its most basic and simple form being used to fetch the GitHub stats for the TanStack Query GitHub project itself:
|
|
|
|
[Open in StackBlitz](https://stackblitz.com/github/TanStack/query/tree/main/examples/react/simple)
|
|
|
|
```tsx
|
|
import {
|
|
QueryClient,
|
|
QueryClientProvider,
|
|
useQuery,
|
|
} from '@tanstack/react-query'
|
|
|
|
const queryClient = new QueryClient()
|
|
|
|
export default function App() {
|
|
return (
|
|
<QueryClientProvider client={queryClient}>
|
|
<Example />
|
|
</QueryClientProvider>
|
|
)
|
|
}
|
|
|
|
function Example() {
|
|
const { isPending, error, data } = useQuery({
|
|
queryKey: ['repoData'],
|
|
queryFn: () =>
|
|
fetch('https://api.github.com/repos/TanStack/query').then((res) =>
|
|
res.json(),
|
|
),
|
|
})
|
|
|
|
if (isPending) return 'Loading...'
|
|
|
|
if (error) return 'An error has occurred: ' + error.message
|
|
|
|
return (
|
|
<div>
|
|
<h1>{data.name}</h1>
|
|
<p>{data.description}</p>
|
|
<strong>👀 {data.subscribers_count}</strong>{' '}
|
|
<strong>✨ {data.stargazers_count}</strong>{' '}
|
|
<strong>🍴 {data.forks_count}</strong>
|
|
</div>
|
|
)
|
|
}
|
|
```
|
|
|
|
[//]: # 'Example'
|
|
[//]: # 'Materials'
|
|
|
|
## You talked me into it, so what now?
|
|
|
|
- Consider taking the official [TanStack Query Course](https://query.gg?s=tanstack) (or buying it for your whole team!)
|
|
- Learn TanStack Query at your own pace with our amazingly thorough [Walkthrough Guide](./installation.md) and [API Reference](./reference/index.md)
|
|
- See the Article [Why You Want React Query](https://tkdodo.eu/blog/why-you-want-react-query).
|
|
|
|
[//]: # 'Materials'
|