From e9bd1830dc4feb4ee1eacbe02d9513ab5618cceb Mon Sep 17 00:00:00 2001 From: Sam Sycamore <71297412+samuelsycamore@users.noreply.github.com> Date: Tue, 5 Sep 2023 16:47:35 -0500 Subject: [PATCH] [docs][material-ui] Revise and split up "Styled engine" doc (#37774) Signed-off-by: Sam Sycamore <71297412+samuelsycamore@users.noreply.github.com> Co-authored-by: Olivier Tassinari Co-authored-by: Brijesh Bittu --- CHANGELOG.md | 2 +- README.md | 4 +- .../installation/installation.md | 8 +- .../interoperability/interoperability-pt.md | 3 +- .../interoperability/interoperability-zh.md | 3 +- .../interoperability/interoperability.md | 4 +- .../guides/right-to-left/right-to-left-pt.md | 4 +- .../guides/right-to-left/right-to-left-zh.md | 4 +- .../guides/right-to-left/right-to-left.md | 4 +- .../styled-components-pt.md} | 0 .../styled-components-zh.md} | 0 .../styled-components/styled-components.md | 115 ++++++++++ .../guides/styled-engine/styled-engine.md | 210 ------------------ .../guides/theme-scoping/theme-scoping.md | 95 ++++++++ .../understand-mui-packages-pt.md | 3 +- .../understand-mui-packages-zh.md | 3 +- .../understand-mui-packages.md | 2 +- docs/data/material/pages.ts | 3 +- .../installation/installation-pt.md | 4 +- .../installation/installation-zh.md | 4 +- .../installation/installation.md | 8 +- .../system/getting-started/usage/basics-pt.md | 4 +- .../system/getting-started/usage/basics-zh.md | 4 +- docs/data/system/styled/styled-pt.md | 3 +- docs/data/system/styled/styled-zh.md | 3 +- docs/data/system/styled/styled.md | 4 +- docs/pages/blog/2021-q2-update.md | 2 +- docs/pages/blog/mui-core-v5.md | 2 +- .../material-ui/guides/styled-components.js | 7 + .../{styled-engine.js => theme-scoping.js} | 2 +- docs/public/_redirects | 4 +- docs/translations/translations-pt.json | 2 +- docs/translations/translations-zh.json | 2 +- docs/translations/translations.json | 3 +- packages/mui-styled-engine-sc/README.md | 2 +- packages/mui-styled-engine-sc/package.json | 2 +- packages/mui-styled-engine/README.md | 2 +- packages/mui-styled-engine/package.json | 2 +- 38 files changed, 285 insertions(+), 248 deletions(-) rename docs/data/material/guides/{styled-engine/styled-engine-pt.md => styled-components/styled-components-pt.md} (100%) rename docs/data/material/guides/{styled-engine/styled-engine-zh.md => styled-components/styled-components-zh.md} (100%) create mode 100644 docs/data/material/guides/styled-components/styled-components.md delete mode 100644 docs/data/material/guides/styled-engine/styled-engine.md create mode 100644 docs/data/material/guides/theme-scoping/theme-scoping.md create mode 100644 docs/pages/material-ui/guides/styled-components.js rename docs/pages/material-ui/guides/{styled-engine.js => theme-scoping.js} (63%) diff --git a/CHANGELOG.md b/CHANGELOG.md index c86117cc0809ba..f46de1efacb502 100644 --- 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/system@5.12.0` diff --git a/README.md b/README.md index db9cb91f303e9a..0614fb67f9c100 100644 --- 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 index b0ecda7dac1f30..e593a70241ac3b 100644 --- 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 -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 index 6c93cf1de96afa..8e4c3d07dceb77 100644 --- 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: diff --git a/docs/data/material/guides/interoperability/interoperability-zh.md b/docs/data/material/guides/interoperability/interoperability-zh.md index 2e4a50485eb227..0aaa8dafbb421a 100644 --- 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: diff --git a/docs/data/material/guides/interoperability/interoperability.md b/docs/data/material/guides/interoperability/interoperability.md index 7f5e9218eb52eb..d80e88e0312e8b 100644 --- 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: 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 index f385c7f14fa576..da2e53a4f473f8 100644 --- 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 index 7ca5b81cf343bb..32b8346dbae9a4 100644 --- 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 index ea22cad2f4cecf..12ade3e18831e4 100644 --- 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/docs/data/material/guides/styled-engine/styled-engine-pt.md b/docs/data/material/guides/styled-components/styled-components-pt.md similarity index 100% rename from docs/data/material/guides/styled-engine/styled-engine-pt.md rename to docs/data/material/guides/styled-components/styled-components-pt.md diff --git a/docs/data/material/guides/styled-engine/styled-engine-zh.md b/docs/data/material/guides/styled-components/styled-components-zh.md similarity index 100% rename from docs/data/material/guides/styled-engine/styled-engine-zh.md rename to docs/data/material/guides/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 new file mode 100644 index 00000000000000..d08a54e727b7df --- /dev/null +++ b/docs/data/material/guides/styled-components/styled-components.md @@ -0,0 +1,115 @@ +# Using styled-components + +

Learn how to use styled-components instead of Emotion with Material UI.

+ +:::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 `` 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** + + + +```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: + + + +- [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. +::: diff --git a/docs/data/material/guides/styled-engine/styled-engine.md b/docs/data/material/guides/styled-engine/styled-engine.md deleted file mode 100644 index 015c26c5cf4b3a..00000000000000 --- a/docs/data/material/guides/styled-engine/styled-engine.md +++ /dev/null @@ -1,210 +0,0 @@ -# `@mui/styled-engine` - -

Configuring your preferred styling library.

- -The default style library used for generating CSS styles for Material UI components is [Emotion](https://github.com/emotion-js/emotion). -All of the Material UI 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. - -## How to switch to styled-components - -:::error -Using `styled-components` as an engine at this moment is not working when used in a SSR projects. -The reason is that the `babel-plugin-styled-components` is not picking up correctly the usages of the `styled()` utility inside the `@mui` packages. -For more details, take a look at this [issue](https://github.com/mui/material-ui/issues/29742). -We strongly recommend using Emotion for SSR projects. -::: - -If you already have [styled-components](https://github.com/styled-components/styled-components) installed, it's possible to use it exclusively. -There are currently two packages available to choose from: - -- `@mui/styled-engine` - a thin wrapper around [emotion's `styled()`](https://emotion.sh/docs/styled) API, with the addition of few other required utilities, such as the `` component, the `css` and `keyframe` helpers, etc. This is the default. -- `@mui/styled-engine-sc` - a similar wrapper around `styled-components`. - -These two packages implement the same interface, which makes it possible to replace one with the other. -By default, `@mui/material` has `@mui/styled-engine` as a dependency, but you can configure your bundler to replace it with `@mui/styled-engine-sc`. - -### yarn - -If you are using yarn, you can configure it using a package resolution: - -**package.json** - - - -```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" -+ }, - } -``` - -### npm - -As package resolutions are not available in npm at this moment, you need to update you bundler's config to add this alias. Here is an example of how you can do it, if you use `webpack`: - -**webpack.config.js** - -```diff - module.exports = { - //... -+ resolve: { -+ alias: { -+ '@mui/styled-engine': '@mui/styled-engine-sc' -+ }, -+ }, - }; -``` - -If you are using TypeScript, you will need to also update the TSConfig. - -**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 - -If you are using create-react-app, there is a ready-to-use template in the example projects. -You can use these `styled-component` examples as a reference: - - - -- [create-react-app](https://github.com/mui/material-ui/tree/master/examples/material-ui-cra-styled-components) -- [create-react-app with TypeScript](https://github.com/mui/material-ui/tree/master/examples/material-ui-cra-styled-components-ts) -- [and many others](https://github.com/mui/material-ui/tree/master/examples) - -:::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. -::: - -This package-swap approach is identical to the replacement of React with [Preact](https://github.com/preactjs/preact). The Preact team has documented a large number of installation configurations. If you are stuck with Material UI + styled-components, don't hesitate to check out how they solve the problem, as you can likely transfer the solution. - -## Theme scoping - -:::warning -Having more than one styling libraries could introduce unnecessary complexity to your project. You should have a very good reason to do this. -::: - -Material UI, starting from [v5.12.0](https://github.com/mui/material-ui/releases/tag/v5.12.0), can coexist with other libraries that depend on emotion or styled-components. To do that, render Material UI's `ThemeProvider` as an inner provider and use the `THEME_ID` to store the theme. - -```js -import { ThemeProvider, THEME_ID, createTheme } from '@mui/material/styles'; -import { AnotherThemeProvider } from 'another-ui-library'; - -const materialTheme = createTheme(…your theme); - -function App() { - return ( - - - …components from another library and Material UI - - - ) -} -``` - -The theme of Material UI will be separated from the other library, so when you use APIs such as `styled`, `sx` prop, and `useTheme`, you will be able to access Material UI's theme like you normally would. - -### Minimum version - -[Theme scoping](https://github.com/mui/material-ui/pull/36664) has been added to Material UI v5.12.0, so be sure you're running at that version or higher. - -### Using with [Theme UI](https://theme-ui.com/) - -Render Material UI's theme provider below Theme UI's provider and assign the material theme to the `THEME_ID` property. - -```js -import { ThemeUIProvider } from 'theme-ui'; -import { - ThemeProvider as MaterialThemeProvider, - createTheme as materialCreateTheme, - THEME_ID, -} from '@mui/material/styles'; - -const themeUITheme = { - fonts: { - body: 'system-ui, sans-serif', - heading: '"Avenir Next", sans-serif', - monospace: 'Menlo, monospace', - }, - colors: { - text: '#000', - background: '#fff', - primary: '#33e', - }, -}; - -const materialTheme = materialCreateTheme(); - -function App() { - return ( - - - Theme UI components and Material UI components - - - ); -} -``` - -### Using with Chakra UI - -Render Material UI's theme provider below Chakra UI's provider and assign the material theme to the `THEME_ID` property. - -```js -import { ChakraProvider, extendTheme as chakraExtendTheme } from '@chakra-ui/react'; -import { - ThemeProvider as MaterialThemeProvider, - createTheme as materialCreateTheme, - THEME_ID, -} from '@mui/material/styles'; - -const chakraTheme = chakraExtendTheme(); -const materialTheme = materialCreateTheme(); - -function App() { - return ( - - - Chakra UI components and Material UI components - - - ); -} -``` diff --git a/docs/data/material/guides/theme-scoping/theme-scoping.md b/docs/data/material/guides/theme-scoping/theme-scoping.md new file mode 100644 index 00000000000000..4a73c7b2e0ad6b --- /dev/null +++ b/docs/data/material/guides/theme-scoping/theme-scoping.md @@ -0,0 +1,95 @@ +# Theme scoping + +

Learn how to use multiple styling solutions in a single Material UI app.

+ +:::warning +Having more than one styling library can introduce unnecessary complexity to your project. +You should have a very good reason to do this. +::: + +Starting with [v5.12.0](https://github.com/mui/material-ui/releases/tag/v5.12.0), Material UI can coexist with other component libraries that depend on Emotion or styled-components—this is possible thanks to _theme scoping_. + +To do this, you need to render Material UI's `ThemeProvider` as an inner provider and use the `THEME_ID` to store the theme, as shown below: + +```js +import { ThemeProvider, THEME_ID, createTheme } from '@mui/material/styles'; +import { AnotherThemeProvider } from 'another-ui-library'; + +const materialTheme = createTheme(/* your theme */); + +function App() { + return ( + + + {/* components from another library and Material UI */} + + + ); +} +``` + +The Material UI theme will be separated from the other library, so when you use APIs such as `styled`, the `sx` prop, and `useTheme`, you'll be able to access Material UI's theme like you normally would. + +## Minimum version + +[Theme scoping](https://github.com/mui/material-ui/pull/36664) was introduced in Material UI v5.12.0, so make sure you're running that version or higher. + +### Using with Theme UI + +Render Material UI's theme provider below Theme UI's provider and assign the Material theme to the `THEME_ID` property: + +```js +import { ThemeUIProvider } from 'theme-ui'; +import { createTheme as materialCreateTheme, THEME_ID } from '@mui/material/styles'; + +const themeUITheme = { + fonts: { + body: 'system-ui, sans-serif', + heading: '"Avenir Next", sans-serif', + monospace: 'Menlo, monospace', + }, + colors: { + text: '#000', + background: '#fff', + primary: '#33e', + }, +}; + +const materialTheme = materialCreateTheme(); + +function App() { + return ( + + + Theme UI components and Material UI components + + + ); +} +``` + +### Using with Chakra UI + +Render Material UI's theme provider below Chakra UI's provider and assign the material theme to the `THEME_ID` property: + +```js +import { ChakraProvider, extendTheme as chakraExtendTheme } from '@chakra-ui/react'; +import { + ThemeProvider as MaterialThemeProvider, + createTheme as muiCreateTheme, + THEME_ID, +} from '@mui/material/styles'; + +const chakraTheme = chakraExtendTheme(); +const materialTheme = muiCreateTheme(); + +function App() { + return ( + + + Chakra UI components and Material UI components + + + ); +} +``` diff --git a/docs/data/material/guides/understand-mui-packages/understand-mui-packages-pt.md b/docs/data/material/guides/understand-mui-packages/understand-mui-packages-pt.md index ce78d768041b4a..7075b8b7610fec 100644 --- a/docs/data/material/guides/understand-mui-packages/understand-mui-packages-pt.md +++ b/docs/data/material/guides/understand-mui-packages/understand-mui-packages-pt.md @@ -91,7 +91,8 @@ Material UI relies on styling engines to inject CSS into your app. These engines By default, Material UI uses [Emotion](https://emotion.sh/docs/styled) as its styling engine—it's included in the [installation](/material-ui/getting-started/installation/) process. If you plan to stick with Emotion, then `@mui/styled-engine` is a dependency in your app, and you don't need to install it separately. -If you prefer to use [styled-components](https://styled-components.com/docs/basics#getting-started), then you need to install `@mui/styled-engine-sc` in place of the Emotion packages. See the [Styled engine guide](/material-ui/guides/styled-engine/) for more details. +If you prefer to use [styled-components](https://styled-components.com/docs/basics#getting-started), then you need to install `@mui/styled-engine-sc` in place of the Emotion packages. +See the [styled-components guide](/material-ui/guides/styled-components/) for more details. In either case, you won't interact much with either of these packages beyond installation—they're used internally in `@mui/system`. diff --git a/docs/data/material/guides/understand-mui-packages/understand-mui-packages-zh.md b/docs/data/material/guides/understand-mui-packages/understand-mui-packages-zh.md index ce78d768041b4a..7075b8b7610fec 100644 --- a/docs/data/material/guides/understand-mui-packages/understand-mui-packages-zh.md +++ b/docs/data/material/guides/understand-mui-packages/understand-mui-packages-zh.md @@ -91,7 +91,8 @@ Material UI relies on styling engines to inject CSS into your app. These engines By default, Material UI uses [Emotion](https://emotion.sh/docs/styled) as its styling engine—it's included in the [installation](/material-ui/getting-started/installation/) process. If you plan to stick with Emotion, then `@mui/styled-engine` is a dependency in your app, and you don't need to install it separately. -If you prefer to use [styled-components](https://styled-components.com/docs/basics#getting-started), then you need to install `@mui/styled-engine-sc` in place of the Emotion packages. See the [Styled engine guide](/material-ui/guides/styled-engine/) for more details. +If you prefer to use [styled-components](https://styled-components.com/docs/basics#getting-started), then you need to install `@mui/styled-engine-sc` in place of the Emotion packages. +See the [styled-components guide](/material-ui/guides/styled-components/) for more details. In either case, you won't interact much with either of these packages beyond installation—they're used internally in `@mui/system`. diff --git a/docs/data/material/guides/understand-mui-packages/understand-mui-packages.md b/docs/data/material/guides/understand-mui-packages/understand-mui-packages.md index 5f8b47f923f74a..a3877bcc0845b4 100644 --- a/docs/data/material/guides/understand-mui-packages/understand-mui-packages.md +++ b/docs/data/material/guides/understand-mui-packages/understand-mui-packages.md @@ -96,7 +96,7 @@ By default, Material UI uses [Emotion](https://emotion.sh/docs/styled) as its st If you plan to stick with Emotion, then `@mui/styled-engine` is a dependency in your app, and you don't need to install it separately. If you prefer to use [styled-components](https://styled-components.com/docs/basics#getting-started), then you need to install `@mui/styled-engine-sc` in place of the Emotion packages. -See the [Styled engine guide](/material-ui/guides/styled-engine/) for more details. +See the [styled-components guide](/material-ui/guides/styled-components/) for more details. In either case, you won't interact much with either of these packages beyond installation—they're used internally in `@mui/system`. diff --git a/docs/data/material/pages.ts b/docs/data/material/pages.ts index e046d612b8c7db..38040df6ad46f5 100644 --- a/docs/data/material/pages.ts +++ b/docs/data/material/pages.ts @@ -185,7 +185,8 @@ const pages: MuiPage[] = [ { pathname: '/material-ui/guides/understand-mui-packages', title: 'Understand MUI packages' }, { pathname: '/material-ui/guides/typescript', title: 'TypeScript' }, { pathname: '/material-ui/guides/interoperability', title: 'Style library interoperability' }, - { pathname: '/material-ui/guides/styled-engine' }, + { pathname: '/material-ui/guides/styled-components', title: 'Using styled-components' }, + { pathname: '/material-ui/guides/theme-scoping' }, { pathname: '/material-ui/guides/minimizing-bundle-size' }, { pathname: '/material-ui/guides/composition' }, { pathname: '/material-ui/guides/routing' }, diff --git a/docs/data/system/getting-started/installation/installation-pt.md b/docs/data/system/getting-started/installation/installation-pt.md index 5f817125506f32..e2db8bdacc3a49 100644 --- a/docs/data/system/getting-started/installation/installation-pt.md +++ b/docs/data/system/getting-started/installation/installation-pt.md @@ -28,4 +28,6 @@ npm install @mui/system @mui/styled-engine-sc styled-components yarn add @mui/system @mui/styled-engine-sc styled-components ``` -Take a look at the [Styled Engine guide](/material-ui/guides/styled-engine/) for more information about how to configure `styled-components` as the style engine. +:::warning +Visit the [styled-components guide](/material-ui/guides/styled-components/) for more information on configuration. +::: diff --git a/docs/data/system/getting-started/installation/installation-zh.md b/docs/data/system/getting-started/installation/installation-zh.md index 5f817125506f32..e2db8bdacc3a49 100644 --- a/docs/data/system/getting-started/installation/installation-zh.md +++ b/docs/data/system/getting-started/installation/installation-zh.md @@ -28,4 +28,6 @@ npm install @mui/system @mui/styled-engine-sc styled-components yarn add @mui/system @mui/styled-engine-sc styled-components ``` -Take a look at the [Styled Engine guide](/material-ui/guides/styled-engine/) for more information about how to configure `styled-components` as the style engine. +:::warning +Visit the [styled-components guide](/material-ui/guides/styled-components/) for more information on configuration. +::: diff --git a/docs/data/system/getting-started/installation/installation.md b/docs/data/system/getting-started/installation/installation.md index b747fefac67cf0..e30d095310fb62 100644 --- a/docs/data/system/getting-started/installation/installation.md +++ b/docs/data/system/getting-started/installation/installation.md @@ -43,8 +43,12 @@ pnpm add @mui/system @mui/styled-engine-sc styled-components -:::warning -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/system/getting-started/usage/basics-pt.md b/docs/data/system/getting-started/usage/basics-pt.md index 5067e7943488b0..151e6408da65c5 100644 --- a/docs/data/system/getting-started/usage/basics-pt.md +++ b/docs/data/system/getting-started/usage/basics-pt.md @@ -40,7 +40,9 @@ npm install @mui/system @mui/styled-engine-sc styled-components yarn add @mui/system @mui/styled-engine-sc styled-components ``` -Take a look at the [Styled Engine guide](/material-ui/guides/styled-engine/) for more information about how to configure `styled-components` as the style engine. +:::warning +Visit the [styled-components guide](/material-ui/guides/styled-components/) for more information on configuration. +::: ## Por que usar o sistema? diff --git a/docs/data/system/getting-started/usage/basics-zh.md b/docs/data/system/getting-started/usage/basics-zh.md index 34fd6f538a144b..8c2eff65e53990 100644 --- a/docs/data/system/getting-started/usage/basics-zh.md +++ b/docs/data/system/getting-started/usage/basics-zh.md @@ -40,7 +40,9 @@ npm install @mui/system @mui/styled-engine-sc styled-components yarn add @mui/system @mui/styled-engine-sc styled-components ``` -Take a look at the [Styled Engine guide](/material-ui/guides/styled-engine/) for more information about how to configure `styled-components` as the style engine. +:::warning +Visit the [styled-components guide](/material-ui/guides/styled-components/) for more information on configuration. +::: ## 为什么要使用系统？ diff --git a/docs/data/system/styled/styled-pt.md b/docs/data/system/styled/styled-pt.md index 04904de52109b5..5d131701b31df0 100644 --- a/docs/data/system/styled/styled-pt.md +++ b/docs/data/system/styled/styled-pt.md @@ -4,7 +4,8 @@ ## Introduction -All the MUI components are styled with this `styled()` utility. This utility is built on top of the `styled()` module of [`@mui/styled-engine`](/material-ui/guides/styled-engine/) and provides additional features. +All MUI components are styled with the `styled()` utility. +This utility is built on top of the `styled()` module of `@mui/styled-engine` and provides additional features. ### Importação diff --git a/docs/data/system/styled/styled-zh.md b/docs/data/system/styled/styled-zh.md index 9ca11d464c23bf..8d50510d72be83 100644 --- a/docs/data/system/styled/styled-zh.md +++ b/docs/data/system/styled/styled-zh.md @@ -4,7 +4,8 @@ ## Introduction -All the MUI components are styled with this `styled()` utility. This utility is built on top of the `styled()` module of [`@mui/styled-engine`](/material-ui/guides/styled-engine/) and provides additional features. +All MUI components are styled with the `styled()` utility. +This utility is built on top of the `styled()` module of `@mui/styled-engine` and provides additional features. ### 引用路径 diff --git a/docs/data/system/styled/styled.md b/docs/data/system/styled/styled.md index 3aff351312fc4e..caf36b312d82a0 100644 --- a/docs/data/system/styled/styled.md +++ b/docs/data/system/styled/styled.md @@ -4,8 +4,8 @@ ## Introduction -All the MUI components are styled with this `styled()` utility. -This utility is built on top of the `styled()` module of [`@mui/styled-engine`](/material-ui/guides/styled-engine/) and provides additional features. +All MUI components are styled with the `styled()` utility. +This utility is built on top of the `styled()` module of `@mui/styled-engine`and provides additional features. ### Import path diff --git a/docs/pages/blog/2021-q2-update.md b/docs/pages/blog/2021-q2-update.md index 801e179afbabe9..a05495c650d2db 100644 --- a/docs/pages/blog/2021-q2-update.md +++ b/docs/pages/blog/2021-q2-update.md @@ -38,7 +38,7 @@ Here are the most significant improvements since March 2021. - 👩‍🎤 We have rolled out the new **style engine** to all the components. The community provided invaluable assistance in completing this effort. In v5, we have standardized on the `styled()` API as the styling foundation we build on top of, and introduced the [the `sx` prop](https://mui.com/system/getting-started/the-sx-prop/) for one-off customizations. - The `styled()` API is loved by the community, and implemented by a number of styling libraries: styled-components, emotion, stitches, goober, etc. It allows us to support them all with [adapters](https://mui.com/material-ui/guides/styled-engine/#how-to-switch-to-styled-components). + The `styled()` API is loved by the community, and implemented by a number of styling libraries: styled-components, emotion, stitches, goober, etc. It allows us to support them all with [adapters](https://mui.com/material-ui/guides/styled-components/). - ⚒️ We added a [codemod CLI](https://github.com/mui/material-ui/tree/HEAD/packages/mui-codemod) and 17 transformations (so far) to automatically migrate codebases from v4 to v5. If you're not familiar with what a codemod is, check out [Effective Refactoring with Codemods by Edd Yerburgh](https://www.youtube.com/watch?v=H9qtLutnT_g). diff --git a/docs/pages/blog/mui-core-v5.md b/docs/pages/blog/mui-core-v5.md index 7608354640fdba..27676c0da833e7 100644 --- a/docs/pages/blog/mui-core-v5.md +++ b/docs/pages/blog/mui-core-v5.md @@ -126,7 +126,7 @@ After [exploring](https://github.com/mui/material-ui/issues/22342) many differen - If you are using a different styling library, feel free to contribute a wrapper. For instance, there is [one attempt with goober](https://github.com/mui/material-ui/pull/27776), a library obsessing on bundle size (3kB gzipped). This allows developers to swap between different style engines. For example, styled-components users no longer need to bundle Emotion **and** styled-component, nor do they need to configure the server-side rendering for each. - How does the [swap work](https://mui.com/material-ui/guides/styled-engine/#how-to-switch-to-styled-components)? The same way it does from React to Preact. + How does the [swap work](https://mui.com/material-ui/guides/styled-components/)? The same way it does from React to Preact. 3. For the last couple of months, we have been [sponsoring](https://opencollective.com/emotion) Emotion with a $100/month grant. We are now increasing this amount to $1,000/month. It's in our best interest to help ensure the library keeps pushing the envelope, leading the state of the art in a competitive space. diff --git a/docs/pages/material-ui/guides/styled-components.js b/docs/pages/material-ui/guides/styled-components.js new file mode 100644 index 00000000000000..67960b77dda448 --- /dev/null +++ b/docs/pages/material-ui/guides/styled-components.js @@ -0,0 +1,7 @@ +import * as React from 'react'; +import MarkdownDocs from 'docs/src/modules/components/MarkdownDocs'; +import * as pageProps from 'docs/data/material/guides/styled-components/styled-components.md?@mui/markdown'; + +export default function Page() { + return ; +} diff --git a/docs/pages/material-ui/guides/styled-engine.js b/docs/pages/material-ui/guides/theme-scoping.js similarity index 63% rename from docs/pages/material-ui/guides/styled-engine.js rename to docs/pages/material-ui/guides/theme-scoping.js index 8039ae54850404..91706bcfa7fe66 100644 --- a/docs/pages/material-ui/guides/styled-engine.js +++ b/docs/pages/material-ui/guides/theme-scoping.js @@ -1,6 +1,6 @@ import * as React from 'react'; import MarkdownDocs from 'docs/src/modules/components/MarkdownDocs'; -import * as pageProps from 'docs/data/material/guides/styled-engine/styled-engine.md?@mui/markdown'; +import * as pageProps from 'docs/data/material/guides/theme-scoping/theme-scoping.md?@mui/markdown'; export default function Page() { return ; diff --git a/docs/public/_redirects b/docs/public/_redirects index 1a1ebd34a1b0fc..9b45e8509f1fc6 100644 --- a/docs/public/_redirects +++ b/docs/public/_redirects @@ -488,14 +488,12 @@ https://v4.material-ui.com/* https://v4.mui.com/:splat 301! /base-ui/react-components/ /base-ui/all-components/ 301 /system/getting-started/overview/ /system/getting-started/ 301 /blog/introducing-mui-base/ /blog/introducing-base-ui/ 301 -/joy-ui/guides/next-js-app-router/ /joy-ui/integrations/next-js-app-router/ 301 -/joy-ui/guides/using-joy-ui-and-material-ui-together/ /joy-ui/integrations/material-ui/ 301 -/joy-ui/guides/using-icon-libraries/ /joy-ui/integrations/icon-libraries/ 301 /joy-ui/guides/themeable-component/ /joy-ui/customization/creating-themed-components/ 301 /joy-ui/guides/overriding-component-structure/ /joy-ui/customization/overriding-component-structure/ 301 /material-ui/react-tree-view/ /x/react-tree-view/ 301 /material-ui/api/tree-view/ /x/api/tree-view/tree-view/ 301 /material-ui/api/tree-item/ /x/api/tree-view/tree-item/ 301 +/material-ui/guides/styled-engine/ /material-ui/guides/styled-components/ 301 # Proxies diff --git a/docs/translations/translations-pt.json b/docs/translations/translations-pt.json index 7b866002dd9279..7d64828fc07d26 100644 --- a/docs/translations/translations-pt.json +++ b/docs/translations/translations-pt.json @@ -315,7 +315,7 @@ "/material-ui/guides/understand-mui-packages": "Understand MUI packages", "/material-ui/guides/typescript": "TypeScript", "/material-ui/guides/interoperability": "Style library interoperability", - "/material-ui/guides/styled-engine": "Styled engine", + "/material-ui/guides/styled-components": "Styled components", "/material-ui/guides/minimizing-bundle-size": "Minimizing bundle size", "/material-ui/guides/composition": "Composition", "/material-ui/guides/routing": "Routing", diff --git a/docs/translations/translations-zh.json b/docs/translations/translations-zh.json index cfb05484a2f749..0df8a8cf518bd2 100644 --- a/docs/translations/translations-zh.json +++ b/docs/translations/translations-zh.json @@ -315,7 +315,7 @@ "/material-ui/guides/understand-mui-packages": "Understand MUI packages", "/material-ui/guides/typescript": "TypeScript", "/material-ui/guides/interoperability": "Style library interoperability", - "/material-ui/guides/styled-engine": "Styled engine", + "/material-ui/guides/styled-components": "Styled components", "/material-ui/guides/minimizing-bundle-size": "Minimizing bundle size", "/material-ui/guides/composition": "Composition", "/material-ui/guides/routing": "Routing", diff --git a/docs/translations/translations.json b/docs/translations/translations.json index 6954460bf699c4..9ece0cfcf5727e 100644 --- a/docs/translations/translations.json +++ b/docs/translations/translations.json @@ -417,7 +417,8 @@ "/material-ui/guides/understand-mui-packages": "Understand MUI packages", "/material-ui/guides/typescript": "TypeScript", "/material-ui/guides/interoperability": "Style library interoperability", - "/material-ui/guides/styled-engine": "Styled engine", + "/material-ui/guides/styled-components": "Using styled-components", + "/material-ui/guides/theme-scoping": "Theme scoping", "/material-ui/guides/minimizing-bundle-size": "Minimizing bundle size", "/material-ui/guides/composition": "Composition", "/material-ui/guides/routing": "Routing", diff --git a/packages/mui-styled-engine-sc/README.md b/packages/mui-styled-engine-sc/README.md index e005a2144d2a9b..935bc0cad09cba 100644 --- a/packages/mui-styled-engine-sc/README.md +++ b/packages/mui-styled-engine-sc/README.md @@ -7,4 +7,4 @@ It's designed for developers who would like to use `styled-components` as the ma -[The documentation](https://mui.com/material-ui/guides/styled-engine/) +[The documentation](https://mui.com/material-ui/guides/styled-components/) diff --git a/packages/mui-styled-engine-sc/package.json b/packages/mui-styled-engine-sc/package.json index 9e47b9f0245755..c89948bf7b7a74 100644 --- a/packages/mui-styled-engine-sc/package.json +++ b/packages/mui-styled-engine-sc/package.json @@ -20,7 +20,7 @@ "bugs": { "url": "https://github.com/mui/material-ui/issues" }, - "homepage": "https://mui.com/material-ui/guides/styled-engine/", + "homepage": "https://mui.com/material-ui/guides/styled-components/", "funding": { "type": "opencollective", "url": "https://opencollective.com/mui" diff --git a/packages/mui-styled-engine/README.md b/packages/mui-styled-engine/README.md index a3e61bc2d67844..e9c59aee7f1c7d 100644 --- a/packages/mui-styled-engine/README.md +++ b/packages/mui-styled-engine/README.md @@ -8,4 +8,4 @@ It is used internally in the `@mui/system` package. -[The documentation](https://mui.com/material-ui/guides/styled-engine/) +[The documentation](https://mui.com/material-ui/guides/styled-components/) diff --git a/packages/mui-styled-engine/package.json b/packages/mui-styled-engine/package.json index 2b342983a45cfc..655ea05f8cf4e4 100644 --- a/packages/mui-styled-engine/package.json +++ b/packages/mui-styled-engine/package.json @@ -20,7 +20,7 @@ "bugs": { "url": "https://github.com/mui/material-ui/issues" }, - "homepage": "https://mui.com/material-ui/guides/styled-engine/", + "homepage": "https://mui.com/system/getting-started/", "funding": { "type": "opencollective", "url": "https://opencollective.com/mui"