Updating past 3.1.1 breaks postCSS plugins customisation. Fully debugged, just needs fixing

[shadowusr]

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

First, I'd like to thank you for the lovely tool you've made!

Why this is an issue

In our project, we use two plugins: docusaurus-plugin-sass and Tailwind (implemented by ourselves). Updating to anything past 3.1.1 breaks Tailwind integration in sass files, effectively breaking it everywhere in our project. This issue is unrelated to #10005.

Why this is happening

I've spent a while debugging this issue and was able to narrow down the exact cause.

How plugins work in our case:

1. docusaurus-plugin-sass adds a sass loader to webpack config
2. Tailwind plugin enriches postCSS options with necessary integrations, affecting both css loaders and sass loaders

Let's look at how things were in 3.1.1:

docusaurus/packages/docusaurus/src/commands/start.ts

Line 156 in 8017f6a

plugins.forEach((plugin) => {

As we can see, each plugin is treated iteratively, both configureWebpack and configurePostcss are executed. Everything works fine.

Now let's look at the latest version 3.3.2:

docusaurus/packages/docusaurus/src/commands/start/webpack.ts

Line 138 in bc638d6

config = executePluginsConfigurePostCss({plugins, config});

As we can see, first, configurePostCss is executed for ALL plugins, then configureWebpack is executed for ALL plugins. Obviously this breaks our case: first, Tailwind plugin enriches PostCSS options of css loaders, then a sass loaders are added, but they don't have necessary PostCSS plugins.

Reproducible demo

https://github.com/gemini-testing/testplane-docs

Steps to reproduce

1. Checkout the repo — it works fine on 3.1.1
2. Update docusaurus to 3.2+ via npm
3. Tailwind stops working, because sass loaders are not getting our tailwind plugin.

Expected behavior

Sass+Tailwind work fine together as they did before.

Actual behavior

Sass loaders don't get tailwind plugins in postcss options.

Your environment

• Public source code: https://github.com/gemini-testing/testplane-docs
• Public site URL: not yet available
• Docusaurus version used: 3.1.1 (works) and 3.3.2 (broken)
• Environment name and version (e.g. Chrome 89, Node.js 16.4): Node 20
• Operating system and version (e.g. Ubuntu 20.04.2 LTS): MacOS Ventura

Self-service

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

[slorber]

I understand the issue thanks for reporting.

Indeed, if a plugin add a loader that has a postcss config, that postcss config should also be configured.

The sass plugin uses our getStyleLoader function (using postcss under the hood) so yes this has to be modified by the configurePostCss to work:
https://github.com/rlamana/docusaurus-plugin-sass/blob/master/docusaurus-plugin-sass.js

I'll fix it in #10132

Note your 3.1.1 setup looks dependent on plugin ordering, I suspect using the sass plugin last would break it too.

---

I took a look at your repro, but it's not clear exactly what I'm supposed to see. The repo seems quite empty, and I don't see any meaningful change when upgrading. What does "works" and "broken" mean? What am I supposed to see, on what page?

How can I be sure my attempt to fix the problem works if I can't see it broken in the first place?

"Tailwind stops working": how can I see that it stops working?