30. Monorepos con Nx

30.1 Qué vas a poder hacer al terminar

30.2 Qué es un monorepo y qué problema resuelve

Un monorepo (repositorio único) es un repositorio de control de versiones que contiene varios proyectos —aplicaciones, librerías, herramientas— que se desarrollan juntos, con un historial compartido y, normalmente, un pipeline único que entiende las dependencias entre ellos. Un polyrepo (o multirepo) es la estrategia contraria: un repositorio por aplicación o por equipo.

La definición importa porque mucha gente llama «monorepo» a meter dos carpetas en el mismo Git sin herramientas. Eso es un monorepo en bruto: funciona hasta que alguien cambia un tipo compartido y rompe tres aplicaciones sin enterarse. Un monorepo serio añade límites explícitos, grafo de dependencias, ejecución selectiva (affected) y, idealmente, caché reproducible.

30.2.1 El problema que el polyrepo no escala bien

Imagina TaskFlow partido en tres repos: taskflow-api, taskflow-web y taskflow-shared. Quieres añadir el campo prioridad a una tarea. El flujo real acaba siendo:

1. Cambias el DTO en taskflow-shared, subes versión (semver), publicas el paquete.
2. Actualizas la API para consumir la nueva versión, despliegas.
3. Actualizas el frontend, que a menudo se queda una o dos versiones atrás «porque el PR es otro».
4. Durante días conviven tres versiones del mismo contrato. Los bugs de desajuste aparecen en producción, no en CI.

Eso no es un fallo de disciplina: es el coste estructural de versionar contratos internos como si fueran APIs públicas. El monorepo elimina ese baile: un solo commit puede tocar DTO, controlador Nest y servicio Angular. El CI valida el conjunto. El atomic commit es la propiedad más valiosa.

30.2.2 Historia breve

La lección histórica es simple: el monorepo no es una moda estética. Es una respuesta a un coste de coordinación que crece con el número de límites artificiales entre código que, en realidad, cambia junto.

30.2.3 Cuándo sí y cuándo no

  POLYREPO                         MONOREPO (TaskFlow)

  ┌────────────┐                   ┌──────────────────────────────┐
  │ web.git    │──npm pkg──┐       │  apps/web   apps/api         │
  └────────────┘           │       │  libs/shared/dto             │
  ┌────────────┐           ▼       │  libs/shared/types           │
  │ shared.git │──────► registry   │  libs/data-access/...        │
  └────────────┘           ▲       │                              │
  ┌────────────┐           │       │  un commit = cambio atómico  │
  │ api.git    │──npm pkg──┘       │  CI conoce el grafo          │
  └────────────┘                   └──────────────────────────────┘

30.3 Nx: instalación, workspace, apps vs libs, tags y boundaries

Nx es un sistema de build para monorepos JavaScript/TypeScript (y más allá). No sustituye a npm/pnpm/yarn como instalador de paquetes: se apoya en ellos. Su valor está en conocer el grafo de proyectos, generar estructura con plugins, ejecutar tareas (build, test, lint, serve) de forma inteligente y cachear resultados.

30.3.1 Instalación y creación del workspace

La forma recomendada hoy es crear el workspace con el CLI oficial. Elige el package manager que ya uses en el equipo; en este libro preferimos pnpm por su eficiencia de disco y sus workspaces nativos, pero npm y yarn son perfectamente válidos.

# Crear un workspace integrado orientado a aplicaciones
npx create-nx-workspace@latest taskflow --preset=apps

# Alternativa: workspace vacío para ir añadiendo plugins
# npx create-nx-workspace@latest taskflow --preset=ts

cd taskflow
# Añadir soporte Angular y Nest (plugins oficiales)
pnpm add -D @nx/angular @nx/nest @nx/js @nx/node

Tras la creación tendrás, como mínimo, un nx.json (configuración global: caché, named inputs, target defaults), un package.json raíz y una estructura de proyectos. La CLI nx (o pnpm exec nx) es el punto de entrada de casi todo.

npx nx graph                 # abre el grafo interactivo
npx nx show projects         # lista proyectos
npx nx show project api      # detalle de un proyecto
npx nx run api:build         # ejecuta el target build de api
npx nx run-many -t test      # tests de todos los proyectos
npx nx affected -t lint,test,build

30.3.2 Apps frente a libs

En la jerga de Nx (y de Angular desde hace años):

• App: artefacto desplegable. Tiene punto de entrada, se construye hacia un binario o bundle, se sirve o se ejecuta. Ejemplos TaskFlow: apps/web (Angular), apps/api (NestJS), quizá apps/api-e2e.
• Lib: código reutilizable sin ciclo de vida de despliegue propio. Se importa desde apps u otras libs. Ejemplos: libs/shared/dto, libs/web/ui, libs/api/data-access-tasks.

La regla de oro: las apps orquestan; las libs encapsulan. Si una app importa otra app, has roto el modelo. Si una lib «hace de casi-app» (arranca servidor, lee variables de entorno de producción), también.

  ┌─────────────────────────────────────────────────────────┐
  │                        APPS                             │
  │   apps/web (Angular)          apps/api (NestJS)         │
  └──────────────┬──────────────────────────┬───────────────┘
                 │ importan                 │
                 ▼                          ▼
  ┌──────────────────────┐     ┌────────────────────────────┐
  │ libs/web/*           │     │ libs/api/*                 │
  │  ui, feature-*,      │     │  feature-*, data-access-*, │
  │  data-access-*       │     │  util-*                    │
  └──────────┬───────────┘     └─────────────┬──────────────┘
             │                               │
             └──────────────┬────────────────┘
                            ▼
               ┌─────────────────────────┐
               │ libs/shared/*           │
               │  types, dto, util       │
               │  (sin Angular ni Nest)  │
               └─────────────────────────┘

30.3.3 Tags y module boundaries

Los tags son etiquetas declarativas en cada proyecto (scope:web, scope:api, scope:shared, type:feature, type:ui, type:data-access, type:util). Por sí solos no hacen nada. Cobran sentido con la regla de ESLint @nx/enforce-module-boundaries, que define qué tag puede depender de qué otro.

{
  "name": "shared-dto",
  "tags": ["scope:shared", "type:util"],
  "targets": {
    "lint": { "executor": "@nx/eslint:lint" }
  }
}

// Fragmento conceptual de la regla @nx/enforce-module-boundaries
{
  files: ['**/*.ts'],
  rules: {
    '@nx/enforce-module-boundaries': [
      'error',
      {
        allow: [],
        depConstraints: [
          {
            sourceTag: 'scope:web',
            onlyDependOnLibsWithTags: ['scope:web', 'scope:shared'],
          },
          {
            sourceTag: 'scope:api',
            onlyDependOnLibsWithTags: ['scope:api', 'scope:shared'],
          },
          {
            sourceTag: 'scope:shared',
            onlyDependOnLibsWithTags: ['scope:shared'],
          },
          {
            sourceTag: 'type:feature',
            onlyDependOnLibsWithTags: [
              'type:feature',
              'type:ui',
              'type:data-access',
              'type:util',
            ],
          },
          {
            sourceTag: 'type:ui',
            onlyDependOnLibsWithTags: ['type:ui', 'type:util'],
          },
          {
            sourceTag: 'type:data-access',
            onlyDependOnLibsWithTags: ['type:data-access', 'type:util'],
          },
        ],
      },
    ],
  },
}

// El frontend importa código Nest / MikroORM del backend
import { Task } from '@taskflow/api/data-access-tasks';
import { EntityManager } from '@mikro-orm/core';

export class TasksBrowserService {
  // Esto acopla el bundle del navegador al ORM del servidor
}

// Solo DTOs/tipos compartidos + cliente HTTP propio
import { CreateTaskDto, TaskDto } from '@taskflow/shared/dto';
import { Injectable, inject } from '@angular/core';
import { HttpClient } from '@angular/common/http';
import { Observable } from 'rxjs';

@Injectable({ providedIn: 'root' })
export class TasksApi {
  private readonly http = inject(HttpClient);

  create(dto: CreateTaskDto): Observable<TaskDto> {
    return this.http.post<TaskDto>('/api/tasks', dto);
  }
}

30.4 Generators y executors; project.json / package-based vs integrated

Nx separa dos conceptos que en otros sistemas se mezclan:

• Generator: código que escribe ficheros (scaffolding). Ejemplo: crear una lib Angular, un módulo Nest, un componente. Se ejecuta con nx g ....
• Executor: código que ejecuta una tarea (build, test, serve, lint). Se declara en los targets de cada proyecto y se invoca con nx run proyecto:target.

Esta separación es poderosa: puedes cambiar el executor de build (esbuild, webpack, vite, swc) sin cambiar cómo generas librerías, y puedes escribir generators propios que respeten las convenciones de TaskFlow.

30.4.1 Generators en la práctica

# Aplicación Angular
npx nx g @nx/angular:application web --directory=apps/web --routing --style=scss

# Aplicación NestJS
npx nx g @nx/nest:application api --directory=apps/api

# Librería de DTOs compartidos (JS/TS puro)
npx nx g @nx/js:library shared-dto --directory=libs/shared/dto --importPath=@taskflow/shared/dto

# Librería de UI Angular
npx nx g @nx/angular:library web-ui --directory=libs/web/ui --importPath=@taskflow/web/ui

# Librería data-access Nest (módulo Nest importable)
npx nx g @nx/nest:library api-data-access-tasks \
  --directory=libs/api/data-access-tasks \
  --importPath=@taskflow/api/data-access-tasks

El flag importPath define el alias TypeScript (paths en tsconfig.base.json). Usa siempre un scope de organización (@taskflow/...) para que las importaciones lean como paquetes reales, no como rutas relativas de diecisiete niveles.

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@taskflow/shared/dto": ["libs/shared/dto/src/index.ts"],
      "@taskflow/shared/types": ["libs/shared/types/src/index.ts"],
      "@taskflow/web/ui": ["libs/web/ui/src/index.ts"],
      "@taskflow/web/data-access-tasks": ["libs/web/data-access-tasks/src/index.ts"],
      "@taskflow/api/data-access-tasks": ["libs/api/data-access-tasks/src/index.ts"]
    }
  }
}

30.4.2 Executors y project.json

En un workspace integrated, cada proyecto declara sus targets en project.json (o en el package.json con inferencia, según versión y plugins). Un target tipico:

{
  "name": "api",
  "tags": ["scope:api", "type:app"],
  "targets": {
    "build": {
      "executor": "@nx/js:tsc",
      "outputs": ["{options.outputPath}"],
      "options": {
        "outputPath": "dist/apps/api",
        "main": "apps/api/src/main.ts",
        "tsConfig": "apps/api/tsconfig.app.json"
      }
    },
    "serve": {
      "executor": "@nx/js:node",
      "options": {
        "buildTarget": "api:build",
        "watch": true
      }
    },
    "test": {
      "executor": "@nx/jest:jest",
      "options": {
        "jestConfig": "apps/api/jest.config.ts"
      }
    }
  }
}

Los outputs son críticos para la caché: Nx necesita saber qué carpetas/ficheros produce un target para reutilizarlos. Si omites outputs, la caché no restaura artefactos aunque el cálculo de hash diga «hit».

30.4.3 Package-based frente a integrated

Para este libro recomendamos integrated en TaskFlow: los plugins de Angular y Nest ahorran semanas de configuración webpack/vite/Jest y alinean targets. Si tu monorepo es sobre todo paquetes publicados a npm sin apps Angular, package-based puede ser más honesto.

{
  "namedInputs": {
    "default": ["{projectRoot}/**/*", "sharedGlobals"],
    "production": [
      "default",
      "!{projectRoot}/**/?(*.)+(spec|test).[jt]s?(x)?(.snap)",
      "!{projectRoot}/tsconfig.spec.json",
      "!{projectRoot}/jest.config.[jt]s"
    ],
    "sharedGlobals": ["{workspaceRoot}/tsconfig.base.json"]
  },
  "targetDefaults": {
    "build": {
      "dependsOn": ["^build"],
      "inputs": ["production", "^production"],
      "cache": true
    },
    "test": {
      "inputs": ["default", "^production"],
      "cache": true
    },
    "lint": {
      "cache": true
    }
  }
}

dependsOn: ["^build"] significa: antes de construir este proyecto, construye las dependencias del grafo. Es lo que evita que web compile contra una lib desactualizada en disco.

30.4.4 Generators propios: codificar el estándar del equipo

Cuando el equipo supera las tres personas, el problema deja de ser «saber usar Nx» y pasa a ser «hacer siempre lo mismo». Si cada feature Angular se crea a mano, acabas con cuatro estilos de carpeta, tags a medias y un index.ts que exporta el mundo. Un generator propio (o un wrapper documentado sobre los generators oficiales) es la forma de convertir la convención en código.

Un generator mínimo para TaskFlow debería: crear la lib bajo libs/web/feature-*, asignar tags scope:web y type:feature, generar un fichero de rutas exportado, un componente contenedor y un stub de test, y registrar el importPath en tsconfig.base.json. No necesita ser sofisticado el primer día: necesita ser la única forma aceptable de crear features. El coste de mantener el generator se amortiza en el primer mes.

En entrevistas y en auditorías de arquitectura, una señal de madurez del monorepo es precisamente esa: no solo hay carpetas bonitas, hay un camino automatizado que hace difícil hacerlo mal. Nx brilla aquí porque el mismo ecosistema que ejecuta builds también ejecuta scaffolding; no dependes de un script bash frágil copiado en un wiki.

30.5 Grafo de dependencias, affected commands, caché local y remota

El project graph es el mapa de quién importa a quién. Nx lo calcula analizando package.json, imports TypeScript y configuración de proyectos. Sin grafo fiable, ni affected ni la caché merecen confianza.

npx nx graph
npx nx graph --file=graph.json   # exportar para CI o auditorías
npx nx show project web --web    # detalle de un proyecto

  Cambio en libs/shared/dto
           │
           ▼
     ┌─────────────┐
     │ shared-dto  │  ← affected directamente
     └──────┬──────┘
            │ lo consumen
     ┌──────┴───────┐
     ▼              ▼
 ┌─────────┐   ┌─────────┐
 │ web     │   │ api     │  ← affected transitivamente
 │ (build, │   │ (build, │
 │  test)  │   │  test)  │
 └─────────┘   └─────────┘
     libs/web/ui NO affected si no depende de dto

30.5.1 Comandos affected

nx affected compara el grafo con un rango de commits (por defecto, contra la base de la rama) y ejecuta targets solo en los proyectos tocados o que dependen de lo tocado.

# Contra main (local)
npx nx affected -t lint,test,build --base=main --head=HEAD

# En GitHub Actions suele usarse la base del PR
npx nx affected -t lint,test,build \
  --base=origin/main \
  --head=HEAD \
  --parallel=3

30.5.2 Caché local y remota

Cuando un target es cacheable, Nx calcula un hash a partir de: fuentes del proyecto (según inputs), fuentes de dependencias, runtime (versión de Node, variables listadas), flags del comando. Si el hash ya existe, restaura stdout/stderr y outputs sin reejecutar.

• Caché local: carpeta .nx/cache en la máquina. Acelera el ciclo del desarrollador y el re-run del mismo job en el mismo runner.
• Caché remota (Nx Cloud u otro remote cache compatible): comparte hashes entre máquinas y entre CI y desarrolladores. El primer build en CI beneficia a todos los demás.

{  "targets": {
    "build": {
      "executor": "@nx/js:tsc",
      "options": {
        "outputPath": "dist/apps/api",
        "main": "apps/api/src/main.ts",
        "tsConfig": "apps/api/tsconfig.app.json"
      }
    }
  }
}

{  "targets": {
    "build": {
      "executor": "@nx/js:tsc",
      "outputs": ["{options.outputPath}"],
      "options": {
        "outputPath": "dist/apps/api",
        "main": "apps/api/src/main.ts",
        "tsConfig": "apps/api/tsconfig.app.json"
      }
    }
  }
}

Sin outputs, un cache hit puede «tener éxito» y dejarte sin artefactos en dist/. El síntoma clásico: el job de Docker no encuentra la carpeta compilada aunque Nx diga que el build estaba cacheado.

{
  "targetDefaults": {
    "build": {
      "cache": true,
      "inputs": ["production", "^production", { "env": "NODE_ENV" }]
    }
  }
}

Incluye en inputs solo lo que realmente cambia el resultado. Meter {workspaceRoot}/**/* invalida la caché ante cualquier README tocado. Por eso existen namedInputs de producción que excluyen specs.

30.5.3 Determinismo: la caché solo es segura si el target lo es

La caché de Nx asume que, con los mismos inputs, obtienes el mismo resultado. Si tus tests leen la hora del sistema, escriben en una carpeta fuera de outputs, dependen del orden de un readdir o fallan uno de cada veinte, la caché se convierte en una máquina de falsos verdes o de misterios. Antes de activar remote cache en serio, haz una pasada de higiene:

• Tests sin reloj real: inyecta relojes o usa librerías de fake timers.
• Prohibido escribir en rutas absolutas del home del usuario dentro de un target cacheable.
• Semillas fijas en datos aleatorios de fixtures.
• Variables de entorno relevantes declaradas en inputs o normalizadas en CI (TZ=UTC, NODE_ENV=test).

Un truco de diagnóstico: ejecuta dos veces el mismo target con caché fría y caliente y compara no solo el exit code, sino el artefacto (hash de dist/). Si el hash del output cambia sin cambiar inputs, tienes no-determinismo. Encontrarlo pronto es más barato que perseguir un flaky en producción atribuido «a Nx».

En equipos que vienen de polyrepo, la primera reacción ante un cache hit sospechoso es desactivar la caché globalmente. Resiste esa tentación: desactívala solo en el target enfermo ("cache": false), corrige la causa, y vuelve a activarla. La caché es un multiplicador; el determinismo es el prerequisito.

30.6 Librerías compartidas: tipos, DTOs, UI, data-access

El diseño de libs es donde se gana o se pierde el monorepo. Una taxonomía clara evita el antipatrón «libs/shared/misc con 200 exports».

30.6.1 Taxonomía recomendada para TaskFlow

export const TASK_STATUSES = ['todo', 'doing', 'done', 'blocked'] as const;
export type TaskStatus = (typeof TASK_STATUSES)[number];

export const PRIORITIES = ['low', 'medium', 'high'] as const;
export type Priority = (typeof PRIORITIES)[number];

import { IsEnum, IsNotEmpty, IsOptional, IsString, MaxLength } from 'class-validator';
import { Priority, PRIORITIES, TaskStatus, TASK_STATUSES } from '@taskflow/shared/types';

export class CreateTaskDto {
  @IsString()
  @IsNotEmpty()
  @MaxLength(200)
  title!: string;

  @IsOptional()
  @IsString()
  @MaxLength(4000)
  description?: string;

  @IsEnum(TASK_STATUSES)
  status: TaskStatus = 'todo';

  @IsEnum(PRIORITIES)
  priority: Priority = 'medium';
}

export class TaskDto {
  id!: string;
  title!: string;
  description?: string;
  status!: TaskStatus;
  priority!: Priority;
  projectId!: string;
  createdAt!: string;
  updatedAt!: string;
}

import { Entity, PrimaryKey, Property, Enum } from '@mikro-orm/core';
import { Priority, TaskStatus } from '@taskflow/shared/types';
import { randomUUID } from 'crypto';

@Entity({ tableName: 'tasks' })
export class Task {
  @PrimaryKey({ type: 'uuid' })
  id: string = randomUUID();

  @Property({ length: 200 })
  title!: string;

  @Property({ type: 'text', nullable: true })
  description?: string;

  @Enum({ items: () => ['todo', 'doing', 'done', 'blocked'] })
  status: TaskStatus = 'todo';

  @Enum({ items: () => ['low', 'medium', 'high'] })
  priority: Priority = 'medium';

  @Property({ fieldName: 'project_id' })
  projectId!: string;

  @Property({ onCreate: () => new Date() })
  createdAt: Date = new Date();

  @Property({ onCreate: () => new Date(), onUpdate: () => new Date() })
  updatedAt: Date = new Date();
}

Observa la separación: la entidad conoce MikroORM; el DTO conoce class-validator; ambos comparten solo los tipos primitivos del dominio. El mapeo entidad↔DTO vive en el servicio de aplicación Nest, no en shared.

import { Injectable } from '@nestjs/common';
import { EntityManager } from '@mikro-orm/core';
import { CreateTaskDto, TaskDto } from '@taskflow/shared/dto';
import { Task } from './task.entity';

@Injectable()
export class TasksService {
  constructor(private readonly em: EntityManager) {}

  async create(dto: CreateTaskDto, projectId: string): Promise<TaskDto> {
    const task = this.em.create(Task, { ...dto, projectId });
    await this.em.persistAndFlush(task);
    return this.toDto(task);
  }

  private toDto(task: Task): TaskDto {
    return {
      id: task.id,
      title: task.title,
      description: task.description,
      status: task.status,
      priority: task.priority,
      projectId: task.projectId,
      createdAt: task.createdAt.toISOString(),
      updatedAt: task.updatedAt.toISOString(),
    };
  }
}

30.6.2 Reglas de importación (no circular, no app→app)

• Prohibido app → app. Si web necesita algo de api, ese algo debe bajar a una lib (normalmente shared dto/types, o un contrato OpenAPI generado).
• Prohibido ciclo lib A ↔ lib B. Extrae el trozo común a una tercera lib más baja (util o types).
• UI no importa data-access. El componente presentacional recibe inputs/outputs; la feature cablea el servicio.
• data-access web no importa data-access api. El navegador no debe ver entidades ORM.
• shared no importa scope web ni api.

// libs/web/feature-tasks importa data-access
// y data-access importa un helper de feature-tasks
import { taskListColumns } from '@taskflow/web/feature-tasks';
import { TasksApi } from '@taskflow/web/data-access-tasks';
// Ciclo: feature → data-access → feature

// Extraer columnas a libs/web/ui o libs/web/util-tasks
import { taskListColumns } from '@taskflow/web/ui';
import { TasksApi } from '@taskflow/web/data-access-tasks';
// feature-tasks importa ambos; nadie importa feature desde abajo

30.7 Angular + Nest en el mismo workspace: estructura TaskFlow

Esta es la estructura que recomendamos como punto de partida. No es dogma: es un mapa que escala hasta varios dominios sin obligarte a microfrontends.

taskflow/
├── apps/
│   ├── web/                 # Angular (shell + rutas)
│   ├── web-e2e/             # Playwright/Cypress
│   ├── api/                 # NestJS (main, AppModule)
│   └── api-e2e/
├── libs/
│   ├── shared/
│   │   ├── types/           # enums y tipos de dominio
│   │   ├── dto/             # contratos HTTP + class-validator
│   │   └── util/            # helpers puros (fechas, ids…)
│   ├── web/
│   │   ├── ui/              # design system ligero
│   │   ├── util-*/          # pipes, guards Angular reutilizables
│   │   ├── data-access-*/   # HttpClient + estado remoto
│   │   └── feature-*/       # rutas smart (listado, detalle…)
│   └── api/
│       ├── util-*/          # filtros, pipes Nest transversales
│       ├── data-access-*/   # entidades MikroORM + servicios
│       └── feature-*/       # módulos de dominio (TasksModule…)
├── tools/                   # scripts, generators propios
├── nx.json
├── tsconfig.base.json
└── package.json

30.7.1 Apps delgadas

La app Nest debería limitarse a arranque, configuración y composición de módulos. La lógica vive en libs.

import { Module } from '@nestjs/common';
import { MikroOrmModule } from '@mikro-orm/nestjs';
import { TasksFeatureModule } from '@taskflow/api/feature-tasks';
import { ProjectsFeatureModule } from '@taskflow/api/feature-projects';
import mikroOrmConfig from './mikro-orm.config';

@Module({
  imports: [
    MikroOrmModule.forRoot(mikroOrmConfig),
    TasksFeatureModule,
    ProjectsFeatureModule,
  ],
})
export class AppModule {}

import { Routes } from '@angular/router';

export const appRoutes: Routes = [
  {
    path: 'tasks',
    loadChildren: () =>
      import('@taskflow/web/feature-task-list').then((m) => m.TASK_LIST_ROUTES),
  },
  {
    path: 'projects',
    loadChildren: () =>
      import('@taskflow/web/feature-projects').then((m) => m.PROJECT_ROUTES),
  },
  { path: '', pathMatch: 'full', redirectTo: 'tasks' },
];

El lazy loading por feature lib permite que el grafo de Nx y el code-splitting de Angular cuenten la misma historia: una feature es una unidad de ownership, de test y de carga diferida.

30.7.2 Desarrollo local: un comando, dos procesos

En local conviene levantar API y web con un target compuesto, y un proxy en el dev-server de Angular hacia Nest para evitar CORS durante el desarrollo.

{
  "/api": {
    "target": "http://localhost:3000",
    "secure": false,
    "changeOrigin": true
  }
}

{
  "scripts": {
    "web": "nx serve web",
    "api": "nx serve api",
    "dev": "nx run-many -t serve -p api,web --parallel=2",
    "affected": "nx affected -t lint,test,build"
  }
}

30.7.3 Ownership, CODEOWNERS y ritmo de PRs

El monorepo concentra el tráfico de pull requests. Sin reglas, libs/shared/dto se convierte en el pasillo donde todo el mundo deja mudanzas. Define ownership explícito:

/apps/web/                       @taskflow/frontend
/apps/api/                       @taskflow/backend
/libs/web/                       @taskflow/frontend
/libs/api/                       @taskflow/backend
/libs/shared/                    @taskflow/platform
/nx.json                         @taskflow/platform
/tsconfig.base.json              @taskflow/platform
/.github/workflows/              @taskflow/platform

El equipo platform (aunque sean dos personas a media jornada) cuida tooling, boundaries y shared. Un cambio de DTO exige revisión de platform + del lado consumidor. Parece fricción; en realidad es el sustituto del versionado semver entre repos. Si shared cambia sin revisión, el monorepo solo acelera la propagación de errores.

Sobre el ritmo: prefiere PRs pequeños que toquen una vertical (feature + dto + test) frente a PRs «limpieza general» de veinte libs. Affected y los revisores humanos agradecen lo mismo. Si necesitas un refactor transversal (renombrar un enum), sepáralo de features nuevas y comunícalo: es el equivalente monorepo a un major bump.

30.7.4 Estrategia de tests en el monorepo

No todos los tests deben correr en todos los PRs. Una estratificación sana para TaskFlow:

• Unitarios por lib (Jest/Vitest): rápidos, cacheables, affected fino. Son la red principal.
• Tests de módulo Nest en libs data-access/feature: suben confianza sin levantar el browser.
• Tests de componente Angular en ui/feature: acotados; evita TestBed gigantes por PR.
• e2e (web-e2e): solo si affected incluye web o api (o en nightly). Caros y frágiles; no son el primer filtro.
• Contract smoke: un job que levanta api y valida OpenAPI/DTO básicos cuando cambia shared o api.

El error clásico es trasladar al monorepo la costumbre polyrepo de «la CI de mi repo corre mis e2e siempre». Multiplicado por N apps, el pipeline muere. Affected no es opcional a escala: es la única forma de mantener la promesa de feedback en minutos.

// En Angular: importar un servicio Nest por path relativo
import { TasksService } from
  '../../../api/src/app/tasks/tasks.service';

import { TaskDto } from '@taskflow/shared/dto';
// Cada lado implementa su adaptador:
// Nest: TasksService + controlador
// Angular: TasksApi (HttpClient)

30.8 Module Federation / microfrontends con Nx

Nx ofrece soporte de primera clase para Module Federation (webpack y, en evolución, variantes con esbuild/rsbuild según versión del plugin). Permite que varias aplicaciones Angular se carguen en runtime como remotos de un shell (host).

30.8.1 Cuándo sí

• Varios equipos despliegan independientemente partes del frontend con calendarios distintos.
• El tamaño del bundle monolítico ya es un problema medido (no supuesto) y el lazy loading por rutas no basta porque los equipos necesitan pipelines separados.
• Hay un shell estable y remotos con contratos de versión explícitos.

30.8.2 Cuándo no

• TaskFlow con un solo equipo o dos personas: Module Federation añade versionado runtime, duplicación de dependencias compartidas y depuración más dura.
• Solo quieres compartir componentes: usa libs, no microfrontends.
• Solo quieres code-splitting: loadChildren en el router basta.

// En el shell (host): cargar un remoto en runtime
export const appRoutes: Routes = [
  {
    path: 'admin',
    loadChildren: () =>
      import('admin/Routes').then((m) => m.remoteRoutes),
  },
];

// El nombre 'admin/Routes' lo resuelve Module Federation,
// no el bundler como un path TypeScript normal.

  SIN MF (recomendado TaskFlow inicial)     CON MF (equipos/deploy independientes)

  ┌────────────────────┐                    ┌──────────┐
  │ apps/web (único)   │                    │  host    │
  │  feature-tasks     │                    └────┬─────┘
  │  feature-projects  │                         │ carga runtime
  │  libs/web/*        │                    ┌────┴─────┬──────────┐
  └────────────────────┘                    ▼          ▼          ▼
                                       remoto      remoto     remoto
                                       tasks       projects   admin

Si más adelante TaskFlow crece a un módulo de administración desplegado por otro equipo, entonces evalúa MF. Hasta entonces, libs + lazy routes.

Un criterio de decisión práctico: escribe en una frase quién despliega qué y con qué frecuencia. Si la respuesta es «el mismo equipo, el mismo pipeline, la misma versión de Angular», Module Federation no te está comprando independencia real; solo te vende la ilusión. Si la respuesta es «el equipo de Admin despliega los jueves sin coordinar con Core, y aceptan versionar el contrato del shell», entonces el coste de MF (shared dependencies, debugging cross-app, contratos de semver en runtime) puede merecer la pena. Documenta ese contrato igual que documentarías una API HTTP: qué exporta el remoto, qué versiones del shell soporta y cómo se hace rollback si el remoto rompe el host.

En la práctica, muchos equipos llegan a MF demasiado pronto porque han leído que «microfrontends escalan organizaciones». La organización escala primero con libs, ownership y CI affected. MF es el último escalón, no el primero.

30.9 CI: affected, parallel, caching en GitHub Actions

El capítulo 21 cubrió pipelines genéricos. Aquí el matiz es Nx: el CI debe dejar de construir el mundo entero en cada push.

name: CI
on:
  pull_request:
    branches: [main]
  push:
    branches: [main]

concurrency:
  group: ci-${{ github.ref }}
  cancel-in-progress: true

jobs:
  main:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: pnpm/action-setup@v4
        with:
          version: 9

      - uses: actions/setup-node@v4
        with:
          node-version: '22'
          cache: 'pnpm'

      - run: pnpm install --frozen-lockfile

      - name: Derivar base de affected
        id: base
        run: |
          if [ "${{ github.event_name }}" = "pull_request" ]; then
            echo "base=origin/${{ github.base_ref }}" >> "$GITHUB_OUTPUT"
          else
            echo "base=HEAD~1" >> "$GITHUB_OUTPUT"
          fi

      - name: Lint, test y build afectados
        run: |
          pnpm exec nx affected -t lint,test,build \
            --base=${{ steps.base.outputs.base }} \
            --head=HEAD \
            --parallel=3 \
            --configuration=ci

Puntos críticos del workflow:

• fetch-depth: 0: affected necesita historia Git para comparar. Un checkout superficial rompe el cálculo de la base.
• Base distinta en PR y en push a main: en PR, el branch destino; en push, el commit anterior (o el último tag verde, según política).
• --parallel: aprovecha CPU del runner; ajústalo al tamaño de la máquina (3–4 en runners estándar).
• Caché de pnpm + caché de Nx: son capas distintas. La primera evita descargar node_modules; la segunda evita reejecutar builds/tests.

- name: Restaurar caché Nx
  uses: actions/cache@v4
  with:
    path: .nx/cache
    key: nx-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}-${{ github.sha }}
    restore-keys: |
      nx-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}-
      nx-${{ runner.os }}-

# Alternativa más potente: Nx Cloud (remote cache distribuida)
# NX_CLOUD_ACCESS_TOKEN en secretos del repositorio

# Lista proyectos affected y decide
pnpm exec nx show projects --affected --base=origin/main --head=HEAD | tee affected.txt
if grep -qE '^(web|web-e2e)$' affected.txt; then
  pnpm exec nx run web-e2e:e2e
fi

- uses: actions/checkout@v4
  # fetch-depth por defecto = 1
- run: npx nx affected -t test --base=main
  # sin origin/main fetch → base incorrecta

- uses: actions/checkout@v4
  with:
    fetch-depth: 0
- run: git fetch origin main:main
- run: pnpm exec nx affected -t test --base=main --head=HEAD

30.10 Versionado y publicación de libs

En TaskFlow, la mayoría de las libs no se publican a un registro npm: se consumen por path aliases dentro del workspace. Publicar solo tiene sentido cuando:

• Otro repositorio (cliente externo, app móvil, partner) debe consumir DTOs o SDK.
• Extraes un design system verdaderamente reutilizable fuera del producto.

Si publicas, trata esas libs como producto: semver, changelog, y no rompas consumidores con cambios silenciosos en el barrel.

# Independent versioning con cambios detectados por Conventional Commits
# (herramientas habituales: Nx Release, changesets, semantic-release)

pnpm exec nx release plan          # o el flujo de tu herramienta
pnpm exec nx release               # bump + changelog + publish

# Solo paquetes marcados como publishable
# package.json de la lib: "publishConfig": { "access": "restricted" }

{
  "name": "@taskflow/shared-dto",
  "version": "0.0.1",
  "type": "commonjs",
  "main": "./index.js",
  "types": "./index.d.ts",
  "publishConfig": {
    "access": "restricted",
    "registry": "https://npm.pkg.github.com"
  }
}

Para releases de las apps (web, api), el artefacto es la imagen Docker o el bundle estático (capítulo 21), no un paquete npm. El monorepo puede etiquetar el repo entero (taskflow-web@1.4.0) o usar un solo calendario de producto: elige una convención y no mezcles las dos sin documentarlo.

30.11 Alternativas: Turborepo, pnpm workspaces, Yarn — comparación honesta

Nx no es la única forma de operar un monorepo. Elegir herramienta es elegir qué problemas quieres que resuelva el framework y cuáles asumes tú.

packages:
  - 'apps/*'
  - 'libs/*'
  - 'libs/shared/*'

{
  "$schema": "https://turbo.build/schema.json",
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**"]
    },
    "test": {
      "dependsOn": ["build"],
      "outputs": ["coverage/**"]
    },
    "lint": {}
  }
}

Con Turborepo + pnpm consigues caché y orden de tasks. Lo que no consigues «de serie» es: generar un módulo Nest alineado, validar que scope:web no importa entidades ORM, ni un grafo visual del mismo nivel. Puedes añadir ESLint boundaries a mano, pero entonces estás reconstruyendo parte de Nx.

Una trampa frecuente es adoptar Nx y seguir trabajando como si fuera un polyrepo: cada equipo solo mira «su» app, nadie mantiene shared, y el grafo se pudre con dependencias fantasma. La herramienta no impone la cultura; como mucho la hace visible. Programa una revisión trimestral del grafo (nx graph), del número de ciclos detectados, del tiempo medio de CI y del porcentaje de cache hits. Esas cuatro métricas te dicen si el monorepo está sano mejor que cualquier debate abstracto sobre «si Nx merece la pena».

pnpm --filter @taskflow/api test
pnpm --filter "./libs/shared/**" lint
pnpm --filter "...@taskflow/web" build   # web + dependencias

30.12 Errores comunes y cómo solucionarlos

export * from './api/task.entity';
export * from './web/task-card.component';
export * from './dto/create-task.dto';
// Un solo barrel mezcla ORM, Angular y DTOs

// @taskflow/shared/dto
export * from './lib/create-task.dto';
// @taskflow/api/data-access-tasks
export * from './lib/task.entity';
// @taskflow/web/ui
export * from './lib/task-card.component';

{  "name": "@taskflow/web/ui",
  "dependencies": {
    "@angular/core": "19.0.0",
    "rxjs": "7.8.1"
  }
}

{  "name": "@taskflow/web/ui",
  "peerDependencies": {
    "@angular/core": "^19.0.0",
    "rxjs": "^7.8.0"
  }
}

30.13 Buenas y malas prácticas

30.14 Preguntas frecuentes

30.15 Ejercicios

depConstraints: [
  {
    sourceTag: 'scope:web',
    onlyDependOnLibsWithTags: ['scope:web', 'scope:shared'],
  },
  {
    sourceTag: 'scope:api',
    onlyDependOnLibsWithTags: ['scope:api', 'scope:shared'],
  },
  {
    sourceTag: 'scope:shared',
    onlyDependOnLibsWithTags: ['scope:shared'],
  },
]

- uses: actions/checkout@v4
  with:
    fetch-depth: 0
- uses: pnpm/action-setup@v4
  with:
    version: 9
- uses: actions/setup-node@v4
  with:
    node-version: '22'
    cache: 'pnpm'
- run: pnpm install --frozen-lockfile
- name: affected
  run: |
    BASE="origin/${{ github.base_ref }}"
    if [ "${{ github.event_name }}" = "push" ]; then BASE="HEAD~1"; fi
    pnpm exec nx affected -t lint,test,build --base="$BASE" --head=HEAD --parallel=3

// libs/api/data-access-tasks/src/lib/tasks.module.ts
import { Module } from '@nestjs/common';
import { MikroOrmModule } from '@mikro-orm/nestjs';
import { Task } from './task.entity';
import { TasksService } from './tasks.service';

@Module({
  imports: [MikroOrmModule.forFeature([Task])],
  providers: [TasksService],
  exports: [TasksService, MikroOrmModule],
})
export class TasksDataAccessModule {}

// libs/api/feature-tasks/src/lib/tasks.controller.ts
import { Body, Controller, Post } from '@nestjs/common';
import { CreateTaskDto, TaskDto } from '@taskflow/shared/dto';
import { TasksService } from '@taskflow/api/data-access-tasks';

@Controller('tasks')
export class TasksController {
  constructor(private readonly tasks: TasksService) {}

  @Post()
  create(@Body() dto: CreateTaskDto): Promise<TaskDto> {
    return this.tasks.create(dto, dto.projectId ?? 'default');
  }
}

30.16 Resumen del capítulo

Evita dos antipatrones tempranos. El primero es la carpeta shared-everything donde acaba el código que nadie sabe dónde poner: en seis meses es un grafo circular con olor a aplicación disfrazada de librería. El segundo es copiar DTOs «por si acaso» en web y api «para no acoplar»: has recreado el polyrepo dentro del monorepo. La regla práctica: si el cambio debe ser atómico, es una lib compartida; si el ciclo de vida es independiente de verdad, es otro deployable (app) con contrato versionado.

Cuando el equipo crezca, documenta el mapa de tags en el README del workspace y añade un diagrama del project graph generado por nx graph en la wiki interna. Las reglas de boundary que no se entienden se desactivan; las que se enseñan en el onboarding se respetan. Nx no sustituye arquitectura: la hace verificable.

En entrevistas, explica el trade-off en una frase: «pagamos complejidad de tooling para ganar atomicidad de cambios y CI selectivo». Luego da un ejemplo con TaskFlow (shared DTO + affected). Si solo dices «usamos Nx porque está de moda», pierdes la pregunta. Si puedes dibujar el grafo apps/libs y decir qué tag impide que web-ui importe MikroORM, demuestras criterio de arquitectura frontend/backend en monorepo.

Relaciona este capítulo con Docker/CI (21), integración full-stack (18) y migraciones (31): un monorepo bien cacheado hace barato el tren de actualizaciones porque el coste de verificar el impacto está acotado. Un polyrepo sin versionado interno cuidadoso hace cada major update un proyecto de sincronización humana.

30.17 Recursos adicionales

• Nx · Getting Started — punto de entrada oficial al modelo de workspace.
• Nx · Enforce Module Boundaries — tags, constraints y deep imports.
• Nx · Affected — cálculo de proyectos afectados y uso en CI.
• Nx · Remote Cache — caché distribuida y buenas prácticas de inputs/outputs.
• Nx · Angular plugin — generators y executors Angular.
• Nx · Nest plugin — applications y libraries NestJS.
• Nx · Integrated vs Package-based — cuándo elegir cada estilo de workspace.
• Nx · Module Federation recipes — host, remotes y microfrontends.
• Nx · Generators — scaffolding y generators personalizados.
• Nx · CI setup — plantillas y recomendaciones oficiales de pipeline.
• Turborepo docs — alternativa de orquestación ligera.
• pnpm workspaces — workspaces y filtros.