React-admin: Roadmap to React-Admin 3.0

[fzaninotto]

React-admin v2 is about one year old. We've kept backward compatibility for a year, but it means we can't yet use all the new shiny tools that our dependencies have shipped since then in major releases.

The objectives of the next release, v3, are to:

• [x] Upgrade dependencies to the latest major version
  
  
  
  • [x] Upgrade react and react-dom to 16.8 to use Hooks (#3170)
  
  
  • [x] Upgrade material-ui to 4.2.1 (instead of 1.5) to use... a lot of things, uncluding the useStyle hook (#3191)
  
  
  • [x] Upgrade react-redux to 7.1.0 (instead of 5.0) to use useDispatch and useSelector hooks instead of connect (#3170)
  
  
  • [x] Upgrade redux-saga to 1.0 (because we're on a non-supported version) (#3212)
  
  
  • [x] Switch from redux-form to react-final-form (#3455)
  
  
• [x] Turn logic components into hooks
  
  
  
  • [x] Replace fetch, accumulate, undo and callback sagas by data hooks for fetching the dataProvider (useQuery, useMutation, useDataProvider) (#3181)
  
  
  • [x] Add CRUD hooks (#3253)
  
  
  • [x] Replace auth saga by auth hooks (useAuth, usePermissions) (#3368)
  
  
  • [x] Replace i18n saga by i18n hooks (useTranslate, useLocale, useSeltLocale) (#3188, #3672, #3685))
  
  
  • [x] Replace notification, redirect, and refresh sagas by hooks (useNotify, useRedirect, useRefresh) (#3425)
  
  
  • [x] Add controller hooks to replace our controller components (#3213, #3217, #3228, #3236, #3398, #3377, #3406, #3409)
  
  
  • [x] Add useMediaQuery hook to replace the Responsive component (#3329)
  
  
  • [x] Update the documentation to use hooks (#3688)
  
  
  • [x] Update the examples to use hooks
  
  
• [x] Turn providers to objects instead of functions
  
  
  
  • [x] authProvider (#3614)
  
  
  • [x] i18nProvider (#3699)
  
  
  • [x] dataProvider (#3726)
  
  
• [x] Fix breaking change issues
  
  
  
  • [x] Replace injected elements by injected components (#3262)
  
  
  • [x] Upgrade redux-saga to 1.0 (#3212)
  
  
  • [x] Redirection to login should be done in the authProvider (#3269)
  
  
  • [x] Decouple data actions from views
  
  
  • [x] Rename appLayout to layout in (#3055)
  
  
  • [x] Use theme to store sidebar width (#3323)
  
  
  • [x] Replace papaparse by something lighter (#3324)
  
  
  • [x] Deprecation of react-router-redux (#3170)
  
  
  • [x] rename isLoading to loading everywhere (#3644)
  
  
  • [x] Remove deprecated components (#3247, #3517)
  
  
• [x] UI adjustments
  
  
  
  • [x] Move actions out of the main card (#3214)
  
  
  • [x] Replace Headroom by MUI native implementation of auto-hiding app bar (#3247)
  
  
  • [x] Use filled variant by default in forms (#3594)
  
  
• [x] Make sure the core codebase doesn't need the crudXXX actions and the fetch saga
• [x] Reimplement AutocompleteInput and AutocompleteArrayInput using downshift (#3031, #3667)
• [x] Decide whether we should stick to connected-react-router or not (because it's not active)
• [x] Move most dependencies into peerDependencies for internal packages (#3763)
• [x] Overhaul HTTP error handling (#3757)

This will lead to a deep transformation of the library. We hope to minimize the breaking changes, but developers will have to follow a migration guide to use this new version with existing code. We'll try to make that as painless as possible.

We'll need help from volunteers to test the changes before releasing a stable version. We'll publish alpha and beta releases for that purpose.

We expect the 3.0 to be released sometime in the Summer of 2019. Development has already started and is visible on the next branch. We tag related pull request with the 3.0 milestone so you can track our progress.

Comments are welcome. Help migrating class components to functional components using hooks is also welcome (although we don't have the objective of migrating all the codebase to functional components for 3.0. This can happen later).

[zahidraza]

I think it would be better to migrate to react-final-form instead of redux-form 8.2

[fzaninotto]

@zahidraza can you elaborate ?

[zahidraza]

Author of redux-form recommends not using redux-form if someone is just getting started.Here is excerpt from redux-from:

If you're just getting started with your application and are looking for a form solution, the general consensus of the community is that you should not put your form state in Redux. The author of Redux Form took all of the lessons he learned about form use cases from maintaining Redux Form and built 🏁 React Final Form, which he recommends you use if you are just starting your project. It's also pretty easy to migrate to from Redux Form, because the component APIs are so similar

This blog explains the reason behind his decision. So, since you are rewriting, I thought it would be better to migrate to react-final-form

[hcldan]

What about using Formik instead and ditching all the saga stuff?

[fzaninotto]

What saga stuff? Why should we use formik instead of other solutions? Please share your analysis of the pros and cons of the current solution vs your proposal.

[hcldan]

Saga stuff: https://github.com/marmelab/react-admin/blob/master/packages/ra-core/package.json#L67
Formik: recommended via React team: https://reactjs.org/docs/forms.html#fully-fledged-solutions

Comparison: People using saga say it's easy to write unit tests. It looks to me like maybe that's true, but it seems to come as a trade off of readable, maintainable code. It's not necessarily that the library's goals are bad, but using generators to implement it seems pretty gratuitous.

[fzaninotto]

We don't use sagas for forms, but for handling side effects (like HTTP requests etc). Formik wouldn't replace them.

As for using Formik vs redux-form or react-final-form, your analysis is a bit short.

[hcldan]

Look. Not my project. Do whatever you want, there's no need for that kind of tone.

What about using Formik instead? You don't seem to care. Fair enough. If you don't care to do the analysis on why it's being used and its design principles, that's your call. It was just a question.

and ditching all the sage stuff? I think using generators the way saga does is gross and results in complex back-assward code to read. You may not. That would be fair too, if you answered my question instead of getting snippy and aborting because I didn't spoon feed you Formix info.

[fzaninotto]

@hcldan I understood that you wanted to use Formik because that would help remove sagas. Now I understand that you proposed 2 different changes.

Now about formik, I do care, that's why I'm asking you your pros and cons. You brought the subject here, not me. When we choose a library we try to base our choice on more than other people's opinions, and that includes objective facts, past experiences, known caveats, etc. See #3246 as a way to structure your argumentation.

As for sagas, if you don't like them, what do you suggest we replace them with? They provide a much necessary feature (handling side effects).

Lastly, I don't have the impression that I used a bad tone. I'm asking you for more than opinions. Please drink the kool-aid or you'll be banned from this repo, no other warning.

[esistgut]

Are you considering Typescript for this new release?

[yuriydobryanskyyempeek]

btw, just curious - why did you choose typescript over flow? Flow seems like a more natural choice for react

[fzaninotto]

The TypeScript migration has started 6 months ago (see the language composition in the GitHub header). The ra-core package is already migrated, the rest will happen progressively - and the 3.0 release isn’t constrained by the completion of the migration.

As for the typescript vs flow question, let’s say that there is no consensus and that we had to make a choice. We consider, contrary to you, that TypesScript is the more natural choice (see e.g. material ui).

[dziamid]

Can we export react-admin.d.ts file, regardless of the fact that not all components have been covered with types? I think even partial type-safety is better than no type-safety.

[fzaninotto]

Unfortunately, no. That's a limit of TypeScript (see https://github.com/Microsoft/TypeScript/issues/7546)

[djhi]

We could add one ourselves right ?

[fzaninotto]

Yes, but we’d have to write it by hand.

[dziamid]

I've made one for myself with help of dts-gen and some tweaks.
https://gist.github.com/dziamid/aa750155641fbb95d77a82b2eca74993
You already have a lot of typed goodness exported in ra-core, so I'm using that to override any loosely typed dts-gen definitions.

[TheHyphen]

Excited for the new release. 🎉Particularly the upgrade to hooks.

I was wondering if you are planning any production ready starter or a boilerplate for react-admin that we can just clone and get started. Sort of like the very popular https://github.com/react-boilerplate/react-boilerplate.

This boilerplate also uses redux-saga, react-router and connected-react-router and reselect and react hooks much like react-admin. It also includes some other cool things like hot reload, CLI component scaffolding and offline first approach.

[fzaninotto]

No, we won't create a bootstrap as it's as easy as installing create-react-app then the react-admin package.

[wmwart]

Good day. I have an idea. Rather, the need. When developing an application that uses field access, its own implementation becomes very cumbersome (each field of each form must be wrapped in a function that, if there is access, the component will draw, otherwise null).
When developing v3, could you add the access property to all fields and forms (similar to the validate function)?

import React from 'react';
import PropTypes from 'prop-types';

const ExampleField = ({ access, ...props }) => {
    if (!access) return null;
    return <div />
};

ExampleField.propTypes = {
    access: PropTypes.func,
  ...
};

ExampleField.defaultProps = {
    access: (field) => true,
};

This is very helpful when using third-party access control libraries.
What do you think?

[fzaninotto]

You can already use the WithPermissions component for that, and we'll make a hook for the same use case to make it easier. I think it'll solve your use case. Also, you can already implement the syntax you describe in userland by creating a custom Form component.

[wmwart]

Thanks for the suggestion. I use WithPermissions. This led to such a need. The code in the user components of the form becomes several times larger, only in order to implement such simple logic. Of course, you can leave it as it is, and everything will work. I am just for convenience and good readability in projects.

[nik-lampe]

I agree with @zahidraza that redux-form should be replaced with react-final-form.
I think formik would be fine as well, but as redux-form is already used the transition to react-final-form (same principles, it's really easy to reuse lots of the code) this seems like the better choice to me.
Here's why

1. I think the most important part ist an opinionated but kind of senseful one, already stated by @zahidraza

The general consensus of the community is that you should not put your form state in Redux

As stated here: https://codeburst.io/final-form-the-road-to-the-checkered-flag-cd9b75c25fe, which refers to here: https://github.com/reduxjs/redux/issues/1287#issuecomment-175351978

I agree with this. A form should be mounted an unmounted with all it's data.

1. This issue was a result of all the forms using the same part of the state
   https://github.com/marmelab/react-admin/issues/2129
   It has been solved, but in my opinion the solution is just a workaround. It works though... 😁

2. Also moving to react-final-form decouples the forms from redux.

Though it's not a really important change, so I totally understand if you say, that it should not be done

[wmwart]

Idea for improvement. All Inputs use the parameter helperText={touched && error}. This leads to a situation where you need to install a custom helperText, but this deprives the error message and the user does not understand what happened. Offer:

export Input extends Component {
    ...
    render() {
        ... 
        const { touched, error } = meta;

        return (
            <Field
                ...
                helperText={this.props.setHelperText( touched, error )}
        ...
            />
        );
    }
}

Input.propTypes = {
    ...
    setHelperText: PropTypes.func,
    ...
};

Input.defaultProps = {
    ...
    setHelperText: ( touched, error ) => {
        return touched && error
    },
    ...
};

export default addField(Input);

What do you think about it?

[fzaninotto]

To discuss individual improvements, please open a new issue, otherwise this thread will become impossible to follow.

[AnirudhaGohokar]

First of all thanks a lot for this great starter-kit. Excellent work!
Although the library is highly customizable , its still tightly coupled with material-ui . Would it be possible to keep it opt-in?
PS: am already working on a fork of v2.0 to remove this dependency as am planning to use materializecss instead.

[djhi]

Although the library is highly customizable , its still tightly coupled with material-ui

That's why we introduced ra-core and ra-ui-materialui. I understand it is not documented yet but you can already reimplement the UI without redevelopping everything. Someone started one for bootstrap (see https://github.com/bootstrap-styled/react-admin).

[ngocketit]

This is great! It'd be really nice if we can decouple the UI elements (such as tables etc) from the resources & logic of fetching data. Currently, the list view, show view and so on are bound to the resource, which makes it very difficult (if impossible) to use them in nested views.

[djhi]

I'll need a more concret example to answer

[aymendhaya]

Hi all,

Since i'm finding here some suggestions for the upcoming v3, can i suggest using breadcrumbs provided by MUI v4. it will be awesome to have it on the top bar with navigation possibilities.

I hope the idea can help :)

[fzaninotto]

Hi @aymendhaya, and thanks for your suggestion. This can already be achieved in user land in V2, no need to wait for v3. Also, v3.0 will focus on breaking changes, so there is little chance that breadcrumbs are added shortly.

[esistgut]

Disclaimer 1#: this is more of a question than a suggestion so I'm not sure if it belongs on this issue, if it doesn't tell me and I will delete this comment to avoid clogging the thread.
Disclaimer 2#: I'm a react-admin user but I'm not too familiar with its internals so this could be partially or totally wrong.
I was wondering: apollo-link seems to have some kind of overlap with your concept of Data Provider. As far as I can understand using a graphql data provider with apollo-link and apollo-link-rest could, for example, replace your rest data provider, apollo-link-firebase could replace the 3rd party firebase provider, etc...
State management could be offloaded to apollo in a similar fashion too.
So I guess my question is: have you considered relaying more on Apollo and its ecosystem to avoid the possible duplication of work?

[fzaninotto]

Interesting topic.

Using GraphQL as a general query engine would make sense if react-admin requested composite records and only a subset of fields, but in fact we need the exact opposite. We need whole resources to share between the fields and pages, and react-admin emits a data request before react knows which fields are displayed.

Besides, we have the concept of 'Resource', which is much closer with REST than GraphQL.

So even though part of the job in apollo-link-rest looks like what we've done in react-admin, the request API differs (GraphQL query vs function call) and the philosophy differs, too (remote procedure call vs RPC).

We won't consider using apollo-link-rest in react-admin.

[firepol]

Hi, in the objectives of the migration I didn't see Typescript mentioned, but in the discussion I read that you'll migrate to Typescript. i'm using vanilla javascript in my little project based on react-admin, I'm not really excited to migrate my code to Typescript. Will my code still work (with little adjustments for the migration) or will I need to rewrite it to Typescript?

In other words, will Typescript be required to use react-admin 3.0?

[djhi]

In other words, will Typescript be required to use react-admin 3.0?

No. This is an internal change which allows us to provide TypeScripts types for those who use it. Nothing changes for the others

[cyberlake]

Hi, any plans to release this version with @next tag before the release? something like react-admin@next

Thanks for the great project, btw!

[developerium]

Hi
Why are you planning to Switch from redux-form to react-final-form?
I mean just because of this ?

[djhi]

@developerium mainly yes. My opinion is that a form state does not belong to the global app state. Besides, we faced many bugs around default values, re-initialization of the form state, etc because of it.

[developerium]

@djhi how difficult do you predict the migration to new version of react-admin will be? Since it does not seem to be backward compatible?

[djhi]

We update the upgrade guide with each pull request targeting the next branch when the pr has breaking changes. Take a look ! :)

[m4theushw]

Is there anyone working on the migration to react-final-form? I am willing to contribute but there is some changes that will break the backward compatibility and I don't know how to proceed.

[djhi]

@m4theushw Yes, I started it by refactoring the validators and will work on the actual migration very soon

[dgkm]

Couple of ideas for ease of customisation and improve the usability (codeless).

It's just a quick brain dump and may not be organised well.

• Component Registry: maintain a dictionary of field types with mapping to Input and View components to use
  
  
  
  • Example field types: Primary key, Reference Key, Text, Number, Date, DateTime
  
  
• List: whether it is Rest or GraphQl, in most cases there will be more fields in the response for a query on the given entity than the displayed.
  
  
  
  • Render List based on the predefined JSON configuration input having field to widget mapping including options such as Column name, Data formatter, enableSort, etc.
  
  
  • provide a column selector for user or admin to configure and generate the field list JSON configuration, with options as said above and drag-and-drop for adding and removing columns and reordering
  
  
  • Dynamic filter option based with relevant conditions on the field type either in the registry or GraphQl inflection
  
  
• Edit/Create:
  
  
  
  • Generate the create or edit forms based on the JSON layout configuration having mapping between the field, component registry and the placement
  
  
  • Create or Edit Form designer with a pane having list of the fields in the selected entity and drag-and-drop option to design the form. With options for each selected field to add label, id, required, placeholder, validations, expressions, mask, etc.
  
  

It looks biggy. But, In addition to change the underlying libraries and optimisation, I think it's worth looking at adding these features for better usability.

Please keep me posted on your feedback.

[fzaninotto]

@dgkm Please don't use this thread as a feature request, open a new issue for each idea to open the discussion.

As a side note, we will not take the path of configuring the view based on rules. This was what we did with marmelab/ng-admin and we don't want to take that path. Also, this can be done in user land.

[mehrdad-shokri]

@fzaninotto How much is next branch stable now?
Also how much time would it take to migrate to next when it's released?

[djhi]

@mehrdad-shokri https://github.com/marmelab/react-admin/issues/3194#issuecomment-509002564

[mehrdad-shokri]

@djhi how about its state of stability?

[djhi]

If you mean how many breaking changes are we still planning to include, it's currently difficult to answer. Check the list of tasks in the first comment, you'll see that some will probably add more breaking changes (the redux-form migration to final-form for example)

[mehrdad-shokri]

@djhi no I mean I wanna start my project based on next branch. is it stable enough to do that?

[js-chris]

@djhi I also like to use react-admin in a new project, but I also need to use material-ui 4. Do you think it is possible to start my new project with the next branch for a couple of weeks, before switching to Version 3?

And how would be the best way to install it? I tried:
yarn add react-admin@next ra-data-json-server@next prop-types
But ra-ui-materialui and ra-core are still 2.9.4

Thanks
Chris

[afilp]

About switching to react-final-form, should we be worried about this statement there?

_"If you need to mutate your data via dispatching Redux actions, you should probably use Redux Form."_
https://github.com/final-form/react-final-form#redux-example

[smeng9]

@afilp Currently if we want to link two inputs, we are mutating data via dispatching Redux actions. This is the use case of using Redux Form. Not sure if there is any react-final-form equivalent to achieve this.

[nik-lampe]

See my comment in #3285

Maybe comments concerning the subject of switchting to react-final-form should be made there, to keep this thread here clear 🙌

[mehrdad-shokri]

Can someone on the team provide some information for us?
I'm starting a new admin dashboard and I wanna start my project on next version.
Is it stable enough to start my development based on next? (encountering some minor bugs is acceptable for me)
Can I use master branch in a project where I use material-ui version 4? Is it possible to create custom components with material-ui 4 and use it as a prop component for react-admin?

[fzaninotto]

@mehrdad-shokri We'll publish an alpha release when we consider the API is stable enough. Until then, we don't recommend that you use the next version.

We expect the 3.0 to be released sometime in the Summer of 2019.

[mehrdad-shokri]

@fzaninotto how about the second part of my question? Can you guide me on that too?

[fzaninotto]

No, master requires material-ui v1.

[mehrdad-shokri]

@fzaninotto so with your descriptions I'm blocked. My boilerplate is based on material-ui 4.
I can't use master version since it requires material-ui v1, and you don't recommend me to use next version.
What should I do?

[fzaninotto]

Sorry, I can't help you, please use stackoverflow for support.

[mehrdad-shokri]

It's not a technical question to ask on SO. My question was related to the roadmap of this project

[aymendhaya]

@mehdad-shokri you can by now use mui v3.x.x with the actual 2.x react-admin until the v3 is released. There is a hack published on the net on how you can do it.

[fzaninotto]

I've just published [email protected]. Not yet ready for production, but if you're feelling adventurous, we need your feedback!

[js-chris]

Thank you very much. @fzaninotto!

I tried a fresh install, but got this error:
./node_modules/ra-core/esm/util/renderWithRedux.js
Module not found: Can't resolve 'react-testing-library' in '/sites/react/react-admin-alpha/node_modules/ra-core/esm/util'

Do you know what is happening here?

[fzaninotto]

@js-chris that's a bug - see #3431

[paaacman]

Thanks for react-admin !
Do you know when you may release a stable version of React-Admin 3.0 ?

[fzaninotto]

@paaacman when it's done.

[fzaninotto]

I've just published react-admin 3.0.0-alpha.1. There should not be any more problems at installation.

https://github.com/marmelab/react-admin/releases/tag/v3.0.0-alpha.1

[esistgut]

Not sure if this is intentional but ra-language-french is stuck at version alpha.0.

[fzaninotto]

Yes, there was nothing new in this package so Lerna didn't republish it.

[dgkm]

@fzaninotto I tried the following and able to start the demo without any issues.

1. git clone https://github.com/marmelab/react-admin.git react-admin-alpha
2. cd react-admin-alpha
3. yarn
4. yarn build
5. yarn build-demo
6. yarn run-demo

Please confirm if I'm missing anything?

Because from an UI perspective I was unable to find out much difference in the demo app other than I felt bit slow to start with.

Also, please let me know if any particular test case to be tested in the demo app.

[fzaninotto]

@dgkm You've cloned the master branch, which is the 2.x branch. To install the 3.0, use npm and install [email protected].

As for the feedback we're waiting, more than regressions you may notice in the demo, we'd love to hear about difficulties you have when upgrading an existing app, or the usability of the new APIs (mostly hooks).

Concerning performance, we haven't done any profiling on the 3.0.0 branch yet, so it may be slower than the 2.x branch. We'll do an optimization pass before releasing the stable version.

[dgkm]

In fact I checked out the alpha.1 with git checkout v3.0.0-alpha.1 before I ran 3. yarn

Sure, I will try upgrading the existing project installing [email protected] using package installer and come back.

Between, do you any draft document or note about upgrade procedure or is it as simple as installing react-admin package?

[dgkm]

I'm getting the following error on startup after the upgrade without changing anything other than react-admin package:

Element type is invalid: expected a string (for built-in components) or a class/function (for composite components) but got: object.

Check the render method of CoreAdmin.

at line this.setState({ dataProvider }); in the App.js (refer to the screenshot below)

Any thoughts?

[djhi]

@dgkm There is an upgrade guide at the repository root. Try following it ?

[nanoander]

Hi, I'm asking here since it doesn't deserve its own issue.
Is it possible to use React-Admin v3 with NextJs, or there's any incompatibility?
Thanks.

[pooriyababaei]

Hi. Please fix FileInput problem in version 2.9.4. it accepts nothing. There is already an issue for this problem.

[djhi]

I locked this issue as many people use it to ask unrelated questions or howto questions which should be asked on Stackoverflow. Please read the contributing guide.

[fzaninotto]

We've finally ticked all the boxes: react-admin v3 is out in beta. We'll now focus on fixing bugs and improving performance and documentation, and we hope to publish a stable v3 within a few weeks.

New features will have to wait until 3.1, and new breaking changes will have to wait until 4.0 (which is not even scheduled).

[fzaninotto]

React-admin v3 was released yesterday!