React Generate Skill

React Generate Skill

⚠️ 重要：本 Skill 严格依赖 frontend-request-skill

本 Skill 不重新发明请求层。所有 HTTP / 错误处理 / 鉴权相关代码必须复用 frontend-request-skill 的标准实现：

接入本 Skill 前，请先阅读 frontend-request-skill 的 SKILL.md 与核心 reference。

Overview

This skill transforms a vague React project idea into a production-ready React 18 + TypeScript SPA with consistent architecture, design tokens, static assets, and coding standards.

1. Pre-development: brainstorm, scope, and produce a detailed specification.
2. Project initialization: scaffold the project, directory structure, CLAUDE.md, AGENTS.md, tsconfig.json, vite.config.ts.
3. Development: install frontend-request-skill's request layer, set up theme system, design the layout, and build core pages.
4. Post-development: lint, type-check (tsc --noEmit), verify the build.

When to Use

Invoke this skill when the user asks for:

• "帮我做一个 React 项目"
• "初始化一个 React + TypeScript 模板"
• "做一个 React 后台管理系统"
• "用 React 搭一个 xxx 网站"
• "帮我生成一个标准的 React 项目结构"
• Any request that involves creating a new React SPA from scratch (H5 / 后台 / 文档站)

Not for: React Native / 小程序 / Taro / 移动端 hybrid — use react-native-init-skill instead.

Workflow Summary

Copy code
Phase 1: Pre-development
  → Ask 3-5 clarifying questions
  → Write spec.md (scope, pages, data model, API outline)

Phase 2: Project Initialization
  → npm create vite@latest scaffold
  → Replace placeholders
  → Create standard directory structure (including src/api/, src/services/, src/config/)
  → Generate CLAUDE.md (≤ 50 lines, references frontend-request-skill)
  → Generate AGENTS.md (≤ 400 lines, on-demand references)
  → Apply tsconfig.json strict template
  → Apply vite.config.ts template (path alias + auto-import)
  → Copy code-examples/ (types / stores / components / pages)

Phase 3: Development
  → Install frontend-request-skill's request layer (copy from references/)
  → Configure src/config/api.config.ts (BASE_URL / PREFIX / SUCCESS_CODES)
  → Configure src/config/error.config.ts (ERROR_CODE_MAP)
  → Set up src/styles/globals.css theme variables
  → Implement core pages using code-examples/ as template
  → Write hooks (useAuth, useFetch, ...)

Phase 4: Post-development
  → npm run lint           # ESLint must pass
  → npm run type-check     # tsc --noEmit must pass
  → npm run build          # Must build successfully
  → Summarize deliverables

Phase 1: Pre-development

1.1 Brainstorming Questions

Ask 3-5 focused questions:

1. "这个项目解决什么问题？核心目标用户是谁？"
2. "主要功能有哪些？请列出 3-5 个核心页面或核心流程。"
3. "你倾向哪种视觉风格？清新健康 / 极简工具 / 活泼社区 / 商务数据？"
4. "UI 库偏好？Ant Design / Material UI / Chakra UI / Radix UI / 自研？"
5. "是否需要登录、权限、用户系统？"

1.2 Write spec.md

Create spec.md with:

markdownCopy code
# {{PROJECT_NAME}} 项目规格说明

## 1. 项目定位
- 产品名称：
- 目标用户：
- 核心价值：
- 对标产品：

## 2. 核心功能
1. ...
2. ...
3. ...

## 3. 页面清单
| 页面 | 路径 | 说明 |
|------|------|------|
| 首页/Dashboard | src/pages/Dashboard.tsx | ... |

## 4. 数据模型
- User: { id, username, nickname, avatar, role, tenantId, createdAt }
- ...

## 5. API 轮廓
- POST /api/auth/login → { token, refreshToken, user }
- GET /api/users → { items, total }
- ...

## 6. 设计风格
- 风格：极简工具 / 商务数据 / ...
- 主色：#10b981
- UI 库：Ant Design 5.x
- 是否深色：否

Phase 2: Project Initialization

2.1 Create the React Project

bashCopy code
npm create vite@latest {{project-name}} -- --template react-ts
cd {{project-name}}
npm install

# 状态管理
npm install zustand

# UI 库（Ant Design 默认）
npm install antd @ant-design/icons

# 路由
npm install react-router-dom

# 工具
npm install -D @types/node

2.2 Apply tsconfig.json (STRICT MODE)

必须按 references/tsconfig-template.md 完整配置：

jsoncCopy code
{
  "compilerOptions": {
    "target": "ES2020",
    "useDefineForClassFields": true,
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "module": "ESNext",
    "skipLibCheck": true,
    "moduleResolution": "bundler",
    "allowImportingTsExtensions": true,
    "resolveJsonModule": true,
    "isolatedModules": true,
    "noEmit": true,
    "jsx": "react-jsx",
    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noFallthroughCasesInSwitch": true,
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  },
  "include": ["src"],
  "references": [{ "path": "./tsconfig.node.json" }]
}

2.3 Apply vite.config.ts

按 references/vite-config-template.md 完整配置：

typescriptCopy code
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { fileURLToPath, URL } from 'node:url';

export default defineConfig({
  plugins: [react()],
  resolve: {
    alias: {
      '@': fileURLToPath(new URL('./src', import.meta.url)),
    },
  },
});

2.4 Create Standard Directory Structure

按 references/project-structure.md 创建完整目录。关键目录：

Copy code
src/
├── api/              # 必须按 frontend-request-skill 划分
│   ├── request.ts
│   ├── upload.ts
│   ├── sse.ts (按需)
│   └── modules/
├── services/
│   └── auth.service.ts
├── config/
│   ├── api.config.ts
│   └── error.config.ts
├── stores/           # Zustand Store
│   ├── userStore.ts
│   └── appStore.ts
├── hooks/           # useAuth, useFetch 等
├── pages/            # 页面（不是 views）
├── components/       # 组件
├── types/           # ApiResponse<T> / RequestError
├── utils/           # auth.ts / error.ts / toast.ts
└── styles/          # 全局样式

2.5 Install frontend-request-skill's Request Layer

严格按 references/api-integration.md 复制以下文件：

禁止：

• ❌ 自己写 request.ts（必须按标准复制）
• ❌ 在组件里直接调 localStorage（必须走 utils/auth.ts）
• ❌ 在组件里写 401 处理（必须交给 auth.service.ts）

2.6 Generate CLAUDE.md (≤ 50 lines)

必须用 references/claude-md-template.md 模板，强制 ≤ 50 行。

模板已包含：

• 显式声明依赖 frontend-request-skill
• 9 条红线（含 fetch 标准、auth.service 收口）
• 完整的目录约定

2.7 Generate AGENTS.md (≤ 400 lines)

按 references/agents-md-template.md。按主题拆分章节，AI 按需查阅。

2.8 Copy Code Examples

从 references/code-examples/ 复制：

Phase 3: Development

3.1 Set Up the Theme System

按 SKILL.md § 3.1 创建 src/styles/globals.css（CSS 变量或 Ant Design ConfigProvider）。

3.2 Implement Pages

参考 references/code-examples/pages/UserManagement.tsx 的结构：

typescriptCopy code
import { useState, useEffect } from 'react';
import type { User, UserListParams } from '@/types/user';

export function UserManagement() {
  const [loading, setLoading] = useState(false);
  const [tableData, setTableData] = useState<User[]>([]);

  // 业务方法（全部用 async/await + try/catch + unknown）
  async function loadData() {
    setLoading(true);
    try {
      const res = await userApi.list(query);
      setTableData(res.data.list);
    } catch (err: unknown) {
      if (err && typeof err === 'object' && 'code' in err) {
        showError(err);
      }
    } finally {
      setLoading(false);
    }
  }

  useEffect(() => {
    loadData();
  }, []);
}

3.3 Implement State Management

参考 references/code-examples/stores/userStore.ts：

• ✅ Zustand 风格
• ✅ 使用 create
• ✅ 显式导出 store
• ✅ 提供 reset 方法

3.4 Shared Components（仅复用 ≥3 次）

参考 references/component-standards.md。

Phase 4: Post-development

4.1 Run Type Check（必须 0 error）

bashCopy code
npm run type-check    # tsc --noEmit

红线：任何 .tsx / .ts 文件必须通过类型检查。

4.2 Run Lint（必须 0 error）

bashCopy code
npm run lint

4.3 Run Build

bashCopy code
npm run build    # 自动先跑 type-check，再 vite build

4.4 Summarize Deliverables

提供：

1. 项目结构概览
2. 已生成文件清单
3. 主题色 / UI 库选择
4. type-check / lint / build 状态
5. 与 frontend-request-skill 的对齐清单

Resources

本 Skill 包含以下参考资料：

外部依赖：

• frontend-request-skill — 请求层规范（必装）

Best Practices

• 复用 frontend-request-skill：不自己写 request.ts、不在组件里调 localStorage、不在组件里写 401 跳转。
• TypeScript 严格模式：strict: true 全开，提交前必须 tsc --noEmit 通过。
• CLAUDE.md ≤ 50 行：超出部分移到 AGENTS.md。
• CSS 变量优先：业务代码只用 CSS 变量，禁止裸色值。
• Ant Design 优先：能用的组件就用，不手写。
• 3 次复用原则：组件被复用 ≥3 次才抽到 src/components/。
• Hooks 提取逻辑：可复用的逻辑抽到 src/hooks/。
• 每个组件文件带 lang="ts"：.tsx 文件必须带类型。
• 请求层严格分层：api/ 只管 HTTP / services/ 收口业务 / hooks/ 给组件用。
• 错误捕获用 unknown：不用 any，必要时用类型守卫。
• 完成必跑 3 件套：type-check + lint + build，全部 0 error。

Red Lines（绝不可违反）

1. ❌ 不用 axios（必须 fetch）
2. ❌ 不用 any 类型
3. ❌ 不用 console.log
4. ❌ 不用 class 组件（必须函数组件 + Hooks）
5. ❌ 不用 .jsx（必须 .tsx）
6. ❌ 不用裸色值
7. ❌ 不手写 Ant Design 已有的组件
8. ❌ 不在组件里直接调 localStorage
9. ❌ 不在组件里写 401 跳转
10. ❌ 不用 ESLint 规则覆盖 TypeScript 检查

触发词

react-generate、React Generate Skill