Skip to content

Commit

Permalink
[docs] Expand on the JSS and class name generator docs (#12447)
Browse files Browse the repository at this point in the history
[docs] Expand on the JSS and class name generator docs
  • Loading branch information
atrauzzi authored and oliviertassinari committed Aug 8, 2018
1 parent 8622d95 commit c937ab0
Showing 1 changed file with 14 additions and 10 deletions.
24 changes: 14 additions & 10 deletions docs/src/pages/getting-started/faq/faq.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,18 +5,22 @@
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.

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 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**.

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.
[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?

Expand Down

0 comments on commit c937ab0

Please sign in to comment.