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

fzaninotto · 2025-05-19T09:36:34Z

The 'how to test' instructions must be updated, as the tester must select the optimistic mutation mode before submitting the form.

fzaninotto · 2025-05-19T09:39:03Z

When doing an optimistic offline mutation, the loader in the app bar keeps spinning forever even tough the optimistic update is already applied. Is it a good UI? Instead, I think we should have a way to mention the pending updates, e.g. using a badge on the loader icon.

fzaninotto

We're getting closer!

fzaninotto · 2025-05-19T09:27:23Z

examples/simple/src/Layout.tsx

-    </AppBar>
-);
+const MyAppBar = () => {
+    const isOnline = useIsOnline();


I'd name the hook useIsOffline instead, since you only ever check that it's false.

docs/DataProviders.md

fzaninotto · 2025-05-19T10:37:37Z

docs/DataProviders.md

+)
+```
+{% endraw %}
+


You're missing a sentence to explain that the setup is done here - the rest is only for developers with custom methods.

docs/Edit.md

fzaninotto · 2025-05-19T11:26:29Z

packages/ra-ui-materialui/src/detail/EditView.tsx

@@ -95,6 +117,10 @@ const Root = styled('div', {
    [`& .${EditClasses.noActions}`]: {
        marginTop: '1em',
    },
+    [`& .${EditClasses.offline}`]: {


Code smell: The Offline component should work as is, without CSS customization.

fzaninotto · 2025-05-19T11:30:41Z

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

-            <div>
+            <Stack direction="row" alignItems="center" gap={1}>
                <ErrorIcon role="presentation" color="error" fontSize="small" />
-                <span style={visuallyHidden}>
-                    {typeof error === 'string' ? error : error?.message}
-                </span>
-            </div>
+                <Typography
+                    component="span"
+                    variant="body2"
+                    sx={{ color: 'error.main' }}
+                >
+                    <Translate i18nKey="ra.notification.http_error">
+                        Server communication error
+                    </Translate>
+                </Typography>
+            </Stack>


You've changed the content and design here. Can you elaborate on why you did that?

We only had an icon for error before with no message for users not using assistive tools. We discussed this together

fzaninotto · 2025-05-19T11:34:04Z

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

+    }
+
+    if (
+        !record ||


this is already in the previous condition

fzaninotto · 2025-05-19T11:55:40Z

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

+            {...rest}
+            offline={
+                offline ?? (
+                    <Labeled {...rest}>


It feels weird to repeat rest several times, plus some aren't compatible with Labeled. I wouldn't apply them here, and pass the source and label props explicitly instead.

fzaninotto · 2025-05-19T12:00:58Z

packages/ra-ui-materialui/src/list/index.ts

@@ -13,6 +13,7 @@ export * from './ListGuesser';
 export * from './ListNoResults';
 export * from './ListToolbar';
 export * from './ListView';
+export * from '../Offline';


reexported from the wrong directory (the .. is weird here)

Co-authored-by: Francois Zaninotto <[email protected]>

djhi · 2025-06-06T14:37:42Z

When doing an optimistic offline mutation, the loader in the app bar keeps spinning forever even tough the optimistic update is already applied. Is it a good UI? Instead, I think we should have a way to mention the pending updates, e.g. using a badge on the loader icon.

The loading indicator now has a badge when users are offline and there are pending mutations. This badge also has a tooltip that explains it.

slax57

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

slax57 · 2025-06-25T15:45:17Z

docs/DataProviders.md

+
+queryClient.setMutationDefaults('banUser', {
+    mutationFn: async (userId) => {
+        return dataProviderFn.banUser(userId);


Suggested change

return dataProviderFn.banUser(userId);

return dataProvider.banUser(userId);

slax57 · 2025-06-25T15:49:05Z

examples/simple/package.json

+        "@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",


Suggested change

"@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",

"@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",

slax57 · 2025-06-25T15:51:08Z

examples/simple/src/Layout.tsx

+/**
+ * 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 = () => {


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.

Madeorsk · 2025-06-26T08:32:28Z

examples/simple/src/posts/PostCreate.tsx

+// be possible if the app was also a PWA.
+// We only do that for optimistic and undoable modes in order to not break any existing tests that expect
+// the id to be generated by the server (e.g. by FakeRest).
+let next_id = 100;


Why 100? You could technically already have another post with ID 100, isn't it?
For client-generated ids, I use negative numbers, to quickly notice that they are not real IDs, and is usually enough to ensure that they are not conflicting with persisted data.

But they are real ids. They won't be replaced on the backend. I would use uuid but that's too much changes of the current data. Besides, we actually control the simple example data and know we don't have ids greater than 100. I believe this is enough to showcase and test the feature

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?

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

fzaninotto requested changes May 19, 2025

View reviewed changes

Apply suggestions from code review

466aeb1

Co-authored-by: Francois Zaninotto <[email protected]>

vercel bot deployed to Preview – react-admin-storybook May 19, 2025 12:55 View deployment

djhi added 10 commits May 19, 2025 15:24

Fix exports

72ff0b1

Fix list children handling of offline state

6d3daeb

Fix detail views handling of offline state

c7b22d6

Fix reference inputs handling of offline state

1be8e73

Fix ReferenceOneField

01a1a94

Improve ReferenceInput

10ae938

Correctly export Offline component

9849a2c

Avoid offline specific styles in details views

4a3cb09

Rename isOnline hook to useIsOffline

84207e0

Improve Offline component design for reference fields and inputs

2e2e10c

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

Make sure users know about pending operations

8452c4f

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

djhi added 3 commits June 10, 2025 12:03

Improve mutation mode selector

a55d5ef

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

Madeorsk requested changes Jun 26, 2025

View reviewed changes

	return dataProviderFn.banUser(userId);
	return dataProvider.banUser(userId);


		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 />;

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!

fzaninotto commented May 19, 2025

Uh oh!

fzaninotto commented May 19, 2025

Uh oh!

fzaninotto left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

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!

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

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!

djhi commented Jun 6, 2025

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

djhi commented Feb 24, 2025 •

edited

Loading

djhi May 19, 2025 •

edited

Loading