Docusaurus: Move to Tailwind / Tailwind Preset

[jaredpalmer]

💥 Proposal

This may be belong in the Infima repo, but I strongly suggest Docusaurus consider Tailwind. Tailwind already solves for theming out of the box. It also gives developers much more freedom. You can still re-implement Infima's core classes with tailwind, so this actually wouldn't _need_ to be a breaking change.

The benefits:

• Smaller CSS footprint
• Better theming
• Less custom CSS needed on other pages

Next Steps

• Start on a new Tailwind preset
• Get it to feature-parity with classic theme

Have you read the Contributing Guidelines on issues?

Yes

[slorber]

Hi,

I'm not very familar with Tailwind yet.

Currently Infima is a css lib with a few postcss. But it also includes some lightweight vanilla JS components

If I understand correctly, you mean we could implement current Infima CSS classes as a Tailwind preset, instead of the existing css/postcss ?

So we would publish that preset and enable users to extend / customize it more easily?

---

I see the value of Tailwind, and a similar goal of styling co-located to the markup.

Its scope is larger than current Infima:

• People having complex D2 sites will probably need additional one-of CSS styles that's not provided by Infima (afaik it also happens to Tailwind users). Atomic/utility CSS will grow slower than hand-made CSS.
• There are also simple D2 sites that do not require additional styles. Can we use Tailwind without adding unnecessary CSS to these sites?

[jaredpalmer]

Yes you can and should always purge unused tailwind css. Only the classes actually used in the codebase are kept.

[kvnxiao]

Hoping this is helpful information, as I got TailwindCSS v2 to properly work with the PostCSS config that Docusaurus v2 already uses.

I'm using a custom configureWebpack plugin in a file plugins/my-loaders/index.js like so:

module.exports = function (context, options) {
  return {
    name: 'postcss-tailwindcss-loader',
    configureWebpack(config, isServer, utils) {
      return {
        module: {
          rules: [
            {
              test: /\.css$/,
              use: [
                {
                  loader: require.resolve('postcss-loader'),
                  options: {
                    ident: 'postcss',
                    plugins: () => [
                      require('postcss-import'),
                      require('tailwindcss'),
                      require('postcss-preset-env')({
                        autoprefixer: {
                          flexbox: 'no-2009',
                        },
                        stage: 4,
                      }),
                    ],
                  },
                },
              ],
            },
          ],
        },
      }
    },
  }
}

with package.json referencing a local module dependency "my-loaders": "file:plugins/my-loaders", and docusaurus.config.js plugins entry set up as plugins: ['my-loaders'],

And a tailwind.config.js like so:

module.exports = {
  purge: ['./src/**/*.html', './src/**/*.js', './src/**/*.tsx'],
  darkMode: false, // or 'media' or 'class'
  theme: {
    extend: {},
  },
  variants: {
    extend: {},
  },
  plugins: [],
}

A reference commit summarizing the above info: https://github.com/Discord4J/documentation/commit/20192796254feb1e4229ca1191191031f4d3e065

Note that the PostCSS version in which Docusaurus v2 currently uses is 7.0.XX, while the latest version of PostCSS is 8.0.X and TailwindCSS v2 by default uses PostCSS V8. I had to use a v7 compatibility install of TailwindCSS v2 for this to all work: "tailwindcss": "npm:@tailwindcss/postcss7-compat" in package.json dependencies.

I'm thinking that maybe tailwindcss can be added directly to the https://github.com/facebook/docusaurus/blob/master/packages/docusaurus/src/webpack/utils.ts#L64-L71 plugin block for getStyleLoaders with PurgeCSS configured for first class support. Since tailwindcss has PurgeCSS enabled, users who don't use tailwindcss will never see it or even know because all the tailwindcss related css rules will be removed. And there should be no performance penalties in terms of time spent compiling for users who don't import tailwindcss into their .css files or index.js/index.tsx.

[slorber]

Thanks for these infos.

We'll look at this more in depth soon, as we'll work on our theme gallery (https://github.com/facebook/docusaurus/issues/3522) and Tailwind support is part of it

[clairefro]

@kvnxiao I tried your config for tailwind and can't seem to get past this error (looks like it's still looking for postcss 8):

Error: Cannot find module 'postcss-import'

Do you have a working repo I could take a look at?

[kvnxiao]

@clairefro https://github.com/Discord4J/documentation

You will need to install postcss-import