react-vite-scaffold

Vite React 项目脚手架

参考：https://www.heropy.dev/p/6iFzkB

用于搭建基于 Vite 的 React（CSR）项目，或自动补齐现有项目中缺失配置的技能。

必须执行的检查清单（MANDATORY）

技能启动后立即将以下项目逐一添加到 TodoWrite，然后按顺序执行。禁止跳过。

1. 检测项目状态（第 1 步）
2. 确定模式：脚手架模式还是补齐模式（第 2 步）
3. 创建项目［仅限脚手架模式］（第 3 步）
4. 安装并配置 Tailwind CSS［未安装 tailwindcss 时］（第 4 步）
5. 配置路径别名［vite.config/tsconfig 中未配置 alias 时］（第 5 步）
6. 配置 ESLint + Prettier［不存在 .prettierrc 或未安装 prettier 包时］（第 6 步）
7. 创建 .prettierrc［文件不存在时］（第 7 步）
8. 创建 .vscode/settings.json［文件不存在时］（第 8 步）
9. 最终验证 — 重新扫描第 1 步中的检测表，确认所有配置均已就绪；如有缺失，重新执行相应步骤（第 9 步）

满足条件时，将各项目标记为“skipped”并完成，但须先说明判断依据（文件/包是否存在），再继续。

操作流程

第 1 步：检测项目状态

检查以下文件，以判断当前项目状态：

检查对象	检测方法
是否为空目录	当前目录中没有文件，或不存在 package.json
Vite 项目	存在 vite.config.ts 或 vite.config.js
TypeScript	存在 tsconfig.json 或 tsconfig.app.json
Tailwind CSS	package.json 的 dependencies/devDependencies 中存在 tailwindcss
ESLint 配置	存在 eslint.config.js 或 eslint.config.mjs
Prettier 配置	存在 .prettierrc
VSCode 设置	存在 .vscode/settings.json
包管理器	pnpm-lock.yaml → pnpm，yarn.lock → yarn，bun.lockb/bun.lock → bun，package-lock.json 或不存在锁文件 → npm

第 2 步：分支处理

如果是空目录（脚手架模式）：

1. 执行项目创建命令
2. 自动应用以下所有配置

如果是现有 Vite 项目（补齐模式）：

1. 根据上述检测标准自动判断安装状态
2. 识别缺失的配置并自动创建
3. 不修改已存在的配置文件

第 3 步：创建项目

将 {pm} 替换为根据包管理器检测规则确定的包管理器。（npm、pnpm、yarn、bun） 要求：Node.js 22+、NPM 10+

在当前目录中创建 Vite 项目：

{pm} create vite@latest . -- --template react-compiler-ts --no-interactive

第 4 步：安装 Tailwind CSS［条件：未安装 tailwindcss 时］

{pm} i -D tailwindcss @tailwindcss/vite

在 vite.config.ts 中添加 Tailwind 插件（tailwindcss()）：

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

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

在 src/index.css 文件最顶部添加：

@import 'tailwindcss';

第 5 步：配置路径别名［条件：vite.config 或 tsconfig 中未配置 @ alias 时］

配置 vite.config.ts 的 resolve.alias：

export default defineConfig({
  resolve: {
    alias: [
      { find: '@', replacement: '/src' }
    ]
  }
})

在 tsconfig.app.json 中添加路径别名：

{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

如果使用 TypeScript v5 或更低版本（通过 tsc --version 确认），请在 paths 上方添加 "baseUrl": "."。

第 6 步：配置 ESLint + Prettier［条件：未安装 prettier 包或 eslint-plugin-prettier 时］

创建 Vite 项目时已包含 ESLint 相关包。 安装 Prettier 相关包：

{pm} install -D prettier eslint-config-prettier eslint-plugin-prettier prettier-plugin-tailwindcss

在 eslint.config.js 中添加 Prettier 集成：

import prettierRecommended from 'eslint-plugin-prettier/recommended'

export default defineConfig([
  {
    extends: [
      prettierRecommended
    ]
  }
])

第 7 步：.prettierrc［条件：文件不存在时］

如果不存在 .prettierrc 文件，则在项目根目录中创建：

{
  "semi": false,
  "singleQuote": true,
  "singleAttributePerLine": true,
  "bracketSameLine": true,
  "endOfLine": "auto",
  "trailingComma": "none",
  "arrowParens": "avoid",
  "plugins": ["prettier-plugin-tailwindcss"]
}

第 8 步：.vscode/settings.json［条件：文件不存在时］

如果不存在 .vscode/settings.json 文件，则创建：

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode"
}

第 9 步：最终验证（MANDATORY）

完成所有步骤后，再次扫描第 1 步中的检测表，确认以下项目：

• 已安装 tailwindcss、@tailwindcss/vite + 已在 vite.config.ts 中注册插件 + src/index.css 中存在 @import 'tailwindcss'
• vite.config.ts 和 tsconfig.app.json 中均存在 @ 路径别名
• 已安装 prettier、eslint-config-prettier、eslint-plugin-prettier、prettier-plugin-tailwindcss
• eslint.config.js 中包含 prettierRecommended
• 存在 .prettierrc
• 存在 .vscode/settings.json

**如果有缺失项，请返回相应步骤并立即补齐。**验证通过前禁止结束任务。

注意事项

• 不覆盖已存在的配置文件
• 在现有项目补齐模式下，无需提问，自动执行
• 根据现有项目的锁文件判断包管理器：
  • pnpm-lock.yaml → pnpm
  • yarn.lock → yarn
  • bun.lockb 或 bun.lock → bun
  • package-lock.json 或不存在锁文件 → npm
• 空目录（脚手架模式）下使用 npm