#Tailwind 插件变更

Modern.js 3.0 推荐通过 Rsbuild 原生方式接入 Tailwind CSS，不再依赖 @modern-js/plugin-tailwindcss 插件，从而充分利用 Rsbuild 提供的更灵活的配置能力和更优的构建体验。

#迁移步骤

本小节中的迁移操作都是仅当项目中实际使用了 @modern-js/plugin-tailwindcss 插件时才需要执行。

#1. 移除旧插件

移除 @modern-js/plugin-tailwindcss 依赖和配置。

2.0 版本：

import { defineConfig } from '@modern-js/app-tools';
import tailwindcssPlugin from '@modern-js/plugin-tailwindcss';

export default defineConfig({
  plugins: [tailwindcssPlugin()],
});

3.0 版本：

import { defineConfig } from '@modern-js/app-tools';

export default defineConfig({
  plugins: [],
});

同时移除 package.json 中的 @modern-js/plugin-tailwindcss 依赖。

#2. 配置 PostCSS

创建或更新 postcss.config.cjs 文件。

module.exports = {
  plugins: {
    tailwindcss: {},
  },
};

#3. Tailwind CSS 配置迁移

单一配置情况：

• 若仅在 tailwind.config.{ts,js} 中配置，则无需额外处理
• 若仅在 modern.config.ts 中配置，需将 Tailwind 相关配置移植到 tailwind.config.{ts,js} 中

双重配置情况：

若在 tailwind.config.{ts,js} 与 modern.config.ts 中都有配置，需要合并两者的配置内容，并将合并后的配置移植到 tailwind.config.{ts,js}。

特殊目录处理：

若项目中存在 storybook 或 config/html 目录，需在 tailwind.config.{ts,js} 的 content 中补充：

export default {
  content: [
    './src/**/*.{js,jsx,ts,tsx}',
    './storybook/**/*', // 如果存在 storybook 目录
    './config/html/**/*.{html,ejs,hbs}', // 如果存在 config/html 目录
  ],
};

#4. CSS 样式引入

将 CSS 导入方式变更为 @tailwind 指令方式。

2.0 版本：

@import 'tailwindcss/base.css';
@import 'tailwindcss/components.css';
@import 'tailwindcss/utilities.css';

3.0 版本：

@tailwind base;
@tailwind components;
@tailwind utilities;

#5. Twin.macro 集成

若项目中有使用 twin.macro，需要手动配置。未使用则可忽略此步骤。

处理步骤：

1. 手动安装依赖：pnpm add twin.macro styled-components babel-plugin-macros -D
2. 在 modern.config.ts 中配置 babel-plugin-macros 插件：

export default defineConfig({
  plugins: [appTools()],
  tools: {
    babel: {
      plugins: [
        [
          'babel-plugin-macros',
          {
            twin: {
              preset: 'styled-components',
              config: './tailwind.config.ts',
            },
          },
        ],
      ],
    },
  },
});

#Tailwind CSS V2 版本迁移

如果你的项目仍使用 Tailwind CSS v2，我们推荐你升级到 v3 以支持 JIT 等能力。关于 Tailwind CSS v2 与 v3 版本之间的差异，请参考：

• Tailwind CSS v3.0
• Upgrade Guide

Tailwind CSS v2 迁移同样参考上述步骤，但需要注意的是，原插件自动适配 Tailwind v2（purge 配置）与 v3（content 配置）的差异。移除插件后，如果使用 v2，需在 tailwind.config.{ts,js} 中使用 purge 配置项来指定需要保留的 CSS 类名。