ADR-002: 迁移至 pnpm + Turborepo Monorepo

Status

Accepted

Date

2026-03-18

Context

项目计划引入共享类型包（@stormflow/shared）和未来可能的更多包。单仓库结构下，跨包共享代码需要使用相对路径导入，不利于维护和扩展。

Options Considered

Option A: 单仓库 + 路径别名

• Pros: 零配置，直接用相对路径或 TypeScript paths 引用共享代码
• Cons: 随着包增多路径管理混乱，无法独立发布，构建缺乏缓存

Option B: pnpm workspace + Turborepo

• Pros: 原生 workspace 协议管理依赖，Turborepo 提供任务编排和构建缓存，包边界清晰
• Cons: 初始配置稍复杂，需要理解 workspace 和 turbo pipeline 概念

Option C: Nx

• Pros: 功能丰富，内置依赖图分析和受影响检测
• Cons: 配置重，对小型项目过于复杂，与 Nuxt 生态集成不如 Turborepo 自然

Decision

采用 pnpm workspace + Turborepo 的 monorepo 架构：

• apps/web/ — Nuxt 4 前端应用（@stormflow/web）
• packages/shared/ — 共享类型和工具函数（@stormflow/shared）
• 根目录仅安装 Turborepo，所有应用依赖安装在各自包中
• 使用 workspace:* 协议引用工作区内部包

Consequences

• 共享代码通过 workspace 包管理，类型安全且易于维护
• Turborepo 提供任务编排、并行执行和构建缓存
• CI 使用 turbo run 命令，享受缓存加速
• 未来可轻松添加新的 apps 或 packages