Configura y gestiona un monorepo con Turborepo o Nx que comparte código entre múltiples aplicaciones, optimiza los builds con caché inteligente y mantiene la estructura organizada a medida que el proyecto crece. Con la estructura de carpetas, la gestión de dependencias compartidas y la configuración de CI/CD.
Cuándo usarlo: Monorepo, Turborepo, Nx, arquitectura frontend, packages compartidos, CI/CD
Herramienta recomendada: Claude
Eres un Staff Engineer con experiencia migrando proyectos de repositorios separados a monorepos con Turborepo y Nx en stacks de TypeScript, React y Node.js con equipos de 5-30 ingenieros. Contexto: - Stack: [TypeScript + React / Node.js / Next.js / Vue / otro] - Situación actual: [múltiples repos separados / un repo con todo mezclado / empezando desde cero] - Apps que quieres gestionar: [web app / app móvil / API / scripts / packages de UI] - Equipo: [N ingenieros] - Herramienta elegida o a evaluar: [Turborepo / Nx / no sé cuál elegir] ## Monorepo con Turborepo — [Proyecto] ### 🤔 Turborepo vs. Nx: cuándo elegir cada uno **Turborepo:** - Más simple de configurar y entender - Ideal para equipos que quieren monorepo sin overhead de configuración - Mejor integración con el ecosistema npm/pnpm existente - El turbo.json es muy legible **Nx:** - Más potente — generadores de código, grapho de dependencias visual, plugins por framework - Ideal para proyectos grandes con muchas apps y librerías - Mayor curva de aprendizaje inicial - Mejor para equipos grandes que necesitan automatización de scaffolding **La recomendación pragmática:** Si tienes <5 apps y el equipo no supera 10 personas → Turborepo. Si tienes >5 apps, múltiples frameworks o necesitas generadores → Nx. ### 🏗️ La estructura del monorepo con Turborepo ``` my-monorepo/ ├── apps/ │ ├── web/ # Next.js app principal │ ├── api/ # Node.js / Express API │ └── docs/ # Docusaurus o VitePress │ ├── packages/ │ ├── ui/ # Componentes de UI compartidos │ ├── config/ # Configuraciones compartidas │ │ ├── eslint/ │ │ ├── tsconfig/ │ │ └── tailwind/ │ ├── database/ # Schema de Prisma + utilidades de DB │ └── utils/ # Funciones de utilidad compartidas │ ├── turbo.json # Configuración de Turborepo ├── package.json # Root package.json └── pnpm-workspace.yaml # Configuración de workspace (con pnpm) ``` ### ⚙️ La configuración básica de Turborepo **turbo.json:** ```json { "$schema": "https://turbo.build/schema.json", "globalDependencies": ["**/.env.*local"], "pipeline": { "build": { "dependsOn": ["^build"], // "^" = primero build las dependencias "outputs": [".next/**", "!.next/cache/**", "dist/**"] }, "test": { "dependsOn": ["^build"], "outputs": ["coverage/**"] }, "lint": { "outputs": [] }, "dev": { "cache": false, // dev no se cachea "persistent": true // proceso persistente (no termina) } } } ``` **Root package.json:** ```json { "name": "my-monorepo", "private": true, "scripts": { "build": "turbo build", "dev": "turbo dev", "lint": "turbo lint", "test": "turbo test", "format": "prettier --write \"**/*.{ts,tsx,md}\"" }, "devDependencies": { "turbo": "latest", "prettier": "latest" } } ``` **pnpm-workspace.yaml:** ```yaml packages: - 'apps/*' - 'packages/*' ``` ### 📦 Cómo usar un package compartido en una app **En packages/ui/package.json:** ```json { "name": "@myrepo/ui", "version": "0.0.1", "main": "./index.tsx", "exports": { ".": "./index.tsx" } } ``` **En apps/web/package.json:** ```json { "dependencies": { "@myrepo/ui": "workspace:*" // pnpm resuelve al package local } } ``` **En apps/web/app/page.tsx:** ```typescript import { Button, Card } from '@myrepo/ui' // Import directo del package del monorepo — hot reload funciona ``` ### 🚀 El caché inteligente de Turborepo (la mayor ventaja) Turborepo cachea los outputs de cada task. Si el código no ha cambiado, rehusa el resultado anterior. ```bash turbo build # Primera vez: compila todo — 45 segundos # Segunda vez (sin cambios): "cache hit" — 0.5 segundos # Después de cambiar solo web/: solo recompila web/ — 8 segundos ``` **El remote cache con Vercel:** ```bash turbo login turbo link # Ahora el caché se comparte entre todos los desarrolladores y CI ``` ### 🔧 La configuración de CI/CD para el monorepo El pipeline de GitHub Actions que solo ejecuta los tests y builds de los packages afectados por el PR.