Skip to content

Latest commit

 

History

History
247 lines (181 loc) · 11.4 KB

README.md

File metadata and controls

247 lines (181 loc) · 11.4 KB
Raw

react-admin Build Status FOSSA Status

A frontend Framework for building admin applications running in the browser on top of REST/GraphQL APIs, using ES6, React and Material Design. Previously named admin-on-rest. Open sourced and maintained by marmelab.

Demo - Documentation - News - Releases - Support

react-admin-demo

Features

  • Adapts to any backend (REST, GraphQL, SOAP, etc.)
  • Powered by material-ui, redux, redux-form, redux-saga, react-router, recompose, reselect and a few more
  • Super-fast UI thanks to optimistic rendering (renders before the server returns)
  • Undo updates and deletes for a few seconds
  • Complete documentation
  • Relationships (many to one, one to many)
  • Data Validation
  • Internationalization (i18n)
  • Conditional formatting
  • Themeable
  • Supports any authentication provider (REST API, OAuth, Basic Auth, ...)
  • Full-featured Datagrid (sort, pagination, filters)
  • Filter-as-you-type
  • Supports any form layout (simple, tabbed, etc.)
  • Custom actions
  • Large library of components for various data types: boolean, number, rich text, etc.
  • WYSIWYG editor
  • Customize dashboard, menu, layout
  • Super easy to extend and override (it's just React components)
  • Highly customizable interface
  • Can connect to multiple backends
  • Can be included in another React app
  • Inspired by the popular ng-admin library (also by marmelab)

Versions In This Repository

  • master - commits that will be included in the next patch release

  • next - commits that will be included in the next major or minor release

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.

Installation

React-admin is available from npm. You can install it (and its required dependencies) using:

npm install react-admin

#or
yarn add react-admin

Documentation

Read the Tutorial for a 15 minutes introduction. After that, head to the Documentation, or checkout the source code of the demo for an example usage.

At a Glance

// in app.js
import React from 'react';
import { render } from 'react-dom';
import { Admin, Resource } from 'react-admin';
import restProvider from 'ra-data-simple-rest';

import { PostList, PostEdit, PostCreate, PostIcon } from './posts';

render(
    <Admin dataProvider={restProvider('http://localhost:3000')}>
        <Resource name="posts" list={PostList} edit={PostEdit} create={PostCreate} icon={PostIcon}/>
    </Admin>,
    document.getElementById('root')
);

The <Resource> component is a configuration component that allows to define sub components for each of the admin view: list, edit, and create. These components use Material UI and custom components from react-admin:

// in posts.js
import React from 'react';
import { List, Datagrid, Edit, Create, SimpleForm, DateField, TextField, EditButton, DisabledInput, TextInput, LongTextInput, DateInput } from 'react-admin';
import BookIcon from '@material-ui/core/svg-icons/action/book';
export const PostIcon = BookIcon;

export const PostList = (props) => (
    <List {...props}>
        <Datagrid>
            <TextField source="id" />
            <TextField source="title" />
            <DateField source="published_at" />
            <TextField source="average_note" />
            <TextField source="views" />
            <EditButton basePath="/posts" />
        </Datagrid>
    </List>
);

const PostTitle = ({ record }) => {
    return <span>Post {record ? `"${record.title}"` : ''}</span>;
};

export const PostEdit = (props) => (
    <Edit title={<PostTitle />} {...props}>
        <SimpleForm>
            <DisabledInput source="id" />
            <TextInput source="title" />
            <TextInput source="teaser" options={{ multiLine: true }} />
            <LongTextInput source="body" />
            <DateInput label="Publication date" source="published_at" />
            <TextInput source="average_note" />
            <DisabledInput label="Nb views" source="views" />
        </SimpleForm>
    </Edit>
);

export const PostCreate = (props) => (
    <Create title="Create a Post" {...props}>
        <SimpleForm>
            <TextInput source="title" />
            <TextInput source="teaser" options={{ multiLine: true }} />
            <LongTextInput source="body" />
            <TextInput label="Publication date" source="published_at" />
            <TextInput source="average_note" />
        </SimpleForm>
    </Create>
);

Does It Work With My API?

Yes.

React-admin uses an adapter approach, with a concept called Data Providers. Existing providers can be used as a blueprint to design your API, or you can write your own Data Provider to query an existing API. Writing a custom Data Provider is a matter of hours.

Data Provider architecture

See the Data Providers documentation for details.

Batteries Included But Removable

React-admin is designed as a library of loosely coupled React components built on top of material-ui, 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.

Examples

There are several examples inside the examples folder:

  • simple (CodeSandbox): a simple application with posts, comments and users that we use for our e2e tests.
  • tutorial (CodeSandbox): the application built while following the tutorial.
  • demo: (Live) A fictional poster shop admin, serving as the official react-admin demo.

You can run those example applications by calling:

# At the react-admin project root
make install

# or
yarn install

# Run the simple application
make run-simple
# Run the tutorial application
make build
make run-tutorial
# Run the demo application
make build
make run-demo

And then browse to the URL displayed in your console.

Contributing

Pull requests are welcome. You must follow the coding style of the existing files (based on 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.

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.

When developing, most of the time we use the simple example to do visual check. If you called make run-simple, any of the changes you make to the react-admin packages triggers a live update of the simple example in your browser.

However, the simple example is sometimes too limited. You can use the demo example, which is more complete, to test your changes. Unfortunately, due to the fact that we use Create React App for this demo, the make run-demo command doesn't watch the changes made in the packages. You'll have to rebuild the 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.

Automated tests are also crucial in our development process. You can run all the tests (linting, unit and functional tests) by calling:

make test

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

yarn jest

Besides, tests related to the modified files are ran automatically at commit useing a git pre-commit hook. this means you won't be able to commit your changes if they break the tests.

When working on the end to end tests, you can leverage cypress 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).

If you have coding standards problems, you can fix them automatically using prettier by calling

make prettier

However, these commands are ran automatically at each commit so you shouldn't have to worry about them.

If you want to contribute to the documentation, install jekyll, then call

make doc

And then browse to http://localhost:4000/

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.

If you are using react-admin as a dependency, and if you want to try and hack it, here is the advised process:

# in myapp
# install react-admin from GitHub in another directory
$ cd ..
$ git clone [email protected]:marmelab/react-admin.git && cd react-admin && make install
# replace your node_modules/react-admin by a symbolic link to the github checkout
$ cd ../myapp
$ npm link ../react-admin/packages/react-admin
# go back to the checkout, and replace the version of react by the one in your app
$ cd ../react-admin
$ npm link ../myapp/node_modules/react
$ make watch
# in another terminal, go back to your app, and start it as usual
$ cd ../myapp
$ npm run

Tip: If you're on Windows and can't use make, try this Gist.

License

React-admin is licensed under the MIT License, sponsored and supported by marmelab.

FOSSA Status

Donate

This library is free to use, even for commercial purpose. If you want to give back, please talk about it, help newcomers, or contribute code. But the best way to give back is to donate to a charity. We recommend Doctors Without Borders.