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β
14[//]: # 'AdvancedSSRLink'
15β
16The [Advanced Server Rendering guide](./advanced-ssr.md) further teaches you how to apply these patterns to Server Components and Streaming Server Rendering.
17β
18[//]: # 'AdvancedSSRLink'
19β
20## What is a Request Waterfall?
21β
22A 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.
23β
24Consider 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.
25β
26```
271. |-> Markup
282. |-> CSS
292. |-> JS
302. |-> Image
31```
32β
33If you fetch your CSS inside a JS file, you now have a double waterfall:
34β
35```
361. |-> Markup
372. |-> JS
383. |-> CSS
39```
40β
41If that CSS uses a background image, it's a triple waterfall:
42β
43```
441. |-> Markup
452. |-> JS
463. |-> CSS
474. |-> Image
48```
49β
50The best way to spot and analyze your request waterfalls is usually by opening your browsers devtools "Network" tab.
51β
52Each 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!
53β
54## Request Waterfalls & React Query
55β
56Now 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:
57β
58```
591. |-> Markup
602. |-> JS
613. |-> Query
62```
63β
64With 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.
65β
66- Single Component Waterfalls / Serial Queries
67- Nested Component Waterfalls
68- Code Splitting
69β
70### Single Component Waterfalls / Serial Queries
71β
72When 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:
73β
74[//]: # 'DependentExample'
75β
76```tsx
77// Get the user
78const { data: user } = useQuery({
79 queryKey: ['user', email],
80 queryFn: getUserByEmail,
81})
82β
83const userId = user?.id
84β
85// Then get the user's projects
86const {
87 status,
88 fetchStatus,
89 data: projects,
90} = useQuery({
91 queryKey: ['projects', userId],
92 queryFn: getProjectsByUser,
93 // The query will not execute until the userId exists
94 enabled: !!userId,
95})
96```
97β
98[//]: # 'DependentExample'
99β
100While 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.
101β
102[//]: # 'ServerComponentsNote1'
103β
104> 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).
105β
106[//]: # 'ServerComponentsNote1'
107[//]: # 'SuspenseSerial'
108β
109Another example of serial queries is when you use React Query with Suspense:
110β
111```tsx
112function App () {
113 // The following queries will execute in serial, causing separate roundtrips to the server:
114 const usersQuery = useSuspenseQuery({ queryKey: ['users'], queryFn: fetchUsers })
115 const teamsQuery = useSuspenseQuery({ queryKey: ['teams'], queryFn: fetchTeams })
116 const projectsQuery = useSuspenseQuery({ queryKey: ['projects'], queryFn: fetchProjects })
117β
118 // Note that since the queries above suspend rendering, no data
119 // gets rendered until all of the queries finished
120 ...
121}
122```
123β
124Note that with regular `useQuery` these would happen in parallel.
125β
126Luckily, this is easy to fix, by always using the hook `useSuspenseQueries` when you have multiple suspenseful queries in a component.
127β
128```tsx
129const [usersQuery, teamsQuery, projectsQuery] = useSuspenseQueries({
130 queries: [
131 { queryKey: ['users'], queryFn: fetchUsers },
132 { queryKey: ['teams'], queryFn: fetchTeams },
133 { queryKey: ['projects'], queryFn: fetchProjects },
134 ],
135})
136```
137β
138[//]: # 'SuspenseSerial'
139β
140### Nested Component Waterfalls
141β
142[//]: # 'NestedIntro'
143β
144Nested 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`.
145β
146[//]: # 'NestedIntro'
147β
148If 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.
149β
150Let's first look at an example where the child is **not** dependent on the parent.
151β
152[//]: # 'NestedExample'
153β
154```tsx
155function Article({ id }) {
156 const { data: articleData, isPending } = useQuery({
157 queryKey: ['article', id],
158 queryFn: getArticleById,
159 })
160β
161 if (isPending) {
162 return 'Loading article...'
163 }
164β
165 return (
166 <>
167 <ArticleHeader articleData={articleData} />
168 <ArticleBody articleData={articleData} />
169 <Comments id={id} />
170 </>
171 )
172β
173}
174β
175function Comments({ id }) {
176 const { data, isPending } = useQuery({
177 queryKey: ['article-comments', id],
178 queryFn: getArticleCommentsById,
179 })
180β
181 ...
182}
183```
184β
185[//]: # 'NestedExample'
186β
187Note 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:
188β
189[//]: # 'NestedHoistedExample'
190β
191```tsx
192function Article({ id }) {
193 const { data: articleData, isPending: articlePending } = useQuery({
194 queryKey: ['article', id],
195 queryFn: getArticleById,
196 })
197β
198 const { data: commentsData, isPending: commentsPending } = useQuery({
199 queryKey: ['article-comments', id],
200 queryFn: getArticleCommentsById,
201 })
202β
203 if (articlePending) {
204 return 'Loading article...'
205 }
206β
207 return (
208 <>
209 <ArticleHeader articleData={articleData} />
210 <ArticleBody articleData={articleData} />
211 {commentsPending ? (
212 'Loading comments...'
213 ) : (
214 <Comments commentsData={commentsData} />
215 )}
216 </>
217 )
218}
219```
220β
221[//]: # 'NestedHoistedExample'
222[//]: # 'NestedHoistedOutro'
223β
224The 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.
225β
226[//]: # 'NestedHoistedOutro'
227β
228Another 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).
229β
230Next, let's look at a _Dependent Nested Component Waterfall_.
231β
232[//]: # 'DependentNestedExample'
233β
234```tsx
235function Feed() {
236 const { data, isPending } = useQuery({
237 queryKey: ['feed'],
238 queryFn: getFeed,
239 })
240β
241 if (isPending) {
242 return 'Loading feed...'
243 }
244β
245 return (
246 <>
247 {data.map((feedItem) => {
248 if (feedItem.type === 'GRAPH') {
249 return <GraphFeedItem key={feedItem.id} feedItem={feedItem} />
250 }
251β
252 return <StandardFeedItem key={feedItem.id} feedItem={feedItem} />
253 })}
254 </>
255 )
256}
257β
258function GraphFeedItem({ feedItem }) {
259 const { data, isPending } = useQuery({
260 queryKey: ['graph', feedItem.id],
261 queryFn: getGraphDataById,
262 })
263β
264 ...
265}
266```
267β
268[//]: # 'DependentNestedExample'
269β
270The second query `getGraphDataById` is dependent on its 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.
271β
272```
2731. |> getFeed()
2742. |> getGraphDataById()
275```
276β
277[//]: # 'ServerComponentsNote2'
278β
279In 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.
280β
281[//]: # 'ServerComponentsNote2'
282β
283You 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.
284β
285### Code Splitting
286β
287Splitting 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.
288β
289Consider this a slightly modified version of the Feed example.
290β
291[//]: # 'LazyExample'
292β
293```tsx
294// This lazy loads the GraphFeedItem component, meaning
295// it wont start loading until something renders it
296const GraphFeedItem = React.lazy(() => import('./GraphFeedItem'))
297β
298function Feed() {
299 const { data, isPending } = useQuery({
300 queryKey: ['feed'],
301 queryFn: getFeed,
302 })
303β
304 if (isPending) {
305 return 'Loading feed...'
306 }
307β
308 return (
309 <>
310 {data.map((feedItem) => {
311 if (feedItem.type === 'GRAPH') {
312 return <GraphFeedItem key={feedItem.id} feedItem={feedItem} />
313 }
314β
315 return <StandardFeedItem key={feedItem.id} feedItem={feedItem} />
316 })}
317 </>
318 )
319}
320β
321// GraphFeedItem.tsx
322function GraphFeedItem({ feedItem }) {
323 const { data, isPending } = useQuery({
324 queryKey: ['graph', feedItem.id],
325 queryFn: getGraphDataById,
326 })
327β
328 ...
329}
330```
331β
332[//]: # 'LazyExample'
333β
334This example has a double waterfall, looking like this:
335β
336```
3371. |> getFeed()
3382. |> JS for <GraphFeedItem>
3393. |> getGraphDataById()
340```
341β
342But 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!
343β
344```
3451. |> Markup
3462. |> JS for <Feed>
3473. |> getFeed()
3484. |> JS for <GraphFeedItem>
3495. |> getGraphDataById()
350```
351β
352Note that this looks a bit different when server rendering, we will explore that further in the [Server Rendering & Hydration guide](./ssr.md). Also note that it's not uncommon for the route that contains `<Feed>` to also be code split, which could add yet another hop.
353β
354In 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:
355β
356```
3571. |> getFeed()
3582. |> getGraphDataById()
3592. |> JS for <GraphFeedItem>
360```
361β
362This 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.md).
363β
364[//]: # 'ServerComponentsNote3'
365β
366> The tradeoff between:
367>
368> - Include all data fetching code in the main bundle, even if we seldom use it
369> - Put the data fetching code in the code split bundle, but with a request waterfall
370>
371> 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.md).
372β
373[//]: # 'ServerComponentsNote3'
374β
375## Summary and takeaways
376β
377Request Waterfalls are a very common and complex performance concern with many tradeoffs. There are many ways to accidentally introduce them into your application:
378β
379- Adding a query to a child, not realizing a parent already has a query
380- Adding a query to a parent, not realizing a child already has a query
381- Moving a component with descendants that has a query to a new parent with an ancestor that has a query
382- Etc..
383β
384Because 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.
385β
386In the next guide, we'll look at more ways to flatten waterfalls, by leveraging [Prefetching & Router Integration](./prefetching.md).