Skip to content

Commit 4ddd469

Browse files
adguernieradguernier
committed
removed App Router and App Router sections
1 parent f3840c0 commit 4ddd469

1 file changed

Lines changed: 21 additions & 149 deletions

File tree

‎docs/NextJs.md‎

Lines changed: 21 additions & 149 deletions
Original file line numberDiff line numberDiff line change
@@ -15,21 +15,21 @@ Next.js 13 proposes 2 ways to build a React project:
1515
React-admin supports both ways.
1616

1717
## Create a Next.js application
18-
Let's start by creating a new Next.js project called nextjs-react-admin.
18+
Let's start by creating a new Next.js project called next-admin.
1919

2020
```bash
2121
npx create-next-app@latest
2222
```
23-
A prompt will asks you some questions, feel free to choose the options according to your needs.
24-
To easily bootstap the `<Admin>` application, regardless of Next.js router system (eg: Page Router or App router), we will choose to create a `src` folder :
23+
A prompt will asks you some questions, feel free to choose answers according to your needs.
24+
To easily bootstap the `<Admin>` application, regardless of Next.js router system (eg: Pages Router or App router), we will choose to create a `src` folder :
2525

2626
![Install Next.js with command line](./img/install-next-js-command-line.png)
2727

2828
This creates a project with the following folder structure:
2929

30-
| Page Router | App Router |
30+
| Pages Router | App Router |
3131
|-------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------|
32-
| ![ Next Admin folder structure with Page Router ]( ./img/next-admin-with-page-router-folder-structure.png ) | ![ Next Admin folder structure with Page Router ]( ./img/next-admin-with-app-router-folder-structure.png ) |
32+
| ![ Next Admin folder structure with Pages Router ]( ./img/next-admin-with-page-router-folder-structure.png ) | ![ Next Admin folder structure with App Router ]( ./img/next-admin-with-app-router-folder-structure.png ) |
3333

3434
### Adding React-Admin Dependencies
3535

@@ -44,7 +44,7 @@ yarn add react-admin ra-data-json-server
4444

4545
Next, create a `components` directory inside `src`, and an admin App component in `src/components/AdminApp.jsx`:
4646

47-
> **Tips**: If you choose App Router, do not forget to add [the `"use client"` directive](https://nextjs.org/docs/getting-started/react-essentials#the-use-client-directive).
47+
**Tips**: If you choose App Router, do not forget to add [the `"use client"` directive](https://nextjs.org/docs/getting-started/react-essentials#the-use-client-directive). Why the `"use client"` directive? React-admin is designed as a Single-Page Application, rendered on the client-side. It comes with various client-side only libraries (emotion, material-ui, react-query) leveraging the React Context API, and cannot be rendered using React Server components.
4848

4949
```jsx
5050
// in src/components/AdminApp.jsx
@@ -77,7 +77,7 @@ export default AdminApp;
7777

7878
This is a minimal configuration to render CRUD pages for users, posts and comments. React-admin guesses the data structure from the API response.
7979

80-
## Exposing the Admin App Component
80+
### Exposing the Admin App Component
8181
React-admin is designed as a Single-Page Application, rendered on the client-side. It comes with its own routing sytem, which conflicts with the Next.js routing system. So we must prevent Next.js from rendering the react-admin component on the server-side.
8282

8383
To do that, we will have to import our `<AdminApp>` component in Next.js by using the [__lazy loading__ system provided by Next.js](https://nextjs.org/docs/pages/building-your-application/optimizing/lazy-loading) and specify the [`ssr` option to false](https://nextjs.org/docs/pages/building-your-application/optimizing/lazy-loading#with-no-ssr).
@@ -87,10 +87,12 @@ Using dynamic import allows disabling Server-Side Rendering for the `<AdminApp>`
8787
The file you import the Admin app into Next.js depends on the router system you choose :
8888

8989
- if you choose App Router, import `<AdminApp>` in `src/app/page.tsx`,
90-
- otherwise, if you choose Page Router, import `<AdminApp>` in `src/pages/index.tsx`.
90+
- otherwise, if you choose Pages Router, import `<AdminApp>` in `src/pages/index.tsx`.
9191

9292
```tsx
93-
// in src/app/page.tsx or in src/pages/index.tsx depending of the Router you choose
93+
// depending of the Router you choose:
94+
// - in src/app/page.tsx for App Router system
95+
// - or in src/pages/index.tsx for Pages Router system
9496
import dynamic from "next/dynamic";
9597
const AdminApp = dynamic(() => import("@/components/AdminApp"), { ssr: false });
9698

@@ -102,75 +104,10 @@ export default function Home() {
102104
Now, start the server with `yarn dev`, browse to `http://localhost:3000/`, and you should see the working admin:
103105

104106
![Working Page](./img/nextjs-react-admin.webp)
105-
## Next.js With Pages Router
106-
107-
Let's start by creating a new Next.js project called `nextjs-react-admin`.
108-
109-
```bash
110-
npx create-next-app@latest next-admin --ts --use-yarn --eslint --no-tailwind --src-dir --no-app --import-alias "@/*"
111-
```
112-
113-
![Setup Next.js](./img/nextjs-setup.webp)
114-
115-
This creates a project with the following folder structure:
116-
117-
![Basic Architecture Next.js](./img/nextjs-file-structure.png)
118-
119-
### Adding React-Admin Dependencies
120-
121-
Add the `react-admin` npm package, as well as a data provider package. In this example, we'll use `ra-data-json-server` to connect to a test API provided by [JSONPlaceholder](https://jsonplaceholder.typicode.com).
122-
123-
```bash
124-
cd next-admin
125-
yarn add react-admin ra-data-json-server
126-
```
127-
128-
### Creating the Admin App Component
129-
130-
Next, create an `admin` directory inside `src`, and the admin App component in `src/admin/App.jsx`:
131107

132-
```jsx
133-
// in src/admin/App.jsx
134-
import * as React from "react";
135-
import { Admin, Resource, ListGuesser, EditGuesser } from 'react-admin';
136-
import jsonServerProvider from 'ra-data-json-server';
108+
Starting from there, you can [Add an API](#adding-an-api) as described in the next section, and/or add features to the Next.js app, as explained in the [Getting started tutorial](./Tutorial.md)
137109

138-
const dataProvider = jsonServerProvider('https://jsonplaceholder.typicode.com');
139-
140-
const App = () => (
141-
<Admin dataProvider={dataProvider}>
142-
<Resource name="users" list={ListGuesser} edit={EditGuesser} recordRepresentation="name" />
143-
<Resource name="posts" list={ListGuesser} edit={EditGuesser} recordRepresentation="title" />
144-
<Resource name="comments" list={ListGuesser} edit={EditGuesser} />
145-
</Admin>
146-
);
147-
148-
export default App;
149-
```
150-
151-
This is a minimal configuration to render CRUD pages for users, posts and comments. React-admin guesses the data structure from the API response.
152-
153-
### Exposing the Admin App Component
154-
155-
Now, let's configure Next.js to render the admin app component in the root path ('/'). Edit the file called `src/pages/index.tsx`, and replace the content with the following:
156-
157-
```tsx
158-
// in src/pages/index.tsx
159-
import type, { NextPage } from "next";
160-
import dynamic from "next/dynamic";
161-
162-
const App = dynamic(() => import("../admin/App"), { ssr: false });
163-
164-
const Home: NextPage = () => {
165-
return <App />;
166-
};
167-
168-
export default Home;
169-
```
170-
171-
Now, start the server with `yarn dev`, browse to `http://localhost:3000/`, and you should see the working admin:
172-
173-
![Working Page](./img/nextjs-react-admin.webp)
110+
## Pages Router Specific Use Case
174111

175112
### Rendering React-Admin In A Sub Route
176113

@@ -183,17 +120,19 @@ Next.js makes it trivial: create a `src/pages/admin.tsx` file with the same cont
183120
import type, { NextPage } from "next";
184121
import dynamic from "next/dynamic";
185122

186-
const App = dynamic(() => import("../admin/App"), { ssr: false });
123+
const AdminApp = dynamic(() => import("@/components/AdminApp"), { ssr: false });
187124

188125
const Admin: NextPage = () => {
189-
return <App />;
126+
return <AdminApp />;
190127
};
191128

192129
export default Admin;
193130
```
194131

195132
Now the admin renders at `http://localhost:3000/admin`, and you can use the Next.js routing system to add more pages.
196133

134+
**Tip**: If you migrated from the Pages Router, you might have to delete the `.next` directory in your project to ensure NextJS bundles the client dependencies correctly.
135+
197136
### Adding an API
198137

199138
[Next.js allows to serve an API](https://nextjs.org/docs/api-routes/introduction) from the same server. You *could* use this to build a CRUD API by hand. However, we consider that building a CRUD API on top of a relational database is a solved problem and that developers shouldn't spend time reimplementing it.
@@ -266,87 +205,20 @@ yarn add @raphiniert/ra-data-postgrest
266205
```
267206

268207
```jsx
269-
// in src/admin/App.jsx
208+
// in src/components/AdminApp.jsx
270209
import * as React from "react";
271210
import { Admin, Resource, ListGuesser, EditGuesser } from 'react-admin';
272211
import postgrestRestProvider from "@raphiniert/ra-data-postgrest";
273212

274213
const dataProvider = postgrestRestProvider("/api/admin");
275214

276-
const App = () => (
277-
<Admin dataProvider={dataProvider}>
278-
<Resource name="users" list={ListGuesser} edit={EditGuesser} recordRepresentation="name" />
279-
<Resource name="posts" list={ListGuesser} edit={EditGuesser} recordRepresentation="title" />
280-
<Resource name="comments" list={ListGuesser} edit={EditGuesser} />
281-
</Admin>
282-
);
283-
284-
export default App;
285-
```
286-
287-
## Next.js With App Router
288-
289-
Let's start by creating a new Next.js project called `nextjs-react-admin` using the new App Router.
290-
291-
```bash
292-
npx create-next-app@latest next-admin --ts --use-yarn --eslint --no-tailwind --no-src-dir --app --import-alias "@/*"
293-
```
294-
295-
This creates a project with the following folder structure:
296-
297-
![Basic Architecture Next.js App Router](./img/nextjs-file-structure-app-router.png)
298-
299-
### Adding React-Admin Dependencies
300-
301-
Add the `react-admin` npm package, as well as a data provider package. In this example, we'll use `ra-data-json-server` to connect to a test API provided by [JSONPlaceholder](https://jsonplaceholder.typicode.com).
302-
303-
```bash
304-
cd next-admin
305-
yarn add react-admin ra-data-json-server
306-
```
307-
308-
### Creating the Admin App Component
309-
310-
Next, create a `app/Admin.tsx` file with the following code, which initializes the react-admin app:
311-
312-
```jsx
313-
// in app/App.tsx
314-
"use client";
315-
import { Admin, Resource, ListGuesser, EditGuesser } from "react-admin";
316-
import jsonServerProvider from "ra-data-json-server";
317-
318-
const dataProvider = jsonServerProvider("https://jsonplaceholder.typicode.com");
319-
320-
const App = () => (
215+
const AdminApp = () => (
321216
<Admin dataProvider={dataProvider}>
322217
<Resource name="users" list={ListGuesser} edit={EditGuesser} recordRepresentation="name" />
323218
<Resource name="posts" list={ListGuesser} edit={EditGuesser} recordRepresentation="title" />
324219
<Resource name="comments" list={ListGuesser} edit={EditGuesser} />
325220
</Admin>
326221
);
327222

328-
export default App;
329-
```
330-
331-
Before you go further, you need to specify to NextJS to not use Server Side Rendering (SSR) for this component, otherwise, NextJS output will display an error. You can do that as we explain at the beginning of this tutorial. So replace the content of `app/page.tsx` with this :
332-
```jsx
333-
import dynamic from "next/dynamic";
334-
const App = dynamic(() => import("./App"), { ssr: false });
335-
336-
export default function Home() {
337-
return <App />;
338-
}
339-
```
340-
341-
Now, start the server with `yarn dev`, browse to `http://localhost:3000/`, and you should see the working admin:
342-
343-
![Working Page](./img/nextjs-react-admin.webp)
344-
345-
React-admin renders a CRUD for users, posts and comments, guessing the data structure from the API response.
346-
347-
348-
**Tip**: Why the `"use client"` directive? React-admin is designed as a Single-Page Application, rendered on the client-side. It comes with various client-side only libraries (emotion, material-ui, react-query) leveraging the React Context API, and cannot be rendered using React Server components.
349-
350-
**Tip**: If you migrated from the Pages Router, you might have to delete the `.next` directory in your project to ensure NextJS bundles the client dependencies correctly.
351-
352-
Starting from there, you can [Add an API](#adding-an-api) as described in the previous section, and/or add features to the Next.js app, as explained in the [Getting started tutorial](./Tutorial.md)
223+
export default AdminApp;
224+
```

0 commit comments

Comments
 (0)