Monorepo 管理：使用 Openclaw Skills 构建可扩展的应用

什么是 Monorepo 管理？

本技能为构建和管理现代 monorepo 提供了一个全面的框架。它利用 Turborepo、Nx 等强大工具以及 pnpm workspaces，实现无缝的代码共享、跨多个项目的原子更改以及一致的工具链。通过在 Openclaw Skills 生态系统中实施该技能，开发人员可以克服传统的依赖地狱和破碎的 CI/CD 管道等多仓库障碍，确保复杂软件系统的可扩展架构。

无论您是启动新项目还是迁移现有代码库，此方法都强调通过智能缓存和任务编排来实现性能。它为在大型工程组织中保持高速开发提供了所需的技术基础。

下载入口:https://github.com/openclaw/skills/tree/main/skills/wpank/monorepo

安装与下载

1. ClawHub CLI

从源直接安装技能的最快方式。

npx clawhub@latest install monorepo

2. 手动安装

将技能文件夹复制到以下位置之一

全局模式 ~/.openclaw/skills/ 工作区 /skills/

优先级：工作区 > 本地 > 内置

3. 提示词安装

将此提示词复制到 OpenClaw 即可自动安装。

请帮我使用 Clawhub 安装 monorepo。如果尚未安装 Clawhub，请先安装（npm i -g clawhub）。

Monorepo 管理 应用场景

• 从多个断开连接的存储库迁移到统一的工作区。
• 通过智能缓存和任务编排优化构建和测试性能。
• 在前端和后端服务之间共享 UI 组件、实用函数和 TypeScript 类型。
• 使用 Changesets 自动化内部包的版本控制和发布。
• 通过仅运行受影响项目的任务来简化 CI/CD 工作流程。

Monorepo 管理 工作原理

1. 使用 pnpm-workspace.yaml 定义工作区结构，将项目分类为应用程序和包。
2. 配置根目录的 package.json 以管理共享开发依赖项和全局脚本。
3. 在 turbo.json 或 nx.json 中设置任务管道，定义构建、测试和 lint 之间的依赖关系。
4. 使用感知工作区的包管理器来处理包间依赖和过滤。
5. 实施远程缓存和受影响逻辑，以减少本地开发和 CI 环境中的冗余工作。

Monorepo 管理 配置指南

要使用 Openclaw Skills 方法开始使用此技能，请按如下方式初始化您的环境：

# 初始化 pnpm 工作区
touch pnpm-workspace.yaml

# 将 Turborepo 添加到根目录
pnpm add -D turbo -w

# 使用 Nx 生成示例项目
npx create-nx-workspace@latest my-org

# 为工作区内的特定包安装依赖项
pnpm add react --filter @repo/ui

Monorepo 管理 数据架构与分类体系

Monorepo 通过集中的树结构组织数据和配置：

文件/文件夹	用途
apps/	包含可部署的应用程序（例如 Next.js、API 服务）。
packages/	包含共享库、UI 套件和配置。
turbo.json	编排任务执行管道和缓存规则。
pnpm-workspace.yaml	定义哪些目录是 monorepo 工作区的一部分。
nx.json	项目图和受影响命令的高级配置。
.npmrc	配置包提升和同级依赖严格性。

name: monorepo
model: standard
description: Build and manage monorepos with Turborepo, Nx, and pnpm workspaces — covering workspace structure, dependency management, task orchestration, caching, CI/CD, and publishing. Use when setting up monorepos, optimizing builds, or managing shared packages.

Monorepo Management

Build efficient, scalable monorepos that enable code sharing, consistent tooling, and atomic changes across multiple packages and applications.

When to Use

• Setting up a new monorepo or migrating from multi-repo
• Optimizing build and test performance
• Managing shared dependencies across packages
• Configuring CI/CD for monorepos
• Versioning and publishing packages

Why Monorepos?

Advantages: Shared code and dependencies, atomic commits across projects, consistent tooling, easier refactoring, better code visibility.

Challenges: Build performance at scale, CI/CD complexity, access control, large Git history.

Tool Selection

Package Managers

Build Systems

Guidance: Start with Turborepo unless you need Nx's code generation, dependency graph visualization, or plugin ecosystem.

Workspace Structure

my-monorepo/
├── apps/
│   ├── web/              # Next.js app
│   ├── api/              # Backend service
│   └── docs/             # Documentation site
├── packages/
│   ├── ui/               # Shared UI components
│   ├── utils/            # Shared utilities
│   ├── types/            # Shared TypeScript types
│   ├── config-eslint/    # Shared ESLint config
│   └── config-ts/        # Shared TypeScript configs
├── turbo.json            # Turborepo pipeline config
├── pnpm-workspace.yaml   # Workspace definition
└── package.json          # Root package.json

Convention: apps/ for deployable applications, packages/ for shared libraries.

Turborepo Setup

Root Configuration

# pnpm-workspace.yaml
packages:
  - "apps/*"
  - "packages/*"

// package.json (root)
{
  "name": "my-monorepo",
  "private": true,
  "scripts": {
    "build": "turbo run build",
    "dev": "turbo run dev",
    "test": "turbo run test",
    "lint": "turbo run lint",
    "type-check": "turbo run type-check",
    "clean": "turbo run clean && rm -rf node_modules"
  },
  "devDependencies": {
    "turbo": "^2.0.0",
    "prettier": "^3.0.0"
  },
  "packageManager": "pnpm@9.0.0"
}

Pipeline Configuration

// turbo.json
{
  "$schema": "https://turbo.build/schema.json",
  "globalDependencies": ["**/.env.*local"],
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", ".next/**", "!.next/cache/**"],
      "inputs": ["src/**", "package.json", "tsconfig.json"]
    },
    "test": {
      "dependsOn": ["build"],
      "outputs": ["coverage/**"]
    },
    "lint": {
      "outputs": []
    },
    "type-check": {
      "dependsOn": ["^build"],
      "outputs": []
    },
    "dev": {
      "cache": false,
      "persistent": true
    }
  }
}

Key concepts:

• dependsOn: ["^build"] — build dependencies first (topological)
• outputs — what to cache (omit for side-effect-only tasks)
• inputs — what invalidates cache (default: all files)
• persistent: true — for long-running dev servers
• cache: false — disable caching for dev tasks

Package Configuration

// packages/ui/package.json
{
  "name": "@repo/ui",
  "version": "0.0.0",
  "private": true,
  "exports": {
    ".": { "import": "./dist/index.js", "types": "./dist/index.d.ts" },
    "./button": { "import": "./dist/button.js", "types": "./dist/button.d.ts" }
  },
  "scripts": {
    "build": "tsup src/index.ts --format esm,cjs --dts",
    "dev": "tsup src/index.ts --format esm,cjs --dts --watch"
  },
  "devDependencies": {
    "@repo/config-ts": "workspace:*",
    "tsup": "^8.0.0"
  }
}

Nx Setup

npx create-nx-workspace@latest my-org

# Generate projects
nx generate @nx/react:app my-app
nx generate @nx/js:lib utils

// nx.json
{
  "targetDefaults": {
    "build": {
      "dependsOn": ["^build"],
      "inputs": ["production", "^production"],
      "cache": true
    },
    "test": {
      "inputs": ["default", "^production"],
      "cache": true
    }
  },
  "namedInputs": {
    "default": ["{projectRoot}/**/*"],
    "production": ["default", "!{projectRoot}/**/*.spec.*"]
  }
}

# Nx-specific commands
nx build my-app
nx affected:build --base=main    # Only build what changed
nx graph                          # Visualize dependency graph
nx run-many --target=build --all --parallel=3

Nx advantage: nx affected computes exactly which projects changed, skipping unaffected ones entirely.

Dependency Management (pnpm)

# Install in specific package
pnpm add react --filter @repo/ui
pnpm add -D typescript --filter @repo/ui

# Install workspace dependency
pnpm add @repo/ui --filter web

# Install in root (shared dev tools)
pnpm add -D eslint -w

# Run script in specific package
pnpm --filter web dev
pnpm --filter @repo/ui build

# Run in all packages
pnpm -r build

# Filter patterns
pnpm --filter "@repo/*" build
pnpm --filter "...web" build    # web + all its dependencies

# Update all dependencies
pnpm update -r

.npmrc

# Hoist shared dependencies for compatibility
shamefully-hoist=true

# Strict peer dependency management
auto-install-peers=true
strict-peer-dependencies=true

Shared Configurations

TypeScript

// packages/config-ts/base.json
{
  "compilerOptions": {
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "module": "ESNext",
    "moduleResolution": "bundler",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "declaration": true
  }
}

// apps/web/tsconfig.json
{
  "extends": "@repo/config-ts/base.json",
  "compilerOptions": { "outDir": "dist", "rootDir": "src" },
  "include": ["src"]
}

Build Optimization

Remote Caching

# Turborepo + Vercel remote cache
npx turbo login
npx turbo link

# Now builds share cache across CI and all developers
# First build: 2 minutes. Cache hit: 0 seconds.

Cache Configuration

{
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", ".next/**"],
      "inputs": ["src/**/*.tsx", "src/**/*.ts", "package.json"]
    }
  }
}

Critical: Define inputs precisely. If a build only depends on src/, don't let changes to README.md invalidate the cache.

CI/CD

GitHub Actions

name: CI
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0    # Required for affected commands

      - uses: pnpm/action-setup@v4
        with:
          version: 9

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: "pnpm"

      - run: pnpm install --frozen-lockfile
      - run: pnpm turbo run build test lint type-check

Deploy Affected Only

- name: Deploy affected apps
  run: |
    AFFECTED=$(pnpm turbo run build --dry-run=json --filter='[HEAD^1]' | jq -r '.packages[]')
    if echo "$AFFECTED" | grep -q "web"; then
      pnpm --filter web deploy
    fi

Publishing Packages

# Setup Changesets
pnpm add -Dw @changesets/cli
pnpm changeset init

# Workflow
pnpm changeset          # Create changeset (describe what changed)
pnpm changeset version  # Bump versions based on changesets
pnpm changeset publish  # Publish to npm

# .github/workflows/release.yml
- name: Create Release PR or Publish
  uses: changesets/action@v1
  with:
    publish: pnpm changeset publish
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

Best Practices

1. Lock dependency versions — Use exact versions or lock files across the workspace
2. Centralize configs — ESLint, TypeScript, Prettier in shared packages
3. Keep the graph acyclic — No circular dependencies between packages
4. Define cache inputs/outputs precisely — Incorrect cache config wastes time or serves stale builds
5. Share types between frontend/backend — Single source of truth for contracts
6. Unit tests in packages, E2E in apps — Match test scope to package scope
7. README in each package — What it does, how to develop, how to use
8. Use changesets for versioning — Automated, reviewable release process

Common Pitfalls

NEVER Do

• NEVER use * for workspace dependency versions — Use workspace:* with pnpm
• NEVER skip --frozen-lockfile in CI — Ensures reproducible builds
• NEVER cache dev server tasks — They're long-running, not cacheable
• NEVER create circular package dependencies — Breaks build ordering
• NEVER hoist without understanding — shamefully-hoist is a compatibility escape hatch, not a default

Related Skills

• Related: service-layer-architecture — API patterns within monorepo apps
• Related: postgres-job-queue — Background jobs for monorepo services