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

[Doc] Fix react-query links in documentation #8010

Merged
merged 1 commit into from
Jul 26, 2022
Merged
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 README.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ A frontend Framework for building data-driven applications running in the browse

* ☂️ **Opt-In Types**: Develop either in TypeScript or JavaScript

* 👨‍👩‍👧‍👦 Powered by [MUI](https://mui.com/), [react-hook-form](https://react-hook-form.com), [react-router](https://reacttraining.com/react-router/), [react-query](https://react-query.tanstack.com/), [TypeScript](https://www.typescriptlang.org/) and a few more
* 👨‍👩‍👧‍👦 Powered by [MUI](https://mui.com/), [react-hook-form](https://react-hook-form.com), [react-router](https://reacttraining.com/react-router/), [react-query](https://react-query-v3.tanstack.com/), [TypeScript](https://www.typescriptlang.org/) and a few more

## Installation

Expand Down
14 changes: 7 additions & 7 deletions docs/Actions.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ title: "Querying the API"

# Querying the API

React-admin provides special hooks to emit read and write queries to the [`dataProvider`](./DataProviders.md), which in turn sends requests to your API. Under the hood, it uses [react-query](https://react-query.tanstack.com/) to call the `dataProvider` and cache the results.
React-admin provides special hooks to emit read and write queries to the [`dataProvider`](./DataProviders.md), which in turn sends requests to your API. Under the hood, it uses [react-query](https://react-query-v3.tanstack.com/) to call the `dataProvider` and cache the results.

## Getting The `dataProvider` Instance

Expand Down Expand Up @@ -118,7 +118,7 @@ It's up to the Data Provider to interpret this parameter.

## `useQuery` and `useMutation`

Internally, react-admin uses [react-query](https://react-query.tanstack.com/) to call the dataProvider. When fetching data from the dataProvider in your components, if you can't use any of the dataProvider method hooks, you should use that library, too. It brings several benefits:
Internally, react-admin uses [react-query](https://react-query-v3.tanstack.com/) to call the dataProvider. When fetching data from the dataProvider in your components, if you can't use any of the dataProvider method hooks, you should use that library, too. It brings several benefits:

1. It triggers the loader in the AppBar when the query is running.
2. It reduces the boilerplate code since you don't need to use `useState`.
Expand All @@ -127,8 +127,8 @@ Internally, react-admin uses [react-query](https://react-query.tanstack.com/) to

React-query offers 2 main hooks to interact with the dataProvider:

* [`useQuery`](https://react-query.tanstack.com/reference/useQuery): fetches the dataProvider on mount. This is for *read* queries.
* [`useMutation`](https://react-query.tanstack.com/reference/useMutation): fetches the dataProvider when you call a callback. This is for *write* queries, and *read* queries that execute on user interaction.
* [`useQuery`](https://react-query-v3.tanstack.com/reference/useQuery): fetches the dataProvider on mount. This is for *read* queries.
* [`useMutation`](https://react-query-v3.tanstack.com/reference/useMutation): fetches the dataProvider when you call a callback. This is for *write* queries, and *read* queries that execute on user interaction.

Both these hooks accept a query *key* (identifying the query in the cache), and a query *function* (executing the query and returning a Promise). Internally, react-admin uses an array of arguments as the query key.

Expand Down Expand Up @@ -176,15 +176,15 @@ const ApproveButton = ({ record }) => {
};
```

If you want to go beyond data provider method hooks, we recommend that you read [the react-query documentation](https://react-query.tanstack.com/overview).
If you want to go beyond data provider method hooks, we recommend that you read [the react-query documentation](https://react-query-v3.tanstack.com/overview).

## `isLoading` vs `isFetching`

Data fetching hooks return two loading state variables: `isLoading` and `isFetching`. Which one should you use?

The short answer is: use `isLoading`. Read on to understand why.

The source of these two variables is [react-query](https://react-query.tanstack.com/guides/queries#query-basics). Here is how they defined these two variables:
The source of these two variables is [react-query](https://react-query-v3.tanstack.com/guides/queries#query-basics). Here is how they defined these two variables:

- `isLoading`: The query has no data and is currently fetching
- `isFetching`: In any state, if the query is fetching at any time (including background refetching) isFetching will be true.
Expand Down Expand Up @@ -253,7 +253,7 @@ const BanUserButton = ({ userId }) => {

## Query Options

The data provider method hooks (like `useGetOne`) and react-query's hooks (like `useQuery`) accept a query options object as the last argument. This object can be used to modify the way the query is executed. There are many options, all documented [in the react-query documentation](https://react-query.tanstack.com/reference/useQuery):
The data provider method hooks (like `useGetOne`) and react-query's hooks (like `useQuery`) accept a query options object as the last argument. This object can be used to modify the way the query is executed. There are many options, all documented [in the react-query documentation](https://react-query-v3.tanstack.com/reference/useQuery):

- `cacheTime`
- `enabled`
Expand Down
4 changes: 2 additions & 2 deletions docs/Admin.md
Original file line number Diff line number Diff line change
Expand Up @@ -120,7 +120,7 @@ The [Translation Documentation](./Translation.md) details this process.

## `queryClient`

React-admin uses [react-query](https://react-query.tanstack.com/) to fetch, cache and update data. Internally, the `<Admin>` component creates a react-query [`QueryClient`](https://react-query.tanstack.com/reference/QueryClient) on mount, using [react-query's "aggressive but sane" defaults](https://react-query.tanstack.com/guides/important-defaults):
React-admin uses [react-query](https://react-query-v3.tanstack.com/) to fetch, cache and update data. Internally, the `<Admin>` component creates a react-query [`QueryClient`](https://react-query-v3.tanstack.com/reference/QueryClient) on mount, using [react-query's "aggressive but sane" defaults](https://react-query-v3.tanstack.com/guides/important-defaults):

* Queries consider cached data as stale
* Stale queries are refetched automatically in the background when:
Expand Down Expand Up @@ -158,7 +158,7 @@ const App = () => (
);
```

To know which options you can pass to the `QueryClient` constructor, check the [react-query documentation](https://react-query.tanstack.com/reference/QueryClient) and the [query options](https://react-query.tanstack.com/reference/useQuery) and [mutation options](https://react-query.tanstack.com/reference/useMutation) sections.
To know which options you can pass to the `QueryClient` constructor, check the [react-query documentation](https://react-query-v3.tanstack.com/reference/QueryClient) and the [query options](https://react-query-v3.tanstack.com/reference/useQuery) and [mutation options](https://react-query-v3.tanstack.com/reference/useMutation) sections.

The common settings that react-admin developers often overwrite are:

Expand Down
2 changes: 1 addition & 1 deletion docs/Caching.md
Original file line number Diff line number Diff line change
Expand Up @@ -110,7 +110,7 @@ const App = () => {

With this setting, all queries will be considered valid for 5 minutes. That means that react-admin *won't refetch* data from the API if the data is already in the cache and younger than 5 minutes.

Check the details about this cache [in the react-query documentation](https://react-query.tanstack.com/guides/caching).
Check the details about this cache [in the react-query documentation](https://react-query-v3.tanstack.com/guides/caching).

It especially fits admins for API backends with a small number of users (because with a large number of users, there is a high chance that a record kept in the client-side cache for a few minutes may be updated on the backend by another user). It also works with GraphQL APIs.

Expand Down
2 changes: 1 addition & 1 deletion docs/Create.md
Original file line number Diff line number Diff line change
Expand Up @@ -168,7 +168,7 @@ const PostCreate = () => (
```
{% endraw %}

You can also use `mutationOptions` to override success or error side effects, by setting the `mutationOptions` prop. Refer to the [useMutation documentation](https://react-query.tanstack.com/reference/useMutation) in the react-query website for a list of the possible options.
You can also use `mutationOptions` to override success or error side effects, by setting the `mutationOptions` prop. Refer to the [useMutation documentation](https://react-query-v3.tanstack.com/reference/useMutation) in the react-query website for a list of the possible options.

Let's see an example with the success side effect. By default, when the save action succeeds, react-admin shows a notification, and redirects to the new record edit page. You can override this behavior and pass custom success side effects by providing a `mutationOptions` prop with an `onSuccess` key:

Expand Down
2 changes: 1 addition & 1 deletion docs/DataProviders.md
Original file line number Diff line number Diff line change
Expand Up @@ -68,7 +68,7 @@ Access-Control-Expose-Headers: Content-Range

## Enabling Query Logs

React-admin uses `react-query` to call the dataProvider. You can see all the calls made by react-query in the browser thanks to [the react-query devtools](https://react-query.tanstack.com/devtools).
React-admin uses `react-query` to call the dataProvider. You can see all the calls made by react-query in the browser thanks to [the react-query devtools](https://react-query-v3.tanstack.com/devtools).

![React-Query DevTools](./img/react-query-devtools.png)

Expand Down
4 changes: 2 additions & 2 deletions docs/Edit.md
Original file line number Diff line number Diff line change
Expand Up @@ -281,7 +281,7 @@ const PostEdit = () => (
```
{% endraw %}

You can also use `mutationOptions` to override success or error side effects, by setting the `mutationOptions` prop. Refer to the [useMutation documentation](https://react-query.tanstack.com/reference/useMutation) in the react-query website for a list of the possible options.
You can also use `mutationOptions` to override success or error side effects, by setting the `mutationOptions` prop. Refer to the [useMutation documentation](https://react-query-v3.tanstack.com/reference/useMutation) in the react-query website for a list of the possible options.

Let's see an example with the success side effect. By default, when the save action succeeds, react-admin shows a notification, and redirects to the list page. You can override this behavior and pass custom success side effects by providing a `mutationOptions` prop with an `onSuccess` key:

Expand Down Expand Up @@ -431,7 +431,7 @@ const PostEdit = () => (
```
{% endraw %}

Refer to the [useQuery documentation](https://react-query.tanstack.com/reference/useQuery) in the react-query website for a list of the possible options.
Refer to the [useQuery documentation](https://react-query-v3.tanstack.com/reference/useQuery) in the react-query website for a list of the possible options.

## `redirect`

Expand Down
4 changes: 2 additions & 2 deletions docs/Layout.md
Original file line number Diff line number Diff line change
Expand Up @@ -304,7 +304,7 @@ export const MyLayout = (props) => (

## Adding Developer Tools

A custom layout is also the ideal place to add debug tools, e.g. [react-query devtools](https://react-query.tanstack.com/devtools):
A custom layout is also the ideal place to add debug tools, e.g. [react-query devtools](https://react-query-v3.tanstack.com/devtools):

```jsx
// in src/MyLayout.js
Expand All @@ -319,4 +319,4 @@ export const MyLayout = (props) => (
);
```

![React-Query DevTools](./img/react-query-devtools.png)
![React-Query DevTools](./img/react-query-devtools.png)
12 changes: 6 additions & 6 deletions docs/Upgrade.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ React-admin v4 uses MUI (Material-UI) v5. The MUI team has written an upgrade gu

## Redux Is Gone

React-admin no longer relies on Redux. Instead, it relies on [React context](https://reactjs.org/docs/context.html) and third-party libraries (e.g. [react-query](https://react-query.tanstack.com/)).
React-admin no longer relies on Redux. Instead, it relies on [React context](https://reactjs.org/docs/context.html) and third-party libraries (e.g. [react-query](https://react-query-v3.tanstack.com/)).

You will need to update your code if it contains any of the following keywords:

Expand Down Expand Up @@ -665,7 +665,7 @@ To upgrade, check every instance of your code of the following hooks:

And update the calls. If you're using TypeScript, your code won't compile until you properly upgrade the calls.

These hooks are now powered by react-query, so the state argument contains way more than just `isLoading` (`reset`, `status`, `refetch`, etc.). Check the [`useQuery`](https://react-query.tanstack.com/reference/useQuery) and the [`useMutation`](https://react-query.tanstack.com/reference/useMutation) documentation on the react-query website for more details.
These hooks are now powered by react-query, so the state argument contains way more than just `isLoading` (`reset`, `status`, `refetch`, etc.). Check the [`useQuery`](https://react-query-v3.tanstack.com/reference/useQuery) and the [`useMutation`](https://react-query-v3.tanstack.com/reference/useMutation) documentation on the react-query website for more details.

### `useQuery`, `useMutation`, and `useQueryWithStore` Have Been Removed

Expand Down Expand Up @@ -738,7 +738,7 @@ const BanUserButton = ({ userId }) => {
};
```

Refer to [the react-query documentation](https://react-query.tanstack.com/overview) for more information.
Refer to [the react-query documentation](https://react-query-v3.tanstack.com/overview) for more information.

### `<Query>` and `<Mutation>` Have Been Removed

Expand Down Expand Up @@ -804,7 +804,7 @@ const BanUserButton = ({ userId }) => {
};
```

Refer to [the react-query documentation](https://react-query.tanstack.com/overview) for more information.
Refer to [the react-query documentation](https://react-query-v3.tanstack.com/overview) for more information.


### Application Cache No Longer Uses `validUntil`
Expand Down Expand Up @@ -981,7 +981,7 @@ const BookDetail = ({ id }) => {

In general, you should use `isLoading`. It's false as long as the data has never been loaded (whether from the dataProvider or from the cache).

The new props are actually returned by react-query's `useQuery` hook. Check [their documentation](https://react-query.tanstack.com/reference/useQuery) for more information.
The new props are actually returned by react-query's `useQuery` hook. Check [their documentation](https://react-query-v3.tanstack.com/reference/useQuery) for more information.


## Auth Provider
Expand Down Expand Up @@ -1612,7 +1612,7 @@ export const PostList = () => (

### `useGetMainList` Was Removed

`useGetMainList` was a modified version of `useGetList` designed to keep previous data on screen upon navigation. As [this is now supported natively by react-query](https://react-query.tanstack.com/guides/paginated-queries#better-paginated-queries-with-keeppreviousdata), this hook is no longer necessary and has been removed. Use `useGetList()` instead.
`useGetMainList` was a modified version of `useGetList` designed to keep previous data on screen upon navigation. As [this is now supported natively by react-query](https://react-query-v3.tanstack.com/guides/paginated-queries#better-paginated-queries-with-keeppreviousdata), this hook is no longer necessary and has been removed. Use `useGetList()` instead.

### `useUnselectAll` Syntax Changed

Expand Down
6 changes: 3 additions & 3 deletions docs/useGetOne.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ const { data, isLoading, error, refetch } = useGetOne(

The `meta` argument is optional. It can be anything you want to pass to the data provider, e.g. a list of fields to show in the result.

The `options` parameter is optional, and is passed to [react-query's `useQuery` hook](https://react-query.tanstack.com/reference/useQuery). It may contain the following options:
The `options` parameter is optional, and is passed to [react-query's `useQuery` hook](https://react-query-v3.tanstack.com/reference/useQuery). It may contain the following options:

* `cacheTime`
* `enabled`
Expand Down Expand Up @@ -49,9 +49,9 @@ The `options` parameter is optional, and is passed to [react-query's `useQuery`
* `suspense`
* `useErrorBoundary`

Check [react-query's `useQuery` hook documentation](https://react-query.tanstack.com/reference/useQuery) for details on each of these options.
Check [react-query's `useQuery` hook documentation](https://react-query-v3.tanstack.com/reference/useQuery) for details on each of these options.

The react-query [query key](https://react-query.tanstack.com/guides/query-keys) for this hook is `[resource, 'getOne', { id: String(id), meta }]`.
The react-query [query key](https://react-query-v3.tanstack.com/guides/query-keys) for this hook is `[resource, 'getOne', { id: String(id), meta }]`.

## Usage

Expand Down
2 changes: 1 addition & 1 deletion packages/ra-core/src/dataProvider/useCreate.ts
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ import { RaRecord, CreateParams } from '../types';
* This hook uses react-query useMutation under the hood.
* This means the state object contains mutate, isIdle, reset and other react-query methods.
*
* @see https://react-query.tanstack.com/reference/useMutation
* @see https://react-query-v3.tanstack.com/reference/useMutation
*
* @example // set params when calling the create callback
*
Expand Down
6 changes: 3 additions & 3 deletions packages/ra-core/src/dataProvider/useDelete.ts
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ import { RaRecord, DeleteParams, MutationMode } from '../types';
* This hook uses react-query useMutation under the hood.
* This means the state object contains mutate, isIdle, reset and other react-query methods.
*
* @see https://react-query.tanstack.com/reference/useMutation
* @see https://react-query-v3.tanstack.com/reference/useMutation
*
* @example // set params when calling the deleteOne callback
*
Expand Down Expand Up @@ -289,7 +289,7 @@ export const useDelete = <
previousData: callTimePreviousData = previousData,
} = callTimeParams;

// optimistic update as documented in https://react-query.tanstack.com/guides/optimistic-updates
// optimistic update as documented in https://react-query-v3.tanstack.com/guides/optimistic-updates
// except we do it in a mutate wrapper instead of the onMutate callback
// to have access to success side effects

Expand All @@ -310,7 +310,7 @@ export const useDelete = <
* [['posts', 'getMany'], [{ id: 1, title: 'Hello' }]],
* ]
*
* @see https://react-query.tanstack.com/reference/QueryClient#queryclientgetqueriesdata
* @see https://react-query-v3.tanstack.com/reference/QueryClient#queryclientgetqueriesdata
*/
snapshot.current = queryKeys.reduce(
(prev, curr) => prev.concat(queryClient.getQueriesData(curr)),
Expand Down
6 changes: 3 additions & 3 deletions packages/ra-core/src/dataProvider/useDeleteMany.ts
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ import { RaRecord, DeleteManyParams, MutationMode } from '../types';
* This hook uses react-query useMutation under the hood.
* This means the state object contains mutate, isIdle, reset and other react-query methods.
*
* @see https://react-query.tanstack.com/reference/useMutation
* @see https://react-query-v3.tanstack.com/reference/useMutation
*
* @example // set params when calling the deleteMany callback
*
Expand Down Expand Up @@ -297,7 +297,7 @@ export const useDeleteMany = <

const { ids: callTimeIds = ids } = callTimeParams;

// optimistic update as documented in https://react-query.tanstack.com/guides/optimistic-updates
// optimistic update as documented in https://react-query-v3.tanstack.com/guides/optimistic-updates
// except we do it in a mutate wrapper instead of the onMutate callback
// to have access to success side effects

Expand All @@ -318,7 +318,7 @@ export const useDeleteMany = <
* [['posts', 'getMany'], [{ id: 1, title: 'Hello' }]],
* ]
*
* @see https://react-query.tanstack.com/reference/QueryClient#queryclientgetqueriesdata
* @see https://react-query-v3.tanstack.com/reference/QueryClient#queryclientgetqueriesdata
*/
snapshot.current = queryKeys.reduce(
(prev, curr) => prev.concat(queryClient.getQueriesData(curr)),
Expand Down
Loading