From f4c7e187918c51620ac906b0ca873d374a713d46 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Fran=C3=A7ois=20Zaninotto?= <fzaninotto@gmail.com>
Date: Tue, 17 May 2022 22:53:23 +0200
Subject: [PATCH 1/3] [Doc] Fix missing doc for `<Admin queryClient>` prop
---
docs/Admin.md | 72 +++++++++++++++++++++++++++++++++++++++++++
docs/DataProviders.md | 24 +++++++++++++++
2 files changed, 96 insertions(+)
diff --git a/docs/Admin.md b/docs/Admin.md
index 870f010f790..bfe55f895af 100644
--- a/docs/Admin.md
+++ b/docs/Admin.md
@@ -32,6 +32,7 @@ Here are all the props accepted by the component:
- [`dataProvider`](#dataprovider)
- [`authProvider`](#authprovider)
- [`i18nProvider`](#i18nprovider)
+- [`queryClient`](#queryclient)
- [`title`](#title)
- [`dashboard`](#dashboard)
- [`disableTelemetry`](#disabletelemetry)
@@ -95,6 +96,77 @@ The [Auth Provider documentation](./Authentication.md) explains how to implement
The `i18nProvider` props let you translate the GUI. 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):
+
+* Queries consider cached data as stale
+* Stale queries are refetched automatically in the background when:
+ * New instances of the query mount
+ * The window is refocused
+ * The network is reconnected
+ * The query is optionally configured with a refetch interval
+* Query results that are no longer used in the current page are labeled as "inactive" and remain in the cache in case they are used again at a later time.
+* By default, "inactive" queries are garbage collected after 5 minutes.
+* Queries that fail are silently retried 3 times, with exponential backoff delay before capturing and displaying an error to the UI.
+* Query results by default are structurally shared to detect if data has actually changed and if not, the data reference remains unchanged to better help with value stabilization with regards to `useMemo` and `useCallback`.
+
+If you want to override the react-query default query and mutation default options, or use a specific client or mutation cache, you can create your own `QueryClient` instance and pass it to the `<Admin queryClient>` prop:
+
+```jsx
+import { Admin } from 'react-admin';
+import { QueryClient } from 'react-query';
+
+const queryClient = new QueryClient({
+ query: {
+ retry: false,
+ structuralSharing: false,
+ },
+ mutation: {
+ retryDelay: 10000,
+ },
+});
+
+const App = () => (
+ <Admin queryClient={queryClient} dataProvider={...}>
+ ...
+ </Admin>
+);
+```
+
+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.
+
+The common settings that react-admin developers often overwrite are:
+
+```jsx
+import { QueryClient } from 'react-query';
+
+const queryClient = new QueryClient({
+ query: {
+ /**
+ * The time in milliseconds after data is considered stale.
+ * If set to `Infinity`, the data will never be considered stale.
+ */
+ staleTime: 10000,
+ /**
+ * If `false`, failed queries will not retry by default.
+ * If `true`, failed queries will retry infinitely., failureCount: num
+ * If set to an integer number, e.g. 3, failed queries will retry until the failed query count meets that number.
+ * If set to a function `(failureCount, error) => boolean` failed queries will retry until the function returns false.
+ */
+ retry: false,
+ /**
+ * If set to `true`, the query will refetch on window focus if the data is stale.
+ * If set to `false`, the query will not refetch on window focus.
+ * If set to `'always'`, the query will always refetch on window focus.
+ * If set to a function, the function will be executed with the latest data and query to compute the value.
+ * Defaults to `true`.
+ */
+ refetchOnWindowFocus: false,
+ },
+});
+```
+
## `title`
On error pages, the header of an admin app uses 'React Admin' as the main app title. Use the `title` to customize it.
diff --git a/docs/DataProviders.md b/docs/DataProviders.md
index 3c8efadedea..618ad5a6a1b 100644
--- a/docs/DataProviders.md
+++ b/docs/DataProviders.md
@@ -365,6 +365,30 @@ export default App;
**Tip**: This example uses the function version of `setState` (`setDataProvider(() => dataProvider))`) instead of the more classic version (`setDataProvider(dataProvider)`). This is because some legacy Data Providers are actually functions, and `setState` would call them immediately on mount.
+## Default Query Options
+
+If you often need to pass the same query options to the data provider, you can use [the `<Admin queryClient>` prop](./Admin.md#queryclient) to set them globally.
+
+```jsx
+import { Admin } from 'react-admin';
+import { QueryClient } from 'react-query';
+
+const queryClient = new QueryClient({
+ query: {
+ retry: false,
+ staleTime: 10000,
+ },
+});
+
+const App = () => (
+ <Admin queryClient={queryClient} dataProvider={...}>
+ ...
+ </Admin>
+);
+```
+
+To know which query options you can override, check the [Querying the API documentation](./Actions.md#query-options) and [the `<Admin queryClient>` prop documentation](./Admin.md#queryclient).
+
## Combining Data Providers
If you need to build an app relying on more than one API, you may face a problem: the `<Admin>` component accepts only one `dataProvider` prop. You can combine multiple data providers into one using the `combineDataProviders` helper. It expects a function as parameter accepting a resource name and returning a data provider for that resource.
From 6b067d9e7c9345bfdd8d17070b74e45a1bd1768b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Fran=C3=A7ois=20Zaninotto?= <fzaninotto@gmail.com>
Date: Tue, 17 May 2022 22:56:12 +0200
Subject: [PATCH 2/3] Fix wrong syntax
---
docs/Admin.md | 58 +++++++++++++++++++++++--------------------
docs/DataProviders.md | 10 +++++---
2 files changed, 37 insertions(+), 31 deletions(-)
diff --git a/docs/Admin.md b/docs/Admin.md
index bfe55f895af..a3e5234d6ff 100644
--- a/docs/Admin.md
+++ b/docs/Admin.md
@@ -118,12 +118,14 @@ import { Admin } from 'react-admin';
import { QueryClient } from 'react-query';
const queryClient = new QueryClient({
- query: {
- retry: false,
- structuralSharing: false,
- },
- mutation: {
- retryDelay: 10000,
+ defaultOptions: {
+ queries: {
+ retry: false,
+ structuralSharing: false,
+ },
+ mutations: {
+ retryDelay: 10000,
+ },
},
});
@@ -142,27 +144,29 @@ The common settings that react-admin developers often overwrite are:
import { QueryClient } from 'react-query';
const queryClient = new QueryClient({
- query: {
- /**
- * The time in milliseconds after data is considered stale.
- * If set to `Infinity`, the data will never be considered stale.
- */
- staleTime: 10000,
- /**
- * If `false`, failed queries will not retry by default.
- * If `true`, failed queries will retry infinitely., failureCount: num
- * If set to an integer number, e.g. 3, failed queries will retry until the failed query count meets that number.
- * If set to a function `(failureCount, error) => boolean` failed queries will retry until the function returns false.
- */
- retry: false,
- /**
- * If set to `true`, the query will refetch on window focus if the data is stale.
- * If set to `false`, the query will not refetch on window focus.
- * If set to `'always'`, the query will always refetch on window focus.
- * If set to a function, the function will be executed with the latest data and query to compute the value.
- * Defaults to `true`.
- */
- refetchOnWindowFocus: false,
+ defaultOptions: {}
+ queries: {
+ /**
+ * The time in milliseconds after data is considered stale.
+ * If set to `Infinity`, the data will never be considered stale.
+ */
+ staleTime: 10000,
+ /**
+ * If `false`, failed queries will not retry by default.
+ * If `true`, failed queries will retry infinitely., failureCount: num
+ * If set to an integer number, e.g. 3, failed queries will retry until the failed query count meets that number.
+ * If set to a function `(failureCount, error) => boolean` failed queries will retry until the function returns false.
+ */
+ retry: false,
+ /**
+ * If set to `true`, the query will refetch on window focus if the data is stale.
+ * If set to `false`, the query will not refetch on window focus.
+ * If set to `'always'`, the query will always refetch on window focus.
+ * If set to a function, the function will be executed with the latest data and query to compute the value.
+ * Defaults to `true`.
+ */
+ refetchOnWindowFocus: false,
+ },
},
});
```
diff --git a/docs/DataProviders.md b/docs/DataProviders.md
index 618ad5a6a1b..15338fc6b1e 100644
--- a/docs/DataProviders.md
+++ b/docs/DataProviders.md
@@ -374,10 +374,12 @@ import { Admin } from 'react-admin';
import { QueryClient } from 'react-query';
const queryClient = new QueryClient({
- query: {
- retry: false,
- staleTime: 10000,
- },
+ defaultOptions: {
+ queries: {
+ retry: false,
+ staleTime: Infinity,
+ },
+ }
});
const App = () => (
From ba990e3b58948ba123caf56bb98804f40c112991 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Fran=C3=A7ois=20Zaninotto?= <fzaninotto@gmail.com>
Date: Tue, 17 May 2022 22:56:56 +0200
Subject: [PATCH 3/3] Fix typo
---
docs/Admin.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/Admin.md b/docs/Admin.md
index a3e5234d6ff..403155113e1 100644
--- a/docs/Admin.md
+++ b/docs/Admin.md
@@ -144,7 +144,7 @@ The common settings that react-admin developers often overwrite are:
import { QueryClient } from 'react-query';
const queryClient = new QueryClient({
- defaultOptions: {}
+ defaultOptions: {
queries: {
/**
* The time in milliseconds after data is considered stale.