marmelab · WiXSL · Apr 28, 2023 · Apr 28, 2023 · Apr 28, 2023 · Apr 28, 2023
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,34 @@
 # Changelog
 
+## v4.10.2
+
+* Fix custom redirect in pessimistic `<Edit>` or `<Create>` when using `warnWhenUnsavedChanges` ([#8882](https://github.com/marmelab/react-admin/pull/8882)) ([slax57](https://github.com/slax57))
+* Fix `create-react-admin` package manifest ([#8888](https://github.com/marmelab/react-admin/pull/8888)) ([djhi](https://github.com/djhi))
+* [Doc] Fix `<Menu.ResourceItem>` example should use the `name` prop ([#8886](https://github.com/marmelab/react-admin/pull/8886)) ([septentrion-730n](https://github.com/septentrion-730n))
+* [Doc] Update DataProvider List with `ra-strapi-rest` v4 ([#8865](https://github.com/marmelab/react-admin/pull/8865)) ([nazirov91](https://github.com/nazirov91))
+
+## v4.10.1
+
+* Republish all packages, including the `create-react-admin` installer ([fzaninotto](https://github.com/fzaninotto))
+
+## v4.10.0
+
+Note: This release wasn't published to npm, use version 4.10.1 or higher.
+
+* Add `create-react-admin` installer ([#8833](https://github.com/marmelab/react-admin/pull/8833)) ([djhi](https://github.com/djhi))
+* Add `<InfiniteList>` and `<InfinitePagination>` components ([#8781](https://github.com/marmelab/react-admin/pull/8781)) ([fzaninotto](https://github.com/fzaninotto))
+* Add ability to change the sort, filter and selection of `<ArrayField>` ([#8802](https://github.com/marmelab/react-admin/pull/8802)) ([fzaninotto](https://github.com/fzaninotto))
+* Add ability to configure the remove icon of `<FileInputPreview>` ([#8756](https://github.com/marmelab/react-admin/pull/8756)) ([PennyJeans](https://github.com/PennyJeans))
+* Fix `<Datagrid>` does not apply `className` to its root element (minor BC) ([#8804](https://github.com/marmelab/react-admin/pull/8804)) ([slax57](https://github.com/slax57))
+* Fix `useHandleCallback` sometimes causes infinite redirection loop ([#8861](https://github.com/marmelab/react-admin/pull/8861)) ([djhi](https://github.com/djhi))
+* Fix `<AppBar alwaysOn>` hides sidebar menu on scroll ([#8856](https://github.com/marmelab/react-admin/pull/8856)) ([slax57](https://github.com/slax57))
+* Fix `<SimpleFormIterator>` new item's fields default empty string instead of null ([#8792](https://github.com/marmelab/react-admin/pull/8792)) ([kriskw1999](https://github.com/kriskw1999))
+* [Doc] Fix reference to Material UI ([#8857](https://github.com/marmelab/react-admin/pull/8857)) ([oliviertassinari](https://github.com/oliviertassinari))
+* [Doc] Fix Show documentation misses the `aside` prop ([#8855](https://github.com/marmelab/react-admin/pull/8855)) ([fzaninotto](https://github.com/fzaninotto))
+* [Doc] Convert GIF files to WebM ([#8767](https://github.com/marmelab/react-admin/pull/8767)) ([slax57](https://github.com/slax57))
+* [TypeScript] Add some utilities to improve generics ([#8815](https://github.com/marmelab/react-admin/pull/8815)) ([IAmVisco](https://github.com/IAmVisco))
+* [TypeScript] Improve `useRedirect` and `useCreatePath` types ([#8811](https://github.com/marmelab/react-admin/pull/8811)) ([djhi](https://github.com/djhi))
+
 ## v4.9.4
 
 * Fix GraphQL data provider when using different a custom credential type ([#8847](https://github.com/marmelab/react-admin/pull/8847)) ([@rlucia](https://github.com/rlucia))

diff --git a/cypress/package.json b/cypress/package.json
@@ -1,7 +1,7 @@
 {
     "private": true,
     "name": "e2e",
-    "version": "4.9.0",
+    "version": "4.10.0",
     "scripts": {
         "start": "cypress open",
         "test": "yarn node ./start.js"

diff --git a/docs/AuthProviderList.md b/docs/AuthProviderList.md
@@ -7,15 +7,15 @@ title: "Supported Auth Provider Backends"
 
 It's very common that your auth logic is so specific that you'll need to write your own `authProvider`. However, the community has built a few open-source Auth Providers that may fit your need:
 
-- **[Auth0](https://auth0.com/)**: [ra-auth-auth0](https://github.com/marmelab/ra-auth-auth0)
+- **[Auth0](https://auth0.com/)**: [marmelab/ra-auth-auth0](https://github.com/marmelab/ra-auth-auth0)
 - **[AWS Amplify](https://docs.amplify.aws)**: [MrHertal/react-admin-amplify](https://github.com/MrHertal/react-admin-amplify)
-- **[AWS Cognito](https://docs.aws.amazon.com/cognito/latest/developerguide/setting-up-the-javascript-sdk.html)**: [ra-auth-cognito](https://github.com/marmelab/ra-auth-cognito)
+- **[AWS Cognito](https://docs.aws.amazon.com/cognito/latest/developerguide/setting-up-the-javascript-sdk.html)**: [marmelab/ra-auth-cognito](https://github.com/marmelab/ra-auth-cognito)
+- **[Azure Active Directory (using MSAL)](https://github.com/AzureAD/microsoft-authentication-library-for-js/tree/dev/lib/msal-browser)**: [marmelab/ra-auth-msal](https://github.com/marmelab/ra-auth-msal)
 - **[Directus](https://directus.io/)**: [marmelab/ra-directus](https://github.com/marmelab/ra-directus)
 - **[Firebase Auth (Google, Facebook, GitHub, etc.)](https://firebase.google.com/docs/auth/web/firebaseui)**: [benwinding/react-admin-firebase](https://github.com/benwinding/react-admin-firebase#auth-provider)
-- **[Postgrest](https://postgrest.org/): [raphiniert-com/ra-data-postgrest](https://github.com/raphiniert-com/ra-data-postgrest)
-- **[Supabase](https://supabase.io/)**: [marmelab/ra-supabase](https://github.com/marmelab/ra-supabase)
 - **[Keycloak](https://www.keycloak.org/)**: [marmelab/ra-keycloak](https://github.com/marmelab/ra-keycloak)
-- **[Azure Active Directory (using MSAL)](https://github.com/AzureAD/microsoft-authentication-library-for-js/tree/dev/lib/msal-browser)**: [marmelab/ra-auth-msal](https://github.com/marmelab/ra-auth-msal)
+- **[Postgrest](https://postgrest.org/)**: [raphiniert-com/ra-data-postgrest](https://github.com/raphiniert-com/ra-data-postgrest)
+- **[Supabase](https://supabase.io/)**: [marmelab/ra-supabase](https://github.com/marmelab/ra-supabase)
 - **[SurrealDB](https://surrealdb.com/)**: [djedi23/ra-surrealdb](https://github.com/djedi23/ra-surrealdb)
 
 Beyond ready-to-use providers, you may find help in these third-party tutorials about integrating more authentication backends:

diff --git a/docs/CreateReactAdmin.md b/docs/CreateReactAdmin.md
@@ -0,0 +1,25 @@
+---
+layout: default
+title: "The create-react-admin CLI"
+---
+
+# `create-react-admin`
+
+This CLI generates a new react-admin application using [Vite](https://vitejs.dev/). Use it by running the following command:
+
+```sh
+npx create react-admin@latest your-admin-name
+# or
+yarn create react-admin your-admin-name
+```
+
+It will then ask you to choose:
+- a data provider
+- a auth provider
+- the names of the resources to add
+- the package manager to use to install the dependencies
+
+<video controls autoplay muted loop>
+  <source src="./img/create-react-admin.webm" type="video/webm"/>
+  Your browser does not support the video tag.
+</video>
diff --git a/docs/CustomRoutes.md b/docs/CustomRoutes.md
@@ -143,8 +143,8 @@ import PeopleIcon from '@mui/icons-material/People';
 export const MyMenu = () => (
     <Menu>
         <Menu.DashboardItem />
-        <Menu.ResourceItem to="/posts"  />
-        <Menu.ResourceItem to="/comments" />
+        <Menu.ResourceItem name="posts"  />
+        <Menu.ResourceItem name="comments" />
         <Menu.Item to="/settings" primaryText="Users" leftIcon={<SettingsIcon />}/>
         <Menu.Item to="/profile" primaryText="Miscellaneous" leftIcon={<PeopleIcon />}/>
     </Menu>

diff --git a/docs/DataProviderList.md b/docs/DataProviderList.md
@@ -57,7 +57,7 @@ If you can't find a Data Provider for your backend below, no worries! [Writing a
 * **[SQLite](https://www.sqlite.org/index.html)**: [marmelab/ra-sqlite-dataprovider](https://github.com/marmelab/ra-sqlite-dataprovider)
 * **[REST](https://en.wikipedia.org/wiki/Representational_state_transfer)**: [marmelab/ra-data-simple-rest](https://github.com/marmelab/react-admin/tree/master/packages/ra-data-simple-rest)
 * **[Spring Boot](https://spring.io/projects/spring-boot)**: [vishpat/ra-data-springboot-rest](https://github.com/vishpat/ra-data-springboot-rest) 
-* **[Strapi v3](https://strapi.io/)**: [nazirov91/ra-strapi-rest](https://github.com/nazirov91/ra-strapi-rest)
+* **[Strapi v3/v4](https://strapi.io/)**: [nazirov91/ra-strapi-rest](https://github.com/nazirov91/ra-strapi-rest)
 * **[Strapi v4](https://strapi.io/)**: [garridorafa/ra-strapi-v4-rest](https://github.com/garridorafa/ra-strapi-v4-rest)
 * **[Supabase](https://supabase.io/)**: [marmelab/ra-supabase](https://github.com/marmelab/ra-supabase)
 - **[SurrealDB](https://surrealdb.com/)**: [djedi23/ra-surrealdb](https://github.com/djedi23/ra-surrealdb)

diff --git a/docs/RealtimeDataProvider.md b/docs/RealtimeDataProvider.md
@@ -5,6 +5,16 @@ title: "Realtime DataProvider Requirements"
 
 # Realtime DataProvider Requirements
 
+`ra-realtime` provides helper functions to add real-time capabilities to an existing data provider if you use the following real-time backends:
+
+-  [Supabase](#supabase)
+-  [API Platform](#api-platform)
+-  [Mercure](#mercure)
+
+For other backends, you'll need to write your own implementation. Check the [Writing a custom adapter](#writing-a-custom-adapter) section below for more information.
+
+## Realtime Methods & Signature
+
 To enable real-time features, the `dataProvider` must implement three new methods:
 
 -   `subscribe(topic, callback)`
@@ -20,7 +30,87 @@ In addition, to support the lock features, the `dataProvider` must implement 4 m
 -   `getLock(resource, { id, meta })`
 -   `getLocks(resource, { meta })`
 
-## API-Platform Adapter
+## Supabase
+
+The `ra-realtime` package contains a function augmenting a regular (API-based) `dataProvider` with real-time methods based on the capabilities of [Supabase](https://supabase.com/docs/guides/realtime). 
+
+This adapter subscribes to [Postgres Changes](https://supabase.com/docs/guides/realtime/extensions/postgres-changes), and transforms the events into the format expected by `ra-realtime`.
+
+```jsx
+import { createClient } from '@supabase/supabase-js';
+import { supabaseDataProvider } from 'ra-supabase';
+import { addRealTimeMethodsBasedOnSupabase, ListLive } from '@react-admin/ra-realtime';
+import { Admin, Resource, Datagrid, TextField, EmailField } from 'react-admin';
+
+const supabaseClient = createClient(
+    process.env.SUPABASE_URL,
+    process.env.SUPABASE_ANON_KEY
+);
+
+const dataProvider = supabaseDataProvider({
+    instanceUrl: process.env.SUPABASE_URL,
+    apiKey: process.env.SUPABASE_ANON_KEY,
+    supabaseClient
+});
+
+const realTimeDataProvider = addRealTimeMethodsBasedOnSupabase({
+    dataProvider,
+    supabaseClient,
+});
+
+export const App = () => (
+    <Admin dataProvider={realTimeDataProvider}>
+        <Resource name="sales" list={SaleList} />
+    </Admin>
+);
+
+const SaleList = () => (
+    <ListLive>
+        <Datagrid rowClick="edit">
+            <TextField source="id" />
+            <TextField source="first_name" />
+            <TextField source="last_name" />
+            <EmailField source="email" />
+        </Datagrid>
+    </ListLive>
+);
+```
+
+**Tip:** Realtime features are not enabled in Supabase by default, you need to enable them. This can be done either from the [Replication](https://app.supabase.com/project/_/database/replication) section of your Supabase Dashboard, or by running the following SQL query with the [SQL Editor](https://app.supabase.com/project/_/sql):
+
+```sql
+begin;
+
+-- remove the supabase_realtime publication
+drop
+  publication if exists supabase_realtime;
+
+-- re-create the supabase_realtime publication with no tables
+create publication supabase_realtime;
+
+commit;
+
+-- add a table to the publication
+alter
+  publication supabase_realtime add table sales;
+alter
+  publication supabase_realtime add table contacts;
+alter
+  publication supabase_realtime add table contactNotes;
+```
+
+Have a look at the Supabase [Replication Setup](https://supabase.com/docs/guides/realtime/extensions/postgres-changes#replication-setup) documentation section for more info.
+
+`addRealTimeMethodsBasedOnSupabase` accepts the following parameters:
+
+| Prop              | Required | Type             | Default | Description                                              |
+| ----------------- | -------- | ---------------- | ------- | -------------------------------------------------------- |
+| `dataProvider`    | Required | `DataProvider`   | -       | The base dataProvider to augment with realtime methods   |
+| `supabaseClient`  | Required | `SupabaseClient` | -       | The Supabase JS Client                                   |
+
+**Tip**: You may choose to sign your own tokens to customize claims that can be checked in your RLS policies. In order to use these custom tokens with `addRealTimeMethodsBasedOnSupabase`, you must pass an `apikey` field in both Realtime's `headers` and `params` when creating the `supabaseClient`. Please follow the instructions from the [Supabase documentation](https://supabase.com/docs/guides/realtime/extensions/postgres-changes#custom-tokens) for more information about how to do so.
+
+## API-Platform
 
 The `ra-realtime` package contains a function augmenting a regular (API-based) `dataProvider` with real-time methods based on the capabilities of [API-Platform](https://api-platform.com/). Use it as follows:
 
@@ -70,7 +160,7 @@ const GreetingsList = () => (
 );
 ```
 
-## Mercure Adapter
+## Mercure
 
 The `ra-realtime` package contains a function augmenting a regular (API-based) `dataProvider` with real-time methods based on [a Mercure hub](https://mercure.rocks/). Use it as follows:
 
@@ -95,7 +185,7 @@ const App = () => (
 
 If you're using another transport for real-time messages (WebSockets, long polling, GraphQL subscriptions, etc.), you'll have to implement `subscribe`, `unsubscribe`, and `publish` yourself in your `dataProvider`. As an example, here is an implementation using a local variable, that `ra-realtime` uses in tests:
 
-```ts
+```jsx
 let subscriptions = [];
 
 const dataProvider = {

diff --git a/docs/ReferenceField.md b/docs/ReferenceField.md
@@ -79,6 +79,7 @@ With this configuration, `<ReferenceField>` wraps the user's name in a link to t
 | `emptyText` | Optional | `string`            | ''       | Defines a text to be shown when the field has no value or when the reference is missing |
 | `label`     | Optional | `string | Function` | `resources.[resource].fields.[source]`   | Label to use for the field when rendered in layout components  |
 | `link`      | Optional | `string | Function` | `edit`   | Target of the link wrapping the rendered child. Set to `false` to disable the link. |
+| `queryOptions`     | Optional | [`UseQueryOptions`](https://tanstack.com/query/v4/docs/reference/useQuery?from=reactQueryV3&original=https://react-query-v3.tanstack.com/reference/useQuery)                       | `{}`                             | `react-query` client options                                                                   |
 | `sortBy`    | Optional | `string | Function` | `source` | Name of the field to use for sorting when used in a Datagrid |
 
 `<ReferenceField>` also accepts the [common field props](./Fields.md#common-field-props).
@@ -143,6 +144,22 @@ You can also use a custom `link` function to get a custom path for the children.
 />
 ```
 
+## `queryOptions`
+
+Use the `queryOptions` prop to pass options to the `dataProvider.getMany()` query that fetches the referenced record.
+
+For instance, to pass [a custom `meta`](./Actions.md#meta-parameter):
+
+```jsx
+<ReferenceField 
+    source="user_id"
+    reference="users"
+    queryOptions={{ meta: { foo: 'bar' } }}
+>
+    <TextField source="name" />
+</ReferenceField>
+```
+
 ## `reference`
 
 The resource to fetch for the related record.

diff --git a/docs/Tutorial.md b/docs/Tutorial.md
@@ -17,18 +17,24 @@ Here is an overview of the result:
 
 ## Setting Up
 
-React-admin uses React. We'll use [Vite](https://vitejs.dev/) to create an empty React app, and install the `react-admin` package:
+React-admin uses React. We'll use [create-react-admin](https://github.com/marmelab/react-admin/tree/master/packages/create-react-admin) to bootstrap a new admin:
 
 ```sh
-yarn create vite test-admin --template react-ts
-cd test-admin/
-yarn add react-admin ra-data-json-server
+yarn create react-admin test-admin
+```
+
+Choose **JSON Server** as the data provider, then **None** as the auth provider. Don't add any resource for now and just press **Enter**. Finally, choose either `npm` or `yarn` and press **Enter**. Once everything is installed, enter the following commands:
+
+```sh
+cd test-admin
+npm run dev
+# or
 yarn dev
 ```
 
-You should be up and running with an empty React application on port 5173.
+You should be up and running with an empty React admin application on port 5173.
 
-**Tip**: Although this tutorial uses a TypeScript template, you can use react-admin with JavaScript if you prefer. Also, you can use [create-react-app](./CreateReactApp.md), [Next.js](./NextJs.md), [Remix](./Remix.md), or any other React framework to create your admin app. React-admin is framework-agnostic.
+**Tip**: Although this tutorial uses a TypeScript template, you can use react-admin with JavaScript if you prefer. Also, you can use [Vite](https://vitejs.dev/), [create-react-app](./CreateReactApp.md), [Next.js](./NextJs.md), [Remix](./Remix.md), or any other React framework to create your admin app. React-admin is framework-agnostic.
 
 ## Using an API As Data Source
 
@@ -70,57 +76,10 @@ JSONPlaceholder provides endpoints for users, posts, and comments. The admin we'
 
 ## Making Contact With The API Using a Data Provider
 
-Bootstrap the admin app by replacing the `src/App.tsx` by the following code:
-
-```jsx
-// in src/App.tsx
-import { Admin } from "react-admin";
-import jsonServerProvider from "ra-data-json-server";
-
-const dataProvider = jsonServerProvider('https://jsonplaceholder.typicode.com');
-
-const App = () => <Admin dataProvider={dataProvider} />;
-
-export default App;
-```
-
-That's enough for react-admin to render an empty app and confirm that the setup is done: 
+The application has been initialized with enough code for react-admin to render an empty app and confirm that the setup is done: 
 
 [![Empty Admin](./img/tutorial_empty.png)](./img/tutorial_empty.png)
 
-Also, you should change the default Vite CSS file to look like this:
-
-```css
-/* in src/index.css */
-body {
-    margin: 0;
-}
-```
-
-Lastly, add the `Roboto` font to the `index.html` file:
-
-```diff
-// in ./index.html
-<!DOCTYPE html>
-<html lang="en">
-  <head>
-    <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>React Admin</title>
-+   <link
-+     rel="stylesheet"
-+     href="https://fonts.googleapis.com/css?family=Roboto:300,400,500,700&display=swap"
-+   />
-  </head>
-  <body>
-    <div id="root"></div>
-    <script type="module" src="/src/index.tsx"></script>
-  </body>
-</html>
-```
-
-**Tip:** You can also install the `Roboto` font locally by following the instructions from the [Material UI starter guide](https://mui.com/material-ui/getting-started/installation/#roboto-font).
-
 The `<App>` component renders an `<Admin>` component, which is the root component of a react-admin application. This component expects a `dataProvider` prop - a function capable of fetching data from an API. Since there is no standard for data exchanges between computers, you will probably have to write a custom provider to connect react-admin to your own APIs - but we'll dive into Data Providers later. For now, let's take advantage of the `ra-data-json-server` data provider, which speaks the same REST dialect as JSONPlaceholder.
 
 Now it's time to add features!

diff --git a/docs/img/create-react-admin.webm b/docs/img/create-react-admin.webm
diff --git a/docs/navigation.html b/docs/navigation.html
@@ -2,6 +2,7 @@
   <li {% if page.path == 'Tutorial.md' %} class="active" {% endif %}><a class="nav-link" href="./Tutorial.html">Tutorial</a></li>
   <li {% if page.path == 'Features.md' %} class="active" {% endif %}><a class="nav-link" href="./Features.html">Features</a></li>
   <li><a class="nav-link external" href="https://github.com/marmelab/react-admin/releases" target="_blank">What's new?</a></li>
+  <li {% if page.path == 'CreateReactAdmin.md' %} class="active" {% endif %}><a class="nav-link" href="./CreateReactAdmin.html">Create React Admin</a></li>
   <li {% if page.path == 'CreateReactApp.md' %} class="active" {% endif %}><a class="nav-link" href="./CreateReactApp.html">Create React App</a></li>
   <li {% if page.path == 'Vite.md' %} class="active" {% endif %}><a class="nav-link" href="./Vite.html">Vite</a></li>
   <li {% if page.path == 'NextJs.md' %} class="active" {% endif %}><a class="nav-link" href="./NextJs.html">Next.js</a></li>