Claude Code y Turborepo: guía práctica para monorepos

Por qué Claude Code encaja con Turborepo

Un monorepo reúne varias aplicaciones y paquetes compartidos en un mismo repositorio. Al principio parece simple: apps/web, apps/admin, packages/ui. El problema llega cuando aparecen más equipos, más scripts, más despliegues y una CI que tarda demasiado porque ejecuta todo aunque el cambio sea pequeño.

Turborepo ordena ese trabajo con un grafo de tareas y caché. Claude Code aporta valor cuando lo usas como revisor del repositorio: lee package.json, explica dependencias entre paquetes, detecta outputs incompletos y propone comandos de CI más pequeños. No conviene tratarlo solo como generador de archivos.

Esta guía asume Turborepo v2 a fecha 2 de junio de 2026. En turbo.json se usa tasks, no el antiguo pipeline. Para adaptar los ejemplos, revisa las fuentes oficiales: Turborepo configuration, turbo run, Remote Caching y Claude Code memory.

Para más contexto interno, combina este artículo con gestión de monorepos, pnpm workspace con Claude Code y CI/CD con Claude Code.

Estructura objetivo y tres casos de uso

El objetivo es un monorepo TypeScript pequeño sobre pnpm workspace. Empezar pequeño ayuda porque Claude Code respeta mejor límites claros que nombres vagos como shared o common.

flowchart LR
  web["apps/web\nApp de clientes"] --> ui["packages/ui\nUI compartida"]
  admin["apps/admin\nApp interna"] --> ui
  web --> utils["packages/utils\nFunciones compartidas"]
  admin --> utils
  ui --> tsconfig["packages/tsconfig\nConfig TS"]
  utils --> tsconfig

Primer caso: una app de clientes y una app interna comparten botones, formularios y validadores. Separar packages/ui de packages/utils evita que Claude Code mezcle componentes visuales con lógica de negocio.

Segundo caso: una plataforma de contenido con landing, documentación y panel interno. Ejecutar todo en cada pull request se vuelve caro. --affected y --filter permiten verificar solo los paquetes modificados y los que dependen de ellos.

Tercer caso: un SaaS con rutas que afectan ingresos. Pricing, signup, account settings y admin suelen compartir paquetes pequeños. Si lint, type-check, test y build están estandarizados, Claude Code puede cambiar un CTA sin saltarse la red de seguridad de CI.

Copia la estructura mínima

Primero fija la forma del repositorio. Lo importante no es tener muchos paquetes, sino que cada uno tenga una responsabilidad fácil de explicar.

acme-monorepo/
  apps/
    web/
      package.json
      src/
    admin/
      package.json
      src/
  packages/
    ui/
      package.json
      src/
    utils/
      package.json
      src/
    tsconfig/
      package.json
      base.json
  pnpm-workspace.yaml
  package.json
  turbo.json
  CLAUDE.md

pnpm-workspace.yaml puede quedarse así:

packages:
  - "apps/*"
  - "packages/*"

En el package.json raíz, deja scripts que el equipo y Claude Code puedan reutilizar. El 2 de junio de 2026 verifiqué turbo@2.9.16 y pnpm@11.5.1; en un proyecto real, el lockfile debe fijar el resultado.

{
  "name": "acme-monorepo",
  "private": true,
  "packageManager": "pnpm@11.5.1",
  "scripts": {
    "dev": "turbo dev",
    "build": "turbo run build",
    "lint": "turbo run lint",
    "test": "turbo run test",
    "type-check": "turbo run type-check",
    "check": "turbo run lint type-check test build",
    "check:affected": "turbo run lint type-check test build --affected"
  },
  "devDependencies": {
    "turbo": "^2.9.16",
    "typescript": "^5.8.3"
  }
}

Los paquetes internos deben usar workspace:*. Así el package manager resuelve el paquete desde este workspace y no desde un registry por accidente.

{
  "name": "@acme/ui",
  "version": "0.1.0",
  "private": true,
  "type": "module",
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "scripts": {
    "build": "tsc -p tsconfig.json",
    "lint": "eslint src --max-warnings=0",
    "type-check": "tsc -p tsconfig.json --noEmit",
    "test": "vitest run"
  },
  "devDependencies": {
    "@acme/tsconfig": "workspace:*",
    "typescript": "^5.8.3",
    "vitest": "^3.1.0",
    "eslint": "^9.25.0"
  }
}

Define turbo.json con tasks y outputs

El turbo.json raíz es el contrato del repositorio. Cada clave dentro de tasks busca scripts con el mismo nombre en los paquetes. ^build significa que primero se ejecuta el build de las dependencias del paquete.

{
  "$schema": "https://turborepo.dev/schema.json",
  "globalDependencies": ["pnpm-lock.yaml", "tsconfig.base.json", ".env.example"],
  "globalEnv": ["NODE_ENV"],
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", ".next/**", "!.next/cache/**", "out/**"]
    },
    "lint": {
      "dependsOn": ["^build"],
      "outputs": []
    },
    "type-check": {
      "dependsOn": ["^build"],
      "outputs": []
    },
    "test": {
      "dependsOn": ["build"],
      "outputs": ["coverage/**"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    }
  }
}

outputs indica qué artefactos se pueden restaurar desde caché. Si faltan, la caché no ayuda. Si sobran, guardas temporales y cachés internas del framework. En Next.js, excluir .next/cache/** suele ser una opción prudente.

Si una aplicación tiene artefactos distintos, usa un turbo.json dentro del paquete. Los arrays reemplazan la configuración heredada por defecto; para añadir sin perder lo anterior, coloca $TURBO_EXTENDS$ al inicio.

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

Haz que CI sea predecible

Turborepo brilla en CI, pero --affected necesita historial Git. En GitHub Actions, un checkout superficial puede hacer que todos los paquetes parezcan cambiados. Usa fetch-depth: 0.

name: turbo-ci

on:
  pull_request:
  push:
    branches: [main]

permissions:
  contents: read

jobs:
  verify:
    runs-on: ubuntu-latest
    env:
      TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
      TURBO_TEAM: ${{ secrets.TURBO_TEAM }}
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: pnpm/action-setup@v4
        with:
          version: 11.5.1
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: pnpm
      - run: pnpm install --frozen-lockfile
      - run: pnpm turbo run lint type-check test build --affected
      - run: pnpm turbo run build --dry=json > turbo-plan.json
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: turbo-plan
          path: turbo-plan.json

Para Remote Cache, enlaza el repositorio con pnpm dlx turbo login y pnpm dlx turbo link, y pasa TURBO_TOKEN y TURBO_TEAM como secrets en CI. Recuerda que los logs también pueden tratarse como artefactos: no imprimas API keys, datos de clientes ni tokens de sesión.

Deja estos comandos en CLAUDE.md para que Claude Code los reutilice.

pnpm turbo run build --dry=json
pnpm turbo run build --filter=@acme/web...
pnpm turbo run test --filter=...[origin/main]
pnpm turbo run lint --filter=!./apps/docs
pnpm turbo run build --cache=local:rw,remote:r
pnpm turbo run build --force

Prompt para Claude Code

No basta con pedir “configura Turborepo”. Dale límites, prohibiciones y comandos de verificación.

Este repositorio es un monorepo Turborepo v2 + pnpm workspace.

Límites:
- apps/* son aplicaciones desplegables.
- packages/ui contiene solo componentes visuales.
- packages/utils contiene solo funciones independientes del framework.
- packages/* no debe depender de apps/*.
- turbo.json debe usar tasks, no pipeline.

Tarea:
1. Lee package.json y turbo.json, y explica el grafo de tareas.
2. Señala outputs faltantes o sospechosos para la caché.
3. Si hace falta cambiar algo, aplica el diff seguro más pequeño.
4. Ejecuta estos comandos y reporta el resultado:

pnpm turbo run lint type-check test build --affected
pnpm turbo run build --dry=json

Este prompt evita el fallo típico de la IA: una reescritura grande y lateral. También ayuda a rechazar malas ideas como poner llamadas HTTP en packages/ui, importar Next.js desde packages/utils o usar siempre builds completos en CI.

Errores frecuentes

El primer error es copiar ejemplos antiguos con pipeline. En Turborepo v2 se usa tasks. Si migras un repo viejo, pide a Claude Code que explique cada cambio contra la documentación oficial.

El segundo error es cachear demasiado. No incluyas node_modules/**, logs temporales ni cachés internas no desplegables en outputs. Cachea artefactos de build, no todo el directorio.

El tercer error es usar --affected sin historial Git suficiente. Si base y head no existen en el checkout, Turborepo no puede calcular bien el conjunto de paquetes.

El cuarto error es pedir demasiado en una sola tarea. Introduce Turborepo, luego scripts raíz, luego CI. Deja la división de paquetes, la migración de ESLint y las actualizaciones de dependencias para pasos separados.

El quinto error es compartir de más. Un packages/shared enorme convierte cambios pequeños en cambios globales. Paquetes como ui, utils, contracts y tsconfig son más fáciles de revisar.

Monetización y siguientes pasos

Turborepo no solo acelera. Protege rutas de ingresos. Un sitio de contenidos puede bloquear la publicación si el build falla. Un SaaS puede validar pricing, signup, settings y admin en un flujo repetible. En consultoría, CI más corta reduce el tiempo de espera en review.

ClaudeCodeLab ayuda a convertir esto en una práctica de equipo: CLAUDE.md, límites de paquetes, comandos de CI, prompts de review y reglas de despliegue. Para aprender por tu cuenta, sigue con gestión de monorepos y CI/CD con Claude Code. Para adoptarlo con un equipo, empieza en training / consultation.

Resultado al probarlo

Masa aplicó este patrón a un repositorio pequeño con dos apps Vite y un paquete de UI compartida. La primera ejecución corrió todas las tareas; las siguientes mostraron caché en build y type-check. El problema inicial fue un outputs demasiado amplio que guardaba cachés internas del framework y ensuciaba los artefactos de CI. La versión estable fue la de este artículo: tasks de v2, outputs estrechos, verificación affected y un prompt de Claude Code que revisa límites antes de editar archivos.