Skip to content

Commit d71e347

Browse files
committed
Add docs to cover prefetching vs initiate differences
1 parent 96038ff commit d71e347

File tree

1 file changed

+40
-3
lines changed

1 file changed

+40
-3
lines changed

docs/rtk-query/usage/prefetching.mdx

Lines changed: 40 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,25 @@ There are a handful of situations that you may want to do this, but some very co
1919
3. User hovers over a next pagination button
2020
4. User navigates to a page and you know that some components down the tree will require said data. This way, you can prevent fetching waterfalls.
2121

22+
## Prefetching vs Subscriptions
23+
24+
Prefetching is designed as a "fire and forget" operation that loads data into the cache without creating an ongoing subscription. This means:
25+
26+
- **No automatic refetching**: Prefetched data will not automatically refetch when tags are invalidated
27+
- **No subscription management**: You don't need to (and can't) manually unsubscribe from prefetched data
28+
- **Cache cleanup**: Prefetched data without active subscriptions may be removed during normal cache cleanup
29+
- **Returns void**: The prefetch trigger function doesn't return a promise or subscription handle
30+
31+
If you need data that automatically refetches on invalidation or stays in the cache as long as a component is mounted, use a query hook like `useQuery` or `useQuerySubscription` instead. Prefetch is ideal for warming the cache before a user action, while query hooks are for ongoing data needs.
32+
33+
:::tip When to use prefetch vs query hooks
34+
35+
- **Use prefetch** when you want to load data ahead of time (e.g., on hover) but don't need it to stay fresh
36+
- **Use query hooks** when you need data that automatically refetches on invalidation and stays in cache while the component is mounted
37+
- **Use both together**: Prefetch on hover, then let the query hook create a subscription when the user navigates
38+
39+
:::
40+
2241
## Prefetching with React Hooks
2342

2443
Similar to the [`useMutation`](./mutations) hook, the `usePrefetch` hook will not run automatically — it returns a "trigger function" that can be used to initiate the behavior.
@@ -111,12 +130,30 @@ store.dispatch(
111130
)
112131
```
113132

114-
You can also dispatch the query action, but you would be responsible for implementing any additional logic.
133+
### Prefetch vs `initiate()`
115134

116-
```ts title="Alternate method of manual prefetching" no-transpile
117-
dispatch(api.endpoints[endpointName].initiate(arg, { forceRefetch: true }))
135+
While you can also use `initiate()` directly, there are important differences:
136+
137+
```ts title="Using initiate() directly" no-transpile
138+
// This creates a subscription that must be manually cleaned up
139+
const promise = dispatch(
140+
api.endpoints[endpointName].initiate(arg, {
141+
subscribe: true, // Creates a subscription (default)
142+
forceRefetch: true,
143+
}),
144+
)
145+
146+
// You must manually unsubscribe to prevent memory leaks
147+
promise.unsubscribe()
118148
```
119149

150+
**Key differences:**
151+
152+
- **`api.util.prefetch()`**: Automatically uses `subscribe: false`, no cleanup needed
153+
- **`endpoint.initiate()`**: Defaults to `subscribe: true`, requires manual `unsubscribe()` call
154+
155+
Use `prefetch()` for simple "load and forget" scenarios. Use `initiate()` directly only when you need fine-grained control over subscriptions and are prepared to manage the subscription lifecycle yourself.
156+
120157
## Prefetching Examples
121158

122159
### Basic Prefetching

0 commit comments

Comments
 (0)