Monorepos con Nx y Turborepo: Cómo Gestionar Múltiples Proyectos Sin Perder la Cordura

Hola HaWkers, ¿tu empresa tiene frontend, backend, mobile app, bibliotecas compartidas, todo en repositorios separados generando caos de versionamiento?

Monorepos surgieron como solución para este problema. Google, Facebook, Microsoft - gigantes tech mantienen MILLONES de líneas de código en repositorios únicos. En 2025, herramientas como Nx y Turborepo volvieron este approach accesible para cualquier equipo. Vamos a explorar.

Qué es Monorepo y Por Qué Importa

Monorepo: Repositorio Git único conteniendo múltiples proyectos relacionados (apps, libs, packages).

No confundas con:

Monolito: Arquitectura de aplicación única
Multirepo: Cada proyecto en repositorio separado

Nx: El Gigante Completo

Nx es desarrollado por Nrwl y es el más poderoso y complejo. Google usa Nx internamente para gestionar Angular, y la herramienta soporta CUALQUIER stack.

Setup Inicial

# Crear workspace Nx
npx create-nx-workspace@latest my-monorepo

# Elige: integrated (recomendado) o package-based

# Estructura generada:
my-monorepo/
├── apps/
│   ├── frontend/          # App React/Vue/Angular
│   ├── backend/           # API Node.js
│   └── mobile/            # React Native
├── libs/
│   ├── ui/                # Componentes compartidos
│   ├── data-access/       # Capa de datos
│   └── utils/             # Utilitarios
├── nx.json                # Configuración Nx
└── package.json

Creando Apps y Libs

# Generar aplicación React
nx g @nx/react:app frontend

# Generar biblioteca compartida
nx g @nx/react:lib ui --directory=libs/ui

# Generar API Node.js
nx g @nx/node:app backend

# Generar lib TypeScript pura
nx g @nx/js:lib utils --directory=libs/utils

Dependency Graph: Visualización Poderosa

# Ver grafo de dependencias
nx graph

# Nx genera visualización interactiva mostrando:
# - Cuáles apps dependen de cuáles libs
# - Dependencias circulares (¡errores!)
# - Impacto de cambios

nx dependency graph

Builds Inteligentes: Affected Commands

# Testear SOLO lo que cambió
nx affected:test

# Build solo apps/libs afectados
nx affected:build

# Lint solo código modificado
nx affected:lint

# ¿Cómo Nx sabe lo que cambió?
# Compara con branch base (ej: main) y analiza dependencias

Ejemplo Práctico

# Alteras libs/utils/src/date.ts

# Nx detecta automáticamente:
# - apps/frontend depende de libs/utils
# - apps/backend depende de libs/utils
# - apps/mobile NO depende de libs/utils

# Comando affected:build solo rebuilda:
nx affected:build
# ✓ libs/utils
# ✓ apps/frontend
# ✓ apps/backend
# ⊗ apps/mobile (¡saltado!)

# Economía: 40-60% de tiempo de build

Turborepo: Simplicidad y Velocidad

Turborepo (creado por Vercel) se enfoca en simplicidad y caching agresivo. Menos features que Nx, pero setup instantáneo.

Setup Turborepo

# Crear monorepo
npx create-turbo@latest my-turborepo

# Estructura generada:
my-turborepo/
├── apps/
│   ├── web/               # Next.js app
│   └── docs/              # Documentación
├── packages/
│   ├── ui/                # Component library
│   ├── config/            # Shared configs
│   └── tsconfig/          # TypeScript configs
├── turbo.json             # Pipeline config
└── package.json

Configuración de Pipeline

// turbo.json
{
  "$schema": "https://turbo.build/schema.json",
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", ".next/**"]
    },
    "test": {
      "dependsOn": ["build"],
      "outputs": ["coverage/**"]
    },
    "lint": {
      "outputs": []
    },
    "dev": {
      "cache": false
    }
  }
}

Ejecutando Tasks

# Build todo (con cache)
turbo run build

# Test en paralelo máximo
turbo run test

# Dev mode en múltiples apps
turbo run dev --parallel

# Cache remoto (Vercel)
turbo run build --token=<your-token>
# ¡Cache compartido entre todo el equipo!

Nx vs Turborepo: Comparación Directa

Rendimiento: Nx Gana en Escala

Benchmarks oficiales (large-monorepo):

Nx: ~50s para build completo
Turborepo: ~350s para build completo
¡Nx es 7x más rápido en monorepos grandes!

Simplicidad: Turborepo Gana

# Turborepo: Setup en minutos
npx create-turbo@latest

# Nx: Más decisiones iniciales
npx create-nx-workspace@latest
# → Elegir preset
# → Configurar CI
# → Definir estrategia de caching

Ecosistema: Nx Más Completo

Nx ofrece:

Plugins oficiales (React, Angular, Node, Next, Nest, etc)
Generators (code scaffolding automático)
Migrate (actualización automática de dependencias)
Nx Cloud (caching distribuido enterprise)

Turborepo ofrece:

Core build/cache system (extremadamente rápido)
Integración perfecta con Vercel
Simplicidad (menos abstracciones)

¿Cuándo Usar Cada Uno?

Usa Nx si:

Monorepo grande (10+ apps/libs)
Equipo grande (15+ devs)
Múltiples tecnologías (React + Angular + Node)
Necesitas CI/CD complejo
Quieres herramientas avanzadas (generators, migrations)

Usa Turborepo si:

Monorepo pequeño/mediano (< 10 proyectos)
Stack homogéneo (ej: solo Next.js)
Equipo pequeño (< 10 devs)
Valoras simplicidad sobre features
Usas Vercel para deploy

Ejemplo Práctico: Shared Components Library

// packages/ui/src/Button.tsx
import React from 'react';

export interface ButtonProps {
  variant?: 'primary' | 'secondary';
  children: React.ReactNode;
  onClick?: () => void;
}

export function Button({ variant = 'primary', children, onClick }: ButtonProps) {
  return (
    <button
      className={`btn btn-${variant}`}
      onClick={onClick}
    >
      {children}
    </button>
  );
}

// apps/web/pages/index.tsx
import { Button } from '@my-monorepo/ui';

export default function Home() {
  return (
    <div>
      <h1>Mi App</h1>
      <Button variant="primary">Click Me</Button>
    </div>
  );
}

// apps/admin/pages/dashboard.tsx
import { Button } from '@my-monorepo/ui';

export default function Dashboard() {
  return (
    <div>
      <h1>Admin Dashboard</h1>
      <Button variant="secondary">Settings</Button>
    </div>
  );
}

// Cambios en packages/ui afectan AMBAS apps
// Nx/Turborepo rebuildan automáticamente

CI/CD Optimizado para Monorepos

# .github/workflows/ci.yml (Nx)
name: CI

on: [push]

jobs:
  main:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0 # Importante para affected

      - uses: actions/setup-node@v3

      - run: npm ci

      # Corre SOLO tests afectados
      - run: npx nx affected:test --base=origin/main

      # Build solo apps modificadas
      - run: npx nx affected:build --base=origin/main

      # Deploy condicional
      - run: npx nx affected --target=deploy --base=origin/main

# .github/workflows/ci.yml (Turborepo)
name: CI

on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - uses: actions/setup-node@v3

      - run: npm ci

      # Cache remoto Vercel
      - run: npx turbo run test --token=${{ secrets.TURBO_TOKEN }}

      - run: npx turbo run build --token=${{ secrets.TURBO_TOKEN }}

Trampas Comunes

1. Dependencias Fantasmas

App funciona localmente pero quiebra en producción porque dependía de lib no declarada.

Solución: Usa --strict mode en Nx, o externals en Turborepo.

2. Builds Lentos Inicialmente

Primera build puede ser MUY lenta.

Solución: Configura cache remoto (Nx Cloud o Turborepo Remote Cache).

3. Conflictos de Versión

Múltiples apps necesitan versiones diferentes de React.

Solución: Usa resolutions (Yarn) o overrides (npm) cuidadosamente.

El Futuro de los Monorepos

Rust-based tools (como Turbopack) trayendo rendimiento 10x superior
AI-powered refactoring que entiende dependencias complejas
Distributed execution nativo (builds en múltiples máquinas)

Monorepos no son para todos los proyectos, pero para equipos que gestionan múltiples apps relacionadas, son game changer. Elige Nx para poder máximo, Turborepo para simplicidad máxima.

Si quieres entender patrones que ayudan en cualquier proyecto, grande o pequeño, ve: Atajos para Operaciones Condicionales donde exploramos código limpio y eficiente.

¡Vamos a por ello! 🦅

💻 Domina JavaScript de Verdad

El conocimiento que adquiriste en este artículo es solo el comienzo. Hay técnicas, patrones y prácticas que transforman desarrolladores principiantes en profesionales solicitados.

Invierte en Tu Futuro

Preparé un material completo para que domines JavaScript:

Formas de pago:

$9.90 USD (pago único)

📖 Ver Contenido Completo