Add support for offline/local first applications

cypress/e2e/edit.cy.js

@@ -47,7 +47,11 @@ describe('Edit Page', () => {
         it('should redirect to list page after edit success', () => {
             // For some unknown reason, the click on submit didn't work in cypress
             // so we submit with enter
-            EditPostPage.setInputValue('input', 'title', 'Lorem Ipsum{enter}');
+            EditPostPage.setInputValue(
+                'input',
+                'title',
+                'Lorem Ipsum again{enter}'
+            );
             cy.url().should('match', /\/#\/posts$/);
         });
 

cypress/support/CreatePage.js

@@ -11,13 +11,14 @@ export default url => ({
         inputs: `.ra-input`,
         richTextInputError: '.create-page .ra-rich-text-input-error',
         snackbar: 'div[role="alert"]',
-        submitButton: ".create-page div[role='toolbar'] button[type='submit']",
+        submitButton:
+            ".create-page div[role='toolbar'] div:first-child button[type='submit']",
         submitAndShowButton:
-            ".create-page form div[role='toolbar'] button[type='button']:nth-child(2)",
+            ".create-page form div[role='toolbar'] div:first-child button[type='button']:nth-child(2)",
         submitAndAddButton:
-            ".create-page form div[role='toolbar'] button[type='button']:nth-child(3)",
+            ".create-page form div[role='toolbar'] div:first-child button[type='button']:nth-child(3)",
         submitCommentable:
-            ".create-page form div[role='toolbar'] button[type='button']:last-child",
+            ".create-page form div[role='toolbar'] div:first-child button[type='button']:last-child",
         descInput: '.ProseMirror',
         tab: index => `.form-tab:nth-of-type(${index})`,
         title: '#react-admin-title',

docs/DataProviders.md

@@ -884,3 +884,129 @@ 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.
+
+## Offline Support
+
+React Query supports offline/local-first applications. To enable it in your React Admin application, install the required React Query packages:
+
+```sh
+yarn add @tanstack/react-query-persist-client @tanstack/query-sync-storage-persister
+```
+
+Then, register default functions for React Admin mutations on the `QueryClient` to enable resumable mutations (mutations triggered while offline). React Admin provides the `addOfflineSupportToQueryClient` function for this:
+
+```ts
+// in src/queryClient.ts
+import { addOfflineSupportToQueryClient } from 'react-admin';
+import { QueryClient } from '@tanstack/react-query';
+import { dataProvider } from './dataProvider';
+
+export const queryClient = new QueryClient();
+
+addOfflineSupportToQueryClient({
+    queryClient,
+    dataProvider,
+    resources: ['posts', 'comments'],
+});
+```
+
+Then, wrap your `<Admin>` inside a [`<PersistQueryClientProvider>`](https://tanstack.com/query/latest/docs/framework/react/plugins/persistQueryClient#persistqueryclientprovider):
+
+{% raw %}
+```tsx
+// in src/App.tsx
+import { Admin, Resource } from 'react-admin';
+import { PersistQueryClientProvider } from '@tanstack/react-query-persist-client';
+import { createSyncStoragePersister } from '@tanstack/query-sync-storage-persister';
+import { queryClient } from './queryClient';
+import { dataProvider } from './dataProvider';
+import { posts } from './posts';
+import { comments } from './comments';
+
+const localStoragePersister = createSyncStoragePersister({
+    storage: window.localStorage,
+});
+
+export const App = () => (
+    <PersistQueryClientProvider
+        client={queryClient}
+        persistOptions={{ persister: localStoragePersister }}
+        onSuccess={() => {
+            // resume mutations after initial restore from localStorage is successful
+            queryClient.resumePausedMutations();
+        }}
+    >
+        <Admin queryClient={queryClient} dataProvider={dataProvider}>
+            <Resource name="posts" {...posts} />
+            <Resource name="comments" {...comments} />
+        </Admin>
+    </PersistQueryClientProvider>
+)
+```
+{% endraw %}
+
+If you have [custom mutations](./Actions.md#calling-custom-methods) on your dataProvider, you can enable offline support for them too. For instance, if your `dataProvider` exposes a `banUser()` method:
+
+```ts
+const dataProvider = {
+    getList: /* ... */,
+    getOne: /* ... */,
+    getMany: /* ... */,
+    getManyReference: /* ... */,
+    create: /* ... */,
+    update: /* ... */,
+    updateMany: /* ... */,
+    delete: /* ... */,
+    deleteMany: /* ... */,
+    banUser: (userId: string) => {
+        return fetch(`/api/user/${userId}/ban`, { method: 'POST' })
+            .then(response => response.json());
+    },
+}
+
+export type MyDataProvider = DataProvider & {
+    banUser: (userId: string) => Promise<{ data: RaRecord }>
+}
+```
+
+First, you must set a `mutationKey` for this mutation:
+
+{% raw %}
+```tsx
+const BanUserButton = ({ userId }: { userId: string }) => {
+    const dataProvider = useDataProvider();
+    const { mutate, isPending } = useMutation({
+        mutationKey: 'banUser'
+        mutationFn: (userId) => dataProvider.banUser(userId)
+    });
+    return <Button label="Ban" onClick={() => mutate(userId)} disabled={isPending} />;
+};
+```
+{% endraw %}
+
+**Tip**: Note that unlike the [_Calling Custom Methods_ example](./Actions.md#calling-custom-methods), we passed `userId` to the `mutate` function. This is necessary so that React Query passes it too to the default function when resuming the mutation.
+
+Then, register a default function for it:
+
+```ts
+// in src/queryClient.ts
+import { addOfflineSupportToQueryClient } from 'react-admin';
+import { QueryClient } from '@tanstack/react-query';
+import { PersistQueryClientProvider } from '@tanstack/react-query-persist-client';
+import { createSyncStoragePersister } from '@tanstack/query-sync-storage-persister';
+import { dataProvider } from './dataProvider';
+
+export const queryClient = new QueryClient();
+
+addOfflineSupportToQueryClient({
+    queryClient,
+    dataProvider,
+    resources: ['posts', 'comments'],
+});
+
+queryClient.setMutationDefaults('banUser', {
+    mutationFn: async (userId) => {
+        return dataProviderFn.banUser(userId);
+    },
+});
+```

examples/simple/package.json

@@ -12,8 +12,10 @@
     "dependencies": {
         "@mui/icons-material": "^5.16.12",
         "@mui/material": "^5.16.12",
+        "@tanstack/query-sync-storage-persister": "5.47.0",
         "@tanstack/react-query": "^5.21.7",
         "@tanstack/react-query-devtools": "^5.21.7",
+        "@tanstack/react-query-persist-client": "5.47.0",
         "jsonexport": "^3.2.0",
         "lodash": "~4.17.5",
         "ra-data-fakerest": "^5.8.0",

examples/simple/src/Layout.tsx

@@ -1,21 +1,84 @@
 import * as React from 'react';
 import { ReactQueryDevtools } from '@tanstack/react-query-devtools';
-import { AppBar, Layout, InspectorButton, TitlePortal } from 'react-admin';
+import {
+    AppBar,
+    Layout,
+    InspectorButton,
+    TitlePortal,
+    useNotify,
+} from 'react-admin';
+import { onlineManager, useQueryClient } from '@tanstack/react-query';
+import { Stack, Tooltip } from '@mui/material';
+import OfflineIcon from '@mui/icons-material/SignalWifiConnectedNoInternet4';
 import '../assets/app.css';
 
-const MyAppBar = () => (
-    <AppBar>
-        <TitlePortal />
-        <InspectorButton />
-    </AppBar>
-);
+const MyAppBar = () => {
+    const isOnline = useIsOnline();
+    return (
+        <AppBar>
+            <TitlePortal />
+            <Stack direction="row" spacing={1}>
+                {!isOnline ? (
+                    <Tooltip title="Offline">
+                        <OfflineIcon
+                            sx={{
+                                color: 'warning.main',
+                                width: 24,
+                                height: 24,
+                            }}
+                        />
+                    </Tooltip>
+                ) : null}
+            </Stack>
+            <InspectorButton />
+        </AppBar>
+    );
+};
 
-export default ({ children }) => (
+export const MyLayout = ({ children }) => (
     <>
-        <Layout appBar={MyAppBar}>{children}</Layout>
+        <Layout appBar={MyAppBar}>
+            {children}
+            <NotificationsFromQueryClient />
+        </Layout>
         <ReactQueryDevtools
             initialIsOpen={false}
             buttonPosition="bottom-left"
         />
     </>
 );
+
+const useIsOnline = () => {
+    const [isOnline, setIsOnline] = React.useState(onlineManager.isOnline());
+
+    React.useEffect(() => {
+        const handleChange = () => {
+            setIsOnline(onlineManager.isOnline());
+        };
+        return onlineManager.subscribe(handleChange);
+    }, []);
+
+    return isOnline;
+};
+
+/**
+ * When react-query resumes persisted mutations through their default functions (provided in the getOfflineFirstQueryClient file) after the browser tab
+ * has been closed, it cannot handle their side effects unless we set up some defaults. In order to leverage the react-admin notification system
+ * we add a default onSettled function to the mutation defaults here.
+ */
+const NotificationsFromQueryClient = () => {
+    const queryClient = useQueryClient();
+    const notify = useNotify();
+
+    React.useEffect(() => {
+        queryClient.setMutationDefaults([], {
+            onSettled(data, error) {
+                if (error) {
+                    notify(error.message, { type: 'error' });
+                }
+            },
+        });
+    }, [queryClient, notify]);
+
+    return null;
+};