Material-ui: Codemod error when upgrading from v0.18.7 to v1.1.0

[stephenfriedman]

Using the scripts provided here, starting with the first one:

find src -name '*.js' -print | xargs jscodeshift -t node_modules/@material-ui/codemod/lib/v1.0.0/import-path.js

It should be noted that I did already update my imports per the codemod documentation:

Notice: if you are migrating from pre-v1.0, and your imports use material-ui, you will need to manually find and replace all references to material-ui in your code to @material-ui/core.

This results in the following error in the console (likely babel related?):

ERR src/index.js Transformation error SyntaxError: This experimental syntax requires enabling the parser plugin: 'exportDefaultFrom' (1:7) at _class.raise (/Users/stephen/.nvm/versions/node/v10.3.0/lib/node_modules/jscodeshift/node_modules/babylon/lib/index.js:776:15) at _class.expectPlugin (/Users/stephen/.nvm/versions/node/v10.3.0/lib/node_modules/jscodeshift/node_modules/babylon/lib/index.js:2084:18) at _class.parseExport (/Users/stephen/.nvm/versions/node/v10.3.0/lib/node_modules/jscodeshift/node_modules/babylon/lib/index.js:4962:12) at _class.parseStatementContent (/Users/stephen/.nvm/versions/node/v10.3.0/lib/node_modules/jscodeshift/node_modules/babylon/lib/index.js:4049:27) at _class.parseStatement (/Users/stephen/.nvm/versions/node/v10.3.0/lib/node_modules/jscodeshift/node_modules/babylon/lib/index.js:3962:17) at _class.parseBlockOrModuleBlockBody (/Users/stephen/.nvm/versions/node/v10.3.0/lib/node_modules/jscodeshift/node_modules/babylon/lib/index.js:4513:23) at _class.parseBlockBody (/Users/stephen/.nvm/versions/node/v10.3.0/lib/node_modules/jscodeshift/node_modules/babylon/lib/index.js:4500:10) at _class.parseBlockBody (/Users/stephen/.nvm/versions/node/v10.3.0/lib/node_modules/jscodeshift/node_modules/babylon/lib/index.js:5462:44) at _class.parseTopLevel (/Users/stephen/.nvm/versions/node/v10.3.0/lib/node_modules/jscodeshift/node_modules/babylon/lib/index.js:3938:10) at _class.parse (/Users/stephen/.nvm/versions/node/v10.3.0/lib/node_modules/jscodeshift/node_modules/babylon/lib/index.js:5304:17) All done. Results: 1 errors 1 unmodified 17 skipped 3 ok Time elapsed: 1.241seconds

• [ ] This is a v1.x issue (v0.x is no longer maintained).
• [x] I have searched the issues of this repository and believe that this is not a duplicate.

Context

I have a project that I want to upgrade to react v^16.3.2 that is currently using material-ui v0.18.7. I understand that in order to use react v16.x.x that I need to upgrade my material-ui components to v1.x.x. In doing so I attempted to use the migration script but this has failed in my project.

Your Environment

I am running node v10.3.0

| Tech | Version |
|--------------|---------|
| babel-core | v6.26.0 |
| Material-UI | v1.2.1 |
| React | v16.3.2 |
| Node | v10.3.0 |

[oliviertassinari]

Using the scripts provided here, starting with the first one

@stephenfriedman This codemod targets people upgrading from v1.0.0-beta to v1.0.0. I fear you gonna have to do it by hand for anything else.

[stephenfriedman]

@oliviertassinari Does this mean that the only documentation provided for the migration from v0.18.7 to v1.1.0 (or from any v0.x.x to any v1.x.x version) lives here? I cannot seem to find any sources that help with the migration and many of the changes seems to not be backwards compatible regarding the component names/props.

[oliviertassinari]

We have a documentation page to start with the migration: https://material-ui.com/guides/migration-v0x/.

[stephenfriedman]

@oliviertassinari While I understand a developer will have to do some work to comply with a major version change, the documentation for this migration seems lackluster. It suggests to run the codemod, which we determined here in this thread that it cannot be used, then finally says

After that, you are free to migrate one component instance at the time.

This really just feels like it is leaving the devs out to dry, given that this is certainly the bulk of the work and where the problems are that they will encounter.

I have to imagine I am not the first dev to be in this position and am surprised I have not seen too many others raising the issue I am having.

As you can imagine, rewriting an entire project's components almost defeats the purpose of using the library at all.

[petersendidit]

Might be good to add a link to the migration/upgrade guide on the home page for a while as many people will be looking for it. Also might be good to add a link to it from the "Get Started" page. The blog post announcing 1.0 doesn't reference the migration guide at all.

These are all places I had looked for this information and did not find it and figured since #7195 was still open that it had not been completed yet.

[oliviertassinari]

Might be good to add a link to the migration/upgrade guide on the home page for a while as many people will be looking for it.

@petersendidit I agree. I think that we should give more exposure to this page.

The blog post announcing 1.0 doesn't reference the migration guide at all.

@stephenfriedman I'm not sure we can call it a real migration guide. It's pretty much a backbone we created one year ago in the hope people would contribute their experience into it. Some have contributed codemod, some have contributed fixes to the markdown, but it will never be an easy task.
The thing is, breaking changes in UI are hard to recover from. v1.x is a complete rewrite, we started from scratch undoing a lot of API and implementation decisions taken in v0.x.

As you can imagine, rewriting an entire project's components almost defeats the purpose of using the library at all.

Many people in the industry write their own UI components, +50%. It's what I have been doing for years before starting contributing to Material-UI. It's also why I focus on low-level components that can be reused & composed. High-level components are valuable too, but target people how are prototyping.
Also, a large chunk of the value UI component libraries bring comes from the documentation convention & guidance it's providing. It's a common language you can speak with your team.

[stephenfriedman]

@oliviertassinari I really do appreciate the quick answers and support. All of your points are valid. That said, I certainly think that for such a large project with a huge reach, that a slightly more in depth "migration guide" would have tremendous value. Just as you said that much of the value from a UI component library comes from the documentation and guidance it's providing, I think that taking another look at the current migration documentation is in store.

So far the best contribution I have seen is here

Perhaps once I complete the migration I can help contribute to a migration guide.