From a2c80d3315057fa78a79099624af5fa9059043d1 Mon Sep 17 00:00:00 2001 From: Alexander Trauzzi Date: Wed, 8 Aug 2018 08:38:02 -0500 Subject: [PATCH 1/3] Expand on the JSS and class name generator docs First pass, includes: - Reworked a bit of the original problem descriptions to contain more anecdotes and keywords (let me know if I messed anything up there) - Extra symptoms, again, more keyword stuffing ;) - Information for webpack users --- docs/src/pages/getting-started/faq/faq.md | 51 ++++++++++++++++++----- 1 file changed, 41 insertions(+), 10 deletions(-) diff --git a/docs/src/pages/getting-started/faq/faq.md b/docs/src/pages/getting-started/faq/faq.md index 5cb03e0c512586..7690f948c28e93 100644 --- a/docs/src/pages/getting-started/faq/faq.md +++ b/docs/src/pages/getting-started/faq/faq.md @@ -5,18 +5,49 @@ If you still can't find what you're looking for, you can ask the community in [gitter](https://gitter.im/mui-org/material-ui). For how-to questions and other non-issues, please use [StackOverflow](https://stackoverflow.com/questions/tagged/material-ui) instead of Github issues. There is a StackOverflow tag called `material-ui` that you can use to tag your questions. -## How to fix a class names conflict in production? - -This is probably the n°1 issue people are facing starting with Material-UI. -The class names value relies on the concept of [class name generator](/customization/css-in-js#creategenerateclassname-options-class-name-generator). -The whole page needs to be rendered with **one generator**. -You might end up using two class name generators in a variety of contexts: -- You **bundle** two versions of Material-UI. You might have a dependency not correctly setting Material-UI as a peer dependency. -Each version of Material-UI uses its own default class name generator. +## Why aren't my components rendering correctly in production builds? + +This is likely an n°1 issue that happens due to class name conflicts once your code is in a production bundle. For Material-UI to work, the `classNames` values of all components on a page must be generated by a single instance of the [class name generator](/customization/css-in-js#creategenerateclassname-options-class-name-generator). + +To correct this issue, all components on the page need to be initialized such that there is only ever **one class name generator** between them. + +> Another symptom of this issue is when your first mounted component is the only one that seems to render with correct styles and any other after it renders incorrectly. + +You could end up accidentally using two class name generators in a variety of scenarios: +- You accidentally **bundle** two versions of Material-UI. You might have a dependency not correctly setting Material-UI as a peer dependency. - You are using `JssProvider` for a **subset** of your React Tree. -Material-UI has a default class name generator, `JssProvider` is providing a second one. +- You are using multiple entrypoints with one or more common scripts. +- You are using a bundler and it is splitting code in a way results in multiple class name generator instances to be created. + +Overall, it's simple to recover from this problem by wrapping each Material-UI application with [`JssProvider`](/customization/css-in-js#jssprovider) components at the top of their component trees **and using a single class name generator shared between them**. + +In a common module: + +```js +import JssProvider from "react-jss/lib/JssProvider"; +import { createGenerateClassName, jssPreset } from "@material-ui/core"; + +export const generateClassName = createGenerateClassName(); +export const jss = create(jssPreset()); +``` + +Then, in every application root: + +```js +import { generateClassName, jss } from './my-common-module'; + + + // ... your code +``` + +The last part of any solution will vary based on what bundler you are using, but the overall goal is to ensure the common module that contains the first snippet above only gets loaded and run once. + +> If you are using webpack with the [SplitChunksPlugin](https://webpack.js.org/plugins/split-chunks-plugin/), try configuring the [`runtimeChunk` setting under `optimizations`](https://webpack.js.org/configuration/optimization/#optimization-runtimechunk). -It's simple to recover from this problem. Use the [`JssProvider`](/customization/css-in-js#jssprovider) component at the top of your React tree to inject a single class name generator. ## Why do the fixed positioned elements move when a modal is opened? From ebeaac0b294dd357972ef4ba577a30283acec49a Mon Sep 17 00:00:00 2001 From: Alexander Trauzzi Date: Wed, 8 Aug 2018 08:41:26 -0500 Subject: [PATCH 2/3] Consistent quotes. --- docs/src/pages/getting-started/faq/faq.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/src/pages/getting-started/faq/faq.md b/docs/src/pages/getting-started/faq/faq.md index 7690f948c28e93..d96fc463f37e0e 100644 --- a/docs/src/pages/getting-started/faq/faq.md +++ b/docs/src/pages/getting-started/faq/faq.md @@ -24,8 +24,8 @@ Overall, it's simple to recover from this problem by wrapping each Material-UI a In a common module: ```js -import JssProvider from "react-jss/lib/JssProvider"; -import { createGenerateClassName, jssPreset } from "@material-ui/core"; +import JssProvider from 'react-jss/lib/JssProvider'; +import { createGenerateClassName, jssPreset } from '@material-ui/core'; export const generateClassName = createGenerateClassName(); export const jss = create(jssPreset()); From 8563b9d316d5254fbf02aa9c43ad06dc827f04df Mon Sep 17 00:00:00 2001 From: Olivier Tassinari Date: Wed, 8 Aug 2018 20:00:32 +0200 Subject: [PATCH 3/3] small tweaks --- docs/src/pages/getting-started/faq/faq.md | 35 +++-------------------- 1 file changed, 4 insertions(+), 31 deletions(-) diff --git a/docs/src/pages/getting-started/faq/faq.md b/docs/src/pages/getting-started/faq/faq.md index d96fc463f37e0e..130d11e519240b 100644 --- a/docs/src/pages/getting-started/faq/faq.md +++ b/docs/src/pages/getting-started/faq/faq.md @@ -7,47 +7,20 @@ For how-to questions and other non-issues, please use [StackOverflow](https://st ## Why aren't my components rendering correctly in production builds? -This is likely an n°1 issue that happens due to class name conflicts once your code is in a production bundle. For Material-UI to work, the `classNames` values of all components on a page must be generated by a single instance of the [class name generator](/customization/css-in-js#creategenerateclassname-options-class-name-generator). +This is likely an n°1 issue that happens due to class name conflicts once your code is in a production bundle. +For Material-UI to work, the `classNames` values of all components on a page must be generated by a single instance of the [class name generator](/customization/css-in-js#creategenerateclassname-options-class-name-generator). To correct this issue, all components on the page need to be initialized such that there is only ever **one class name generator** between them. -> Another symptom of this issue is when your first mounted component is the only one that seems to render with correct styles and any other after it renders incorrectly. - You could end up accidentally using two class name generators in a variety of scenarios: - You accidentally **bundle** two versions of Material-UI. You might have a dependency not correctly setting Material-UI as a peer dependency. - You are using `JssProvider` for a **subset** of your React Tree. -- You are using multiple entrypoints with one or more common scripts. - You are using a bundler and it is splitting code in a way results in multiple class name generator instances to be created. +> If you are using webpack with the [SplitChunksPlugin](https://webpack.js.org/plugins/split-chunks-plugin/), try configuring the [`runtimeChunk` setting under `optimizations`](https://webpack.js.org/configuration/optimization/#optimization-runtimechunk). Overall, it's simple to recover from this problem by wrapping each Material-UI application with [`JssProvider`](/customization/css-in-js#jssprovider) components at the top of their component trees **and using a single class name generator shared between them**. -In a common module: - -```js -import JssProvider from 'react-jss/lib/JssProvider'; -import { createGenerateClassName, jssPreset } from '@material-ui/core'; - -export const generateClassName = createGenerateClassName(); -export const jss = create(jssPreset()); -``` - -Then, in every application root: - -```js -import { generateClassName, jss } from './my-common-module'; - - - // ... your code -``` - -The last part of any solution will vary based on what bundler you are using, but the overall goal is to ensure the common module that contains the first snippet above only gets loaded and run once. - -> If you are using webpack with the [SplitChunksPlugin](https://webpack.js.org/plugins/split-chunks-plugin/), try configuring the [`runtimeChunk` setting under `optimizations`](https://webpack.js.org/configuration/optimization/#optimization-runtimechunk). - +[A resolution example](/customization/css-in-js#jssprovider). The last part of any solution will vary based on what bundler you are using, but the overall goal is to ensure the common module that contains the first snippet above only gets loaded and run once. ## Why do the fixed positioned elements move when a modal is opened?