Add a global ErrorBoundary

docs/Admin.md

@@ -136,28 +136,30 @@ Three main props lets you configure the core features of the `<Admin>` component
 
 Here are all the props accepted by the component:
 
-| Prop               | Required | Type           | Default        | Description                                              |
-|------------------- |----------|----------------|----------------|----------------------------------------------------------|
-| `dataProvider`     | Required | `DataProvider` | -              | The data provider for fetching resources                 |
-| `children`         | Required | `ReactNode`    | -              | The routes to render                                     |
-| `authCallbackPage` | Optional | `Component`    | `AuthCallback` | The content of the authentication callback page          |
-| `authProvider`     | Optional | `AuthProvider` | -              | The authentication provider for security and permissions |
-| `basename`         | Optional | `string`       | -              | The base path for all URLs                               |
-| `catchAll`         | Optional | `Component`    | `NotFound`     | The fallback component for unknown routes                |
-| `dashboard`        | Optional | `Component`    | -              | The content of the dashboard page                        |
-| `darkTheme`        | Optional | `object`       | `default DarkTheme` | The dark theme configuration                             |
-| `defaultTheme`     | Optional | `boolean`      | `false`        | Flag to default to the light theme                       |
-| `disableTelemetry` | Optional | `boolean`      | `false`        | Set to `true` to disable telemetry collection            |
-| `i18nProvider`     | Optional | `I18NProvider` | -              | The internationalization provider for translations       |
-| `layout`           | Optional | `Component`    | `Layout`       | The content of the layout                                |
-| `loginPage`        | Optional | `Component`    | `LoginPage`    | The content of the login page                            |
-| `notification`     | Optional | `Component`    | `Notification` | The notification component                               |
-| `queryClient`      | Optional | `QueryClient`  | -              | The react-query client                                   |
-| `ready`            | Optional | `Component`    | `Ready`        | The content of the ready page                            |
-| `requireAuth`      | Optional | `boolean`      | `false`        | Flag to require authentication for all routes            |
-| `store`            | Optional | `Store`        | -              | The Store for managing user preferences                  |
-| `theme`            | Optional | `object`       | `default LightTheme` | The main (light) theme configuration                     |
-| `title`            | Optional | `string`       | -              | The error page title                                     |
+| Prop               | Required | Type                                      | Default              | Description                                                     |
+|------------------- |----------|------------------------------------------ |--------------------- |---------------------------------------------------------------- |
+| `dataProvider`     | Required | `DataProvider`                            | -                    | The data provider for fetching resources                        |
+| `children`         | Required | `ReactNode`                               | -                    | The routes to render                                            |
+| `authCallbackPage` | Optional | `Component`                               | `AuthCallback`       | The content of the authentication callback page                 |
+| `authProvider`     | Optional | `AuthProvider`                            | -                    | The authentication provider for security and permissions        |
+| `basename`         | Optional | `string`                                  | -                    | The base path for all URLs                                      |
+| `catchAll`         | Optional | `Component`                               | `NotFound`           | The fallback component for unknown routes                       |
+| `dashboard`        | Optional | `Component`                               | -                    | The content of the dashboard page                               |
+| `darkTheme`        | Optional | `object`                                  | `default DarkTheme`  | The dark theme configuration                                    |
+| `defaultTheme`     | Optional | `boolean`                                 | `false`              | Flag to default to the light theme                              |
+| `disableTelemetry` | Optional | `boolean`                                 | `false`              | Set to `true` to disable telemetry collection                   |
+| `error`            | Optional | `(props: FallbackProps) => Component`     | -                    | A React component rendered in the content area in case of error |
+| `i18nProvider`     | Optional | `I18NProvider`                            | -                    | The internationalization provider for translations              |
+| `layout`           | Optional | `Component`                               | `Layout`             | The content of the layout                                       |
+| `loginPage`        | Optional | `Component`                               | `LoginPage`          | The content of the login page                                   |
+| `notification`     | Optional | `Component`                               | `Notification`       | The notification component                                      |
+| `onError`          | Optional | `(error: Error, info: ErrorInfo) => void` | -                    | A function called when an error appears                         |
+| `queryClient`      | Optional | `QueryClient`                             | -                    | The react-query client                                          |
+| `ready`            | Optional | `Component`                               | `Ready`              | The content of the ready page                                   |
+| `requireAuth`      | Optional | `boolean`                                 | `false`              | Flag to require authentication for all routes                   |
+| `store`            | Optional | `Store`                                   | -                    | The Store for managing user preferences                         |
+| `theme`            | Optional | `object`                                  | `default LightTheme` | The main (light) theme configuration                            |
+| `title`            | Optional | `string`                                  | -                    | The error page title                                            |
 
 
 ## `dataProvider`
@@ -521,6 +523,70 @@ const App = () => (
 ```
 
 
+## `error`
+
+Whenever some client-side errors happens in react-admin, the user sees an error page. React-admin uses [React's Error Boundaries](https://react.dev/reference/react/Component#catching-rendering-errors-with-an-error-boundary) to render this page when any component in the page throws an unrecoverable error. 
+
+![Default error page](./img/adminError.png)
+
+If you want to customize this page, or log the error to a third-party service, create your own `<Error>` component, and pass it to a custom Layout, as follows:
+
+```jsx
+// in src/App.js
+import { Admin } from 'react-admin';
+import { MyError } from './MyError';
+
+export const MyLayout = ({ children }) => (
+    <Admin error={({ props }) => <MyError {...props} />}>
+        {children}
+    </Admin>
+);
+```
+
+```jsx
+// in src/MyError.js
+import * as React from 'react';
+import Button from '@mui/material/Button';
+import ErrorIcon from '@mui/icons-material/Report';
+import History from '@mui/icons-material/History';
+import { useLocation } from 'react-router-dom';
+
+export const MyError = ({
+    error,
+    resetErrorBoundary,
+    ...rest
+}) => {
+    const { pathname } = useLocation();
+    const originalPathname = useRef(pathname);
+
+    // Effect that resets the error state whenever the location changes
+    useEffect(() => {
+        if (pathname !== originalPathname.current) {
+            resetErrorBoundary();
+        }
+    }, [pathname, resetErrorBoundary]);
+
+    return (
+        <div>
+            <h1><ErrorIcon /> Something Went Wrong </h1>
+            <div>A client error occurred and your request couldn't be completed.</div>
+            <div>
+                <Button
+                    variant="contained"
+                    startIcon={<History />}
+                    onClick={() => history.go(-1)}
+                >
+                    Back
+                </Button>
+            </div>
+        </div>
+    );
+};
+```
+
+**Tip:** Some errors appear in a lower level than the admin. To customize this error page too, you can use the [`<Layout>` `error` prop](./Layout.md#error).
+
+
 ## `i18nProvider`
 
 The `i18nProvider` props let you translate the GUI. For instance, to switch the UI to French instead of the default English:
@@ -691,6 +757,45 @@ const App = () => (
 );
 ```
 
+## `onError`
+
+When a error apears, you can override the react-admin function called to grab some informations as follows:
+
+```jsx
+// in src/App.js
+import * as React from 'react';
+import { Admin } from 'react-admin';
+import { MyError } from './MyError';
+
+export const MyLayout = ({ children }) => {
+    const [errorInfo, setErrorInfo] = React.useState<React.ErrorInfo | undefined>(undefined);
+    return (
+        <Admin 
+            error={({ props }) => <MyError {...props} errorInfo={errorInfo} />}
+            onError={(error: Error, info: ErrorInfo) => setErrorInfo(info)}
+        >
+            {children}
+        </Admin>
+    );
+}
+```
+
+```jsx
+// in src/MyError.js
+import * as React from 'react';
+import ErrorIcon from '@mui/icons-material/Report';
+
+export const MyError = ({errorInfo: React.ErrorInfo}) => (
+    <div>
+        <h1><ErrorIcon /> Something Went Wrong </h1>
+        <div>
+            <p>A client error occurred and your request couldn't be completed.</p>
+            <p>Error informations: {JSON.stringify(errorInfo)}</p>
+        </div>
+    </div>
+);
+```
+
 ## `notification`
 
 You can override the notification component, for instance to change the notification duration. A common use case is to change the `autoHideDuration`, and force the notification to remain on screen longer than the default 4 seconds. For instance, to create a custom Notification component with a 5 seconds default:

docs/Layout.md

@@ -211,6 +211,8 @@ export const MyError = ({
 
 **Tip:** [React's Error Boundaries](https://react.dev/reference/react/Component#catching-rendering-errors-with-an-error-boundary) are used internally to display the Error Page whenever an error occurs. Error Boundaries only catch errors during rendering, in lifecycle methods, and in constructors of the components tree. This implies in particular that errors during event callbacks (such as 'onClick') are not concerned. Also note that the Error Boundary component is only set around the main container of React Admin. In particular, you won't see it for errors thrown by the [sidebar Menu](./Menu.md), nor the [AppBar](#adding-a-custom-context). This ensures the user is always able to navigate away from the Error Page.
 
+**Tip:** Some errors appear in a higher level than the layout. To customize this error page too, you can use the [`<Admin>` `error` prop](./Admin.md#error).
+
 ## `menu`
 
 Lets you override the menu.

packages/ra-core/src/core/CoreAdmin.stories.tsx

@@ -0,0 +1,33 @@
+import * as React from 'react';
+import { Route } from 'react-router';
+import { CoreAdmin } from './CoreAdmin';
+import { CustomRoutes } from './CustomRoutes';
+import { FakeBrowserDecorator } from '../storybook/FakeBrowser';
+
+export default {
+    title: 'ra-core/Admin',
+    decorators: [FakeBrowserDecorator],
+    parameters: {
+        initialEntries: ['/error'],
+    },
+};
+
+const ErrorComponent = () => {
+    throw Error();
+};
+
+export const Error = () => (
+    <CoreAdmin>
+        <CustomRoutes noLayout>
+            <Route path="/error" element={<ErrorComponent />} />
+        </CustomRoutes>
+    </CoreAdmin>
+);
+
+export const CustomError = () => (
+    <CoreAdmin error={() => <h1>Something went wrong...</h1>}>
+        <CustomRoutes noLayout>
+            <Route path="/error" element={<ErrorComponent />} />
+        </CustomRoutes>
+    </CoreAdmin>
+);

packages/ra-core/src/core/CoreAdmin.tsx

@@ -91,6 +91,8 @@ export const CoreAdmin = (props: CoreAdminProps) => {
         dashboard,
         dataProvider,
         disableTelemetry,
+        error,
+        onError,
         i18nProvider,
         queryClient,
         layout,
@@ -117,6 +119,8 @@ export const CoreAdmin = (props: CoreAdminProps) => {
                 catchAll={catchAll}
                 title={title}
                 loading={loading}
+                error={error}
+                onError={onError}
                 loginPage={loginPage}
                 requireAuth={requireAuth}
                 ready={ready}