[docs][material-ui] Revise and split up "Styled engine" doc (#37774)

Signed-off-by: Sam Sycamore <[email protected]> Co-authored-by: Olivier Tassinari <[email protected]> Co-authored-by: Brijesh Bittu <[email protected]>
mui · Sep 5, 2023 · e9bd183 · e9bd183
1 parent d9cdb05
commit e9bd183
Show file tree

Hide file tree

Showing 38 changed files with 285 additions and 248 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1471,7 +1471,7 @@ _Apr 11, 2023_
 
 A big thanks to the 9 contributors who made this release possible. Here are some highlights ✨:
 
-- 💫 Added [theme scope](https://mui.com/material-ui/guides/styled-engine/#theme-scoping) for using multiple design systems (#36664) @siriwatknp
+- 💫 Added [theme scope](https://mui.com/material-ui/guides/theme-scoping/) for using multiple design systems (#36664) @siriwatknp
 - 🐛 bug fixes and 📚 documentation improvements.
 
 ### `@mui/[email protected]`

diff --git a/README.md b/README.md
@@ -98,7 +98,7 @@ npm install @mui/system @emotion/react @emotion/styled
 yarn add @mui/system @emotion/react @emotion/styled
 ```
 
-Or if you want to use `styled-components` as a styling engine:
+Or if you want to use styled-components as the styling engine:
 
 **npm:**
 
@@ -112,7 +112,7 @@ npm install @mui/material @mui/styled-engine-sc styled-components
 yarn add @mui/material @mui/styled-engine-sc styled-components
 ```
 
-Visit our [`styled-engine` guide](https://mui.com/material-ui/guides/styled-engine/) for more information about how to configure `styled-components` as the style engine.
+Visit our [styled-components guide](https://mui.com/material-ui/guides/styled-components/) for more information on configuration.
 
 ## Sponsors
 

diff --git a/docs/data/material/getting-started/installation/installation.md b/docs/data/material/getting-started/installation/installation.md
@@ -51,7 +51,13 @@ pnpm add @mui/material @mui/styled-engine-sc styled-components
 
 </codeblock>
 
-Visit the [Styled engine guide](/material-ui/guides/styled-engine/) for more information about how to configure styled-components.
+:::error
+As of late 2021, [styled-components](https://github.com/styled-components/styled-components) is **not compatible** with server-rendered Material UI projects.
+This is because `babel-plugin-styled-components` isn't able to work with the `styled()` utility inside `@mui` packages.
+See [this GitHub issue](https://github.com/mui/material-ui/issues/29742) for more details.
+
+We **strongly recommend** using Emotion for SSR projects.
+:::
 
 ## Peer dependencies
 

diff --git a/docs/data/material/guides/interoperability/interoperability-pt.md b/docs/data/material/guides/interoperability/interoperability-pt.md
@@ -290,7 +290,8 @@ export default function GlobalCssSliderDeep() {
 
 ### Alterar o motor de estilo padrão
 
-By default, MUI components come with Emotion as their style engine. If, however, you would like to use `styled-components`, you can configure your app by following the [styled engine guide](/material-ui/guides/styled-engine/#how-to-switch-to-styled-components) or starting with one of the example projects:
+By default, Material UI components come with Emotion as their style engine. 
+If, however, you would like to use styled-components, you can configure your app by following the [styled-components guide](/material-ui/guides/styled-components/) or starting with one of the example projects:
 
 <!-- #default-branch-switch -->
 

diff --git a/docs/data/material/guides/interoperability/interoperability-zh.md b/docs/data/material/guides/interoperability/interoperability-zh.md
@@ -287,7 +287,8 @@ export default function GlobalCssSliderDeep() {
 
 ### 改变默认的样式引擎
 
-By default, MUI components come with Emotion as their style engine. If, however, you would like to use `styled-components`, you can configure your app by following the [styled engine guide](/material-ui/guides/styled-engine/#how-to-switch-to-styled-components) or starting with one of the example projects:
+By default, Material UI components come with Emotion as their style engine. 
+If, however, you would like to use styled-components, you can configure your app by following the [styled-components guide](/material-ui/guides/styled-components/) or starting with one of the example projects:
 
 <!-- #default-branch-switch -->
 

diff --git a/docs/data/material/guides/interoperability/interoperability.md b/docs/data/material/guides/interoperability/interoperability.md
@@ -289,8 +289,8 @@ export default function GlobalCssSliderDeep() {
 
 ### Change the default styled engine
 
-By default, Material UI components come with Emotion as their style engine. If,
-however, you would like to use `styled-components`, you can configure your app by following the [styled engine guide](/material-ui/guides/styled-engine/#how-to-switch-to-styled-components) or starting with one of the example projects:
+By default, Material UI components come with Emotion as their style engine.
+If, however, you would like to use styled-components, you can configure your app by following the [styled-components guide](/material-ui/guides/styled-components/) or starting with one of the example projects:
 
 <!-- #default-branch-switch -->
 

diff --git a/docs/data/material/guides/right-to-left/right-to-left-pt.md b/docs/data/material/guides/right-to-left/right-to-left-pt.md
@@ -49,7 +49,9 @@ npm install stylis stylis-plugin-rtl
 ```
 
 :::warning
-**Note**: Only `emotion` is compatible with version 2 of the plugin. `styled-components` requires version 1. If you are using `styled-components` as a [styled engine](/material-ui/guides/styled-engine/), make sure to install the correct version.
+Only Emotion is compatible with version 2 of the plugin. 
+styled-components requires version 1. 
+If you're using [styled-components instead of Emotion](/material-ui/guides/styled-components/), make sure to install the correct version.
 :::
 
 In case you are using `jss` (up to v4) or with the legacy `@mui/styles` package, you need [`jss-rtl`](https://github.com/alitaheri/jss-rtl) to flip the styles.

diff --git a/docs/data/material/guides/right-to-left/right-to-left-zh.md b/docs/data/material/guides/right-to-left/right-to-left-zh.md
@@ -49,7 +49,9 @@ npm install stylis stylis-plugin-rtl
 ```
 
 :::warning
-**Note**: Only `emotion` is compatible with version 2 of the plugin. `styled-components` requires version 1. If you are using `styled-components` as a [styled engine](/material-ui/guides/styled-engine/), make sure to install the correct version.
+Only Emotion is compatible with version 2 of the plugin. 
+styled-components requires version 1. 
+If you're using [styled-components instead of Emotion](/material-ui/guides/styled-components/), make sure to install the correct version.
 :::
 
 In case you are using `jss` (up to v4) or with the legacy `@mui/styles` package, you need [`jss-rtl`](https://github.com/alitaheri/jss-rtl) to flip the styles.

diff --git a/docs/data/material/guides/right-to-left/right-to-left.md b/docs/data/material/guides/right-to-left/right-to-left.md
@@ -50,7 +50,9 @@ npm install stylis stylis-plugin-rtl
 ```
 
 :::warning
-Only Emotion is compatible with version 2 of the plugin. `styled-components` requires version 1. If you are using `styled-components` as a [styled engine](/material-ui/guides/styled-engine/), make sure to install the correct version.
+Only Emotion is compatible with version 2 of the plugin.
+styled-components requires version 1.
+If you're using [styled-components instead of Emotion](/material-ui/guides/styled-components/), make sure to install the correct version.
 :::
 
 In case you are using `jss` (up to v4) or with the legacy `@mui/styles` package, you need [`jss-rtl`](https://github.com/alitaheri/jss-rtl) to flip the styles.

diff --git a/.../guides/styled-engine/styled-engine-pt.md → ...styled-components/styled-components-pt.md b/.../guides/styled-engine/styled-engine-pt.md → ...styled-components/styled-components-pt.md
diff --git a/.../guides/styled-engine/styled-engine-zh.md → ...styled-components/styled-components-zh.md b/.../guides/styled-engine/styled-engine-zh.md → ...styled-components/styled-components-zh.md
diff --git a/docs/data/material/guides/styled-components/styled-components.md b/docs/data/material/guides/styled-components/styled-components.md
@@ -0,0 +1,115 @@
+# Using styled-components
+
+<p class="description">Learn how to use styled-components instead of Emotion with Material UI.</p>
+
+:::error
+As of late 2021, [styled-components](https://github.com/styled-components/styled-components) is **not compatible** with server-rendered Material UI projects.
+This is because `babel-plugin-styled-components` isn't able to work with the `styled()` utility inside `@mui` packages.
+See [this GitHub issue](https://github.com/mui/material-ui/issues/29742) for more details.
+
+We **strongly recommend** using Emotion for SSR projects.
+:::
+
+By default, Material UI uses [Emotion](https://github.com/emotion-js/emotion) to generate CSS styles.
+All components rely on the `styled()` API to inject CSS into the page.
+This API is supported by multiple popular styling libraries, which makes it possible to switch between them in Material UI.
+
+MUI provides two different packages to wrap your chosen styling solution for compatibility with Material UI:
+
+- `@mui/styled-engine`: a thin wrapper around Emotion's [`styled()`](https://emotion.sh/docs/styled) API that includes required utilities like the `<GlobalStyles />` component, the `css` and `keyframe` helpers, and more. This is the default, and you do not need to install it.
+- `@mui/styled-engine-sc`: a similar wrapper, but specifically tailored for styled-components. You must install and implement this package to use styled-components with Material UI.
+
+These two packages implement the same interface, making them interchangeable.
+
+## Bundler configuration
+
+By default, `@mui/material` has `@mui/styled-engine` as a dependency.
+To use styled-components, you need to configure your bundler to replace it with `@mui/styled-engine-sc`.
+
+### With yarn
+
+If you're using yarn, you can configure it using a package resolution:
+
+**package.json**
+
+<!-- #default-branch-switch -->
+
+```diff
+ {
+   "dependencies": {
+-    "@mui/styled-engine": "latest"
++    "@mui/styled-engine": "npm:@mui/styled-engine-sc@latest"
+   },
++  "resolutions": {
++    "@mui/styled-engine": "npm:@mui/styled-engine-sc@latest"
++  },
+ }
+```
+
+### With npm
+
+Because package resolutions aren't available with npm, you must update your bundler's config to add this alias.
+The example below shows how to do this with Webpack:
+
+**webpack.config.js**
+
+```diff
+ module.exports = {
+   //...
++  resolve: {
++    alias: {
++      '@mui/styled-engine': '@mui/styled-engine-sc'
++    },
++  },
+ };
+```
+
+For TypeScript, you must also update the `tsconfig.json` as shown here:
+
+**tsconfig.json**
+
+```diff
+ {
+   "compilerOptions": {
++    "paths": {
++      "@mui/styled-engine": ["./node_modules/@mui/styled-engine-sc"]
++    }
+   },
+ }
+```
+
+### Next.js
+
+**next.config.js**
+
+```diff
++const withTM = require('next-transpile-modules')([
++  '@mui/material',
++  '@mui/system',
++  '@mui/icons-material', // If @mui/icons-material is being used
++]);
+
++module.exports = withTM({
+ webpack: (config) => {
+   config.resolve.alias = {
+     ...config.resolve.alias,
++    '@mui/styled-engine': '@mui/styled-engine-sc',
+    };
+    return config;
+  }
++});
+```
+
+## Ready-to-use examples
+
+MUI provides boilerplate examples of Create React App with Material UI and styled-components in both JavaScript and TypeScript:
+
+<!-- #default-branch-switch -->
+
+- [Material UI + CRA + styled-components (JavaScript)](https://github.com/mui/material-ui/tree/master/examples/material-ui-cra-styled-components)
+- [Material UI + CRA + styled-components (TypeScript)](https://github.com/mui/material-ui/tree/master/examples/material-ui-cra-styled-components-ts)
+
+:::warning
+`@emotion/react`, `@emotion/styled`, and `styled-components` are optional peer dependencies of `@mui/material`, so you need to install them yourself.
+See the [Installation guide](/material-ui/getting-started/installation/) for more info.
+:::