|
1 | 1 | # create-subscription
|
2 | 2 |
|
3 |
| -`create-subscription` is a utility for subscribing to external data sources inside React components. It is officially supported and maintained by the React team. |
| 3 | +`create-subscription` is a utility for subscribing to external data sources inside React components. |
4 | 4 |
|
5 |
| -## When should you NOT use this? |
6 |
| - |
7 |
| -This utility should be used for subscriptions to a single value that are typically only read in one place and may update frequently (e.g. a component that subscribes to a geolocation API to show a dot on a map). |
8 |
| - |
9 |
| -Other cases have **better long-term solutions**: |
10 |
| -* Redux/Flux stores should use the [context API](https://reactjs.org/docs/context.html) instead. |
11 |
| -* I/O subscriptions (e.g. notifications) that update infrequently should use [`react-cache`](https://github.com/facebook/react/blob/main/packages/react-cache/README.md) instead. |
12 |
| -* Complex libraries like Relay/Apollo should manage subscriptions manually with the same techniques which this library uses under the hood (as referenced [here](https://gist.github.com/bvaughn/d569177d70b50b58bff69c3c4a5353f3)) in a way that is most optimized for their library usage. |
13 |
| - |
14 |
| -## Limitations in async mode |
15 |
| - |
16 |
| -The main motivation for `create-subscription` is to provide a way for library authors to ensure compatibility with React's upcoming asynchronous rendering mode. `create-subscription` guarantees correctness in async mode, accounting for the subtle bugs and edge cases that a library author might otherwise miss. |
17 |
| - |
18 |
| -However, [it achieves correctness by sometimes de-opting to synchronous mode](https://github.com/facebook/react/issues/13186#issuecomment-403959161), obviating the benefits of async rendering. This is an inherent limitation of storing state outside of React's managed state queue and rendering in response to a change event. |
19 |
| - |
20 |
| -The effect of de-opting to sync mode is that the main thread may periodically be blocked (in the case of CPU-bound work), and placeholders may appear earlier than desired (in the case of IO-bound work). |
21 |
| - |
22 |
| -For **full compatibility** with asynchronous rendering, including both **time-slicing** and **React Suspense**, the suggested longer-term solution is to move to one of the patterns described in the previous section. |
23 |
| - |
24 |
| -## What types of subscriptions can this support? |
25 |
| - |
26 |
| -This abstraction can handle a variety of subscription types, including: |
27 |
| -* Event dispatchers like `HTMLInputElement`. |
28 |
| -* Custom pub/sub components like Relay's `FragmentSpecResolver`. |
29 |
| -* Observable types like RxJS `BehaviorSubject` and `ReplaySubject`. (Types like RxJS `Subject` or `Observable` are not supported, because they provide no way to read the "current" value after it has been emitted.) |
30 |
| -* Native Promises. |
| 5 | +**It is no longer maintained and will not be updated. Use the built-in [`React.useSyncExternalStore`](https://reactjs.org/docs/hooks-reference.html#usesyncexternalstore) instead.** |
31 | 6 |
|
32 | 7 | # Installation
|
33 | 8 |
|
|
0 commit comments