Add support for offline/local first applications #10545

djhi · 2025-02-24T13:15:50Z

Problem

React-admin currently don't handle well the loss of network connectivity: in any demo, if you go to a list page, then simulate being offline using the devtool and try to go to the second page of the same list, it will still display the first page data while the pagination will indeed indicate you are on page 2.

We handled it a bit better by at least showing users a notification when they try to load new data while offline but we can do better and allow for resumable mutations.

Solution

Screenshots

Edit view

Show view

DataTable (same for all list child components

How To Test

Open the simple example
Use the browser devtool to go offline
Click the posts create button and fill it
Go back to the posts list after and notice the new item is there
Open the devtool and note there is no create call to the dataProvider
Use the browser devtool to go online
Open the devtool and note there is a create call to the dataProvider

Then:

Follow the same steps but select the optimistic option in the form toolbar first.
Follow the same steps but click the undoable option in the form toolbar first.
Follow the same steps but edit a record instead of creating it.
Follow the same steps for both edit and create but enter f00bar as the post title to trigger an error once the network is online.

In stories for list components, reference components and detail views, simply switch to offline and hit the storybook refresh button

Additional Checks

The PR targets master for a bugfix, or next for a feature
The PR includes unit tests (if not possible, describe why)
The PR includes one or several stories (if not possible, describe why)
The documentation is up to date

Also, please make sure to read the contributing guidelines.

djhi · 2025-02-25T08:30:28Z

cypress/e2e/edit.cy.js

+            EditPostPage.setInputValue(
+                'input',
+                'title',
+                'Lorem Ipsum again{enter}'


Because react-query now persist queries and mutations for offline mode, the previous test now leaks into the second (e.g. this post has its title changed to Lorem Ipsum). I tried to configure testIsolation in Cypress but our version is probably too old

packages/ra-core/src/controller/list/useListController.ts

djhi · 2025-04-30T12:26:44Z

I can't see a way to test this except e2e. Not sure if we can simulate network loss with cypress though

slax57 · 2025-04-30T12:35:32Z

@djhi since the simple demo has the react-query DevTools enabled, you can use them to simulate network loss I believe (clicking on the 'Wifi' icon does the job). A bit ugly but it should work!

erwanMarmelab

Praise: very understandable doc !!

docs/DataProviders.md

packages/ra-core/src/controller/input/useReferenceInputController.ts

slax57

Only reviewed the docs and the simple demo so far...

docs/DataProviders.md

examples/simple/package.json

examples/simple/src/Layout.tsx

Madeorsk · 2025-06-26T08:03:50Z

docs/DataProviders.md

+
+export const queryClient = new QueryClient();
+
+const queryClientWithOfflineSupport = addOfflineSupportToQueryClient({


What's the point of queryClientWithOfflineSupport variable? Why is it not exported instead of queryClient? Is queryClient mutated when you use addOfflineSupportToQueryClient, so exporting it is not required? Current variable naming makes me think that queryClient doesn't have offline support.

EDIT: in following examples, it's much clearer.

Suggested change

const queryClientWithOfflineSupport = addOfflineSupportToQueryClient({

const baseQueryClient = new QueryClient();

export const queryClient = addOfflineSupportToQueryClient({

queryClient,

dataProvider,

resources: ['posts', 'comments'],

});

Madeorsk · 2025-06-26T08:23:03Z

examples/simple/src/comments/CommentList.tsx

    const translate = useTranslate();

+    if (isPaused && (data == null || isPlaceholderData)) return <Offline />;


Maybe add a quick example about this in docs? At least something mentioning that you can use isPaused and isPlaceholderData to detect that you're in offline mode.

examples/simple/src/posts/PostCreate.tsx

Madeorsk · 2025-06-26T08:44:31Z

packages/ra-core/src/controller/input/useReferenceArrayInputController.ts

@@ -61,6 +61,7 @@ export const useReferenceArrayInputController = <
        error: errorGetMany,
        isLoading: isLoadingGetMany,
        isFetching: isFetchingGetMany,
+        isPaused: isPausedGetMany,
        isPending: isPendingGetMany,
        refetch: refetchGetMany,
    } = useGetManyAggregate<RecordType>(


No isPlaceholderData here? What's the difference with useReferenceArrayFieldController?

Madeorsk · 2025-06-26T08:55:51Z

packages/ra-core/src/dataProvider/addOfflineSupportToQueryClient.ts

+ *     </PersistQueryClientProvider>
+ * );
+ *
+ * @example <caption>Adding offline support with custom mutations</caption>


Aren't these examples mixed up? The first one shows with a custom mutation and the second one without it.

Madeorsk · 2025-06-26T09:36:58Z

packages/ra-ui-materialui/src/Offline.tsx

+    }
+
+    interface ComponentsPropsList {
+        RaOffline: Partial<Offline>;


Use [PREFIX] instead of 'RaOffline'.

Madeorsk · 2025-06-26T09:37:22Z

packages/ra-ui-materialui/src/Offline.tsx

+
+    interface Components {
+        RaOffline?: {
+            defaultProps?: ComponentsPropsList['RaOffline'];


Use typeof PREFIX instead of 'RaOffline'.

Madeorsk · 2025-06-26T09:55:52Z

packages/ra-ui-materialui/src/input/ReferenceInput.stories.tsx

+    </Edit>
+);
+
+export const Offline = ({ dataProvider = dataProviderWithAuthors }) => (


Tested it and the default AutocompleteInput shows "Loading..." instead of the offline component that I expected. I think you need to change useChoicesContext to propagate isPaused and isPlaceholderData to show a better message in offline mode.

Madeorsk · 2025-06-26T10:04:19Z

packages/ra-ui-materialui/src/layout/LoadingIndicator.tsx

+                        title={
+                            <Translate
+                                i18nKey="ra.notifications.pending_operations"
+                                options={{ smart_count: 1 }}


Why { smart_count: 1 }? Shouldn't it be { smart_count: pendingMutations.length }?

Madeorsk · 2025-06-26T10:11:05Z

packages/ra-ui-materialui/src/list/SingleFieldList.stories.tsx

+);
+
+export const Offline = () => (
+    <Wrapper listContext={{ isPaused: true }}>


This story shows nothing. Is it supposed to show the offline component?

slax57

Reviewing the whole PR was hard because it's very big and impacts many components. Likewise, I guess it's hard to keep track of the review comments.

Thant's why I tried to mark as Resolved all comments that I believe are already addressed, but there are still some here and there that still need discussion. So I recommend you go through all of them once more to make sure you're not missing something important.

I also share the comments about inconsistencies regarding isPlaceholderData, for instance I don't understand why useReferenceOneFieldController uses it but not useEditController? Can you clarify your rationale a bit?

That being said, according to my tests, all features work as expected! So well done!! 💪

slax57 · 2025-07-07T15:09:15Z

yarn.lock

+"@tanstack/query-core@npm:5.81.2":
+  version: 5.81.2
+  resolution: "@tanstack/query-core@npm:5.81.2"
+  checksum: 36a6bddec2e7512015bcfbb0d7b0876fab418de9e0ef21ad403598276960e0b7d53efd62832ce462738ad22d9883e31cb5403eafc65dfd9b2f6744c22a9d8e42
+  languageName: node
+  linkType: hard


needs dedupe

slax57 · 2025-07-07T15:10:04Z

docs/DataProviders.md

+
+## Handling Errors For Resumed Mutations
+
+If you enabled offline support, users might trigger mutations while being actually offline. When they're back online, react-query will _resume_ those mutations and they might fail for other reasons (server side validation or errors). However, as users might have navigated away from the page that triggered the mutation, they won't see any notification.


Suggested change

If you enabled offline support, users might trigger mutations while being actually offline. When they're back online, react-query will _resume_ those mutations and they might fail for other reasons (server side validation or errors). However, as users might have navigated away from the page that triggered the mutation, they won't see any notification.

If you enabled offline support, users might trigger mutations while being actually offline. When they're back online, TanStack Query will _resume_ those mutations and they might fail for other reasons (server side validation or errors). However, as users might have navigated away from the page that triggered the mutation, they won't see any notification.

slax57 · 2025-07-07T15:14:30Z

packages/ra-core/src/core/useIsOffine.ts

+    React.useEffect(() => {
+        const handleChange = () => {
+            setIsOnline(onlineManager.isOnline());
+        };
+        return onlineManager.subscribe(handleChange);
+    }, []);


This code looks odd... Shouldn't you subscribe on mount and unsubscribe on unmount? 🤔

slax57 · 2025-07-07T15:15:33Z

docs/DataProviders.md

+    const notify = useNotify();
+
+    React.useEffect(() => {
+        const mutationKeyFilter = []; // An empty array targets all mutations 


mutationKeyFilter is used nowhere I believe 🤔

slax57 · 2025-07-08T12:47:54Z

packages/ra-core/src/dataProvider/useCreate.ts

+    useEffect(() => {
+        mode.current = mutationMode;
+    }, [mutationMode]);


Why do you need that? 🤔

Why only in useCreate? 🤔

slax57 · 2025-07-08T13:03:38Z

packages/ra-ui-materialui/src/Offline.tsx

+    if (!resource) {
+        throw new Error(
+            '<Offline> must be used inside a <Resource> component or provided a resource prop'
+        );
+    }


This limitation seems odd. If it is only required for the translation string, I think there are easy solutions to remove this limitation.

slax57 · 2025-07-08T14:16:38Z

packages/ra-ui-materialui/src/input/ReferenceArrayInput.tsx

+            label={props.label}
+            resource={props.resource}
+        >
+            {offline ?? <Offline variant="inline" />}


why inline? 🤔

slax57 · 2025-07-08T15:55:00Z

packages/ra-ui-materialui/src/field/ReferenceOneField.tsx

+    if (controllerProps.isPaused && controllerProps.referenceRecord == null) {
+        return offline;
+    }
+


It would be nice to have a story to test this component too 😇

djhi added the WIP Work In Progress label Feb 24, 2025

vercel bot deployed to Preview – react-admin-storybook February 24, 2025 21:58 View deployment

vercel bot deployed to Preview – react-admin-storybook February 24, 2025 22:20 View deployment

djhi commented Feb 25, 2025

View reviewed changes

vercel bot deployed to Preview – react-admin-storybook February 25, 2025 08:31 View deployment

djhi added 4 commits March 20, 2025 17:50

Add support for offline/local first applications

aaf7860

Ensure no existing tests are broken

2aa2cba

Try stabilizing tests

a1b2157

Fix e2e tests

9d66e05

djhi force-pushed the support-offline-mode branch from d440e8e to 9d66e05 Compare March 20, 2025 16:53

vercel bot deployed to Preview – react-admin-storybook March 20, 2025 16:57 View deployment

djhi added 2 commits April 25, 2025 16:12

Introduce addOfflineSupportToQueryClient

fe15863

Add documentation

1abc446

vercel bot deployed to Preview – react-admin-storybook April 25, 2025 14:16 View deployment

Trigger build

25ff38b

vercel bot deployed to Preview – react-admin-storybook April 25, 2025 15:12 View deployment

djhi commented Apr 25, 2025

View reviewed changes

packages/ra-core/src/controller/list/useListController.ts Show resolved Hide resolved

slax57 added 2 commits April 29, 2025 10:33

Merge remote-tracking branch 'origin/next' into support-offline-mode

9f83cab

fix merge issues

eae5aa6

vercel bot deployed to Preview – react-admin-storybook April 29, 2025 08:50 View deployment

Merge branch 'next' into support-offline-mode

87e537a

djhi added RFR Ready For Review and removed WIP Work In Progress labels Apr 30, 2025

Cleanup documentation

b0bc9a0

vercel bot deployed to Preview – react-admin-storybook April 30, 2025 11:42 View deployment

Fix e2e tests

cf79b3b

vercel bot deployed to Preview – react-admin-storybook April 30, 2025 12:27 View deployment

erwanMarmelab reviewed May 5, 2025

View reviewed changes

docs/DataProviders.md Show resolved Hide resolved

packages/ra-core/src/controller/input/useReferenceInputController.ts Outdated Show resolved Hide resolved

djhi added 2 commits June 10, 2025 12:09

Improve documentation

8384ca3

Improve notifications for offline mutations

02dbe24

vercel bot deployed to Preview – react-admin-storybook June 20, 2025 08:11 View deployment

Merge branch 'next' into support-offline-mode

0ee8837

vercel bot deployed to Preview – react-admin-storybook June 25, 2025 13:25 View deployment

djhi added 2 commits June 25, 2025 16:12

Fix delete mutations success message handling

b648d08

Fix ReferenceOneField empty case handling

929d606

vercel bot deployed to Preview – react-admin-storybook June 25, 2025 14:16 View deployment

slax57 reviewed Jun 25, 2025

View reviewed changes

docs/DataProviders.md Outdated Show resolved Hide resolved

examples/simple/package.json Outdated Show resolved Hide resolved

examples/simple/src/Layout.tsx Show resolved Hide resolved

Madeorsk requested changes Jun 26, 2025

View reviewed changes

djhi added 9 commits June 26, 2025 14:35

Fix simple example dependencies

1154f17

Fix JSDoc examples

5b7f83a

Remove unnecessary CSS classes

d114f96

Fix Offline types

30a5ec0

Fix LoadingIndicator

68d00a7

Fix SingleFieldList story

ed0f0df

Fix ReferenceInput offline detection

d0586a1

Fix reference fields and inputs

b03dfb4

Improve documentation

dbd8dd1

vercel bot had a problem deploying to Preview – react-admin-storybook June 26, 2025 15:05 Failure

Fix yarn.lock

b8b13c5

vercel bot deployed to Preview – react-admin-storybook June 26, 2025 15:13 View deployment

Document how to handle errors for resumed mutations

a3b1da8

vercel bot deployed to Preview – react-admin-storybook June 26, 2025 15:46 View deployment

slax57 self-requested a review July 7, 2025 10:05

slax57 requested changes Jul 8, 2025

View reviewed changes

djhi added 3 commits July 9, 2025 17:09

Dedupe @tanstack/query-core

4413807

Improve DataProviders documentation

3fda18b

Fix following tanstack/query-core upgrade

66416c1

vercel bot deployed to Preview – react-admin-storybook July 10, 2025 06:57 View deployment


		export const queryClient = new QueryClient();

		const queryClientWithOfflineSupport = addOfflineSupportToQueryClient({

-const queryClientWithOfflineSupport = addOfflineSupportToQueryClient({
+const baseQueryClient = new QueryClient();
+export const queryClient = addOfflineSupportToQueryClient({
+    queryClient,
+    dataProvider,
+    resources: ['posts', 'comments'],
+});

		const translate = useTranslate();

		if (isPaused && (data == null \|\| isPlaceholderData)) return <Offline />;


		## Handling Errors For Resumed Mutations

		If you enabled offline support, users might trigger mutations while being actually offline. When they're back online, react-query will _resume_ those mutations and they might fail for other reasons (server side validation or errors). However, as users might have navigated away from the page that triggered the mutation, they won't see any notification.

Uh oh!

Add support for offline/local first applications #10545

Are you sure you want to change the base?

Add support for offline/local first applications #10545

Uh oh!

Conversation

djhi commented Feb 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Problem

Solution

Screenshots

How To Test

Additional Checks

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

djhi commented Apr 30, 2025

Uh oh!

slax57 commented Apr 30, 2025

Uh oh!

erwanMarmelab left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

slax57 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

slax57 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

djhi commented Feb 24, 2025 •

edited

Loading