Turborepo Monorepo Patterns

Use when setting up or managing a Turborepo-based monorepo. Covers workspace configuration, task pipelines, caching strategies, shared packages, and CI/CD in...

Security Scan

The skill is a coherent Turborepo guide, but its runtime instructions and included CI examples reference several secrets and environment variables (tokens, deploy secrets, and DB-related commands) while the skill metadata declares no required environment variables — this mismatch is a notable risk and should be clarified before use.

Purpose & Capability

The name and description (Turborepo monorepo patterns) match the included content: workspace config, turbo.json examples, shared package patterns, and GitHub Actions CI. The files and examples are appropriate for the stated purpose.

Instruction Scope

SKILL.md and the referenced CI workflow instruct running commands that may use/require secrets and affect external services: remote caching (turbo login/link, turbo --api with --token), GitHub Actions YAML that expects TURBO_TOKEN/TURBO_TEAM and Vercel deploy steps using VERCEL_TOKEN/ORG/PROJECT. The guide also includes database migration/generation commands (prisma db push/migrate) which may require database connection credentials. The instructions do not overstep by reading arbitrary host files, but they do direct potentially destructive or externally-visible actions (deploys, DB migrations) if run with credentials.

Install Mechanism

Instruction-only skill with no install spec and no code files; nothing is downloaded or written by the skill itself. This is the lowest-risk install mechanism.

Credentials

The metadata lists no required environment variables, yet the documentation and CI examples reference multiple tokens/secrets (TURBO_TOKEN, TURBO_TEAM, VERCEL_TOKEN, VERCEL_ORG_ID, VERCEL_PROJECT_ID and implied DB credentials for Prisma). Those env vars are plausible and expected for these operations, but they should be declared in requires.env. The absence of declared env requirements is a mismatch that could lead to accidental credential exposure or accidental execution if users supply secrets without understanding scope.

Persistence & Privilege

The skill is not always-enabled, and it does not request persistent system presence or claim to modify other skills or global agent config. Autonomous invocation is allowed (the platform default) but there are no additional privilege escalations requested by the skill.

What to consider before installing

This skill is a legitimate-looking Turborepo guide, but it references several secrets and operations that have side effects (remote cache tokens, Vercel deploy tokens, and Prisma DB commands). Before installing or invoking it: 1) Treat the CI and CLI examples as templates — do not paste production secrets into the agent environment without reviewing who/what will run them. 2) Expect that to run deploy or DB-migration commands you will need tokens/DB credentials; the skill's metadata does not declare these, so verify where you store secrets and ensure least privilege. 3) Review the included .github/workflows/ci.yml and any prisma migration steps; run in a safe/non-production environment first. 4) If you plan to use this skill programmatically, request that the skill author explicitly declare required env vars (TURBO_TOKEN, TURBO_TEAM, VERCEL_* and any DB connection strings) so you can audit and supply least-privilege secrets. If you cannot confirm those declarations, avoid giving the agent secrets or running commands that perform deploys or DB migrations.

Monorepo with Turborepo

A practical guide to building and managing scalable monorepos using Turborepo.

When to Use

• Setting up a new monorepo with multiple apps/packages
• Optimizing build/test pipelines with caching
• Sharing UI components, utilities, or configs across apps
• Configuring CI for monorepo with selective builds

Core Workflow

1. Initialize Monorepo

npx create-turbo@latest my-monorepo
cd my-monorepo

Workspace layout:

my-monorepo/
├── apps/
│   ├── web/          # Next.js app
│   └── docs/         # Docusaurus
├── packages/
│   ├── ui/           # Shared components
│   ├── config/       # Shared ESLint/TS configs
│   └── utils/        # Shared utilities
├── turbo.json
└── package.json

2. Configure turbo.json Pipeline

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

3. Package.json Root Config

{
  "name": "my-monorepo",
  "private": true,
  "workspaces": ["apps/*", "packages/*"],
  "scripts": {
    "build": "turbo build",
    "dev": "turbo dev",
    "lint": "turbo lint",
    "test": "turbo test",
    "type-check": "turbo type-check",
    "clean": "turbo clean && rm -rf node_modules"
  },
  "devDependencies": {
    "turbo": "latest"
  }
}

4. Shared Package Setup (packages/ui)

// packages/ui/package.json
{
  "name": "@repo/ui",
  "version": "0.0.1",
  "exports": {
    "./*": {
      "import": "./src/*.tsx",
      "require": "./src/*.tsx"
    }
  },
  "scripts": {
    "build": "tsc",
    "lint": "eslint src/",
    "dev": "tsc --watch"
  }
}

5. Remote Caching (Vercel)

npx turbo login
npx turbo link

Or with custom remote cache:

turbo build --api="https://your-cache-server.com" --token="$TURBO_TOKEN" --team="your-team"

6. Selective Builds (Filter)

# Build only affected packages
turbo build --filter=...[HEAD^1]

# Build specific app and its dependencies
turbo build --filter=web...

# Exclude a package
turbo build --filter=!docs

7. CI/CD Integration (GitHub Actions)

See references/ci-github-actions.yml for a complete workflow.

Key Principles

• ^ prefix in dependsOn means "build all dependencies first"
• outputs defines what gets cached; be explicit
• cache: false for dev/watch tasks
• persistent: true for long-running processes
• Always define exports in package.json for shared packages

Troubleshooting

Issue	Solution
Cache miss every run	Check outputs paths are correct
Circular dependency	Use turbo graph to visualize
Package not found	Verify workspaces glob in root package.json
Slow cold build	Enable remote caching