[RFC] Configure Tailwind CSS more intuitively

[chenjiahan]

Summary

There are currently some issues with the use of Tailwind CSS in Modern.js.

This RFC will discuss these issues and provide a usage approach that is more in line with community conventions.

Background

Currently, Modern.js provides two options to configure Tailwind CSS:

• source.designSystem is used to configure the theme option of Tailwind CSS.
• tools.tailwindcss is used to configure all Tailwind CSS options except the theme option.

Tailwind CSS officially uses the tailwind.config.{js,ts,cjs,mjs} file, which is not supported by the current version of Modern.js.

There are several problems with the current implementation:

• Configuring Tailwind CSS becomes complicated, users need to split the config into two parts and pass them to different options:

// modern.config.ts
import tailwindConfig from './tailwind.config';

const { theme, ...rest } = tailwindConfig;

export default {
  source: {
    designSystem: theme,
  },
  tools: {
    tailwindcss: rest,
  }
}  

• If users pass theme option to tools.tailwindcss, the @modern-js/plugin-tailwindcss will throw an error, because the users are expected to use source.designSystem:

// modern.config.ts
import tailwindConfig from './tailwind.config';

export default {
  tools: {
    tailwindcss: tailwindConfig,
  }
}  

# terminal
error   should not exist 'theme' on tools.tailwindcss, please remove it

• The Tailwind CSS autocomplete does not work by default, see #3919 for more details.

Motivation

In this RFC, we want to solve the current problems and make it more intuitive to configure Tailwind CSS in Modern.js.

The most natural way is to configure tailwind.config.js directly, and Modern.js will read the config automatically, so that users do not need to configure the tools.tailwindcss or source.designSystem. And the Tailwind CSS autocomplete will work out-of-box.

Detailed Design

Read Tailwind CSS config file

The @modern-js/plugin-tailwindcss will use tailwindcss/loadConfig to read the following config files if they exist:

• tailwind.config.js
• tailwind.config.ts
• tailwind.config.cjs
• tailwind.config.mjs

The config object will be used to configure the PostCSS plugin of Tailwind CSS.

It is no longer recommended to use tools.tailwindcss or source.designSystem. But if tools.tailwindcss and tailwind.config.* are used at the same time, they will be merged via Object.assign and the priority will be as follows:

• source.designSystem will override tools.tailwindcss.theme.
• tools.tailwindcss will override tailwind.config.*.

Allow use of tools.tailwindcss.theme

It is now allowed to use tools.tailwindcss.theme, which means that tools.tailwindcss is exactly the same as the native Tailwind CSS config.

// modern.config.ts
import tailwindConfig from './tailwind.config';

const { theme, ...rest } = tailwindConfig;

export default {
  tools: {
    tailwindcss: {
      theme: {
        // some configs
      }
    }
  }
}  

Auto create tailwind.config.ts

The tailwind.config.ts file will be created automatically after running the modern new command, and it will contain some default configs:

export default  {
  content: [
    './src/**/*.{js,jsx,ts,tsx}',
    './config/html/**/*.{html,ejs}',
  ],
};

Invalidate the webpack cache

When the tailwind.config.* file is updated, it should invalidate the webpack cache, so we need to add tailwind.config.* to webpack.cache.buildDependencies to ensure this.

Deprecating source.designSystem

The source.designSystem config will be deprecated, it can still work in Modern.js 2.x, but we will recommend the new methods:

• Use the theme option of tailwind.config.* for Tailwind CSS users.
• Use ThemeProvider for Styled Component users. Currently, only very few users are using designSystem with Styled Components.

The tools.tailwindcss config will not be deprecated, as we want to preserve the ability to modify the Tailwind CSS config in Modern.js plugins.

[chenjiahan]

Implementation PR:

• feat(plugin-tailwind): automatically read tailwind config file #4517
• refactor(tailwindcss): allow to use tools.tailwindcss.theme #4506
• feat(builder): add tailwind config to webpack build dependencies #4519
• docs(tailwindcss): mark designSystem as deprecated #4521
• feat(tailwindcss): generate tailwind config file when run new command #4524

[Webming19]

[chenjiahan]

可以直接通过 source.preEntry 来引入一个全局样式文件：https://modernjs.dev/configure/app/source/pre-entry.html#%E6%B7%BB%E5%8A%A0%E5%85%A8%E5%B1%80%E6%A0%B7%E5%BC%8F

[Webming19]

感谢