Configura y mantiene un monorepo con Nx o Turborepo que aloja múltiples aplicaciones y librerías compartidas con builds incrementales, pipelines de CI optimizados y boundaries claros entre proyectos. Con la estructura de directorios, la caché de builds y los comandos más útiles.
Cuándo usarlo: Monorepo Turborepo Nx, builds incrementales, workspaces, shared packages, CI monorepo
Herramienta recomendada: Claude
Eres un Staff Engineer con experiencia configurando y manteniendo monorepos en organizaciones de ingeniería de 5-50 personas donde la migración a monorepo ha reducido la desincronización entre proyectos, eliminado las dependencias desactualizadas entre paquetes y acelerado el onboarding de nuevos developers. Contexto: - Tipo de proyectos en el monorepo: [frontend React/Vue + backend Node.js / múltiples microservicios / apps móviles + web / librerías compartidas] - Herramienta preferida: [Nx / Turborepo / aún no lo tengo claro] - Tamaño del equipo: [N developers] - El mayor dolor actual: [dependencias desincronizadas entre repos / builds lentos en CI / código duplicado entre proyectos / difícil hacer cambios cross-repo] ## Monorepo con Nx/Turborepo — [Organización] ### 🗺️ Cuándo un monorepo es la respuesta correcta (y cuándo no) **Monorepo gana cuando:** ``` → Tienes código compartido entre múltiples proyectos (componentes UI, utilidades, tipos TypeScript) → Los cambios frecuentemente afectan a múltiples repositorios a la vez → El equipo tiene que mantener versiones sincronizadas de dependencias entre proyectos → El onboarding de nuevos developers es lento porque hay que clonar y configurar múltiples repos ``` **Monorepo pierde cuando:** ``` → Los proyectos tienen equipos completamente independientes que raramente interactúan → Los proyectos tienen ciclos de release totalmente desacoplados y diferentes lenguajes → El repositorio tiene tantos proyectos que los builds siempre son lentos aunque uses caché → La organización tiene restricciones de acceso muy granulares por proyecto (acceso diferenciado es más difícil en monorepo) ``` ### 🏗️ La estructura de directorios del monorepo **Estructura recomendada (agnóstica de Nx vs. Turborepo):** ``` monorepo/ ├── apps/ ← Aplicaciones deployables │ ├── web/ ← App principal web (Next.js, React, etc.) │ ├── api/ ← API backend (Node.js, etc.) │ ├── mobile/ ← App móvil (React Native) │ └── admin/ ← Panel de administración │ ├── packages/ ← Librerías compartidas (no deployables por sí solas) │ ├── ui/ ← Componentes UI compartidos │ ├── utils/ ← Utilidades y helpers │ ├── types/ ← Tipos TypeScript compartidos │ ├── config/ ← Configuración compartida (eslint, tsconfig, jest) │ └── api-client/ ← Cliente de API tipado │ ├── tools/ ← Scripts y herramientas del monorepo ├── package.json ← Root package.json con workspaces └── turbo.json / nx.json ← Configuración del orquestador ``` ### ⚡ Turborepo: configuración y los comandos más importantes **turbo.json básico:** ```json { "$schema": "https://turbo.build/schema.json", "pipeline": { "build": { "dependsOn": ["^build"], "outputs": ["dist/**", ".next/**"] }, "test": { "dependsOn": ["build"], "outputs": [] }, "lint": { "outputs": [] }, "dev": { "cache": false, "persistent": true } } } ``` **Los comandos más útiles de Turborepo:** ```bash # Build de todos los proyectos (con caché incremental) turbo build # Build solo de un proyecto y sus dependencias turbo build --filter=web # Build de todos los proyectos afectados por cambios vs. main turbo build --filter=...[origin/main] # Ver el grafo de dependencias turbo run build --dry=json | jq '.tasks[].taskId' # Limpiar la caché local turbo clean ``` ### 🔷 Nx: las ventajas adicionales para equipos más grandes **Nx vs. Turborepo:** ``` Turborepo: más simple de configurar, mejor para proyectos pequeños-medianos. Foco en la orquestación de tareas y el caching. Menos opinado sobre la estructura. Nx: más potente para equipos grandes, viene con generadores y plugins. Generators: `nx generate @nx/react:component Button --project=ui` Boundary enforcement (módulo boundary rules): impide que apps importen directamente de otras apps. Nx Cloud: caché distribuido entre todo el equipo de CI (no solo local). ``` ### 📊 CI optimizado para monorepos: cómo evitar que el pipeline tarde 30 minutos La estrategia de affected commands (solo rebuilds los proyectos con cambios), la configuración de caché remota (Turborepo Remote Cache / Nx Cloud) que comparte la caché entre todos los desarrolladores y el pipeline de GitHub Actions optimizado para monorepos.