Media queries are moved outside their cascade layers in the production CSS build

[lobovskiy]

Have you read the Contributing Guidelines on issues?

• I have read the Contributing Guidelines on issues.

Prerequisites

• I'm using the latest version of Docusaurus.
• I have tried the npm run clear or yarn clear command.
• I have tried rm -rf node_modules yarn.lock package-lock.json and re-installing packages.
• I have tried creating a repro with https://new.docusaurus.io.
• I have read the console error message carefully (if applicable).

Description

I’m using cascade layers, which are enabled by default in v3.9.2 (future: { v4: true } in the config).
I noticed that in the production build, CSS media queries are extracted out of their cascade layers.
In dev mode, the styles look like this:

@layer docusaurus.theme-classic {
  /* some styles here */

  @media (min-width: 997px) {
    /* media query styles here */
  }
}

But in the built CSS bundle they become:

@layer docusaurus.theme-classic {
  /* some styles here */
}

@media (min-width: 997px) {
  /* media query styles here */
}

The media queries are no longer nested inside the cascade layer.
This also happens to imported third-party stylesheets, which breaks the intended cascade order.

Reproducible demo

No response

Steps to reproduce

1. Create a new Docusaurus project: npx create-docusaurus@latest my-website classic
2. Navigate into the project directory: cd my-website
3. Start the development server: npm start
4. Open the site in a browser and inspect the applied CSS in DevTools (Sources panel).
   Observe: media queries are correctly nested inside their corresponding cascade layers.
5. Build the production bundle: npm run build
6. Serve the built site: npm run serve
7. Open the site again in a browser and inspect the built CSS in DevTools (Sources panel).
   Observe: all media queries have been extracted out of the cascade layers and appear at the root level of the stylesheet.

Expected behavior

Media queries should remain nested inside their respective cascade layers in the production CSS bundle, exactly as they appear during development. The cascade layer structure should be preserved for both local and third-party stylesheets.

Actual behavior

During the production build, all media queries are extracted out of their cascade layers and moved to the root level of the compiled CSS. As a result, the cascade layer ordering is broken, affecting both project styles and imported third-party stylesheets.

Your environment

• Public source code: N/A (bug reproducible in a fresh project)
• Public site URL: N/A
• Docusaurus version used: 3.9.2 (with future: { v4: true } enabled by default)
• Environment name and version (e.g. Chrome 89, Node.js 16.4): all browsers, Node.js 22.14.0
• Operating system and version (e.g. Ubuntu 20.04.2 LTS): Windows 11, macOS 26.2

Self-service

• I'd be willing to fix this bug myself.

[slorber]

Can you please provide a runnable minimal repro repository that clearly shows the problem?

[lobovskiy]

Thanks for the response.

The issue can be reproduced directly in the official Docusaurus StackBlitz sandbox: https://docusaurus.new/stackblitz-ts
(no additional setup or custom code required).

Steps

1. Open the sandbox link above.
   It automatically runs yarn install && npm start.

2. Once the dev server is running, go to the site preview and inspect the generated CSS in DevTools -> Sources.
   Media queries are correctly nested inside their cascade layers.
   Dev mode CSS (expected):
   

3. Stop the dev server in the StackBlitz terminal Ctrl + C, build the app npm run build, then serve the production build npm run serve

4. Go to the site preview again (reload it manually if necessary) and inspect the compiled CSS in DevTools -> Sources.
   Media queries are now extracted out of their cascade layers and placed at the root level of the stylesheet.
   Production build CSS (actual):
   

   Here it is formatted:
   

[slorber]

I see thanks

It doesn't seem to reproduce anymore when turning this Docusaurus Faster flag on:

  future: {
    experimental_faster: {
      lightningCssMinimizer: false,
    },
  },

Since the new CSS minimizer is likely to become the default in Docusaurus v4, I'd recommend that you turn it on today: it will be faster and more future-proof than our historical CSS minimizer stack, which is quite outdated.

I'm not sure what is causing our old CSS minimizer to produce this bug, but it may not be worth it to investigate, considering you'd rather use the new CSS minimizer. The bug is likely in a third-party dependency that was written at a time when CSS nesting and cascade layers didn't even exist. Please let me know if it's difficult to upgrade to the new CSS minimizer.

I'll close the issue once we swap the default CSS minimizer.

[lobovskiy]

Thanks for the suggestion!

I tried enabling the new CSS minimizer via experimental_faster.lightningCssMinimizer, and after installing the required dependency (@docusaurus/faster), the production build works correctly - media queries now remain inside their cascade layers.

For reference, I had to add:

  future: {
    v4: true, // Improve compatibility with the upcoming Docusaurus v4
    experimental_faster: {
      lightningCssMinimizer: true,
    },
  },

and install the required dependency npm install @docusaurus/faster.

After that, the issue is no longer reproducible on my side.

Appreciate the explanation and the guidance. Feel free to close the issue.

[slorber]

Thanks

I'll keep the issue open for now, and close this later once the new minimizer becomes the default.