tailwindcss-taro/README.md

TailwindCSS plugin for Taro4 with Vite/Webpack support - 零配置，开箱即用

# TailwindCSS Taro Plugin

> 超越 weapp-tailwindcss 的 TailwindCSS Taro 插件 - **零配置，开箱即用**

[![npm version](https://img.shields.io/npm/v/tailwindcss-taro.svg)](https://www.npmjs.com/package/tailwindcss-taro)
[![license](https://img.shields.io/npm/l/tailwindcss-taro.svg)](https://github.com/your-username/tailwindcss-taro/blob/main/LICENSE)
[![node version](https://img.shields.io/node/v/tailwindcss-taro.svg)](https://nodejs.org/)

## 🎯 核心优势

### ✨ 零配置体验
- **无需**配置 `"postinstall": "weapp-tw patch"` 脚本
- **自动检测**构建目录和文件
- **构建时自动执行**所有兼容性处理
- **开箱即用**，真正的零配置体验

### 🚀 超越 weapp-tailwindcss
- ✅ **更智能** - 自动检测和优化
- ✅ **更强大** - 更全面的兼容性处理
- ✅ **更高效** - 性能优化和缓存机制
- ✅ **更友好** - 详细的日志和错误处理
- ✅ **更完整** - 集成了 CLI 工具

### 🔧 完整功能
- 🎨 **TailwindCSS v3/v4 支持** - 自动检测版本
- 📱 **微信小程序兼容** - 100% 合法的 WXSS
- ⚡ **Vite/Webpack 支持** - 双构建工具支持
- 🔄 **热重载支持** - 开发体验优化
- 📊 **性能分析** - 详细的构建报告
- 🛠️ **CLI 工具** - 独立的命令行工具

## 🚀 快速开始

### 1. 安装

```bash
npm install tailwindcss-taro
# 或
pnpm add tailwindcss-taro
```

### 2. 配置（零配置）

```typescript
// config/index.ts
import { defineConfig } from '@tarojs/cli'
import { createVitePlugin } from 'tailwindcss-taro'

export default defineConfig({
  compiler: {
    type: 'vite',
    vitePlugins: [
      require('tailwindcss'),
      require('autoprefixer'),
      createVitePlugin() // 零配置，自动启用所有功能
    ]
  }
})
```

### 3. 使用

```tsx
// 直接使用 TailwindCSS 类名
function App() {
  return (
    <View className="flex items-center justify-center min-h-screen bg-gray-100">
      <Text className="text-2xl font-bold text-blue-600">
        Hello TailwindCSS Taro!
      </Text>
    </View>
  )
}
```

### 4. 构建

```bash
npm run build:weapp
# 插件自动执行：
# ✅ 处理 TailwindCSS 样式
# ✅ 自动 patch 构建产物
# ✅ 修复类名和选择器
# ✅ 添加运行时支持
```

## ✨ 零配置特性

### 🔧 自动 Patch 功能

插件内置自动 patch 功能，在构建完成后自动执行：

- ✅ **自动检测构建目录** - 支持 `dist`、`build`、`output`、`miniprogram`、`weapp` 等
- ✅ **自动处理 WXSS 文件** - 确保 CSS 100% 合法
- ✅ **自动修复类名** - 处理类名被去除的问题
- ✅ **自动修复选择器** - 处理选择器兼容性问题
- ✅ **自动添加运行时支持** - 提供调试和动态类名支持

### 📋 与 weapp-tw 的对比

| 功能 | weapp-tw | tailwindcss-taro |
|------|----------|------------------|
| 需要 postinstall 脚本 | ✅ 必需 | ❌ **无需** |
| 自动检测构建目录 | ❌ 手动指定 | ✅ **自动检测** |
| 构建时自动执行 | ❌ 需要额外配置 | ✅ **自动执行** |
| 零配置使用 | ❌ 需要配置 | ✅ **完全零配置** |
| 智能错误处理 | ❌ 基础处理 | ✅ **智能处理** |
| 详细日志输出 | ❌ 基础日志 | ✅ **详细日志** |

## 🔧 高级配置

### 自定义配置（可选）

```typescript
createVitePlugin({
  verbose: true, // 详细日志
  enableAutoPatch: true, // 启用自动 patch（默认开启）
  enableRuntime: true, // 启用运行时支持（默认开启）
  enableClassPatch: true, // 启用类名修复（默认开启）
  enableSelectorPatch: true, // 启用选择器修复（默认开启）
  enablePerformanceOptimization: true, // 性能优化
  enableBundleAnalysis: true, // 包分析
  safelist: ['bg-red-500', 'text-blue-600'], // 安全列表
  cssSelectorReplacement: {
    root: 'page',
    universal: 'view,text'
  }
})
```

### Webpack 支持

```typescript
// config/index.ts
import { defineConfig } from '@tarojs/cli'
import { createWebpackPlugin } from 'tailwindcss-taro'

export default defineConfig({
  compiler: {
    type: 'webpack',
    webpackChain(chain) {
      chain.plugin('tailwindcss-taro')
        .use(createWebpackPlugin({
          verbose: true
        }))
    }
  }
})
```

## 🛠️ CLI 工具

### 安装 CLI

```bash
npm install -g tailwindcss-taro
```

### 使用 CLI

```bash
# 自动 patch 构建产物
tailwindcss-taro patch

# 指定平台和目录
tailwindcss-taro patch -p weapp -d ./dist

# 启用所有功能
tailwindcss-taro patch --runtime --class-patch --selector-patch -v

# 分析构建产物
tailwindcss-taro analyze -d ./dist
```

## 📊 性能优势

### 1. 智能缓存
- 缓存处理结果，避免重复计算
- 增量处理，只处理变化的文件
- 内存优化，自动清理过期缓存

### 2. 并行处理
- 支持并行处理多个文件
- 异步 I/O 操作优化
- 多进程处理大型项目

### 3. 性能监控
- 详细的构建时间统计
- 文件大小变化分析
- 缓存命中率监控

## 🔍 调试和监控

### 详细日志

```bash
# 启用详细日志
createVitePlugin({
  verbose: true
})

# 输出示例：
# 🚀 tailwindcss-taro 插件已加载
# 📱 平台: weapp
# 🎯 TailwindCSS 版本: v3
# 🔧 自动 patch: 已启用
# 📁 发现构建目录: dist
# 📦 处理文件: app.wxss
# 🔧 修复类名: pages/index/index.js
# 🎉 自动 patch 完成！
```

### 性能监控

```typescript
createVitePlugin({
  performanceMonitoring: {
    enabled: true,
    threshold: 1000, // 1秒
    format: 'text'
  }
})
```

### 调试模式

```typescript
createVitePlugin({
  debug: {
    enabled: true,
    level: 'debug',
    outputFile: 'tailwindcss-taro-debug.log'
  }
})
```

## 📚 文档

- [快速开始](./docs/getting-started.md) - 零配置快速上手
- [高级配置](./docs/advanced-configuration.md) - 详细配置说明
- [样式示例](./docs/style-examples.md) - 常用样式示例
- [性能优化](./docs/performance-optimization.md) - 性能优化指南
- [故障排除](./docs/troubleshooting.md) - 常见问题解决
- [最佳实践](./docs/best-practices.md) - 开发最佳实践
- [CLI 使用](./docs/cli-usage.md) - CLI 工具使用指南
- [零配置指南](./docs/zero-config.md) - 零配置特性详解

## 🎯 使用场景

### 1. 新项目
```bash
# 创建新项目
taro init myApp
cd myApp

# 安装插件
npm install tailwindcss-taro

# 零配置使用
# 在 config/index.ts 中添加 createVitePlugin()
```

### 2. 现有项目
```bash
# 安装插件
npm install tailwindcss-taro

# 替换现有配置
# 移除 weapp-tailwindcss 相关配置
# 添加 createVitePlugin()
```

### 3. 迁移项目
```bash
# 从 weapp-tailwindcss 迁移
npm uninstall weapp-tailwindcss
npm install tailwindcss-taro

# 移除 package.json 中的 postinstall 脚本
# 更新配置文件
```

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

### 开发环境

```bash
# 克隆项目
git clone https://github.com/your-username/tailwindcss-taro.git
cd tailwindcss-taro

# 安装依赖
npm install

# 开发模式
npm run dev

# 构建
npm run build

# 测试
npm run test
```

## 📄 许可证

MIT License - 详见 [LICENSE](LICENSE) 文件

## 🙏 致谢

感谢以下项目的启发：
- [weapp-tailwindcss](https://github.com/sonofmagic/weapp-tailwindcss) - 原始灵感来源
- [TailwindCSS](https://tailwindcss.com/) - 优秀的 CSS 框架
- [Taro](https://taro.jd.com/) - 跨端开发框架

---

**🎉 享受零配置的 TailwindCSS Taro 开发体验！**