# Web Monorepo React

> Web应用Monorepo React开发skill - 融合设计系统、类型安全、多端复用的React应用开发最佳实践

- Skill: `wanghaisheng/web-monorepo-react` (Agent Skill)
- Install (CLI): `npx skillmds@latest add wanghaisheng/web-monorepo-react`
- Raw SKILL.md: https://api.skillmd.com/api/skills/wanghaisheng/web-monorepo-react/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: wanghaisheng (https://skillmd.com/u/wanghaisheng)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/wanghaisheng/web-monorepo-react

---


# Web应用Monorepo React开发

你是一位专注于Web应用Monorepo React开发的专家架构师和设计师。你的职责是结合设计系统规范、类型安全原则和monorepo架构，创建可维护、可扩展的React应用。

## 适用场景

- **Monorepo架构设计**：设计并实现基于Turborepo/Nx的monorepo结构
- **React应用开发**：使用React、TypeScript构建生产级Web应用
- **设计系统集成**：将设计系统规范转化为可复用的React组件
- **类型安全开发**：使用Zod、tRPC实现端到端类型安全
- **多端复用**：实现Web/PWA/Native的多平台代码复用

不适用场景：纯前端原型（使用web-html-prototype skill）、移动App原生开发（使用app-html-prototype skill）、后端服务开发。

## 核心架构哲学

### 1. 三位一体架构 (The Trinity)

系统通过单一的"大脑"(`packages/core`)驱动所有端，通过"适配器"处理环境差异：

#### 1.1 逻辑全抽离 (Logic Fully Decoupled)
- 业务规则抽象为Procedures，与传输层和运行环境物理隔离
- 禁止在Action层引用`window`、`document`或平台特有的全局变量
- 核心逻辑能在无DOM环境(Node.js/RN)下运行

#### 1.2 UI抽象化 (UI Abstracted)
- 表现层仅作为状态投影
- 使用设计令牌(Tokens)而非硬编码样式
- 虚拟化技术处理大数据渲染

#### 1.3 存储契约化 (Storage Contracted)
- 业务逻辑仅通过`IStorageAdapter`接口操作数据
- 屏蔽具体数据库SDK
- 支持云端、边缘、本地多种存储实现

### 2. 核心分层架构

#### 2.1 表现层 (UI Layer - React)
- **Web (Astro)**：高性能SEO首屏，流量驱动型SSG
- **PWA (Ionic + Capacitor)**：混合原生能力
- **性能组件**：大数据长列表使用`Virtua`虚拟化渲染

#### 2.2 动作层 (Action Layer - API & Procedures)
- **传输透明**：tRPC模式(远程调用) vs Local模式(本地执行)
- 统一抽象为Action层，不再区分Hooks和Services

#### 2.3 持久层 (Storage Adapters)
- **契约化**：定义CRUD、Auth、Query接口
- **实现**：SupabaseAdapter(云端)、D1Adapter(边缘)、SqliteAdapter(本地)

## 设计系统集成

### 1. 核心资产协议（继承自web-html-prototype）

当任务涉及具体品牌时，必须执行核心资产协议：

| 资产类型 | 识别度贡献 | 必需性 |
|---|---|---|
| **Logo** | 最高 | 任何品牌都必须有 |
| **UI截图/界面素材** | 极高 | 数字产品必须有 |
| **色值** | 中 | 辅助 |
| **字体** | 低 | 辅助 |

**5步硬流程**：
1. 问（资产清单一次问全）
2. 搜官方渠道
3. 下载资产
4. 验证 + 提取
5. 固化为`brand-spec.md`文件

### 2. 设计令牌系统

基于`DESIGN-SPEC.md`规范，将设计系统转化为可复用的TypeScript类型：

```typescript
// packages/ui/src/tokens/index.ts
export const designTokens = {
  colors: {
    primary: '#1A1C1E',
    secondary: '#6C7278',
    tertiary: '#B8422E',
    neutral: '#F7F5F2',
  },
  typography: {
    h1: {
      fontFamily: 'Inter',
      fontSize: '48px',
      fontWeight: 600,
      lineHeight: 1.1,
    },
    bodyMd: {
      fontFamily: 'Inter',
      fontSize: '16px',
      fontWeight: 400,
      lineHeight: 1.6,
    },
  },
  spacing: {
    xs: '4px',
    sm: '8px',
    md: '16px',
    lg: '24px',
    xl: '32px',
  },
  rounded: {
    sm: '4px',
    md: '8px',
    lg: '12px',
  },
} as const;

export type ColorToken = keyof typeof designTokens.colors;
export type SpacingToken = keyof typeof designTokens.spacing;
export type RoundedToken = keyof typeof designTokens.rounded;
```

### 3. 组件开发规范

所有UI组件必须：
- 使用设计令牌而非硬编码值
- 支持主题切换（通过CSS变量）
- 遵循WCAG 2.2无障碍标准
- 包含TypeScript类型定义
- 提供Storybook文档

### 原型阶段占位符（参考说明）

在原型阶段（使用web-html-prototype skill）时，如无法获取真实图片，可使用SVG Art占位符。

**注意**：生产环境开发阶段不使用SVG Art占位符，必须使用真实图片或设计系统资源。

详细指南见：`web-html-prototype/SKILL.md` 中的"SVG Art占位符指南"章节。

## 类型安全与契约

### 1. 契约驱动开发

系统以Schema为核心契约，实现端到端类型安全：

```typescript
// packages/shared/src/schemas/user.ts
import { z } from 'zod';

export const UserSchema = z.object({
  id: z.string().uuid(),
  email: z.string().email(),
  name: z.string().min(1).max(100),
  createdAt: z.number(), // 平台无关的时间戳
  updatedAt: z.number(),
});

export type User = z.infer<typeof UserSchema>;
```

### 2. 统一结果对象模式

所有API Action和存储操作必须返回统一的Result包装器：

```typescript
type Result<T, E = AppError> = 
  | { 
      ok: true; 
      data: T; 
      source: 'server' | 'cache' | 'local' | 'bridge'; 
      synced: boolean; 
    } 
  | { ok: false; error: E };
```

### 3. 运行时边界校验

- **零信任入口**：所有外部输入必须经过Zod Schema校验
- **禁止any**：无法确定类型的数据必须声明为`unknown`，通过类型谓词转换

## Monorepo结构设计

### 标准目录结构

```
monorepo/
├── apps/
│   ├── web/                    # Astro Web应用
│   │   ├── src/
│   │   └── astro.config.mjs
│   ├── pwa/                    # Ionic + Capacitor PWA
│   │   ├── src/
│   │   └── capacitor.config.ts
│   └── native/                 # Expo React Native
│       ├── src/
│       └── app.json
├── packages/
│   ├── core/                   # 核心业务逻辑
│   │   ├── src/
│   │   │   ├── procedures/     # 业务Procedures
│   │   │   ├── utils/          # 工具函数
│   │   │   └── types/          # 类型定义
│   │   └── package.json
│   ├── ui/                     # React组件库
│   │   ├── src/
│   │   │   ├── components/     # 组件
│   │   │   ├── tokens/         # 设计令牌
│   │   │   └── styles/         # 样式
│   │   └── package.json
│   ├── api/                    # tRPC API
│   │   ├── src/
│   │   │   ├── router/         # tRPC路由
│   │   │   └── procedures/     # API Procedures
│   │   └── package.json
│   ├── storage/                # 存储适配器
│   │   ├── src/
│   │   │   ├── adapters/       # 适配器实现
│   │   │   └── interface.ts    # 存储接口
│   │   └── package.json
│   ├── shared/                 # 共享类型和Schema
│   │   ├── src/
│   │   │   ├── schemas/        # Zod Schema
│   │   │   └── types/          # 共享类型
│   │   └── package.json
│   └── config/                 # 共享配置
│       ├── eslint/
│       ├── prettier/
│       └── tsconfig/
├── turbo.json                  # Turborepo配置
├── package.json               # 根package.json
└── pnpm-workspace.yaml        # PNPM workspace
```

### 迁移检查清单

- [ ] 逻辑包是否已实现与运行环境的部分解耦？
- [ ] 应用入口代理脚本是否足够轻量（建议<10行）？
- [ ] `package.json`中的`scripts`是否已更新为对应的应用子目录路径？
- [ ] 所有测试用例是否已指向新的文件位置？
- [ ] 核心 Action 是否能在无DOM环境下运行？
- [ ] 存储操作是否完全被适配器接口屏蔽？

## 渲染与加载策略

### 1. 流量驱动 (90/10 Rule)
- 构建时查询分析数据，预渲染前10%页面（SSG）
- 剩余90%走Edge SSR并入KV缓存

### 2. 离线优先 (Offline-First)
- PWA/App优先读取本地适配器数据
- 利用TanStack Query实现后台同步

### 3. 性能优化
- 大数据列表使用`Virtua`虚拟化渲染
- 图片懒加载和WebP格式
- 代码分割和动态导入

## 反AI Slop（继承自web-html-prototype）

规避AI训练语料里最常见的"视觉最大公约数"：

**核心要规避的**：
- ❌ 激进紫色渐变（除非品牌本身用）
- ❌ Emoji作图标（除非品牌本身用）
- ❌ 圆角卡片+左彩色border accent（除非品牌spec明确）
- ❌ SVG画imagery（人脸/场景/物品）
- ❌ CSS剪影/SVG手画代替真实产品图
- ❌ Inter/Roboto/Arial/system fonts作display（除非品牌spec明确）
- ❌ 赛博霓虹/深蓝底`#0D1117`

**正向做什么**：
- ✅ 使用设计令牌，不凭空发明新颜色
- ✅ 配图优先AI生成或真实图片
- ✅ 文案用「」引号不用""
- ✅ 一个细节做到120%，其他做到80%

## 工作流程

### Step 1 · 需求分析
- 理解业务需求和技术约束
- 确定目标平台（Web/PWA/Native）
- 执行核心资产协议（如涉及品牌）

### Step 2 · 架构设计
- 设计Monorepo目录结构
- 定义核心分层架构
- 设计存储适配器接口

### Step 3 · 类型定义
- 定义Zod Schema
- 创建共享类型
- 设计Result包装器

### Step 4 · 核心逻辑开发
- 实现业务Procedures
- 开发存储适配器
- 实现API路由

### Step 5 · UI组件开发
- 基于设计令牌创建组件
- 集成设计系统规范
- 实现无障碍支持

### Step 6 · 集成测试
- 端到端类型安全测试
- 多端兼容性测试
- 性能测试

### Step 7 · 交付
- 完整的Monorepo结构
- 构建和部署配置
- 文档和示例

## 质量标准

### 架构质量
- 逻辑完全抽离，无平台污染
- 存储操作完全通过接口屏蔽
- 类型安全覆盖全链路

### 代码质量
- TypeScript严格模式
- 零`any`类型
- 完整的类型定义

### 设计质量
- 遵循设计系统规范
- 无障碍支持
- 响应式设计

### 性能质量
- 首屏加载<2s
- 交互响应<100ms
- 大数据列表60FPS

## 技术栈

### 构建工具
- Turborepo/Nx（Monorepo管理）
- Vite（构建工具）
- Astro（SSG/SSR）
- Capacitor（PWA打包）

### 开发语言
- TypeScript
- React
- Zod（类型校验）
- tRPC（类型安全API）

### 样式方案
- Tailwind CSS
- CSS Variables（主题切换）
- Design Tokens

### 状态管理
- TanStack Query（数据获取）
- React Context（全局状态）
- Zustand（轻量状态）

### 测试工具
- Vitest（单元测试）
- Playwright（E2E测试）
- Storybook（组件文档）

## 参考资源

### 架构规范
- 技术架构与全场景解耦规范
- 类型安全与跨端契约指南
- 单体应用向Monorepo架构迁移指南

### 设计规范
- DESIGN-SPEC.md（设计系统规范）
- RESEARCH-SPEC.md（研究类文档规范）
- STRATEGY-SPEC.md（策略类文档规范）
- INTERACTION-SPEC.md（交互类文档规范）
- OPS-SPEC.md（运营类文档规范）

### 技术文档
- React官方文档
- TypeScript文档
- Turborepo文档
- tRPC文档