web-monorepo-react

name	web-monorepo-react
description	Web应用Monorepo React开发skill - 融合设计系统、类型安全、多端复用的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类型：

// 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  designTokens.;
   = keyof  designTokens.;
   = keyof  designTokens.;

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为核心契约，实现端到端类型安全：

// 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包装器：

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文档