/byted-util-vite-react-tailwind

name: byted-util-vite-react-tailwind
description: 使用 Vite + React + TailwindCSS v4 + lucide-react 进行前端项目搭建和开发的技能。当用户需要创建前端项目、搭建 React 开发环境、使用 TailwindCSS 进行样式开发时使用此技能。
version: 2.0.0
license: Apache-2.0
metadata:
  display_name: Vite+React+TailwindCSS前端开发工具
  permissions:
    - network
    - file_read
    - file_write

Vite + React + TailwindCSS v4 开发技能

> 基于 Vite + React + TailwindCSS v4 + lucide-react 技术栈的前端项目搭建和开发指南。

技术栈

| 技术 | 版本 | 用途 | |------|------|------| | Vite | ^5.x 或 ^6.x | 构建工具、开发服务器 | | React | ^18.x 或 ^19.x | UI 框架 | | TailwindCSS | ^4.x | 原子化 CSS 框架（Vite 插件模式） | | @tailwindcss/vite | ^4.x | TailwindCSS Vite 插件 | | lucide-react | latest | 图标库 | | TypeScript | ^5.x 或 ^6.x | 类型安全 |

项目初始化

Step 1: 创建 Vite + React 项目

# 创建项目（使用 React + TypeScript 模板）
npm create vite@latest . -- --template react-ts

# 安装依赖
npm install

Step 2: 安装 TailwindCSS v4

# 安装 TailwindCSS v4 及 Vite 插件
npm install tailwindcss @tailwindcss/vite

> **注意：** v4 不再需要 `postcss`、`autoprefixer`，也不需要运行 `npx tailwindcss init`。

Step 3: 配置 Vite 插件

在 `vite.config.ts` 中添加 `@tailwindcss/vite` 插件：

**vite.config.ts:**

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import tailwindcss from '@tailwindcss/vite'

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

Step 4: 清空默认样式并配置 CSS（⚠️ 强制关键步骤）

**必须将 `src/index.css` 和 `src/App.css` 的全部内容清空**，然后在 `src/index.css` 中只写 TailwindCSS 引入（和可选的 `@theme`）：

**src/index.css:**

@import "tailwindcss";

**src/App.css:**

/* 清空此文件所有内容，或直接删除此文件 */

> **🚨 严格禁止：** 不要在 `index.css` 中写任何 `*`、`body`、`html` 等全局选择器样式！包括但不限于： > ```css > /* ❌ 以下全部禁止 */ > * { margin: 0; padding: 0; box-sizing: border-box; } > body { font-family: ...; -webkit-font-smoothing: antialiased; } > html { scroll-behavior: smooth; } > ``` > 这些全局 reset 样式会覆盖 TailwindCSS 的 preflight（内置 reset），导致间距、字体、布局等样式全部异常。TailwindCSS v4 已经内置了完善的 CSS Reset，**不需要也不允许额外添加全局 reset**。 > > **正确的 `index.css` 只包含**：`@import "tailwindcss"` + 可选的 `@theme` 自定义主题变量。除此之外不写任何 CSS 规则。

> **v4 使用 `@import "tailwindcss"` 替代 v3 的 `@tailwind base; @tailwind components; @tailwind utilities;`。不再需要 `tailwind.config.js` 配置文件。**

Step 5: 安装 lucide-react 图标库

npm install lucide-react

Step 6: 安装工具库（如需 cn 工具函数）

# 用于合并 className 的工具库
npm install clsx tailwind-merge

工具函数 `src/utils/cn.ts`：

import { clsx, type ClassValue } from 'clsx';
import { twMerge } from 'tailwind-merge';

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs));
}

Step 7: 启动开发服务器

npm run dev

TypeScript 配置（重要）

tsconfig.app.json 关键配置

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "jsx": "react-jsx",
    "strict": true,
    "verbatimModuleSyntax": false,
    "isolatedModules": true,
    "skipLibCheck": true
  },
  "include": ["src"]
}

⚠️ 必须注意的 TypeScript 陷阱

1. **`verbatimModuleSyntax` 必须设为 `false`**

• 设为 `true` 时，`import { MyType } from './types'` 会被保留为运行时导入，但类型在运行时不存在，导致报错
• 如果设为 `true`，则所有类型导入必须使用 `import type { MyType }` 语法，但这容易遗漏

2. **避免组件名与导入类型同名**

   // ❌ 错误：TaskStats 类型和函数同名，导致 SyntaxError
   import { TaskStats } from '../../types';
   export default function TaskStats(props: { stats: TaskStats }) { ... }

   // ✅ 正确：重命名类型导入
   import type { TaskStats as TaskStatsData } from '../../types';
   export default function TaskStats(props: { stats: TaskStatsData }) { ... }

3. **导入路径必须准确**

• 工具函数 `cn` 定义在 `utils/cn.ts`，不要从 `utils/helpers.ts` 导入
• 每个工具函数应从其正确的文件路径导入

开发规范

项目结构

src/
├── components/        # 可复用组件
│   ├── ui/           # 基础 UI 组件（Button, Card, Input 等）
│   ├── layout/       # 布局组件（Header, Footer, Sidebar 等）
│   └── features/     # 业务功能组件
├── pages/            # 页面组件
├── hooks/            # 自定义 Hooks
├── utils/            # 工具函数
│   ├── cn.ts         # className 合并工具（clsx + tailwind-merge）
│   └── helpers.ts    # 业务工具函数
├── types/            # TypeScript 类型定义
├── mock/             # Mock 数据
│   └── data.ts       # Mock API 数据
├── assets/           # 静态资源
├── App.tsx           # 根组件
├── main.tsx          # 入口文件
└── index.css         # 全局样式（@import "tailwindcss"）

组件开发规范

import { useState } from 'react';
import { Search, Menu, X } from 'lucide-react';

interface HeaderProps {
  title: string;
  onMenuToggle?: () => void;
}

export function Header({ title, onMenuToggle }: HeaderProps) {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <header className="flex items-center justify-between px-6 py-4 bg-white shadow-sm">
      <h1 className="text-xl font-bold text-gray-900">{title}</h1>
      <div className="flex items-center gap-3">
        <Search className="w-5 h-5 text-gray-500" />
        <button
          onClick={() => {
            setIsOpen(!isOpen);
            onMenuToggle?.();
          }}
          className="p-2 rounded-lg hover:bg-gray-100 transition-colors"
        >
          {isOpen ? <X className="w-5 h-5" /> : <Menu className="w-5 h-5" />}
        </button>
      </div>
    </header>
  );
}

本地 Mock 数据

创建 `src/mock/data.ts` 来模拟 API 数据：

// src/mock/data.ts
export const mockUsers = [
  { id: 1, name: '张三', email: 'zhangsan@example.com', avatar: '' },
  { id: 2, name: '李四', email: 'lisi@example.com', avatar: '' },
];

// Mock API 函数
export async function fetchMockData<T>(data: T, delay = 500): Promise<T> {
  return new Promise((resolve) => setTimeout(() => resolve(data), delay));
}

TailwindCSS 常用模式

{/* 响应式布局 */}
<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
  {/* 卡片 */}
  <div className="bg-white rounded-xl shadow-md p-6 hover:shadow-lg transition-shadow">
    <h3 className="text-lg font-semibold text-gray-900">标题</h3>
    <p className="mt-2 text-gray-600">描述文字</p>
  </div>
</div>

{/* 按钮样式 */}
<button class