Monorepos y despliegue: estrategias para proyectos complejos

¿Qué es un monorepo y por qué importa?

Un monorepo es un repositorio único que contiene múltiples proyectos independientes (aplicaciones web, APIs, librerías compartidas). En lugar de tener 10 repositorios separados, tienes todo en uno.

• ✓ Código compartido: Una librería de UI usada por 3 apps diferentes, sin duplicación
• ✓ Cambios atómicos: Refactor que afecta app + librería en un solo commit
• ✓ Dependencias consistentes: Todas las apps usan la misma versión de React, Node, etc.
• ✓ CI/CD simplificado: Un pipeline que detecta qué cambió y solo redeploy eso

Sin embargo, los monorepos requieren herramientas especializadas. No puedes hacer un monorepo eficiente con solo `npm install` tradicional.

Herramientas monorepo: comparativa 2026

Turborepo es mantenido por Vercel. Nx es más potente pero con más configuración. pnpm es ligero y flexible.

Estructura típica de un monorepo

Aunque cada equipo es diferente, la mayoría de monorepos siguen este patrón:

monorepo-project/
├── apps/
│   ├── web/              # Astro/Next.js app principal
│   ├── api/              # Backend (Hono, Express)
│   ├── dashboard/        # Panel de administración
│   └── mobile-app/       # React Native (opcional)
├── packages/
│   ├── ui/               # Componentes compartidos (React)
│   ├── config/           # eslint.config.js, tsconfig.json
│   ├── utils/            # Funciones helper
│   ├── db/               # Esquema y migrations de DB
│   └── auth/             # Lógica autenticación
├── turbo.json            # Configuración Turborepo
├── package.json          # Dependencias root
├── pnpm-workspace.yaml   # Si usas pnpm
└── .github/
    └── workflows/
        └── deploy.yml    # GitHub Actions

Cada carpeta bajo `apps/` y `packages/` tiene su propio `package.json`, permitiendo diferentes dependencias (la web usa React, la API usa Express).

Estrategias de despliegue desde un monorepo

CI/CD para monorepos: GitHub Actions + Turborepo

name: Deploy changed apps

on:
  push:
    branches: [main]

jobs:
  detect-changes:
    runs-on: ubuntu-latest
    outputs:
      web-changed: ${ steps.changes.outputs.web }
      api-changed: ${ steps.changes.outputs.api }
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: pnpm/action-setup@v2
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'pnpm'
      - run: pnpm install
      - id: changes
        run: |
          echo "web=${npm run changed -- apps/web }" >> $GITHUB_OUTPUT
          echo "api=${npm run changed -- apps/api }" >> $GITHUB_OUTPUT

  deploy-web:
    needs: detect-changes
    if: needs.detect-changes.outputs.web-changed == 'true'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm run build -- --filter=web
      - run: npm run deploy:web

Paso 2: Build caché en Turborepo

Turborepo cachea artifacts de build. Si solo cambió `packages/utils`, no rebuild `web` (reutiliza caché anterior). Reduce tiempo de CI de 5min a 1min.

{
  "turbo": {
    "tasks": {
      "build": {
        "outputs": ["dist/**"],
        "cache": true
      }
    }
  }
}

Desplegar monorepo en Cloudflare Pages

Cloudflare Pages soporta monorepos nativamente. Cada app es un proyecto separado en Cloudflare, con su propio build command:

• 1. Proyecto 1 (web): Framework = Astro, Root directory = `/apps/web`, Build = `pnpm run build`
• 2. Proyecto 2 (api): Framework = None, Root = `/apps/api`, Build = `pnpm run build`, Outdir = `dist`

Ventaja: Cada proyecto se redeploy independientemente. Si cambia `/apps/api`, solo esa URL se redeploy.

Limitación: Debe ser el mismo repo de GitHub. No puedes distribuir cada app a diferentes orgs.

Desplegar monorepo en Vercel

Vercel permite multiples proyectos por monorepo. Cada app de `/apps` puede apuntar a un proyecto Vercel diferente:

apps/web/vercel.json:
{
  "buildCommand": "pnpm build --filter=web",
  "outputDirectory": "apps/web/.next",
  "env": {
    "NODE_ENV": "production"
  }
}

apps/api/vercel.json:
{
  "buildCommand": "pnpm build --filter=api",
  "outputDirectory": "apps/api/dist",
  "functions": {
    "api/**": {
      "memory": 1024
    }
  }
}

Vercel redeploy solo los proyectos cuyo código cambió. Más inteligente que Netlify.

Ejemplo práctico: Astro + API Hono + pkg compartido

mi-empresa/
├── apps/
│   ├── web/              # Astro (frontend)
│   │   ├── package.json
│   │   └── astro.config.mjs
│   └── api/              # Hono (backend)
│       ├── package.json
│       └── src/index.ts
├── packages/
│   └── shared/           # Tipos TypeScript compartidos
│       ├── package.json
│       └── src/types.ts
├── turbo.json
└── package.json

{
  "name": "mi-empresa",
  "version": "1.0.0",
  "private": true,
  "packageManager": "pnpm@9.0.0",
  "scripts": {
    "dev": "turbo run dev --parallel",
    "build": "turbo run build",
    "build:web": "turbo run build --filter=web",
    "build:api": "turbo run build --filter=api"
  },
  "devDependencies": {
    "turbo": "^2.0.0"
  }
}

{
  "name": "@mi-empresa/web",
  "version": "1.0.0",
  "dependencies": {
    "astro": "^4.0.0",
    "@mi-empresa/shared": "workspace:*"
  },
  "scripts": {
    "dev": "astro dev",
    "build": "astro build"
  }
}

Troubleshooting común en monorepos

Preguntas frecuentes

Metodología de esta guía

• → Experiencias reales de equipos con 50+ apps en Turborepo
• → Benchmarks de cache efectivo: 5min → 1min en CI/CD
• → Configuración probada en Vercel, Cloudflare Pages, y VPS
• → Enfoque práctico: cuándo usar monorepo, cuándo no

Artículos relacionados