Open History to see the last commit
1---
2id: request-waterfalls
3title: Performance & Request Waterfalls
4---
5β
6Application performance is a broad and complex area and while React Query can't make your APIs faster, there are still things to be mindful about in how you use React Query to ensure the best performance.
7β
8The biggest performance footgun when using React Query, or indeed any data fetching library that lets you fetch data inside of components, is request waterfalls. The rest of this page will explain what they are, how you can spot them and how you can restructure your application or APIs to avoid them.
9β
10The [Prefetching & Router Integration guide](./prefetching.md) builds on this and teaches you how to prefetch data ahead of time when it's not possible or feasible to restructure your application or APIs.
11β
12The [Server Rendering & Hydration guide](./ssr.md) teaches you how to prefetch data on the server and pass that data down to the client so you don't have to fetch it again.
13β
14The [Advanced Server Rendering guide](./advanced-ssr.md) further teaches you how to apply these patterns to Server Components and Streaming Server Rendering.
15β
16## What is a Request Waterfall?
17β
18A request waterfall is what happens when a request for a resource (code, css, images, data) does not start until _after_ another request for a resource has finished.
19β
20Consider a web page. Before you can load things like the CSS, JS etc, the browser first needs to load the markup. This is a request waterfall.
21β
22```
231. |-> Markup
242. |-> CSS
252. |-> JS
262. |-> Image
27```
28β
29If you fetch your CSS inside a JS file, you now have a double waterfall:
30β
31```
321. |-> Markup
332. |-> JS
343. |-> CSS
35```
36β
37If that CSS uses a background image, it's a triple waterfall:
38β
39```
401. |-> Markup
412. |-> JS
423. |-> CSS
434. |-> Image
44```
45β
46The best way to spot and analyze your request waterfalls is usually by opening your browsers devtools "Network" tab.
47β
48Each waterfall represents at least one roundtrip to the server, unless the resource is locally cached (in practice, some of these waterfalls might represent more than one roundtrip because the browser needs to establish a connection which requires some back and forth, but let's ignore that here). Because of this, the negative effects of request waterfalls are highly dependent on the users latency. Consider the example of the triple waterfall, which actually represents 4 server roundtrips. With 250ms latency, which is not uncommon on 3g networks or in bad network conditions, we end up with a total time of 4\*250=1000ms **only counting latency**. If we were able to flatten that to the first example with only 2 roundtrips, we get 500ms instead, possibly loading that background image in half the time!
49β
50## Request Waterfalls & React Query
51β
52Now let's consider React Query. We'll focus on the case without Server Rendering first. Before we can even start making a query, we need to load the JS, so before we can show that data on the screen, we have a double waterfall:
53β
54```
551. |-> Markup
562. |-> JS
573. |-> Query
58```
59β
60With this as a basis, let's look at a few different patterns that can lead to Request Waterfalls in React Query, and how to avoid them.
61β
62- Single Component Waterfalls / Serial Queries
63- Nested Component Waterfalls
64- Code Splitting
65β
66### Single Component Waterfalls / Serial Queries
67β
68When a single component first fetches one query, and then another, that's a request waterfall. This can happen when the second query is a [Dependent Query](./dependent-queries.md), that is, it depends on data from the first query when fetching:
69β
70```tsx
71// Get the user
72const { data: user } = useQuery({
73 queryKey: ['user', email],
74 queryFn: getUserByEmail,
75})
76β
77const userId = user?.id
78β
79// Then get the user's projects
80const {
81 status,
82 fetchStatus,
83 data: projects,
84} = useQuery({
85 queryKey: ['projects', userId],
86 queryFn: getProjectsByUser,
87 // The query will not execute until the userId exists
88 enabled: !!userId,
89})
90```
91β
92While not always feasible, for optimal performance it's better to restructure your API so you can fetch both of these in a single query. In the example above, instead of first fetching `getUserByEmail` to be able to `getProjectsByUser`, introducing a new `getProjectsByUserEmail` query would flatten the waterfall.
93β
94> Another way to mitigate dependent queries without restructuring your API is to move the waterfall to the server where latency is lower. This is the idea behind Server Components which are covered in the [Advanced Server Rendering guide](./advanced-ssr.md).
95β
96Another example of serial queries is when you use React Query with Suspense:
97β
98```tsx
99function App () {
100 // The following queries will execute in serial, causing separate roundtrips to the server:
101 const usersQuery = useSuspenseQuery({ queryKey: ['users'], queryFn: fetchUsers })
102 const teamsQuery = useSuspenseQuery({ queryKey: ['teams'], queryFn: fetchTeams })
103 const projectsQuery = useSuspenseQuery({ queryKey: ['projects'], queryFn: fetchProjects })
104β
105 // Note that since the queries above suspend rendering, no data
106 // gets rendered until all of the queries finished
107 ...
108}
109```
110β
111Note that with regular `useQuery` these would happen in parallel.
112β
113Luckily, this is easy to fix, by always using the hook `useSuspenseQueries` when you have multiple suspenseful queries in a component.
114β
115```tsx
116const [usersQuery, teamsQuery, projectsQuery] = useSuspenseQueries({
117 queries: [
118 { queryKey: ['users'], queryFn: fetchUsers },
119 { queryKey: ['teams'], queryFn: fetchTeams },
120 { queryKey: ['projects'], queryFn: fetchProjects },
121 ],
122})
123```
124β
125### Nested Component Waterfalls
126β
127Nested Component Waterfalls is when both a parent and a child component contains queries, and the parent does not render the child until its query is done. This can happen both with `useQuery` and `useSuspenseQuery`.
128β
129If the child renders conditionally based on the data in the parent, or if the child relies on some part of the result being passed down as a prop from the parent to make its query, we have a _dependent_ nested component waterfall.
130β
131Let's first look at an example where the child is **not** dependent on the parent.
132β
133```tsx
134function Article({ id }) {
135 const { data: articleData, isPending } = useQuery({
136 queryKey: ['article', id],
137 queryFn: getArticleById,
138 })
139β
140 if (isPending) {
141 return 'Loading article...'
142 }
143β
144 return (
145 <>
146 <ArticleHeader articleData={articleData} />
147 <ArticleBody articleData={articleData} />
148 <Comments id={id} />
149 </>
150 )
151β
152}
153β
154function Comments({ id }) {
155 const { data, isPending } = useQuery({
156 queryKey: ['article-comments', id],
157 queryFn: getArticleCommentsById,
158 })
159β
160 ...
161}
162```
163β
164Note that while `<Comments>` takes a prop `id` from the parent, that id is already available when the `<Article>` renders so there is no reason we could not fetch the comments at the same time as the article. In real world applications, the child might be nested far below the parent and these kinds of waterfalls are often trickier to spot and fix, but for our example, one way to flatten the waterfall would be to hoist the comments query to the parent instead:
165β
166```tsx
167function Article({ id }) {
168 const { data: articleData, isPending: articlePending } = useQuery({
169 queryKey: ['article', id],
170 queryFn: getArticleById,
171 })
172β
173 const { data: commentsData, isPending: commentsPending } = useQuery({
174 queryKey: ['article-comments', id],
175 queryFn: getArticleCommentsById,
176 })
177β
178 if (articlePending) {
179 return 'Loading article...'
180 }
181β
182 return (
183 <>
184 <ArticleHeader articleData={articleData} />
185 <ArticleBody articleData={articleData} />
186 {commentsPending ? (
187 'Loading comments...'
188 ) : (
189 <Comments commentsData={commentsData} />
190 )}
191 </>
192 )
193}
194```
195β
196The two queries will now fetch in parallel. Note that if you are using suspense, you'd want to combine these two queries into a single `useSuspenseQueries` instead.
197β
198Another way to flatten this waterfall would be to prefetch the comments in the `<Article>` component, or prefetch both of these queries at the router level on page load or page navigation, read more about this in the [Prefetching & Router Integration guide](./prefetching.md).
199β
200Next, let's look at a _Dependent Nested Component Waterfall_.
201β
202```tsx
203function Feed() {
204 const { data, isPending } = useQuery({
205 queryKey: ['feed'],
206 queryFn: getFeed,
207 })
208β
209 if (isPending) {
210 return 'Loading feed...'
211 }
212β
213 return (
214 <>
215 {data.map((feedItem) => {
216 if (feedItem.type === 'GRAPH') {
217 return <GraphFeedItem key={feedItem.id} feedItem={feedItem} />
218 }
219β
220 return <StandardFeedItem key={feedItem.id} feedItem={feedItem} />
221 })}
222 </>
223 )
224}
225β
226function GraphFeedItem({ feedItem }) {
227 const { data, isPending } = useQuery({
228 queryKey: ['graph', feedItem.id],
229 queryFn: getGraphDataById,
230 })
231β
232 ...
233}
234```
235β
236The second query `getGraphDataById` is dependent on it's parent in two different ways. First of all, it doesn't ever happen unless the `feedItem` is a graph, and second, it needs an `id` from the parent.
237β
238```
2391. |> getFeed()
2402. |> getGraphDataById()
241```
242β
243In this example, we can't trivially flatten the waterfall by just hoisting the query to the parent, or even adding prefetching. Just like the dependent query example at the beginning of this guide, one option is to refactor our API to include the graph data in the `getFeed` query. Another more advanced solution is to leverage Server Components to move the waterfall to the server where latency is lower (read more about this in the [Advanced Server Rendering guide](./advanced-ssr.md)) but note that this can be a very big architectural change.
244β
245You can have good performance even with a few query waterfalls here and there, just know they are a common performance concern and be mindful about them. An especially insidious version is when Code Splitting is involved, let's take a look at this next.
246β
247### Code Splitting
248β
249Splitting an applications JS-code into smaller chunks and only loading the necessary parts is usually a critical step in achieving good performance. It does have a downside however, in that it often introduces request waterfalls. When that code split code also has a query inside it, this problem is worsened further.
250β
251Consider this a slightly modified version of the Feed example.
252β
253```tsx
254// This lazy loads the GraphFeedItem component, meaning
255// it wont start loading until something renders it
256const GraphFeedItem = React.lazy(() => import('./GraphFeedItem'))
257β
258function Feed() {
259 const { data, isPending } = useQuery({
260 queryKey: ['feed'],
261 queryFn: getFeed,
262 })
263β
264 if (isPending) {
265 return 'Loading feed...'
266 }
267β
268 return (
269 <>
270 {data.map((feedItem) => {
271 if (feedItem.type === 'GRAPH') {
272 return <GraphFeedItem key={feedItem.id} feedItem={feedItem} />
273 }
274β
275 return <StandardFeedItem key={feedItem.id} feedItem={feedItem} />
276 })}
277 </>
278 )
279}
280β
281// GraphFeedItem.tsx
282function GraphFeedItem({ feedItem }) {
283 const { data, isPending } = useQuery({
284 queryKey: ['graph', feedItem.id],
285 queryFn: getGraphDataById,
286 })
287β
288 ...
289}
290```
291β
292This example has a double waterfall, looking like this:
293β
294```
2951. |> getFeed()
2962. |> JS for <GraphFeedItem>
2973. |> getGraphDataById()
298```
299β
300But that's just looking at the code from the example, if we consider what the first page load of this page looks like, we actually have to complete 5 round trips to the server before we can render the graph!
301β
302```
3031. |> Markup
3042. |> JS for <Feed>
3053. |> getFeed()
3064. |> JS for <GraphFeedItem>
3075. |> getGraphDataById()
308```
309β
310Note that this looks a bit different when server rendering, we will explore that further in the [Server Rendering & Hydration guide](../ssr). Also note that it's not uncommon for the route that contains `<Feed>` to also be code split, which could add yet another hop.
311β
312In the code split case, it might actually help to hoist the `getGraphDataById` query to the `<Feed>` component and make it conditional, or add a conditional prefetch. That query could then be fetched in parallel with the code, turning the example part into this:
313β
314```
3151. |> getFeed()
3162. |> getGraphDataById()
3172. |> JS for <GraphFeedItem>
318```
319β
320This is very much a tradeoff however. You are now including the data fetching code for `getGraphDataById` in the same bundle as `<Feed>`, so evaluate what is best for your case. Read more about how to do this in the [Prefetching & Router Integration guide](../prefetching).
321β
322> The tradeoff between:
323>
324> - Include all data fetching code in the main bundle, even if we seldom use it
325> - Put the data fetching code in the code split bundle, but with a request waterfall
326>
327> is not great and has been one of the motivations for Server Components. With Server Components, it's possible to avoid both, read more about how this applies to React Query in the [Advanced Server Rendering guide](../advanced-ssr).
328β
329## Summary and takeaways
330β
331Request Waterfalls are a very common and complex performance concern with many tradeoffs. There are many ways to accidentally introduce them into your application:
332β
333- Adding a query to a child, not realizing a parent already has a query
334- Adding a query to a parent, not realizing a child already has a query
335- Moving a component with descendants that has a query to a new parent with an ancestor that has a query
336- Etc..
337β
338Because of this accidental complexity, it pays off to be mindful of waterfalls and regularly examine your application looking for them (a good way is to examine the Network tab every now and then!). You don't necessarily have to flatten them all to have good performance, but keep an eye out for the high impact ones.
339β
340In the next guide, we'll look at more ways to flatten waterfalls, by leveraging [Prefetching & Router Integration](./prefetching.md).