---
id: giuseppe-trisciuoglio/developer-kit/turborepo-monorepo
version: "b9c03642"
license: MIT
install: manual
updated: 2026-06-22
---

# turborepo-monorepo — This skill streamlines the setup and configuration of Turborepo-based monorepo environments, enabling developers to organize multiple projects within a single repository with optimized build caching and task orchestration. Designed for polyglot teams working across Java, TypeScript, Python, PHP, and cloud platforms, it provides validated patterns and workflows to accelerate workspace initialization and dependency management.

Publisher: giuseppe-trisciuoglio · Stars: 311 · Updated: 2026-06-22

Install (manual): `git clone https://github.com/giuseppe-trisciuoglio/developer-kit`

## SKILL.md

# Turborepo Monorepo

## Overview

Provides guidance for Turborepo monorepo management: workspace creation, `turbo.json` task configuration, Next.js/NestJS integration, testing pipelines (Vitest/Jest), CI/CD setup, and build performance optimization.

## When to Use

- Create or initialize Turborepo workspaces
- Configure `turbo.json` tasks with dependencies and outputs
- Set up Next.js/NestJS apps in monorepo structure
- Configure Vitest/Jest test pipelines
- Build CI/CD workflows (GitHub Actions, GitLab CI)
- Implement remote caching with Vercel Remote Cache
- Optimize build times and cache hit ratios
- Debug task dependency or cache issues
- Migrate from other monorepo tools to Turborepo

## Instructions

### Workspace Creation

1. **Create a new workspace:**
   ```bash
   pnpm create turbo@latest my-workspace
   cd my-workspace
   ```

2. **Initialize in existing project:**
   ```bash
   pnpm add -D -w turbo
   ```

3. **Create turbo.json in root** (minimal config):
   ```json
   {
     "$schema": "https://turborepo.dev/schema.json",
     "pipeline": {
       "build": { "dependsOn": ["^build"], "outputs": ["dist/**", ".next/**"] },
       "lint": { "outputs": [] },
       "test": { "dependsOn": ["build"], "outputs": ["coverage/**"] }
     }
   }
   ```

4. **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" } }
   ```

5. **Validate task graph before CI:**
   ```bash
   turbo run build --dry-run --filter=...  # Verify task execution order
   ```

### Task Configuration

1. **Configure tasks** in `turbo.json`:
   ```json
   { "pipeline": { "build": { "dependsOn": ["^build"], "outputs": ["dist/**"] }, "test": { "dependsOn": ["build"], "outputs": ["coverage/**"] }, "lint": { "outputs": [] } } }
   ```

2. **Run tasks:**
   ```bash
   turbo run build                      # All packages
   turbo run lint test build           # Multiple tasks
   turbo run build --filter=web       # Specific package
   ```

3. **Parallel type checking** (use transit nodes to avoid cache issues):
   ```json
   { "pipeline": { "transit": { "dependsOn": ["^transit"] }, "typecheck": { "dependsOn": ["transit"] } } }
   ```

4. **Validate before committing:**
   ```bash
   turbo run build --dry-run  # Check task order and affected packages
   ```

### Framework Integration

**Next.js:** outputs `".next/**"` and env `["NEXT_PUBLIC_*"]` - See [references/nextjs-config.md](references/nextjs-config.md)

**NestJS:** outputs `"dist/**"`, dev tasks with `cache: false, persistent: true` - See [references/nestjs-config.md](references/nestjs-config.md)

### Testing Setup

1. **Vitest configuration:**
   ```json
   {
     "pipeline": {
       "test": {
         "outputs": [],
         "inputs": ["$TURBO_DEFAULT$", "vitest.config.ts"]
       },
       "test:watch": {
         "cache": false,
         "persistent": true
       }
     }
   }
   ```

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

### Package Configurations

1. **Create package-specific turbo.json:**
   ```json
   {
     "extends": ["//"],
     "tasks": {
       "build": {
         "outputs": ["$TURBO_EXTENDS$", ".next/**"]
       }
     }
   }
   ```
   See [references/package-configs.md](references/package-configs.md) for detailed package configuration patterns.

### CI/CD Setup

1. **GitHub Actions with validation checkpoints:**
   ```yaml
   - name: Install dependencies
     run: pnpm install

   - name: Validate affected packages (dry-run)
     run: pnpm turbo run build --filter=[HEAD^] --dry-run
     # VALIDATE: Review output to confirm only expected packages will build

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

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

   - name: Verify cache hits
     run: pnpm turbo run build --filter=[HEAD^] --dry-run | grep "Cache"
     # VALIDATE: Confirm cache hits for unchanged packages
   ```

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

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

## 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"` |

### Dependency Patterns

- `^task` - Run task in dependencies first (topological order)
- `task` - Run task in same package first
- `package#task` - Run specific package's 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/ |

## Best Practices

### Performance Optimization

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

### Caching Strategy

```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

## Common Issues

### Tasks not running in order

**Problem:** Tasks execute in wrong order

**Solution:** Check `dependsOn` configuration

```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"]
    }
  }
}
```

### 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"] }
}
```

## Examples

### Example 1: Create New Workspace

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

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

# Add Next.js app
pnpm add next react react-dom -F apps/web

# Add NestJS API
pnpm add @nestjs/core @nestjs/common -F apps/api
```

### Example 2: Configure Testing Pipeline

**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
    }
  }
}
```

### Example 3: Run Affected Tests in CI

**Input:** "Only test changed packages in CI"

```bash
pnpm run test --filter=[HEAD^]
```

### Example 4: Debug Cache Issues

**Input:** "Why is my cache missing?"

```bash
# Dry run to see what would be executed
turbo run build --dry-run --filter=web

# Show hash inputs
turbo run build --force --filter=web
```

## 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

## Reference Files

For detailed guidance on specific topics, consult:

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


[View on SkillFed](https://skillfed.io/giuseppe-trisciuoglio/developer-kit/turborepo-monorepo) · [View on GitHub](https://github.com/giuseppe-trisciuoglio/developer-kit)