From c0abd0d9a274e411b9405c6ab750b0a107663abf Mon Sep 17 00:00:00 2001 From: shaoyu Date: Tue, 17 Sep 2024 22:22:21 -0700 Subject: [PATCH 1/5] update creating react router to be consistent with migration guide --- docs/Admin.md | 84 ++++++++++++++++++++++++-------------- docs/Routing.md | 105 ++++++++++++++++++++++++++++++------------------ 2 files changed, 121 insertions(+), 68 deletions(-) diff --git a/docs/Admin.md b/docs/Admin.md index 4b4fed0fc7c..14710454585 100644 --- a/docs/Admin.md +++ b/docs/Admin.md @@ -1035,44 +1035,59 @@ const App = () => ( export default App; ``` -## Using A Custom Router +## Using A Custom Router React-admin uses [the react-router library](https://reactrouter.com/) to handle routing, with a [HashRouter](https://reactrouter.com/en/6/router-components/hash-router#hashrouter). This means that the hash portion of the URL (i.e. `#/posts/123` in the example) contains the main application route. This strategy has the benefit of working without a server, and with legacy web browsers. -But you may want to use another routing strategy, e.g. to allow server-side rendering of individual pages. React-router offers various Router components to implement such routing strategies. If you want to use a different router, simply wrap it around your app. React-admin will detect that it's already inside a router, and skip its own router. +But you may want to use another routing strategy, e.g. to allow server-side rendering of individual pages. React-router offers various Router components to implement such routing strategies. If you want to use a different router, simply put your app in a create router function. React-admin will detect that it's already inside a router, and skip its own router. ```tsx -import { BrowserRouter } from 'react-router-dom'; -import { Admin, Resource } from 'react-admin'; -import { dataProvider } from './dataProvider'; +import { RouterProvider, createBrowserRouter } from "react-router-dom"; +import { Admin, Resource } from "react-admin"; +import { dataProvider } from "./dataProvider"; -const App = () => ( - - - - - -); +const App = () => { + const router = createBrowserRouter([ + { + path: "*", + element: ( + + + + ), + }, + ]); + return ; +}; ``` ## Using React-Admin In A Sub Path React-admin links are absolute (e.g. `/posts/123/show`). If you serve your admin from a sub path (e.g. `/admin`), react-admin works seamlessly as it only appends a hash (URLs will look like `/admin#/posts/123/show`). -However, if you serve your admin from a sub path AND use another Router (like [``](https://reactrouter.com/en/main/router-components/browser-router) for instance), you need to set the `` prop, so that react-admin routes include the basename in all links (e.g. `/admin/posts/123/show`). +However, if you serve your admin from a sub path AND use another Router (like [`createBrowserRouter`](https://reactrouter.com/en/main/routers/create-browser-router) for instance), you need to set the `` prop and the [`opts.basename`](https://reactrouter.com/en/main/routers/create-browser-router#optsbasename) of `createBrowserRouter` function, so that react-admin routes include the basename in all links (e.g. `/admin/posts/123/show`). ```tsx import { Admin, Resource } from 'react-admin'; -import { BrowserRouter } from 'react-router-dom'; +import { RouterProvider, createBrowserRouter } from 'react-router-dom'; import { dataProvider } from './dataProvider'; -const App = () => ( - - - - - -); +const App = () => { + const router = createBrowserRouter( + [ + { + path: "*", + element: ( + + + + ), + }, + ], + { basename: "/admin" }, + ); + return ; +}; ``` This makes all links be prefixed with `/admin`. @@ -1086,18 +1101,27 @@ If you want to use react-admin as a sub path of a larger React application, chec You can include a react-admin app inside another app, using a react-router ``: ```tsx -import { BrowserRouter, Routes, Route } from 'react-router-dom'; +import { RouterProvider, Routes, Route, createBrowserRouter } from 'react-router-dom'; import { StoreFront } from './StoreFront'; import { StoreAdmin } from './StoreAdmin'; -export const App = () => ( - - - } /> - } /> - - -); +export const App = () => { + const router = createBrowserRouter( + [ + { + path: "*", + element: ( + + } /> + } /> + + ), + }, + ], + { basename: "/admin" }, + ); + return ; +}; ``` React-admin will have to prefix all the internal links with `/admin`. Use the `` prop for that: diff --git a/docs/Routing.md b/docs/Routing.md index a4614a72543..5028a4a36cf 100644 --- a/docs/Routing.md +++ b/docs/Routing.md @@ -125,44 +125,62 @@ export default App; ## Using A Custom Router -By default, react-admin creates a [HashRouter](https://reactrouter.com/en/6/router-components/hash-router#hashrouter). The hash portion of the URL (i.e. `#/posts/123` in the example) contains the main application route. This strategy has the benefit of working without a server, and with legacy web browsers. - -But you may want to use another routing strategy, e.g. to allow server-side rendering. React-router offers various Router components to implement such routing strategies. If you want to use a different router, simply wrap it around your app. React-admin will detect that it's already inside a router, and skip its own router. - -```jsx -import { BrowserRouter } from 'react-router-dom'; -import { Admin, Resource } from 'react-admin'; - -const App = () => ( - - - - - -); +React-admin uses [the react-router library](https://reactrouter.com/) to handle routing, with a [HashRouter](https://reactrouter.com/en/6/router-components/hash-router#hashrouter). This means that the hash portion of the URL (i.e. `#/posts/123` in the example) contains the main application route. This strategy has the benefit of working without a server, and with legacy web browsers. + +But you may want to use another routing strategy, e.g. to allow server-side rendering of individual pages. React-router offers various Router components to implement such routing strategies. If you want to use a different router, simply put your app in a create router function. React-admin will detect that it's already inside a router, and skip its own router. + +```tsx +import { RouterProvider, createBrowserRouter } from "react-router-dom"; +import { Admin, Resource } from "react-admin"; +import { dataProvider } from "./dataProvider"; + +const App = () => { + const router = createBrowserRouter([ + { + path: "*", + element: ( + + + + ), + }, + ]); + return ; +}; ``` ## Using React-Admin In A Sub Path React-admin links are absolute (e.g. `/posts/123/show`). If you serve your admin from a sub path (e.g. `/admin`), react-admin works seamlessly as it only appends a hash (URLs will look like `/admin#/posts/123/show`). -However, if you serve your admin from a sub path AND use another Router (like `BrowserRouter` for instance), you need to set the `` prop, so that react-admin routes include the basename in all links (e.g. `/admin/posts/123/show`). +However, if you serve your admin from a sub path AND use another Router (like [`createBrowserRouter`](https://reactrouter.com/en/main/routers/create-browser-router) for instance), you need to set the `` prop and the [`opts.basename`](https://reactrouter.com/en/main/routers/create-browser-router#optsbasename) of `createBrowserRouter` function, so that react-admin routes include the basename in all links (e.g. `/admin/posts/123/show`). -```jsx +```tsx import { Admin, Resource } from 'react-admin'; - -const App = () => ( - - - - - -); +import { RouterProvider, createBrowserRouter } from 'react-router-dom'; +import { dataProvider } from './dataProvider'; + +const App = () => { + const router = createBrowserRouter( + [ + { + path: "*", + element: ( + + + + ), + }, + ], + { basename: "/admin" }, + ); + return ; +}; ``` This makes all links be prefixed with `/admin`. -Note that it is your responsibility to serve the admin from the sub path, e.g. by setting the `homepage` field in your `package.json` if you use [Create React App](https://create-react-app.dev/docs/deployment/#building-for-relative-paths). +Note that it is your responsibility to serve the admin from the sub path, e.g. by setting the `base` field in `vite.config.ts` if you use [Vite.js](https://vitejs.dev/config/shared-options.html#base), or the `homepage` field in `package.json` if you use [Create React App](https://create-react-app.dev/docs/deployment/#building-for-relative-paths). If you want to use react-admin as a sub path of a larger React application, check the next section for instructions. @@ -170,29 +188,40 @@ If you want to use react-admin as a sub path of a larger React application, chec You can include a react-admin app inside another app, using a react-router ``: -```jsx -import { BrowserRouter, Routes, Route } from 'react-router-dom'; +```tsx +import { RouterProvider, Routes, Route, createBrowserRouter } from 'react-router-dom'; import { StoreFront } from './StoreFront'; import { StoreAdmin } from './StoreAdmin'; -export const App = () => ( - - - } /> - } /> - - -); +export const App = () => { + const router = createBrowserRouter( + [ + { + path: "*", + element: ( + + } /> + } /> + + ), + }, + ], + { basename: "/admin" }, + ); + return ; +}; ``` React-admin will have to prefix all the internal links with `/admin`. Use the `` prop for that: -```jsx +```tsx // in src/StoreAdmin.js import { Admin, Resource } from 'react-admin'; +import { dataProvider } from './dataProvider'; +import posts from './posts'; export const StoreAdmin = () => ( - + ); From 6d73a25061162f82ae715d5852f391dd5aed51ac Mon Sep 17 00:00:00 2001 From: smeng9 <38666763+smeng9@users.noreply.github.com> Date: Wed, 18 Sep 2024 13:35:09 -0700 Subject: [PATCH 2/5] update quote styles --- docs/Admin.md | 6 +++--- docs/Routing.md | 6 +++--- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/Admin.md b/docs/Admin.md index 14710454585..d2601f818f6 100644 --- a/docs/Admin.md +++ b/docs/Admin.md @@ -1042,9 +1042,9 @@ React-admin uses [the react-router library](https://reactrouter.com/) to handle But you may want to use another routing strategy, e.g. to allow server-side rendering of individual pages. React-router offers various Router components to implement such routing strategies. If you want to use a different router, simply put your app in a create router function. React-admin will detect that it's already inside a router, and skip its own router. ```tsx -import { RouterProvider, createBrowserRouter } from "react-router-dom"; -import { Admin, Resource } from "react-admin"; -import { dataProvider } from "./dataProvider"; +import { RouterProvider, createBrowserRouter } from 'react-router-dom'; +import { Admin, Resource } from 'react-admin'; +import { dataProvider } from './dataProvider'; const App = () => { const router = createBrowserRouter([ diff --git a/docs/Routing.md b/docs/Routing.md index 5028a4a36cf..7e34d7010be 100644 --- a/docs/Routing.md +++ b/docs/Routing.md @@ -130,9 +130,9 @@ React-admin uses [the react-router library](https://reactrouter.com/) to handle But you may want to use another routing strategy, e.g. to allow server-side rendering of individual pages. React-router offers various Router components to implement such routing strategies. If you want to use a different router, simply put your app in a create router function. React-admin will detect that it's already inside a router, and skip its own router. ```tsx -import { RouterProvider, createBrowserRouter } from "react-router-dom"; -import { Admin, Resource } from "react-admin"; -import { dataProvider } from "./dataProvider"; +import { RouterProvider, createBrowserRouter } from 'react-router-dom'; +import { Admin, Resource } from 'react-admin'; +import { dataProvider } from './dataProvider'; const App = () => { const router = createBrowserRouter([ From bd8accc57ad3277e908d692bbde2abd7a96ec7e6 Mon Sep 17 00:00:00 2001 From: shaoyu Date: Mon, 7 Oct 2024 08:56:47 -0700 Subject: [PATCH 3/5] remove misadded basename, update link --- docs/Admin.md | 1 - docs/Routing.md | 3 +-- 2 files changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/Admin.md b/docs/Admin.md index d2601f818f6..f42e97d1315 100644 --- a/docs/Admin.md +++ b/docs/Admin.md @@ -1118,7 +1118,6 @@ export const App = () => { ), }, ], - { basename: "/admin" }, ); return ; }; diff --git a/docs/Routing.md b/docs/Routing.md index 7e34d7010be..fa259ff51fa 100644 --- a/docs/Routing.md +++ b/docs/Routing.md @@ -125,7 +125,7 @@ export default App; ## Using A Custom Router -React-admin uses [the react-router library](https://reactrouter.com/) to handle routing, with a [HashRouter](https://reactrouter.com/en/6/router-components/hash-router#hashrouter). This means that the hash portion of the URL (i.e. `#/posts/123` in the example) contains the main application route. This strategy has the benefit of working without a server, and with legacy web browsers. +React-admin uses [the react-router library](https://reactrouter.com/) to handle routing, with a [HashRouter](https://reactrouter.com/en/routers/create-hash-router). This means that the hash portion of the URL (i.e. `#/posts/123` in the example) contains the main application route. This strategy has the benefit of working without a server, and with legacy web browsers. But you may want to use another routing strategy, e.g. to allow server-side rendering of individual pages. React-router offers various Router components to implement such routing strategies. If you want to use a different router, simply put your app in a create router function. React-admin will detect that it's already inside a router, and skip its own router. @@ -206,7 +206,6 @@ export const App = () => { ), }, ], - { basename: "/admin" }, ); return ; }; From 0ba9a41e32e6ce160dd7ad64098a21a508af1dfc Mon Sep 17 00:00:00 2001 From: Jean-Baptiste Kaiser Date: Tue, 8 Oct 2024 10:30:58 +0200 Subject: [PATCH 4/5] [no ci] fix Admin basename when Using React-Admin In A Sub Path --- docs/Admin.md | 2 +- docs/Routing.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/Admin.md b/docs/Admin.md index f42e97d1315..a81009c2d10 100644 --- a/docs/Admin.md +++ b/docs/Admin.md @@ -1078,7 +1078,7 @@ const App = () => { { path: "*", element: ( - + ), diff --git a/docs/Routing.md b/docs/Routing.md index fa259ff51fa..825434b3366 100644 --- a/docs/Routing.md +++ b/docs/Routing.md @@ -166,7 +166,7 @@ const App = () => { { path: "*", element: ( - + ), From 2e963dececcdeba19eed454cb15c4974da162162 Mon Sep 17 00:00:00 2001 From: Jean-Baptiste Kaiser Date: Tue, 8 Oct 2024 10:33:10 +0200 Subject: [PATCH 5/5] [no ci] fix Admin basename doc descr when Using React-Admin In A Sub Path --- docs/Admin.md | 2 +- docs/Routing.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/Admin.md b/docs/Admin.md index a81009c2d10..57af6399e9b 100644 --- a/docs/Admin.md +++ b/docs/Admin.md @@ -1065,7 +1065,7 @@ const App = () => { React-admin links are absolute (e.g. `/posts/123/show`). If you serve your admin from a sub path (e.g. `/admin`), react-admin works seamlessly as it only appends a hash (URLs will look like `/admin#/posts/123/show`). -However, if you serve your admin from a sub path AND use another Router (like [`createBrowserRouter`](https://reactrouter.com/en/main/routers/create-browser-router) for instance), you need to set the `` prop and the [`opts.basename`](https://reactrouter.com/en/main/routers/create-browser-router#optsbasename) of `createBrowserRouter` function, so that react-admin routes include the basename in all links (e.g. `/admin/posts/123/show`). +However, if you serve your admin from a sub path AND use another Router (like [`createBrowserRouter`](https://reactrouter.com/en/main/routers/create-browser-router) for instance), you need to set the [`opts.basename`](https://reactrouter.com/en/main/routers/create-browser-router#optsbasename) of `createBrowserRouter` function, so that react-admin routes include the basename in all links (e.g. `/admin/posts/123/show`). ```tsx import { Admin, Resource } from 'react-admin'; diff --git a/docs/Routing.md b/docs/Routing.md index 825434b3366..2d6e957fa88 100644 --- a/docs/Routing.md +++ b/docs/Routing.md @@ -153,7 +153,7 @@ const App = () => { React-admin links are absolute (e.g. `/posts/123/show`). If you serve your admin from a sub path (e.g. `/admin`), react-admin works seamlessly as it only appends a hash (URLs will look like `/admin#/posts/123/show`). -However, if you serve your admin from a sub path AND use another Router (like [`createBrowserRouter`](https://reactrouter.com/en/main/routers/create-browser-router) for instance), you need to set the `` prop and the [`opts.basename`](https://reactrouter.com/en/main/routers/create-browser-router#optsbasename) of `createBrowserRouter` function, so that react-admin routes include the basename in all links (e.g. `/admin/posts/123/show`). +However, if you serve your admin from a sub path AND use another Router (like [`createBrowserRouter`](https://reactrouter.com/en/main/routers/create-browser-router) for instance), you need to set the [`opts.basename`](https://reactrouter.com/en/main/routers/create-browser-router#optsbasename) of `createBrowserRouter` function, so that react-admin routes include the basename in all links (e.g. `/admin/posts/123/show`). ```tsx import { Admin, Resource } from 'react-admin';