Back to Details

monorepo

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Monorepo Architecture

Monorepo架构

Use this skill to create predictable package boundaries, shared tooling, and fast incremental builds.
使用该技能可创建可预测的包边界、共享工具链以及快速增量构建。

Use This Skill When

适用场景

  • Multiple apps share code and release cadence.
  • You need shared packages (
    ui
    , 
    types
    , 
    config
    , 
    utils
    ).
  • Build/test/lint pipelines need workspace-level orchestration.
  • 多个应用共享代码与发布节奏。
  • 你需要共享包（如
    ui
    、
    types
    、
    config
    、
    utils
    ）。
  • 构建/测试/代码检查流水线需要工作区级别的编排。

Core Contract

核心约定

  1. Keep deployable apps in 
    apps/
    .
  2. Keep reusable packages in 
    packages/
    .
  3. Use workspace protocol dependencies (
    workspace:*
    ).
  4. Use Turbo pipelines for dependency-aware task execution.
  5. Keep environment variables explicit per app/package boundary.
  1. 将可部署应用放在
    apps/
    目录下。
  2. 将可复用包放在
    packages/
    目录下。
  3. 使用工作区协议依赖（
    workspace:*
    ）。
  4. 使用Turbo流水线执行依赖感知型任务。
  5. 为每个应用/包边界显式定义环境变量。

Recommended Structure

推荐结构

text
apps/
packages/
turbo.json
pnpm-workspace.yaml
package.json
text
apps/
packages/
turbo.json
pnpm-workspace.yaml
package.json

Implementation Workflow

实施流程

1) Workspace Setup

1) 工作区设置

  • Configure 
    pnpm-workspace.yaml
    .
  • Define root scripts for 
    dev
    , 
    build
    , 
    lint
    , 
    test
    .
  • Add Turbo pipeline with 
    dependsOn
    and 
    outputs
    .
  • 配置
    pnpm-workspace.yaml
    。
  • 定义根目录下的
    dev
    、
    build
    、
    lint
    、
    test
    脚本。
  • 添加带有
    dependsOn
    和
    outputs
    的Turbo流水线。

2) Shared Packages

2) 共享包

  • Create 
    packages/ui
    , 
    packages/types
    , 
    packages/config
    .
  • Export public APIs from package roots.
  • Keep package boundaries strict and testable.
  • 创建
    packages/ui
    、
    packages/types
    、
    packages/config
    。
  • 从包根目录导出公共API。
  • 保持包边界严格且可测试。

3) App Integration

3) 应用集成

  • Consume shared packages via workspace deps.
  • Keep app-specific runtime config local to app.
  • Avoid hidden coupling through root-only env assumptions.
  • 通过工作区依赖引入共享包。
  • 将应用特定的运行时配置保留在应用本地。
  • 避免通过仅根目录环境变量的假设产生隐式耦合。

4) Operational Quality

4) 运维质量

  • Cache-friendly tasks and deterministic outputs.
  • Per-package ownership and CI filters.
  • Versioning/release strategy documented.
  • 支持缓存的任务与确定性输出。
  • 按包划分所有权与CI过滤规则。
  • 记录版本控制/发布策略。

Output Requirements for Agent

Agent输出要求

  • Folder layout proposal.
  • Workspace and Turbo config.
  • Shared package strategy.
  • CI/build command matrix.
  • 文件夹布局提案。
  • 工作区与Turbo配置。
  • 共享包策略。
  • CI/构建命令矩阵。

References

参考资料

  • Detailed setup files and command examples: 
    references/guide.md
  • 详细的设置文件与命令示例：
    references/guide.md