You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
A frontend Framework for building admin applications running in the browser on top of REST/GraphQL services, using ES6, [React](https://facebook.github.io/react/) and [Material Design](https://material.io/). Open sourced and maintained by [marmelab](https://marmelab.com/).
3
+
A frontend Framework for building data-driven applications running in the browser on top of REST/GraphQL APIs, using ES6, [React](https://facebook.github.io/react/) and [Material Design](https://material.io/). Previously named [admin-on-rest](https://github.com/marmelab/admin-on-rest). Open sourced and maintained by [marmelab](https://marmelab.com/).
* Adapts to any backend (REST, GraphQL, SOAP, etc.)
12
-
* Complete documentation
13
-
* Optimistic rendering (renders before the server returns)
12
+
* Powered by [material-ui](https://material-ui.com/), [redux](https://redux.js.org/), [react-final-form](https://final-form.org/react), [react-router](https://reacttraining.com/react-router/) and a few more
13
+
* Super-fast UI thanks to optimistic rendering (renders before the server returns)
* Large library of components for various data types: boolean, number, rich text, etc.
22
+
* Conditional formatting
20
23
* Filter-as-you-type
21
24
* Supports any form layout (simple, tabbed, etc.)
22
-
* Data Validation
23
25
* Custom actions
24
-
* Large library of components for various data types: boolean, number, rich text, etc.
25
26
* WYSIWYG editor
26
27
* Customize dashboard, menu, layout
27
28
* Super easy to extend and override (it's just React components)
28
-
* Highly customizable interface
29
-
* Can connect to multiple backends
30
-
* Leverages the best libraries in the React ecosystem (Redux, redux-form, redux-saga, material-ui)
31
29
* Can be included in another React app
32
-
* Inspired by the popular [ng-admin](https://github.com/marmelab/ng-admin) library (also by marmelab)
33
-
34
-
## Versions In This Repository
35
-
36
-
*[master](https://github.com/marmelab/react-admin/commits/master) - commits that will be included in the next _patch_ release
37
-
38
-
*[next](https://github.com/marmelab/react-admin/commits/next) - commits that will be included in the next _major_ or _minor_ release
39
-
40
-
Bugfix PRs that don't break BC should be made against **master**. All other PRs (new features, bugfix with BC break) should be made against **next**.
41
30
42
31
## Installation
43
32
44
33
React-admin is available from npm. You can install it (and its required dependencies)
45
34
using:
46
35
47
36
```sh
48
-
npm install --save-dev react-admin
37
+
npm install react-admin
38
+
#or
39
+
yarn add react-admin
49
40
```
50
41
51
42
## Documentation
52
43
53
-
Read the [Tutorial](https://marmelab.com/react-admin/Tutorial.html) for a 15 minutes introduction. After that, head to the [Documentation](https://marmelab.com/react-admin/Readme.html), or checkout the [source code of the demo](https://github.com/marmelab/react-admin-demo) for an example usage.
44
+
Read the [Tutorial](https://marmelab.com/react-admin/Tutorial.html) for a 30 minutes introduction. After that, head to the [Documentation](https://marmelab.com/react-admin/Readme.html), or checkout the [source code of the demo](https://github.com/marmelab/react-admin-demo) for an example usage.
54
45
55
46
## At a Glance
56
47
@@ -77,7 +68,8 @@ The `<Resource>` component is a configuration component that allows to define su
@@ -135,71 +127,155 @@ See the [Data Providers documentation](https://marmelab.com/react-admin/DataProv
135
127
136
128
## Batteries Included But Removable
137
129
138
-
React-admin is designed as a library of loosely coupled React components built on top of [material-ui](https://www.material-ui.com/#/), in addition to controller functions implemented the Redux way. It is very easy to replace one part of react-admin with your own, e.g. to use a custom datagrid, GraphQL instead of REST, or bootstrap instead of Material Design.
130
+
React-admin is designed as a library of loosely coupled React components built on top of [material-ui](https://material-ui.com/), in addition to custom react hooks exposing reusable controller logic. It is very easy to replace one part of react-admin with your own, e.g. to use a custom datagrid, GraphQL instead of REST, or Bootstrap instead of Material Design.
131
+
132
+
## Examples
139
133
140
-
## Run the example
134
+
There are several examples inside the `examples` folder:
141
135
142
-
You can run the example app by calling:
136
+
*`simple` ([CodeSandbox](https://codesandbox.io/s/github/marmelab/react-admin/tree/master/examples/simple)): a simple application with posts, comments and users that we use for our e2e tests.
137
+
*`tutorial` ([CodeSandbox](https://codesandbox.io/s/github/marmelab/react-admin/tree/master/examples/tutorial)): the application built while following the tutorial.
138
+
*`demo`: ([Live](https://marmelab.com/react-admin-demo/)) A fictional poster shop admin, serving as the official react-admin demo.
139
+
140
+
You can run those example applications by calling:
143
141
144
142
```sh
145
-
npm install
146
-
make run
143
+
# At the react-admin project root
144
+
make install
145
+
# or
146
+
yarn install
147
+
148
+
# Run the simple application
149
+
make run-simple
150
+
151
+
# Run the tutorial application
152
+
make build
153
+
make run-tutorial
154
+
155
+
# Run the demo application
156
+
make build
157
+
make run-demo
147
158
```
148
159
149
-
And then browse to [http://localhost:8080/](http://localhost:8080/).
150
-
The credentials are **login/password**
160
+
And then browse to the URL displayed in your console.
161
+
162
+
## Support
163
+
164
+
You can get professional support from Marmelab via [React-Admin Enterprise Edition](https://marmelab.com/ra-enterprise), or community support via [StackOverflow](https://stackoverflow.com/questions/tagged/react-admin).
165
+
166
+
## Versions In This Repository
167
+
168
+
*[master](https://github.com/marmelab/react-admin/commits/master) - commits that will be included in the next _patch_ release
169
+
170
+
*[next](https://github.com/marmelab/react-admin/commits/next) - commits that will be included in the next _major_ or _minor_ release
171
+
172
+
Bugfix PRs that don't break BC should be made against **master**. All other PRs (new features, bugfix with BC break) should be made against **next**.
151
173
152
174
## Contributing
153
175
154
-
Pull requests are welcome. You must follow the coding style of the existing files (based on [prettier](https://github.com/prettier/prettier)), and include unit tests and documentation. Be prepared for a thorough code review, and be patient for the merge - this is an open-source initiative.
176
+
If you want to give a hand: Thank you! There are many things you can do to help making react-admin better.
177
+
178
+
The easiest task is **bug triaging**. Check that new issues on GitHub follow the issue template and give a way to reproduce the issue. If not, comment on the issue to ask precisions. Then, try and reproduce the issue following the description. If you managed to reproduce the issue, add a comment to say it. Otherwise, add a comment to say that something is missing.
179
+
180
+
The second way to contribute is to **answer support questions on [StackOverflow](https://stackoverflow.com/questions/tagged/react-admin)**. There are many beginner questions there, so even if you're not super experienced with react-admin, there is someone you can help there.
181
+
182
+
Pull requests for **bug fixes** are welcome on the [GitHub repository](https://github.com/marmelab/react-admin). There is always a bunch of [issues labeled "Good First Issue"](https://github.com/marmelab/react-admin/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22) in the bug tracker - start with these.
183
+
184
+
If you want to **add a feature**, you can open a Pull request on the `next` branch. We don't accept all features - we try to keep the react-admin code small and manageable. Try and see if your feature can't be built as an additional `npm` package. If you're in doubt, open a "Feature Request" issue to see if the core team would accept your feature before developing it.
185
+
186
+
For all Pull requests, you must follow the coding style of the existing files (based on [prettier](https://github.com/prettier/prettier)), and include unit tests and documentation. Be prepared for a thorough code review, and be patient for the merge - this is an open-source initiative.
155
187
156
-
You can run the tests (linting, unit and functional tests) by calling
188
+
**Tip**: Most of the commands used by the react-admin developers are automated in the `makefile`. Feel free to type `make` without argument to see a list of the available commands.
189
+
190
+
### Setup
191
+
192
+
Clone this repository and run `make install` to grab the dependencies, then `make build` to compile the sources from TypeScript to JS.
193
+
194
+
### Online one-click Setup
195
+
196
+
You can use Gitpod(An Online Open Source VS Code like IDE which is free for Open Source) for working on issues and making PRs. With a single click it will launch a workspace and automatically clone the repo, run `make install` and `make start` so that you can start straight away.
197
+
198
+
[](https://gitpod.io/from-referrer/)
199
+
200
+
### Testing Your Changes In The Example Apps
201
+
202
+
When developing, most of the time we use the **simple example** to do visual check. It's the same application that we use in CodeSandbox to reproduce errors (see https://codesandbox.io/s/github/marmelab/react-admin/tree/master/examples/simple). The source is located under `examples/simple/`. Call `make run` to launch that example on port 8080 (http://localhost:8080). This command includes a `watch` on the react-admin source, so any of the changes you make to the react-admin packages triggers a live update of the simple example in your browser.
203
+
204
+
However, the simple example is sometimes too limited. You can use the **demo example** (the source for https://marmelab.com/react-admin-demo/), which is more complete. The source is located under `examples/demo/`. Call `make run-demo` to launch the demo example with a REST dataProvider, or `make run-graphql-demo` to run it with a GraphQL dataProvider. Unfortunately, due to the fact that we use Create React App for this demo, these commands don't watch the changes made in the packages. You'll have to rebuild the react-admin packages after a change (using `make build`, or the more targeted `make build-ra-core`, `make build-ra-ui-materialui`, etc) to see the effect in the demo app.
205
+
206
+
Both of these examples work without server - the API is simulated on the client-side.
207
+
208
+
### Testing Your Changes In Your App
209
+
210
+
Using `yarn link`, you can have your project use a local checkout of the react-admn package instead of npm. This allows you to test react-admin changes in your app:
211
+
212
+
```sh
213
+
# Register your local react-admin as a linkable package
214
+
$ cd /code/path/to/react-admin/packages/react-admin && yarn link
215
+
216
+
# Replace the npm-installed version with a symlink to your local version
217
+
$ cd /code/path/to/myapp/ && yarn link react-admin
218
+
219
+
# If you run into issues with React red-screen, then you need to register your app's version of React as a linkable package
220
+
221
+
$ cd /code/path/to/myapp/node_modules/react && yarn link
222
+
# And then replace the npm-installed version of React with a symlink to your app's node_modules version
223
+
$ cd /code/path/to/react-admin/ && yarn link react
224
+
225
+
# Rebuild the packages with the same version of React
226
+
$ cd /code/path/to/react-admin/ && make build
227
+
228
+
# Return to your app and ensure all dependencies have resolved
229
+
$ cd /code/path/to/myapp/ && yarn install
230
+
231
+
# Start your app
232
+
$ yarn start
233
+
```
234
+
235
+
### Automated Tests
236
+
237
+
Automated tests are also crucial in our development process. You can run all the tests (linting, unit and functional tests) by calling:
157
238
158
239
```sh
159
240
make test
160
241
```
161
242
162
-
If you have coding standards problems, you can fix them automatically using `prettier`by calling
243
+
Unit tests use `jest`, so you should be able to run a subset of tests, or run tests continuously on change, by passing options to
163
244
164
245
```sh
165
-
make prettier
246
+
yarn jest
166
247
```
167
248
168
-
If you want to contribute to the documentation, install jekyll, then call
249
+
Besides, tests related to the modified files are ran automatically at commit using a git pre-commit hook. This means you won't be able to commit your changes if they break the tests.
250
+
251
+
When working on the end to end tests, you can leverage [cypress](https://www.cypress.io/) runner by starting the simple example yourself (`make run-simple` or `yarn run-simple`) and starting cypress in another terminal (`make test-e2e-local` or `yarn test-e2e-local`).
252
+
253
+
### Coding Standards
254
+
255
+
If you have coding standards problems, you can fix them automatically using `prettier` by calling
169
256
170
257
```sh
171
-
make doc
258
+
make prettier
172
259
```
173
260
174
-
And then browse to [http://localhost:4000/](http://localhost:4000/)
261
+
However, these commands are ran automatically at each commit so you shouldn't have to worry about them.
175
262
176
-
*Note*: if you have added a section with heading to the docs, you also have to add it to `docs/_layouts/default.html` (the links on the left) manually.
263
+
### Documentation
177
264
178
-
If you are using react-admin as a dependency, and if you want to try and hack it, here is the advised process:
265
+
If you want to contribute to the documentation, install [jekyll](https://jekyllrb.com/docs/home/), then call
179
266
180
267
```sh
181
-
# in myapp
182
-
# install react-admin from GitHub in another directory
183
-
$ cd ..
184
-
$ git clone git@github.com:marmelab/react-admin.git &&cd react-admin && make install
185
-
# replace your node_modules/react-admin by a symbolic link to the github checkout
186
-
$ cd ../myapp
187
-
$ npm link ../react-admin
188
-
# go back to the checkout, and replace the version of react by the one in your app
189
-
$ cd ../react-admin
190
-
$ npm link ../myapp/node_modules/react
191
-
$ make watch
192
-
# in another terminal, go back to your app, and start it as usual
193
-
$ cd ../myapp
194
-
$ npm run
268
+
make doc
195
269
```
196
270
197
-
**Tip**: If you're on Windows and can't use `make`, try [this Gist](https://gist.github.com/mantis/bb5d9f7d492f86e94341816321500934).
271
+
And then browse to [http://localhost:4000/](http://localhost:4000/)
198
272
199
273
## License
200
274
201
275
React-admin is licensed under the [MIT License](https://github.com/marmelab/react-admin/blob/master/LICENSE.md), sponsored and supported by [marmelab](https://marmelab.com).
This library is free to use, even for commercial purpose. If you want to give back, please talk about it, [help newcomers](https://stackoverflow.com/questions/tagged/react-admin), or contribute code. But the best way to give back is to **donate to a charity**. We recommend [Doctors Without Borders](https://www.doctorswithoutborders.org/).
0 commit comments