Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: Fix broken links in React framework documentation #8801

Closed
wants to merge 1 commit into from
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/framework/react/guides/dependent-queries.md
Original file line number Diff line number Diff line change
Expand Up @@ -90,6 +90,6 @@ const usersMessages = useQueries({

## A note about performance

Dependent queries by definition constitutes a form of [request waterfall](../../../react/guides/request-waterfalls), which hurts performance. If we pretend both queries take the same amount of time, doing them serially instead of in parallel always takes twice as much time, which is especially hurtful when it happens on a client that has high latency. If you can, it's always better to restructure the backend APIs so that both queries can be fetched in parallel, though that might not always be practically feasible.
Dependent queries by definition constitutes a form of [request waterfall](./request-waterfalls), which hurts performance. If we pretend both queries take the same amount of time, doing them serially instead of in parallel always takes twice as much time, which is especially hurtful when it happens on a client that has high latency. If you can, it's always better to restructure the backend APIs so that both queries can be fetched in parallel, though that might not always be practically feasible.

In the example above, instead of first fetching `getUserByEmail` to be able to `getProjectsByUser`, introducing a new `getProjectsByUserEmail` query would flatten the waterfall.
4 changes: 2 additions & 2 deletions docs/framework/react/guides/initial-query-data.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,8 +8,8 @@ There are many ways to supply initial data for a query to the cache before you n
- Declaratively:
- Provide `initialData` to a query to prepopulate its cache if empty
- Imperatively:
- [Prefetch the data using `queryClient.prefetchQuery`](../../../react/guides/prefetching)
- [Manually place the data into the cache using `queryClient.setQueryData`](../../../react/guides/prefetching)
- [Prefetch the data using `queryClient.prefetchQuery`](./prefetching)
- [Manually place the data into the cache using `queryClient.setQueryData`](./prefetching)

## Using `initialData` to prepopulate a query

Expand Down
4 changes: 2 additions & 2 deletions docs/framework/react/guides/migrating-to-react-query-3.md
Original file line number Diff line number Diff line change
Expand Up @@ -103,8 +103,8 @@ try {

Together, these provide the same experience as before, but with added control to choose which component trees you want to reset. For more information, see:

- [QueryErrorResetBoundary](../../reference/QueryErrorResetBoundary)
- [useQueryErrorResetBoundary](../../reference/useQueryErrorResetBoundary)
- [QueryErrorResetBoundary](../reference/QueryErrorResetBoundary)
- [useQueryErrorResetBoundary](../reference/useQueryErrorResetBoundary)

### `QueryCache.getQuery()` has been replaced by `QueryCache.find()`.

Expand Down
24 changes: 12 additions & 12 deletions docs/framework/react/guides/migrating-to-react-query-4.md
Original file line number Diff line number Diff line change
Expand Up @@ -58,9 +58,9 @@ Please note in the case of `TypeScript` you need to use `tsx` as the parser; oth

### Query Keys (and Mutation Keys) need to be an Array

In v3, Query and Mutation Keys could be a String or an Array. Internally, React Query has always worked with Array Keys only, and we've sometimes exposed this to consumers. For example, in the `queryFn`, you would always get the key as an Array to make working with [Default Query Functions](../default-query-function) easier.
In v3, Query and Mutation Keys could be a String or an Array. Internally, React Query has always worked with Array Keys only, and we've sometimes exposed this to consumers. For example, in the `queryFn`, you would always get the key as an Array to make working with [Default Query Functions](./default-query-function) easier.

However, we have not followed this concept through to all apis. For example, when using the `predicate` function on [Query Filters](../filters) you would get the raw Query Key. This makes it difficult to work with such functions if you use Query Keys that are mixed Arrays and Strings. The same was true when using global callbacks.
However, we have not followed this concept through to all apis. For example, when using the `predicate` function on [Query Filters](./filters) you would get the raw Query Key. This makes it difficult to work with such functions if you use Query Keys that are mixed Arrays and Strings. The same was true when using global callbacks.

To streamline all apis, we've decided to make all keys Arrays only:

Expand Down Expand Up @@ -100,7 +100,7 @@ Please note in the case of `TypeScript` you need to use `tsx` as the parser; oth

### The idle state has been removed

With the introduction of the new [fetchStatus](../queries#fetchstatus) for better offline support, the `idle` state became irrelevant, because `fetchStatus: 'idle'` captures the same state better. For more information, please read [Why two different states](../queries#why-two-different-states).
With the introduction of the new [fetchStatus](./queries#fetchstatus) for better offline support, the `idle` state became irrelevant, because `fetchStatus: 'idle'` captures the same state better. For more information, please read [Why two different states](./queries#why-two-different-states).

This will mostly affect `disabled` queries that don't have any `data` yet, as those were in `idle` state before:

Expand All @@ -110,7 +110,7 @@ This will mostly affect `disabled` queries that don't have any `data` yet, as th
+ fetchStatus: 'idle' // [!code ++]
```

Also, have a look at [the guide on dependent queries](../dependent-queries)
Also, have a look at [the guide on dependent queries](./dependent-queries)

#### disabled queries

Expand All @@ -121,7 +121,7 @@ Due to this change, disabled queries (even temporarily disabled ones) will start
isInitialLoading // [!code ++]
```

See also the guide on [disabling queries](../disabling-queries#isInitialLoading)
See also the guide on [disabling queries](./disabling-queries#isInitialLoading)

### new API for `useQueries`

Expand All @@ -142,7 +142,7 @@ The `useQueries` hook now accepts an object with a `queries` prop as its input.

### Undefined is an illegal cache value for successful queries

In order to make bailing out of updates possible by returning `undefined`, we had to make `undefined` an illegal cache value. This is in-line with other concepts of react-query, for example, returning `undefined` from the [initialData function](../initial-query-data#initial-data-function) will also _not_ set data.
In order to make bailing out of updates possible by returning `undefined`, we had to make `undefined` an illegal cache value. This is in-line with other concepts of react-query, for example, returning `undefined` from the [initialData function](./initial-query-data#initial-data-function) will also _not_ set data.

Further, it is an easy bug to produce `Promise<void>` by adding logging in the queryFn:

Expand All @@ -156,7 +156,7 @@ This is now disallowed on type level; at runtime, `undefined` will be transforme

### Queries and mutations, per default, need network connection to run

Please read the [New Features announcement](#proper-offline-support) about online / offline support, and also the dedicated page about [Network mode](../network-mode)
Please read the [New Features announcement](#proper-offline-support) about online / offline support, and also the dedicated page about [Network mode](./network-mode)

Even though React Query is an Async State Manager that can be used for anything that produces a Promise, it is most often used for data fetching in combination with data fetching libraries. That is why, per default, queries and mutations will be `paused` if there is no network connection. If you want to opt-in to the previous behavior, you can globally set `networkMode: offlineFirst` for both queries and mutations:

Expand Down Expand Up @@ -242,7 +242,7 @@ The filter defaults to `all`, and you can choose to only match `active` or `inac

#### refetchActive / refetchInactive

[queryClient.invalidateQueries](../../../../reference/QueryClient/#queryclientinvalidatequeries) had two additional, similar flags:
[queryClient.invalidateQueries](../../../reference/QueryClient#queryclientinvalidatequeries) had two additional, similar flags:

```
refetchActive: Boolean
Expand Down Expand Up @@ -280,7 +280,7 @@ React.useEffect(() => mySideEffectHere(data), [data])

### `persistQueryClient` and the corresponding persister plugins are no longer experimental and have been renamed

The plugins `createWebStoragePersistor` and `createAsyncStoragePersistor` have been renamed to [`createSyncStoragePersister`](../../plugins/createSyncStoragePersister) and [`createAsyncStoragePersister`](../../plugins/createAsyncStoragePersister) respectively. The interface `Persistor` in `persistQueryClient` has also been renamed to `Persister`. Checkout [this stackexchange](https://english.stackexchange.com/questions/206893/persister-or-persistor) for the motivation of this change.
The plugins `createWebStoragePersistor` and `createAsyncStoragePersistor` have been renamed to [`createSyncStoragePersister`](..//plugins/createSyncStoragePersister) and [`createAsyncStoragePersister`](../plugins/createAsyncStoragePersister) respectively. The interface `Persistor` in `persistQueryClient` has also been renamed to `Persister`. Checkout [this stackexchange](https://english.stackexchange.com/questions/206893/persister-or-persistor) for the motivation of this change.

Since these plugins are no longer experimental, their import paths have also been updated:

Expand All @@ -296,15 +296,15 @@ Since these plugins are no longer experimental, their import paths have also bee

### The `cancel` method on promises is no longer supported

The [old `cancel` method](../query-cancellation#old-cancel-function) that allowed you to define a `cancel` function on promises, which was then used by the library to support query cancellation, has been removed. We recommend to use the [newer API](../query-cancellation) (introduced with v3.30.0) for query cancellation that uses the [`AbortController` API](https://developer.mozilla.org/en-US/docs/Web/API/AbortController) internally and provides you with an [`AbortSignal` instance](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) for your query function to support query cancellation.
The [old `cancel` method](./query-cancellation#old-cancel-function) that allowed you to define a `cancel` function on promises, which was then used by the library to support query cancellation, has been removed. We recommend to use the [newer API](./query-cancellation) (introduced with v3.30.0) for query cancellation that uses the [`AbortController` API](https://developer.mozilla.org/en-US/docs/Web/API/AbortController) internally and provides you with an [`AbortSignal` instance](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) for your query function to support query cancellation.

### TypeScript

Types now require using TypeScript v4.1 or greater

### Supported Browsers

As of v4, React Query is optimized for modern browsers. We have updated our browserslist to produce a more modern, performant and smaller bundle. You can read about the requirements [here](../../installation#requirements).
As of v4, React Query is optimized for modern browsers. We have updated our browserslist to produce a more modern, performant and smaller bundle. You can read about the requirements [here](../installation#requirements).

### `setLogger` is removed

Expand Down Expand Up @@ -427,7 +427,7 @@ React Query defaults to "tracking" query properties, which should give you a nic

### Bailing out of updates with setQueryData

When using the [functional updater form of setQueryData](../../../../reference/QueryClient/#queryclientsetquerydata), you can now bail out of the update by returning `undefined`. This is helpful if `undefined` is given to you as `previousValue`, which means that currently, no cached entry exists and you don't want to / cannot create one, like in the example of toggling a todo:
When using the [functional updater form of setQueryData](../../../reference/QueryClient#queryclientsetquerydata), you can now bail out of the update by returning `undefined`. This is helpful if `undefined` is given to you as `previousValue`, which means that currently, no cached entry exists and you don't want to / cannot create one, like in the example of toggling a todo:

```tsx
queryClient.setQueryData(['todo', id], (previousTodo) =>
Expand Down
14 changes: 7 additions & 7 deletions docs/framework/react/guides/migrating-to-v5.md
Original file line number Diff line number Diff line change
Expand Up @@ -169,7 +169,7 @@ Custom loggers were already deprecated in 4 and have been removed in this versio

### Supported Browsers

We have updated our browserslist to produce a more modern, performant and smaller bundle. You can read about the requirements [here](../../installation#requirements).
We have updated our browserslist to produce a more modern, performant and smaller bundle. You can read about the requirements [here](../installation#requirements).

### Private class fields and methods

Expand Down Expand Up @@ -218,7 +218,7 @@ useQuery<number, string>({
})
```

For a way to set a different kind of Error globally, see [the TypeScript Guide](../../typescript#registering-a-global-error).
For a way to set a different kind of Error globally, see [the TypeScript Guide](../typescript#registering-a-global-error).

### eslint `prefer-query-object-syntax` rule is removed

Expand Down Expand Up @@ -494,21 +494,21 @@ Note that the infinite list must be bi-directional, which requires both `getNext

### Infinite Queries can prefetch multiple pages

Infinite Queries can be prefetched like regular Queries. Per default, only the first page of the Query will be prefetched and will be stored under the given QueryKey. If you want to prefetch more than one page, you can use the `pages` option. Read the [prefetching guide](../prefetching) for more information.
Infinite Queries can be prefetched like regular Queries. Per default, only the first page of the Query will be prefetched and will be stored under the given QueryKey. If you want to prefetch more than one page, you can use the `pages` option. Read the [prefetching guide](./prefetching) for more information.

### New `combine` option for `useQueries`

See the [useQueries docs](../../reference/useQueries#combine) for more details.
See the [useQueries docs](../reference/useQueries#combine) for more details.

### Experimental `fine grained storage persister`

See the [experimental_createPersister docs](../../../react/plugins/createPersister) for more details.
See the [experimental_createPersister docs](../plugins/createPersister) for more details.

[//]: # 'FrameworkSpecificNewFeatures'

### Typesafe way to create Query Options

See the [TypeScript docs](../../typescript#typing-query-options) for more details.
See the [TypeScript docs](../typescript#typing-query-options) for more details.

### new hooks for suspense

Expand All @@ -524,6 +524,6 @@ const { data: post } = useSuspenseQuery({

The experimental `suspense: boolean` flag on the query hooks has been removed.

You can read more about them in the [suspense docs](../suspense).
You can read more about them in the [suspense docs](./suspense).

[//]: # 'FrameworkSpecificNewFeatures'
8 changes: 4 additions & 4 deletions docs/framework/react/guides/network-mode.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,13 +3,13 @@ id: network-mode
title: Network Mode
---

TanStack Query provides three different network modes to distinguish how [Queries](../queries) and [Mutations](../mutations) should behave if you have no network connection. This mode can be set for each Query / Mutation individually, or globally via the query / mutation defaults.
TanStack Query provides three different network modes to distinguish how [Queries](./queries) and [Mutations](./mutations) should behave if you have no network connection. This mode can be set for each Query / Mutation individually, or globally via the query / mutation defaults.

Since TanStack Query is most often used for data fetching in combination with data fetching libraries, the default network mode is [online](#network-mode-online).

## Network Mode: online

In this mode, Queries and Mutations will not fire unless you have network connection. This is the default mode. If a fetch is initiated for a query, it will always stay in the `state` (`pending`, `error`, `success`) it is in if the fetch cannot be made because there is no network connection. However, a [fetchStatus](../queries#fetchstatus) is exposed additionally. This can be either:
In this mode, Queries and Mutations will not fire unless you have network connection. This is the default mode. If a fetch is initiated for a query, it will always stay in the `state` (`pending`, `error`, `success`) it is in if the fetch cannot be made because there is no network connection. However, a [fetchStatus](./queries#fetchstatus) is exposed additionally. This can be either:

- `fetching`: The `queryFn` is really executing - a request is in-flight.
- `paused`: The query is not executing - it is `paused` until you have connection again
Expand All @@ -19,7 +19,7 @@ The flags `isFetching` and `isPaused` are derived from this state and exposed fo

> Keep in mind that it might not be enough to check for `pending` state to show a loading spinner. Queries can be in `state: 'pending'`, but `fetchStatus: 'paused'` if they are mounting for the first time, and you have no network connection.

If a query runs because you are online, but you go offline while the fetch is still happening, TanStack Query will also pause the retry mechanism. Paused queries will then continue to run once you re-gain network connection. This is independent of `refetchOnReconnect` (which also defaults to `true` in this mode), because it is not a `refetch`, but rather a `continue`. If the query has been [cancelled](../query-cancellation) in the meantime, it will not continue.
If a query runs because you are online, but you go offline while the fetch is still happening, TanStack Query will also pause the retry mechanism. Paused queries will then continue to run once you re-gain network connection. This is independent of `refetchOnReconnect` (which also defaults to `true` in this mode), because it is not a `refetch`, but rather a `continue`. If the query has been [cancelled](./query-cancellation) in the meantime, it will not continue.

## Network Mode: always

Expand All @@ -37,7 +37,7 @@ In those situations, the first fetch might succeed because it comes from an offl

## Devtools

The [TanStack Query Devtools](../../devtools) will show Queries in a `paused` state if they would be fetching, but there is no network connection. There is also a toggle button to _Mock offline behavior_. Please note that this button will _not_ actually mess with your network connection (you can do that in the browser devtools), but it will set the [OnlineManager](../../../../reference/onlineManager) in an offline state.
The [TanStack Query Devtools](../devtools) will show Queries in a `paused` state if they would be fetching, but there is no network connection. There is also a toggle button to _Mock offline behavior_. Please note that this button will _not_ actually mess with your network connection (you can do that in the browser devtools), but it will set the [OnlineManager](../../../reference/onlineManager) in an offline state.

## Signature

Expand Down
Loading
Loading