Guía Turborepo Monorepo: Gestión de proyectos de aplicaciones múltiples

Los monorepos que contienen múltiples aplicaciones y paquetes compartidos son ahora la arquitectura estándar para las empresas que crean productos de software interconectados. Turborepo, adquirido por Vercel, proporciona la capa de orquestación de compilación que hace que los monorepos sean prácticos: maneja dependencias de tareas, almacenamiento en caché y ejecución paralela en docenas de paquetes.

Conclusiones clave

• El almacenamiento en caché remoto de Turborepo puede reducir los tiempos de compilación de CI entre un 80 y un 90 % en cambios incrementales
• Las canalizaciones de tareas garantizan que los paquetes se construyan automáticamente en el orden de dependencia correcto
• Los paquetes compartidos (tipos, validadores, utilidades) eliminan la duplicación de código entre aplicaciones.
• Los espacios de trabajo pnpm proporcionan administración de dependencias eficiente en disco para monorepos

---

Arquitectura Monorepo

Estructura del directorio

Un monorepo típico de Turborepo separa las aplicaciones de los paquetes compartidos:

my-monorepo/
  apps/
    api/           # NestJS backend
    web/           # Next.js frontend
    docs/          # Documentation site
    mobile/        # React Native app
  packages/
    db/            # Drizzle ORM schemas and migrations
    types/         # Shared TypeScript types
    validators/    # Zod validation schemas
    utils/         # Shared utility functions
    ui/            # Shared UI components
    config/        # Shared configuration (ESLint, TypeScript)
  turbo.json       # Turborepo configuration
  pnpm-workspace.yaml
  package.json     # Root package.json

Configuración del espacio de trabajo

Defina espacios de trabajo en pnpm-workspace.yaml:

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

Cada espacio de trabajo tiene su propio paquete.json con dependencias y scripts. Se hace referencia a los paquetes compartidos mediante el protocolo del espacio de trabajo:

{
  "dependencies": {
    "@myorg/types": "workspace:*",
    "@myorg/validators": "workspace:*",
    "@myorg/utils": "workspace:*"
  }
}

---

Configuración de Turborepo

Canalización de tareas

turbo.json define cómo se relacionan las tareas entre sí:

{
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", ".next/**"]
    },
    "dev": {
      "dependsOn": ["^build"],
      "cache": false,
      "persistent": true
    },
    "lint": {
      "dependsOn": ["^build"]
    },
    "test": {
      "dependsOn": ["build"]
    }
  }
}

Conceptos clave:

• depende de: ["^build"]: el símbolo de intercalación (^) significa "construir todas las dependencias primero". Al crear la aplicación web, Turborepo crea primero paquetes/tipos, paquetes/validadores y paquetes/utilidades.
• salidas: Archivos que Turborepo almacena en caché. En ejecuciones posteriores, si las entradas no han cambiado, Turborepo reproduce la salida almacenada en caché en lugar de reconstruirla.
• persistente: verdadero: para servidores de desarrollo que siguen ejecutándose.
• cache: false: deshabilita el almacenamiento en caché para tareas que siempre deben ejecutarse (como servidores de desarrollo).

---

Paquetes compartidos

Paquete de tipos

Centralice los tipos de TypeScript utilizados en todas las aplicaciones:

// packages/types/src/user.ts
export interface User {
  id: string;
  email: string;
  name: string;
  role: "admin" | "user" | "support";
  createdAt: Date;
}

export type CreateUserDTO = Omit<User, "id" | "createdAt">;
export type UpdateUserDTO = Partial<CreateUserDTO>;

Paquete de validadores

Esquemas Zod compartidos entre frontend y backend:

// packages/validators/src/user.ts
import { z } from "zod";

export const createUserSchema = z.object({
  email: z.string().email(),
  name: z.string().min(2).max(255),
  role: z.enum(["admin", "user", "support"]),
});

Configuración de compilación

Los paquetes compartidos deben estar prediseñados antes de que las aplicaciones puedan consumirlos. Configure cada paquete con un script de compilación que compila TypeScript en JavaScript:

{
  "scripts": {
    "build": "tsc --project tsconfig.json",
    "dev": "tsc --watch"
  }
}

---

Estrategia de almacenamiento en caché

Almacenamiento en caché local

Turborepo almacena en caché los resultados de las tareas en node_modules/.cache/turbo de forma predeterminada. Cuando ejecuta turbo build y nada ha cambiado, Turborepo reproduce la salida almacenada en caché en milisegundos.

Almacenamiento en caché remoto

Para CI/CD, habilite el almacenamiento en caché remoto para compartir artefactos de compilación entre los miembros del equipo y las ejecuciones de CI:

npx turbo login
npx turbo link

El almacenamiento en caché remoto significa que una compilación completada en una máquina de desarrollador o ejecución de CI está disponible para todos. El impacto es dramático: las compilaciones incrementales de CI caen de 10 minutos a menos de 1 minuto.

---

Flujo de trabajo de desarrollo

Ejecutando todas las aplicaciones

pnpm dev       # Starts all apps and watches all packages

Turborepo primero crea paquetes compartidos (porque el desarrollo depende de ^build) y luego inicia los servidores de desarrollo de aplicaciones en paralelo. Los cambios en los paquetes compartidos desencadenan reconstrucciones que se propagan a las aplicaciones consumidoras.

Ejecución de aplicaciones específicas

pnpm dev --filter=web     # Only the web app and its dependencies
pnpm dev --filter=api     # Only the API and its dependencies

El filtrado es esencial para monorepos grandes donde no es necesario iniciar todo.

---

Optimización de CI/CD

Detección de paquetes afectados

Turborepo determina qué paquetes cambiaron desde la última confirmación y solo ejecuta tareas para los paquetes afectados:

turbo build --filter=...[HEAD^1]

Esto ejecuta la compilación solo para los paquetes que cambiaron en la última confirmación y sus dependientes.

Ejecución paralela

Turborepo ejecuta tareas independientes en paralelo. Si los paquetes/tipos y los paquetes/utilidades no tienen una relación de dependencia, se construyen simultáneamente. El nivel de concurrencia se adapta a los núcleos de CPU disponibles.

---

Preguntas frecuentes

P: ¿Cuántos paquetes puede manejar un Turborepo monorepo?

Turborepo maneja monorepos con cientos de paquetes. El rendimiento aumenta bien porque el gráfico de tareas se analiza al inicio y el almacenamiento en caché significa que la mayoría de los paquetes omiten compilaciones en cambios incrementales.

P: ¿Deberíamos usar pnpm o npm para espacios de trabajo?

Se recomienda encarecidamente pnpm para monorepos. Su almacén direccionable por contenido deduplica las dependencias entre paquetes, lo que ahorra una cantidad significativa de espacio en disco y tiempo de instalación. Los espacios de trabajo pnpm también son más estrictos con respecto a la resolución de dependencias, detectando declaraciones de dependencia faltantes.

P: ¿Cómo manejamos las diferentes versiones de Node.js en todas las aplicaciones?

Utilice el campo de motores en cada paquete.json para especificar los requisitos de la versión de Node.js. Para diferencias en el tiempo de ejecución, configure CI para usar la versión adecuada por aplicación.

P: ¿Podemos adoptar Turborepo de forma incremental?

Sí. Agregue turbo.json a un proyecto de espacio de trabajo pnpm existente y configure canalizaciones de tareas. Los scripts existentes siguen funcionando. Obtiene almacenamiento en caché y orquestación de tareas inmediatamente sin reestructuración.

---

¿Qué sigue?

Turborepo transforma el desarrollo de monorepo de una carga de mantenimiento a un multiplicador de productividad. Comience con una estructura simple y crezca según lo requiera su proyecto.

Comuníquese con ECOSIRE para obtener consultoría sobre arquitectura monorepo, o explore nuestros servicios de integración de Odoo para arquitecturas ERP de múltiples aplicaciones.

---

Publicado por ECOSIRE: ayuda a las empresas a escalar con soluciones de software empresarial.