turborepo-monorepo

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Turborepo Monorepo

Overview

概述

Provides comprehensive guidance for working with Turborepo monorepos in TypeScript/JavaScript projects. Turborepo is a high-performance build system written in Rust that optimizes task execution through intelligent caching, parallelization, and dependency graph analysis. This skill covers workspace creation, task configuration, framework integration (Next.js, NestJS, Vite), testing setup, CI/CD pipelines, and performance optimization.

为TypeScript/JavaScript项目中使用Turborepo monorepo提供全面指导。Turborepo是一款用Rust编写的高性能构建系统，通过智能缓存、并行化和依赖图分析优化任务执行。本技能涵盖工作区创建、任务配置、框架集成（Next.js、NestJS、Vite）、测试搭建、CI/CD流水线以及性能优化等内容。

When to Use

适用场景

Use this skill when:

Creating a new Turborepo workspace or initializing in an existing project
Configuring
```
turbo.json
```
tasks with proper dependencies and outputs
Setting up Next.js or NestJS applications in a monorepo
Configuring Vitest or Jest testing pipelines
Implementing CI/CD workflows (GitHub Actions, CircleCI, GitLab CI)
Setting up remote caching or Vercel Remote Cache
Optimizing build times and cache hit ratios
Managing package configurations for specific apps/libs
Debugging task dependency issues
Migrating from other monorepo tools to Turborepo

Trigger phrases: "create Turborepo workspace", "Turborepo monorepo", "turbo.json config", "Turborepo Next.js", "Turborepo NestJS", "Turborepo CI/CD", "Vitest Turborepo"

在以下场景中使用本技能：

创建新的Turborepo工作区或在现有项目中初始化
配置带有正确依赖和输出的
```
turbo.json
```
任务
在monorepo中搭建Next.js或NestJS应用
配置Vitest或Jest测试流水线
实现CI/CD工作流（GitHub Actions、CircleCI、GitLab CI）
搭建远程缓存或Vercel Remote Cache
优化构建时间和缓存命中率
管理特定应用/库的包配置
调试任务依赖问题
从其他monorepo工具迁移到Turborepo

触发短语： "create Turborepo workspace", "Turborepo monorepo", "turbo.json config", "Turborepo Next.js", "Turborepo NestJS", "Turborepo CI/CD", "Vitest Turborepo"

Instructions

操作指南

Workspace Creation

工作区创建

Create a new workspace:

bash

# Using pnpm (recommended)
pnpm create turbo@latest my-workspace

# Using npm
npm create turbo@latest my-workspace

# Using yarn
yarn create turbo my-workspace

Initialize in an existing project:
bash
```
pnpm add -D -w turbo
```

Create turbo.json in root:

json

{
  "$schema": "https://turborepo.dev/schema.json",
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", ".next/**"]
    },
    "lint": {
      "outputs": []
    },
    "test": {
      "dependsOn": ["build"],
      "outputs": ["coverage/**"]
    }
  }
}

Add scripts to root package.json:

json

{
  "scripts": {
    "build": "turbo run build",
    "dev": "turbo run dev",
    "lint": "turbo run lint",
    "test": "turbo run test",
    "clean": "turbo run clean"
  }
}

创建新工作区：

bash

# 使用pnpm（推荐）
pnpm create turbo@latest my-workspace

# 使用npm
npm create turbo@latest my-workspace

# 使用yarn
yarn create turbo my-workspace

在现有项目中初始化：
bash
```
pnpm add -D -w turbo
```

在根目录创建turbo.json：

json

{
  "$schema": "https://turborepo.dev/schema.json",
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", ".next/**"]
    },
    "lint": {
      "outputs": []
    },
    "test": {
      "dependsOn": ["build"],
      "outputs": ["coverage/**"]
    }
  }
}

在根package.json中添加脚本：

json

{
  "scripts": {
    "build": "turbo run build",
    "dev": "turbo run dev",
    "lint": "turbo run lint",
    "test": "turbo run test",
    "clean": "turbo run clean"
  }
}

Task Configuration

任务配置

Configure task dependencies:

json

{
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**"]
    },
    "test": {
      "dependsOn": ["build"],
      "outputs": ["coverage/**"]
    },
    "lint": {
      "outputs": []
    }
  }
}

Run tasks across packages:

bash

# Run task for all packages
turbo run build

# Run multiple tasks
turbo run lint test build

# Run for specific package
turbo run build --filter=web

Use transit nodes for parallel type checking:

json

{
  "pipeline": {
    "transit": {
      "dependsOn": ["^transit"]
    },
    "typecheck": {
      "dependsOn": ["transit"],
      "outputs": []
    }
  }
}

配置任务依赖：

json

{
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**"]
    },
    "test": {
      "dependsOn": ["build"],
      "outputs": ["coverage/**"]
    },
    "lint": {
      "outputs": []
    }
  }
}

跨包运行任务：

bash

# 为所有包运行任务
turbo run build

# 运行多个任务
turbo run lint test build

# 为指定包运行任务
turbo run build --filter=web

使用中转节点实现并行类型检查：

json

{
  "pipeline": {
    "transit": {
      "dependsOn": ["^transit"]
    },
    "typecheck": {
      "dependsOn": ["transit"],
      "outputs": []
    }
  }
}

Framework Integration

框架集成

Next.js app configuration:

json

{
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": [".next/**", "!.next/cache/**"],
      "env": ["NEXT_PUBLIC_*"]
    }
  }
}

See references/nextjs-config.md for complete Next.js setup.

NestJS API configuration:

json

{
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**"]
    },
    "start:dev": {
      "cache": false,
      "persistent": true
    }
  }
}

See references/nestjs-config.md for complete NestJS setup.

Next.js应用配置：

json

{
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": [".next/**", "!.next/cache/**"],
      "env": ["NEXT_PUBLIC_*"]
    }
  }
}

完整Next.js搭建请查看references/nextjs-config.md。

NestJS接口配置：

json

{
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**"]
    },
    "start:dev": {
      "cache": false,
      "persistent": true
    }
  }
}

完整NestJS搭建请查看references/nestjs-config.md。

Testing Setup

测试搭建

Vitest configuration:

json

{
  "pipeline": {
    "test": {
      "outputs": [],
      "inputs": ["$TURBO_DEFAULT$", "vitest.config.ts"]
    },
    "test:watch": {
      "cache": false,
      "persistent": true
    }
  }
}

Run affected tests:
bash
```
turbo run test --filter=[HEAD^]
```
See references/testing-config.md for complete testing setup.

Vitest配置：

json

{
  "pipeline": {
    "test": {
      "outputs": [],
      "inputs": ["$TURBO_DEFAULT$", "vitest.config.ts"]
    },
    "test:watch": {
      "cache": false,
      "persistent": true
    }
  }
}

运行受影响的测试：
bash
```
turbo run test --filter=[HEAD^]
```
完整测试搭建请查看references/testing-config.md。

Package Configurations

包配置

Create package-specific turbo.json:

json

{
  "extends": ["//"],
  "tasks": {
    "build": {
      "outputs": ["$TURBO_EXTENDS$", ".next/**"]
    }
  }
}

See references/package-configs.md for detailed package configuration patterns.

创建包专属turbo.json：

json

{
  "extends": ["//"],
  "tasks": {
    "build": {
      "outputs": ["$TURBO_EXTENDS$", ".next/**"]
    }
  }
}

详细包配置模式请查看references/package-configs.md。

CI/CD Setup

CI/CD搭建

GitHub Actions basic workflow:

yaml

- name: Install dependencies
  run: pnpm install

- name: Run tests
  run: pnpm run test --filter=[HEAD^]

- name: Build
  run: pnpm run build --filter=[HEAD^]

Remote cache setup:
bash
```
# Login to Vercel
npx turbo login

# Link repository
npx turbo link
```
See references/ci-cd.md for complete CI/CD setup examples.

GitHub Actions基础工作流：

yaml

- name: 安装依赖
  run: pnpm install

- name: 运行测试
  run: pnpm run test --filter=[HEAD^]

- name: 构建
  run: pnpm run build --filter=[HEAD^]

远程缓存搭建：
bash
```
# 登录Vercel
npx turbo login

# 关联仓库
npx turbo link
```
完整CI/CD搭建示例请查看references/ci-cd.md。

Task Properties Reference

任务属性参考

Property	Description	Example
`dependsOn`	Tasks that must complete first	`["^build"]` - dependencies first
`outputs`	Files/folders to cache	`["dist/**"]`
`inputs`	Files for cache hash	`["src/*/.ts"]`
`env`	Environment variables affecting hash	`["DATABASE_URL"]`
`cache`	Enable/disable caching	`true` or `false`
`persistent`	Long-running task	`true` for dev servers
`outputLogs`	Log verbosity	`"full"` , `"new-only"` , `"errors-only"`

属性	描述	示例
`dependsOn`	必须先完成的前置任务	`["^build"]` - 先执行依赖包的任务
`outputs`	需要缓存的文件/文件夹	`["dist/**"]`
`inputs`	用于生成缓存哈希的文件	`["src/*/.ts"]`
`env`	影响缓存哈希的环境变量	`["DATABASE_URL"]`
`cache`	启用/禁用缓存	`true` 或 `false`
`persistent`	长期运行的任务	开发服务器设置为 `true`
`outputLogs`	日志详细程度	`"full"` , `"new-only"` , `"errors-only"`

Dependency Patterns

依赖模式

```
^task
```
- Run task in dependencies first (topological order)
```
task
```
- Run task in same package first
```
package#task
```
- Run specific package's task

```
^task
```
- 先在依赖包中执行该任务（拓扑顺序）
```
task
```
- 先在当前包中执行该任务
```
package#task
```
- 执行指定包的特定任务

Filter Syntax

过滤语法

Filter	Description
`web`	Only web package
`web...`	web + all dependencies
`...web`	web + all dependents
`...web...`	web + deps + dependents
`[HEAD^]`	Packages changed since last commit
`./apps/*`	All packages in apps/

过滤规则	描述
`web`	仅针对web包
`web...`	web包及其所有依赖包
`...web`	web包及其所有依赖它的包
`...web...`	web包、其依赖包及依赖它的包
`[HEAD^]`	自上次提交后有变更的包
`./apps/*`	apps目录下的所有包

Best Practices

最佳实践

Performance Optimization

性能优化

Use specific outputs - Only cache what's needed
Fine-tune inputs - Exclude files that don't affect output
Transit nodes - Enable parallel type checking
Remote cache - Share cache across team/CI
Package configurations - Customize per-package behavior

使用特定输出 - 仅缓存必要内容
微调输入配置 - 排除不影响输出的文件
使用中转节点 - 启用并行类型检查
远程缓存 - 在团队/CI环境中共享缓存
包级配置 - 针对不同包自定义行为

Caching Strategy

缓存策略

json

{
  "pipeline": {
    "build": {
      "outputs": ["dist/**"],
      "inputs": ["$TURBO_DEFAULT$", "!README.md", "!**/*.md"]
    }
  }
}

json

{
  "pipeline": {
    "build": {
      "outputs": ["dist/**"],
      "inputs": ["$TURBO_DEFAULT$", "!README.md", "!**/*.md"]
    }
  }
}

Task Organization

任务组织

Independent tasks - No
```
dependsOn
```
: lint, format, spellcheck
Build tasks -
```
dependsOn: ["^build"]
```
: build, compile
Test tasks -
```
dependsOn: ["build"]
```
: test, e2e
Dev tasks -
```
cache: false, persistent: true
```
: dev, watch

独立任务 - 无
```
dependsOn
```
：lint、format、拼写检查
构建任务 -
```
dependsOn: ["^build"]
```
：build、compile
测试任务 -
```
dependsOn: ["build"]
```
：test、e2e
开发任务 -
```
cache: false, persistent: true
```
：dev、watch

Workspace Structure

工作区结构

my-workspace/
├── apps/
│   ├── web/           # Next.js app
│   └── api/           # NestJS backend
├── packages/
│   ├── ui/            # React component library
│   └── config/        # Shared configs
├── turbo.json
├── package.json
└── pnpm-workspace.yaml

my-workspace/
├── apps/
│   ├── web/           # Next.js应用
│   └── api/           # NestJS后端
├── packages/
│   ├── ui/            # React组件库
│   └── config/        # 共享配置
├── turbo.json
├── package.json
└── pnpm-workspace.yaml

Common Issues

常见问题

Tasks not running in order

任务执行顺序错误

Problem: Tasks execute in wrong order

Solution: Check

dependsOn

configuration

json

{
  "build": {
    "dependsOn": ["^build"]
  }
}

问题： 任务未按预期顺序执行

解决方案： 检查

dependsOn

配置

json

{
  "build": {
    "dependsOn": ["^build"]
  }
}

Cache misses on unchanged files

未修改文件却出现缓存未命中

Problem: Cache invalidating unexpectedly

Solution: Review

globalDependencies

and

inputs

json

{
  "globalDependencies": ["tsconfig.json"],
  "pipeline": {
    "build": {
      "inputs": ["$TURBO_DEFAULT$", "!*.md"]
    }
  }
}

问题： 缓存意外失效

解决方案： 检查

globalDependencies

和

inputs

配置

json

{
  "globalDependencies": ["tsconfig.json"],
  "pipeline": {
    "build": {
      "inputs": ["$TURBO_DEFAULT$", "!*.md"]
    }
  }
}

Type errors after cache hit

缓存命中后出现类型错误

Problem: TypeScript errors not caught due to cache

Solution: Use transit nodes for type checking

json

{
  "transit": { "dependsOn": ["^transit"] },
  "typecheck": { "dependsOn": ["transit"] }
}

问题： 缓存导致TypeScript错误未被捕获

解决方案： 使用中转节点执行类型检查

json

{
  "transit": { "dependsOn": ["^transit"] },
  "typecheck": { "dependsOn": ["transit"] }
}

Examples

示例

Example 1: Create New Workspace

示例1：创建新工作区

Input: "Create a Turborepo with Next.js and NestJS"

bash

pnpm create turbo@latest my-workspace
cd my-workspace

输入： "创建包含Next.js和NestJS的Turborepo"

bash

pnpm create turbo@latest my-workspace
cd my-workspace

Add Next.js app

添加Next.js应用

pnpm add next react react-dom -F apps/web

Add NestJS API

添加NestJS接口

pnpm add @nestjs/core @nestjs/common -F apps/api

undefined

pnpm add @nestjs/core @nestjs/common -F apps/api

undefined

Example 2: Configure Testing Pipeline

示例2：配置测试流水线

Input: "Set up Vitest for all packages"

json

{
  "pipeline": {
    "test": {
      "dependsOn": ["build"],
      "outputs": ["coverage/**"],
      "inputs": ["$TURBO_DEFAULT$", "vitest.config.ts"]
    },
    "test:watch": {
      "cache": false,
      "persistent": true
    }
  }
}

输入： "为所有包配置Vitest"

json

{
  "pipeline": {
    "test": {
      "dependsOn": ["build"],
      "outputs": ["coverage/**"],
      "inputs": ["$TURBO_DEFAULT$", "vitest.config.ts"]
    },
    "test:watch": {
      "cache": false,
      "persistent": true
    }
  }
}

Example 3: Run Affected Tests in CI

示例3：在CI中仅运行受影响的测试

Input: "Only test changed packages in CI"

bash

pnpm run test --filter=[HEAD^]

输入： "在CI中仅测试有变更的包"

bash

pnpm run test --filter=[HEAD^]

Example 4: Debug Cache Issues

示例4：调试缓存问题

Input: "Why is my cache missing?"

bash

undefined

输入： "为什么我的缓存未命中？"

bash

undefined

Dry run to see what would be executed

空运行查看将要执行的内容

turbo run build --dry-run --filter=web

Show hash inputs

查看哈希输入项

turbo run build --force --filter=web

undefined

turbo run build --force --filter=web

undefined

Constraints and Warnings

约束与注意事项

Node.js 18+ is required for Turborepo
Package manager field required in root
```
package.json
```
Outputs must be specified for caching to work
Persistent tasks cannot have dependents
Windows: WSL or Git Bash recommended
Remote cache requires Vercel account or self-hosted solution
Large monorepos may need increased
```
concurrency
```
settings

Turborepo要求Node.js 18+
根目录
```
package.json
```
中必须指定包管理器字段
必须指定输出项才能启用缓存
长期运行任务不能有依赖它的任务
Windows系统：推荐使用WSL或Git Bash
远程缓存需要Vercel账号或自托管解决方案
大型monorepo可能需要调整
```
concurrency
```
配置

Reference Files

参考文件

For detailed guidance on specific topics, consult:

Topic	Reference File
turbo.json template	references/turbo.json
Next.js integration	references/nextjs-config.md
NestJS integration	references/nestjs-config.md
Vitest/Jest/Playwright	references/testing-config.md
GitHub/CircleCI/GitLab CI	references/ci-cd.md
Package configurations	references/package-configs.md

如需特定主题的详细指导，请查阅：

主题	参考文件
turbo.json模板	references/turbo.json
Next.js集成	references/nextjs-config.md
NestJS集成	references/nestjs-config.md
Vitest/Jest/Playwright	references/testing-config.md
GitHub/CircleCI/GitLab CI	references/ci-cd.md
包配置	references/package-configs.md