docusaurus icon indicating copy to clipboard operation
docusaurus copied to clipboard

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

Open shadowusr opened this issue 1 year ago • 0 comments

Have you read the Contributing Guidelines on issues?

Prerequisites

  • [X] I'm using the latest version of Docusaurus.
  • [X] I have tried the npm run clear or yarn clear command.
  • [X] I have tried rm -rf node_modules yarn.lock package-lock.json and re-installing packages.
  • [X] I have tried creating a repro with https://new.docusaurus.io.
  • [X] 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: https://github.com/facebook/docusaurus/blob/8017f6a6776ba1bd7065e630a52fe2c2654e2f1b/packages/docusaurus/src/commands/start.ts#L156

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: https://github.com/facebook/docusaurus/blob/bc638d674bfbde1e254ef306697f47e764b5e107/packages/docusaurus/src/commands/start/webpack.ts#L138

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.

shadowusr avatar May 04 '24 21:05 shadowusr