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:

• Upgrade dependencies to the latest major version
  • Upgrade react and react-dom to 16.8 to use Hooks ([RFR] Upgrade dependencies #3170)
  • Upgrade material-ui to 4.2.1 (instead of 1.5) to use... a lot of things, uncluding the useStyle hook ([RFR] Upgrade material-ui to v4 #3191)
  • Upgrade react-redux to 7.1.0 (instead of 5.0) to use useDispatch and useSelector hooks instead of connect ([RFR] Upgrade dependencies #3170)
  • Upgrade redux-saga to 1.0 (because we're on a non-supported version) ([RFR] Upgrade redux saga #3212)
  • Switch from redux-form to react-final-form ([BC Break] Migrate from redux-form to react-final-form #3455)
• Turn logic components into hooks
  • Replace fetch, accumulate, undo and callback sagas by data hooks for fetching the dataProvider (useQuery, useMutation, useDataProvider) ([RFR] Data hooks #3181)
  • Add CRUD hooks ([RFR] Add Crud hooks #3253)
  • Replace auth saga by auth hooks (useAuth, usePermissions) ([RFR] Add auth hooks #3368)
  • Replace i18n saga by i18n hooks (useTranslate, useLocale, useSeltLocale) ([RFR] Add useTranslate hook #3188, [RFR] Refactor I18n layer to use hooks #3672, [RFR] I18n provider new signature #3685))
  • Replace notification, redirect, and refresh sagas by hooks (useNotify, useRedirect, useRefresh) ([RFR] Declare fetch side effects as function #3425)
  • Add controller hooks to replace our controller components ([RFR] Use hooks in controllers #3213, [RFR] Extract custom hooks from controllers #3217, [RFR] Reference hooks #3228, [RFR] Reference many hooks #3236, [RFR] Add useEditController hook #3398, [RFR] Add useListController hook #3377, [RFR] Add useShowController hook #3406, [RFR] Add useCreateController hook #3409)
  • Add useMediaQuery hook to replace the Responsive component ([RFR] Migrate Responsive to custom media queries #3329)
  • Update the documentation to use hooks ([RFR] Code cleanup #3688)
  • Update the examples to use hooks
• Turn providers to objects instead of functions
  • authProvider ([RFR] Add missing translation in NullableBooleanInput #3614)
  • i18nProvider ([RFR] Replace I18nProvider function by object #3699)
  • dataProvider ([RFR] Convert DataProvider to Object #3726)
• Fix breaking change issues
  • Replace injected elements by injected components ([RFR] Replace injected elements by injected components #3262)
  • Upgrade redux-saga to 1.0 ([RFR] Upgrade redux saga #3212)
  • Redirection to login should be done in the authProvider ([RFR] Delegate the redirection after logout to authProvider #3269)
  • Decouple data actions from views
  • Rename appLayout to layout in (Rename appLayout prop to layout in <Admin> component  #3055)
  • Use theme to store sidebar width ([RFR] Use theme to store sidebar width #3323)
  • Replace papaparse by something lighter ([RFR] Replace papaparse with a lighter library #3324)
  • Deprecation of react-router-redux ([RFR] Upgrade dependencies #3170)
  • rename isLoading to loading everywhere ([RFR] Rename isLoading to loading everywhere #3644)
  • Remove deprecated components ([RFR] Replace Headroom by native Material-ui solution #3247, [RFR] Remove BulkActions in V3 #3517)
• UI adjustments
  • Move actions out of the main card ([RFR] Move Actions out of the Card #3214)
  • Replace Headroom by MUI native implementation of auto-hiding app bar ([RFR] Replace Headroom by native Material-ui solution #3247)
  • Use filled variant by default in forms ([RFR] Improve form look and feel #3594)
• Make sure the core codebase doesn't need the crudXXX actions and the fetch saga
• Reimplement AutocompleteInput and AutocompleteArrayInput using downshift ([RFR] New AutocompleteInput using Downshift #3031, [RFR] New AutocompleteArrayInput #3667)
• Decide whether we should stick to connected-react-router or not (because it's not active)
• Move most dependencies into peerDependencies for internal packages ([RFR] move stateful to peer dependencies and devDependencies within modules, add them to react-admin as dependencies #3763)
• Overhaul HTTP error handling (Ensure DataProvider does not alter the original error #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 microsoft/TypeScript#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: reduxjs/redux#1287 (comment)

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

2. This issue was a result of all the forms using the same part of the state
   Reset record-form not triggered on Create #2129
   It has been solved, but in my opinion the solution is just a workaround. It works though... 😁

3. 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.

[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 react-admin@3.0.0-alpha.0. 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 react-admin@3.0.0-alpha.1.

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 react-admin@3.0.0-alpha.1 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.

[pooriababaei]

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!