Add documentation for MUI5 with ts, npm, styled-components, webpack

[dash-tobin]

I'm having a difficult time migrating an existing project from v4 to v5 using ts, npm, styled-components, and webpack module federation.

• [ x] I have searched the issues of this repository and believe that this is not a duplicate.

Summary 💡

Help users who already have styled-components in an existing project migrate to MUI5
It should describe and give implementation examples of using StyledEngineProvider with both emotion and styled-components.
Official documentation describing the issues around styled-components and npm, mainly the (to date) requirement of emotion (#27846 (comment)).
*Included should describe why the codemon preset-safe imports StyledEngineProvider from styled-components and how to proceed with the migration using this implementation method (examples).
It should describe how to add styled-engine-sc aliases and plugins to webpack config & tsconfig
If anything, it should help users migrate from styled-components to emotion
FYI codemon preset-safe does not wrap styled-components ThemeProvider in StyledEngineProvider

Examples 🌈

if using typescript:
add this to paths object in tsconfig.json
"paths": { ... "@mui/styled-engine": ["./node_modules/@mui/styled-engine-sc"] }
If using webpack:
Add these lines to webpack.config.js

            resolve: {
                alias: {
                    ...
                    '@mui/styled-engine': path.resolve(__dirname, './node_modules/@mui/styled-engine-sc'),

                }
            }

              plugins: [
                shared: {
                    ...
                    '@mui/styled-engine': {
                        singleton: true,
                        requiredVersion: deps['@mui/styled-engine-sc'],
                    },
                }
            ]

If npx codemon preset-safe does not wrap styled-components ThemeProvider, you must change order of components ( or correct me with needed information):

  <StyledEngineProvider injectFirst>
      <ThemeProvider theme={theme}>
        <MuiThemeProvider theme={muiTheme}>

not

    <ThemeProvider theme={theme}>
      <StyledEngineProvider injectFirst>
        <MuiThemeProvider theme={muiTheme}>

Motivation 🔦

I am trying to get my company to upgrade to material-ui v5

[mnajdova]

@dash-tobin thanks for sharing this. We try to keep https://github.com/mui-org/material-ui/tree/HEAD/examples/create-react-app-with-styled-components up to date regarding the integration with styled-components.

As you already mentioned, you need to add:

webpack alias - https://github.com/mui-org/material-ui/blob/master/examples/create-react-app-with-styled-components-typescript/config-overrides.js#L5
TypeScript path (if you are using TypeScript) - https://github.com/mui-org/material-ui/blob/master/examples/create-react-app-with-styled-components-typescript/tsconfig.json#L18

It would have been much more easier if npm supported package aliases, but for now, this is the recommended setup.

---

FYI codemon preset-safe does not wrap styled-components ThemeProvider in StyledEngineProvider

You should use the ThemeProvider from @mui/material/styles. See https://mui.com/guides/migration-v4/#themeprovider-setup

---

Regarding the styled components integration, we have a note in this step about how to install it: https://mui.com/guides/migration-v4/#update-mui-version The guide is already pretty long, it would be much more confusing if we were to include in it setup for styled-components too. I am open to ideas about how we can improve it.

[dash-tobin]

Thank you for the response. I did look at this documentation before creating the issue, so it may be just me in this boat, but my hope is that others could also be helped by even more robust documentation. Though the migration doc is long I wouldn't mind more clarification if it means easier migration. Splitting these specifics here: How to Switch to Styled-Components, is a nice touch. This could be a home for emotion requirement (if using npm) I pointed to earlier.
My biggest issues revolve around:

1. StyledEngineProvider. If I had styled-components installed previous to running the npm codemon preset-safe, the codemon inserts import { ThemeProvider, Theme, StyledEngineProvider } from 'styled-components'. Because there is limited documentation (Style Library) on implementing StyledEngineProvider I was confused by the change and wondered if I should then remove this from styled-components import in leu of importing via '@mui/material/styles' or should figure out if it's possible to declare similar to declaring DefaultTheme (TypeScript) .

2. The github example you reference (both typescript and js) don't give an example implementation of StyledEngineProvider and ThemeProvider or any implementation of styled-components, simply the config. IMO It would be super helpful to have examples that are a bit more robust.
   Again I appreciate your time and love the new ideas. Due to the size and scope of my company's projects, I believe the migration process for our projects will likely resort to implementing with styled-components and slowly migrate over to emotion.

[mnajdova]

1. StyledEngineProvider. If I had styled-components installed previous to running the npm codemon preset-safe, the codemon inserts import { ThemeProvider, Theme, StyledEngineProvider } from 'styled-components'.

This looks like a bug in the codemod. Could you maybe provide a simple reproduction of it? A file or parts of file could be enough.

2. The github example you reference (both typescript and js) don't give an example implementation of StyledEngineProvider and ThemeProvider or any implementation of styled-components, simply the config. IMO It would be super helpful to have examples that are a bit more robust.
   Again I appreciate your time and love the new ideas. Due to the size and scope of my company's projects, I believe the migration process for our projects will likely resort to implementing with styled-components and slowly migrate over to emotion.

Note that StyledEngineProvider, ThemeProvider should always be imported from @mui/material/styles! If the codemod is not doing this, it is a bug. In the examples, we try to keep them simple, this is why StyledEngineProvder is not used. Also, note that it is needed probably only while you still have JSS in your bundle (if that is the case). If you use styled-components as a styling engine and for overrides, you should not even need the StyledEngineProvider.

[MonstraG]

If you use styled-components as a styling engine and for overrides, you should not even need the StyledEngineProvider.

That is a great info I didn't see mentioned literally anywhere else.
While we're at it, where I should import styled from?

I have like 4 options:

excluding "styled-components" itself.

[siriwatknp]

where I should import styled from?

If you are using @mui/material, you should import from @mui/material/styles like this

import { styled } from '@mui/material/styles';

// or
import { styled } from '@mui/material';

[MonstraG]

import { styled } from '@mui/material';

Where should I import { css } from? Following gives me errors:

import { css } from "@mui/styled-engine";

const Container = styled("div")<{ $heightLimit: boolean }>`
	min-width: 0;

	${({ $heightLimit }) =>
		$heightLimit &&
		css`
		    height: 100vh;
		`}
`;

Gives big ts error ending in readonly SimpleInterpolation[] missing [...] from type ArrayInterpolation<some stuff here>

With styled imported like this:
import styled, { css } from "@mui/styled-engine";
it works.

But I think that results in 2 instances of name generator in the app, breaking class names in ssr

[siriwatknp]

Where should I import { css } from? Following gives me errors:

Please check the documentation. https://mui.com/guides/interoperability/#the-css-prop

[MonstraG]

Please check the documentation. https://mui.com/guides/interoperability/#the-css-prop

This is a link to Emotion section of the page.

I'm using styled-components, same as the issue op

[siriwatknp]

I'm using styled-components

@mnajdova I am not sure about styled-components css api. We might need to document it also.

[MonstraG]

@mnajdova I am not sure about styled-components css api. We might need to document it also.

And while we're here, there is also @keyframes, which is not mentioned anywhere.

[mnajdova]

We are not re-exporting the css and keyframes utilities from @mui/material, they are only exported from the @mui/system package. I'd say we should export them from @mui/material/styles so that developers don't need to think about where to import what from. The rule would be: if you are using material-design, import everything from '@mui/material/styles'; if you are building custom design system, import everything from @mui/system.

I will take a look now on the styled-components's CSS issue.

[mnajdova]

@MonstraG please create a new issue for the TypeScript issue regarding the CSS prop. It's likely that we would need to update the typings for the styled utility. We need to have different based on which styled engine will be used (emotion or styled-components).

For styled-components, npm and webpack please see #28559

There is already a PR that will close the issue. I am marking this as duplicate of #28559