[docs] 0.x => 1.x migration guide

[rsolomon]

I apologize if this has been addressed already. I spent some time searching previous issues but didn't see anything obvious. It would be immensely helpful if a migration was published to help those heavily invested in the 0.x version of MUI migrate to 1.x.

[oliviertassinari]

@rsolomon That's a great question, thanks for asking.

I think that we should wait the beta or pre-releases version before starting working on a migration guide. Thing changes, I would rather keep the guide close to the v1.0.0 release.
I don't think that we will be able to get a migration guide covering everything, but, we can try our best to match 80% of it with 20% of the effort. Ideally, the migration guide would be written by someone how did that migration.
Personally, I have migrated my codebases a long time ago to the next branch, actually started two projects with it. So it's unlikely I work on it, but I will help anyone interested.

[oliviertassinari]

To ease the migration process, you can install both versions of the same time with yarn alias:

yarn add material-ui@latest
yarn add material-ui-next@npm:material-ui@next

then

import FlatButton from 'material-ui/FlatButton'; // v0.x
import Button from 'material-ui-next/Button'; // v1.x

[lzzparis]

A migration guide would be incredibly helpful, so I'm glad that this is being tracked for the v1.0.0-prerelease. Wondering kind of content will be included. I'd love to see:

• Component comparisons including:
  • What's been renamed, condensed, deprecated
  • How existing component instances need to be updated
• Theme or other core updates that need to be made

Is this in progress?

[AubreyF]

@oliviertassinari Installing both versions simultaneously sounds like a workable transition strategy, but in practice each version's MuiThemeProvider theme structure is different enough that I haven't had success in getting both versions to coexist peacefully in the same project.

Once solution to this could be including an MuiThemeProvider container for each interface section rather than a single container for the entire app, and migrating each section from v0.18 to v1 independently. Another potential solution could be nesting multiple MuiThemeProviders, which appears to be again supported after it's intentional deprecation in #4155. In my tests, the latter approach results in "Cannot read property 'floatingLabelColor' of undefined" errors or elements turning black when interacted, depending on whether I nest the v0.18 or v1 theme as a child of the other. Any thoughts on making this work successfully?

[edit]
I now have elements from both V0.18 and V1 playing nicely together!
For others who are interested, here's the approach that worked:

import MuiThemeProvider from 'material-ui/styles/MuiThemeProvider';
import MuiThemeProviderNext from 'material-ui-next/styles/MuiThemeProvider';
import {muiThemev018, muiThemev1} from '../styles/AppStyle';

//...

<MuiThemeProviderNext theme={muiThemev1}>
  <MuiThemeProvider muiTheme={muiThemev018}>
    // ...
  </MuiThemeProvider>
</MuiThemeProviderNext>

[oliviertassinari]

Another potential solution could be nesting multiple MuiThemeProviders

@AubreyF This is what I have been doing on SplitMe.

[eyn]

import FlatButton from 'material-ui/FlatButton'; // v0.x
import Button from 'material-ui-next/Button'; // v1.x

Works really well apart from where there is a peer-dependency on 'material-ui' when the wrong version can be resolved (particularly with material-ui-icons). This can be fixed with a webpack plugin to rewrite requests from the material-ui-icons (or any other module) and redirect them to material-ui-next.

Example plugin is here: https://gist.github.com/eyn/deda28b68390fc81cbe7145cc43513ea

Just add it to your webpack config and include it under the config's resolve key:

  resolve: {
    extensions: [".jsx", ".js", ".json"],
    plugins: [MaterialUIIconResolver]
  },

[audrium]

For those who wonder how to add webpack config to your create-react-app project check out react-app-rewired. Worked for me like a charm

[remy-poirier]

Hi,

I would like to begin migration from v0.XX.X to v1 too, and I would like to install them both.

How can I do that using NPM please ? I couldn't find a way to alias material-ui-next and use both in my application.

Any help would be nice, thank you !

[eyn]

There is no longer a need to use the Webpack Plugin for material-ui-icons - see here: #8458

[sagar-sm]

Just wanted to mention how I did it on a project using NPM's package.json, for those of you who do not wish to move from npm to yarn -

TL;DR: Clone the v1-beta branch, build it and push the build directory as a new git repository aliased under a new name. Then npm install directly from the git repository.

1. Clone and cd into this repository and git checkout v1-beta.
2. Run yarn && yarn build
3. Copy all the contents inside the /build directory into a new directory.
4. Change the package name inside the package.json of the built version to an alias of your choice, e.g. material-ui-next.
5. Init a git repository and push it to convenient remote, say, Github.
6. npm i --save git+https://github.com/<your-username>/material-ui-next.git should install the aliased version of the repository, and you can use it along with your v0 installation as highlighted by @AubreyF.

package.json

 "material-ui": "^0.19.4",
 "material-ui-next": "git+https://github.com/uplevel-technology/material-ui-next.git",
 "material-ui-icons": "^1.0.0-beta.17",

It's not the most ideal process as you have to manually keep updating your aliased repository from the remote branch, but I am willing to pay this price for a smooth transition from v0 to v1.

[Amol023]

@oliviertassinari, Thank you for the solution! The Snackbar on V1 is awesome

But our build tools (jenkins) doesn't seem to understand 'material-ui-next': 'yarn:material-ui@next'

Any suggestions?

[nWidart]

Hello,

When using typescript, is there a specific version of the @types/material-ui to use? ^0.20.7 seem to have some of the types.

Thanks,

[tqle]

Hi,
I just updated to the latest and didn't see where or why Reboot got renamed or deprecated.
I had to change the "material-ui/Reboot" import to "cssBaseline". There was no documentation on this on this page https://material-ui.com/style/css-baseline/.

Can you make note that Reboot is deprecated and needs to be replaced with CssBaseline?
Also can you make note on the css-baseline page, that the CssBaseline must before you are using a BrowserRouter.
Ex:

      <MuiThemeProvider>
         <CssBaseline/>
        <BrowserRouter>
          <!-- Main Component -->
        </BrowserRouter>
      </MuiThemeProvider>

[oliviertassinari]

@tqle You need to pay attention to the release notes.
@nWidart TypeScript definitions are hosted on Material-UI. You do no longer need the @types/material-ui dependency.

[tqle]

Thank you Olivier. I missed that in the release notes.

[devuxer]

1.0 newbie question: Do I need to separately install jss and react-jss or are JSS features already built in to material-ui?

[mbrookes]

@devuxer Please try to avoid piling on to existing issues with unrelated questions. That being said, welcome!

The answer to your question is in the docs (and the README):

https://material-ui.com/getting-started/installation/
https://material-ui.com/getting-started/usage/#quick-start

[devuxer]

@mbrookes,

Apologies for piling onto this issue, but I am in fact trying to migrate from 0.x to 1.0, and this was something I thought would be something of concern to others trying to make the same leap.

Thank you for those links, but I read both of those before posting, and "JSS" doesn't appear on either page. There are pages that discuss JSS, but I'm still not clear on whether I need additional JSS npm packages or if material-ui is all I need.

EDIT: Ahh, I think I found my answer in the FAQ. Don't know how I missed that the first time around.

[anuragagarwal561994]

I am trying to make a gist here for my upgrades if it helps anyone. It is currently WIP.

[clu3]

the codemod https://github.com/mui-org/material-ui/tree/master/packages/material-ui-codemod doesn't seem to work. Any one got any success with it?

[mbrookes]

@abuteler Please see #11369

[yyyyaaa]

Does anyone have guideline to migrate from 1.0.0-beta.31 to the latest stable version?

[bitcoin-coder-bob]

@clu3 check out olivier's comment here: #11819 (comment)

[tomasdev]

@yyyyaaa I had to do a couple find & replace in files for from 'material-ui/ to from '@material-ui/core/ but then followed https://material-ui.com/guides/migration-v0x/ and it worked seamlessly! though now I'm fixing minor CSS changes that happened. It will also require to update to React 16.3+

[oliviertassinari]

We are maintaining a migration guide for the v3 to v4 migration. It will much easier this time! We have also deferred a few breaking changes to v5 to make it easier.

[maxjf1]

ADD pickers reference on the migration guide (no suport from v1)

[themakerman]

@sagar-sm Hey sagar, could you advice me on migrating from v0 to v4 now? My project is made with V0, i dont want to rewrite everything. The goal is to use both v0 and latest simultaneously using npm without using npm-alias. Similar to your solution of installing directly from git repo but not sure how will the guide me from v0 to v4