CSS is different between local development build and built for prod

[SimenB]

🐛 Bug Report

When running docusaurus start the CSS is different than running docusaurus build followed by docusaurus serve.

Have you read the Contributing Guidelines on issues?

Yup

To Reproduce

1. Check out chore: remove sass from website jestjs/jest#11229
2. Run yarn from root
3. cd into website/
4. Compare yarn docusaurus start and yarn docusaurus build && yarn docusaurus serve

Expected behavior

The website should look identical

Actual Behavior

The CSS looks different

Dev:

Prod:

I assume this is some bug in the ordering of css files when built vs running in dev mode.

Your Environment

• Public source code: https://github.com/facebook/jest/tree/master/website
• Public site url: https://jestjs.io/
• Docusaurus version used: 2.0.0-alpha.c32d8bd11
• Environment name and version: Chrome 89.0.4389.90, Node v14.16.0
• Operating system and version (desktop or mobile): macOS Big Sur 11.2.3

Reproducible Demo

Checkout the branch from jestjs/jest#11229 (https://github.com/SimenB/jest/tree/remove-sass), instructions are above in this issue (it's just "run the website"). From that PR you can also see that the netlify preview shows the same CSS as the local docusarus build version

[slorber]

Hi,

As explained in DM, this is not an issue with Docusaurus itself but rather it's an issue with the site that has conflicting CSS rules that are too dependent on CSS insertion order.

CSS is code-splitted by Webpack and lazy-loaded and inserted in pages on demand.

For example when you go to https://jestjs.io/help, the following CSS files load:

Now when you navigate to the homepage you get new CSS files loaded on-demand:

This order may be different according to the navigation patterns of the user, webpack code-splitting heuristics, and you should make sure that one CSS chunk does not mess-up with another CSS chunk and that the order somehow does not matter.

That's why we use CSS-in-JS or methodologies like BEM: to avoid polluting the global CSS namespace and preventing this kind of problem from happening.

You didn't have this on Docusaurus 1 because on each navigation you "reset" the page CSS as it's not a real SPA navigation. The problem appears in Docusaurus 2 because it's an SPA navigation, but you'll have the same problem with CRA, Gatsby, Next, VuePress...

Let's continue this in DM and find a solution for the Jest website.

May also be related to #3678

[SimenB]

I still think it's a bug that dev and prod do not agree on a fresh navigation (or refresh) on the same page. It's not about navigation in that case - some prod optimization breaks css insertion order. The fact other frameworks may or may not have the same bug doesn't make it any less of a bug.

But of course if we fix this for Jest it doesn't really impact me anymore, so I'm happy with that resolution 😀

[slorber]

It also affects other projects of the React ecosystem.

facebook/create-react-app#7190
gatsbyjs/gatsby#9733
gatsbyjs/gatsby#9733

If you have any solution to fix this problem let me know, but I don't have any apart advising you to scope your styles and make them independent or insertion order and specificity issues.

All this is why we invented CSS in JS:
https://speakerdeck.com/vjeux/react-css-in-js

Here the problem is "non-deterministic resolution". It's not something new and it affects many sites for many years already.