Workspaces y Monorepos

Los workspaces de npm enlazan paquetes internos en un solo repositorio para que el código compartido se envíe sin necesidad de publicarlo en un registro por cada cambio.

Receta

Tarjeta de receta de referencia rápida: lista para copiar y pegar.

{
  "name": "@acme/platform",
  "private": true,
  "workspaces": ["apps/*", "packages/*"],
  "scripts": {
    "build": "npm run build -w @acme/shared && npm run build -w @acme/api"
  }
}

// apps/api/package.json
{
  "name": "@acme/api",
  "dependencies": {
    "@acme/shared": "workspace:*"
  }
}

Cuándo usarlo:

• Múltiples servicios desplegables comparten tipos o utilidades de TypeScript.
• Quieres un solo archivo lockfile y un solo npm ci para toda la organización.
• Los paquetes internos cambian en el mismo PR que sus consumidores.

Ejemplo práctico

platform/
  package.json          # raíz de workspaces
  package-lock.json
  apps/
    api/
      package.json      # @acme/api
      src/server.ts
  packages/
    shared/
      package.json      # @acme/shared
      src/index.ts

// packages/shared/package.json
{
  "name": "@acme/shared",
  "version": "0.0.0",
  "type": "module",
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "scripts": {
    "build": "tsc -p tsconfig.json"
  }
}

// apps/api/src/server.ts
import { createLogger } from "@acme/shared";
 
const log = createLogger("api");
log.info("listening");

npm install          # enlaza los workspaces
npm run build -w @acme/shared
npm run dev -w @acme/api

Lo que esto demuestra:

• workspace:* le dice a npm que cree un enlace simbólico al paquete local @acme/shared.
• -w apunta a un solo workspace sin cd.
• El paquete compartido se construye antes de que la API importe la salida compilada.

En detalle

Cómo funciona

• Los globs workspaces de la raíz descubren los archivos package.json bajo apps/* y packages/*.
• npm install eleva las dependencias compartidas y crea enlaces simbólicos a los paquetes internos en node_modules del consumidor.
• workspace:* se resuelve a la versión local en el momento de la instalación; la publicación lo reemplaza con el semver concreto.
• Un package-lock.json en la raíz captura todo el grafo.

Protocolo workspace:

Notas de TypeScript

// packages/shared/tsconfig.json
{
  "compilerOptions": {
    "composite": true,
    "declaration": true,
    "outDir": "dist",
    "rootDir": "src"
  }
}

• Habilita composite para referencias de proyectos entre paquetes.
• Los consumidores deben importar desde nombres de paquetes (@acme/shared), no rutas relativas a packages/shared/src.

Errores comunes

• Importar rutas de origen entre paquetes - Evita los límites del paquete y rompe la publicación. Solución: exporta a través de main/exports de package.json.
• Olvidar construir librerías compartidas - La API se ejecuta contra dist/ obsoleto. Solución: ordena los scripts build o usa dependencias de pipeline de Turborepo.
• Dependencias fantasma - El hoisting te permite importar paquetes no declarados. Solución: considera pnpm o ESLint import-x/no-extraneous-dependencies.
• Paquetes internos con versión 0.0.0 - Está bien para monorepos privados; las librerías publicables necesitan un semver real antes de npm publish. Solución: ejecuta npm version en el paquete antes del lanzamiento externo.
• Dependencias circulares de workspace - @acme/a depende de @acme/b y viceversa. Solución: extrae el kernel compartido a @acme/core.

Alternativas

Preguntas frecuentes

npm run test -w @acme/api
npm run build --workspaces --if-present

npm install zod -w @acme/api

Relacionado

• Conceptos básicos de los gestores de paquetes - pnpm vs npm para monorepos
• Turborepo para Node - builds de workspace cacheados
• Monorepo de múltiples servicios - límites de servicio

Versiones de la pila: Esta página fue escrita para Node.js 24.18.0 (LTS activa), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 y NestJS 11.