Skip to content

Commit 57301f8

Browse files
brookslybrandbrookslybrand
authored
docs: Network Concurrency Management (#13829)
* Cleanup spa.md intro * Add concurrency doc from Remix docs * Tweak some wording
1 parent a0ac387 commit 57301f8

File tree

2 files changed

+136
-3
lines changed

2 files changed

+136
-3
lines changed

‎docs/explanation/concurrency.md

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
---
2+
title: Network Concurrency Management
3+
---
4+
5+
# Network Concurrency Management
6+
7+
[MODES: framework, data]
8+
9+
## Overview
10+
11+
When building web applications, managing network requests can be a daunting task. The challenges of ensuring up-to-date data and handling simultaneous requests often lead to complex logic in the application to deal with interruptions and race conditions. React Router simplifies this process by automating network management while mirroring and expanding upon the intuitive behavior of web browsers.
12+
13+
To help understand how React Router handles concurrency, it's important to remember that after `form` submissions, React Router will fetch fresh data from the `loader`s. This is called revalidation.
14+
15+
## Natural Alignment with Browser Behavior
16+
17+
React Router's handling of network concurrency is heavily inspired by the default behavior of web browsers when processing documents.
18+
19+
### Link Navigation
20+
21+
**Browser Behavior**: When you click on a link in a browser and then click on another before the page transition completes, the browser prioritizes the most recent `action`. It cancels the initial request, focusing solely on the latest link clicked.
22+
23+
**React Router Behavior**: React Router manages client-side navigation the same way. When a link is clicked within a React Router application, it initiates fetch requests for each `loader` tied to the target URL. If another navigation interrupts the initial navigation, React Router cancels the previous fetch requests, ensuring that only the latest requests proceed.
24+
25+
### Form Submission
26+
27+
**Browser Behavior**: If you initiate a form submission in a browser and then quickly submit another form again, the browser disregards the first submission, processing only the latest one.
28+
29+
**React Router Behavior**: React Router mimics this behavior when working with forms. If a form is submitted and another submission occurs before the first completes, React Router cancels the original fetch requests. It then waits for the latest submission to complete before triggering page revalidation again.
30+
31+
## Concurrent Submissions and Revalidation
32+
33+
While standard browsers are limited to one request at a time for navigations and form submissions, React Router elevates this behavior. Unlike navigation, with [`useFetcher`][use_fetcher] multiple requests can be in flight simultaneously.
34+
35+
React Router is designed to handle multiple form submissions to server `action`s and concurrent revalidation requests efficiently. It ensures that as soon as new data is available, the state is updated promptly. However, React Router also safeguards against potential pitfalls by refraining from committing stale data when other `action`s introduce race conditions.
36+
37+
For instance, if three form submissions are in progress, and one completes, React Router updates the UI with that data immediately without waiting for the other two so that the UI remains responsive and dynamic. As the remaining submissions finalize, React Router continues to update the UI, ensuring that the most recent data is displayed.
38+
39+
Using this key:
40+
41+
- `|`: Submission begins
42+
- ✓: Action complete, data revalidation begins
43+
- ✅: Revalidated data is committed to the UI
44+
- ❌: Request cancelled
45+
46+
We can visualize this scenario in the following diagram:
47+
48+
```text
49+
submission 1: |----✓-----✅
50+
submission 2: |-----✓-----✅
51+
submission 3: |-----✓-----✅
52+
```
53+
54+
However, if a subsequent submission's revalidation completes before an earlier one, React Router discards the earlier data, ensuring that only the most up-to-date information is reflected in the UI:
55+
56+
```text
57+
submission 1: |----✓---------❌
58+
submission 2: |-----✓-----✅
59+
submission 3: |-----✓-----✅
60+
```
61+
62+
Because the revalidation from submission (2) started later and landed earlier than submission (1), the requests from submission (1) are canceled and only the data from submission (2) is committed to the UI. It was requested later, so it's more likely to contain the updated values from both (1) and (2).
63+
64+
## Potential for Stale Data
65+
66+
It's unlikely your users will ever experience this, but there are still chances for the user to see stale data in very rare conditions with inconsistent infrastructure. Even though React Router cancels requests for stale data, they will still end up making it to the server. Canceling a request in the browser simply releases browser resources for that request; it can't "catch up" and stop it from getting to the server. In extremely rare conditions, a canceled request may change data after the interrupting `action`'s revalidation lands. Consider this diagram:
67+
68+
```text
69+
👇 interruption with new submission
70+
|----❌----------------------✓
71+
|-------✓-----✅
72+
👆
73+
initial request reaches the server
74+
after the interrupting submission
75+
has completed revalidation
76+
```
77+
78+
The user is now looking at different data than what is on the server. Note that this problem is both extremely rare and exists with default browser behavior, too. The chance of the initial request reaching the server later than both the submission and revalidation of the second is unexpected on any network and server infrastructure. If this is a concern with your infrastructure, you can send timestamps with your form submissions and write server logic to ignore stale submissions.
79+
80+
## Example
81+
82+
In UI components like comboboxes, each keystroke can trigger a network request. Managing such rapid, consecutive requests can be tricky, especially when ensuring that the displayed results match the most recent query. However, with React Router, this challenge is automatically handled, ensuring that users see the correct results without developers having to micromanage the network.
83+
84+
```tsx filename=app/pages/city-search.tsx
85+
export async function loader({ request }) {
86+
const { searchParams } = new URL(request.url);
87+
const cities = await searchCities(searchParams.get("q"));
88+
return cities;
89+
}
90+
91+
export function CitySearchCombobox() {
92+
const fetcher = useFetcher<typeof loader>();
93+
94+
return (
95+
<fetcher.Form action="/city-search">
96+
<Combobox aria-label="Cities">
97+
<ComboboxInput
98+
name="q"
99+
onChange={event =>
100+
// submit the form onChange to get the list of cities
101+
fetcher.submit(event.target.form)
102+
}
103+
/>
104+
105+
{/* render with the loader's data */}
106+
{fetcher.data ? (
107+
<ComboboxPopover className="shadow-popup">
108+
{fetcher.data.length > 0 ? (
109+
<ComboboxList>
110+
{fetcher.data.map(city => (
111+
<ComboboxOption
112+
key={city.id}
113+
value={city.name}
114+
/>
115+
))}
116+
</ComboboxList>
117+
) : (
118+
<span>No results found</span>
119+
)}
120+
</ComboboxPopover>
121+
) : null}
122+
</Combobox>
123+
</fetcher.Form>
124+
);
125+
}
126+
```
127+
128+
All the application needs to know is how to query the data and how to render it. React Router handles the network.
129+
130+
## Conclusion
131+
132+
React Router offers developers an intuitive, browser-based approach to managing network requests. By mirroring browser behaviors and enhancing them where needed, it simplifies the complexities of concurrency, revalidation, and potential race conditions. Whether you're building a simple webpage or a sophisticated web application, React Router ensures that your user interactions are smooth, reliable, and always up to date.
133+
134+
[use_fetcher]: ../api/hooks/useFetcher

‎docs/how-to/spa.md

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,10 +4,9 @@ title: Single Page App (SPA)
44

55
# Single Page App (SPA)
66

7-
There are two ways to ship a single page app with React Router
7+
[MODES: framework]
88

9-
- **as a library** - Instead of using React Router's framework features, you can use it as a library in your own SPA architecture. Refer to [React Router as a Library](../start/library/installation) guides.
10-
- **as a framework** - This guide will focus here
9+
This guides focuses on how to build Single Page Apps with React Router Framework mode. If you're using React Router as a library, you can use it to build your own SPA architecture.
1110

1211
## Overview
1312

0 commit comments

Comments
 (0)