La estructura típica: apps y packages

Casi todos los monorepos del ecosistema JavaScript convergen en la misma silueta: una carpeta apps/ con lo que se despliega y una carpeta packages/ con lo que se comparte. No es una moda estética. Detrás de esas dos carpetas hay una distinción de fondo entre sumideros —cosas que se consumen pero de las que nadie depende— y fuentes —cosas de las que todo lo demás depende—. Entender esa dirección del grafo, y las convenciones que la protegen, es lo que separa un monorepo que escala de una carpeta grande que se convierte en barro.

apps/ y packages/: sumideros y fuentes

El pnpm-workspace.yaml de la raíz declara dónde viven los paquetes, casi siempre con dos globs:

# pnpm-workspace.yaml
packages:
  - "apps/*"
  - "packages/*"
  - "tooling/*"

apps/ contiene las unidades desplegables: la web, el panel de administración, la API, la app móvil. Son sumideros del grafo —nodos hoja—: consumen paquetes pero nadie las consume a ellas. Por eso se marcan "private": true, para que un pnpm publish -r accidental nunca las suba a un registro, y por eso rara vez llevan versión semántica: no se distribuyen, se despliegan.

packages/ contiene las fuentes: la librería de componentes, los utilitarios, el cliente de API, los tipos compartidos. Son nodos de los que cuelga el resto. Un paquete puede ser puramente interno —solo lo consume el propio repo con workspace:*— o estar destinado a publicarse en npm. Muchos monorepos añaden una tercera carpeta, tooling/ o config/, para las configuraciones compartidas: el tsconfig base, la config de ESLint u Oxlint, la de Tailwind. Son fuentes también, pero de reglas en lugar de código de ejecución.

Una nota sobre las apps: aunque sean sumideros, a veces hay que sacar una sola de ellas del monorepo para meterla en una imagen de contenedor sin arrastrar el repo entero. Para eso existe pnpm deploy, que genera una copia autónoma de la app con sus dependencias ya resueltas y sin symlinks al resto del árbol.

# saca una sola app del monorepo, autonoma y sin symlinks
pnpm --filter @acme/web deploy ./out

Librerías internas: JIT frente a compiladas

Un paquete interno se consume declarándolo con el protocolo workspace: y pnpm lo enlaza por symlink en lugar de descargarlo. Pero hay una decisión de diseño que casi nadie explica y que determina la velocidad de todo el repo: qué expone ese paquete, código fuente o código compilado.

// packages/ui/package.json  (paquete JIT: expone el fuente)
{
  "name": "@acme/ui",
  "exports": { ".": "./src/index.ts" }
}

En el sabor JIT —just-in-time, o “internal package” sin build— el paquete apunta su exports directamente a ./src/index.ts. No tiene paso de compilación propio: es el bundler de la app consumidora (Vite, Turbopack) quien transpila ese TypeScript al vuelo, como si fuera código de la propia app. La ventaja es enorme: cero configuración de build por paquete, cero carpeta dist/ que mantener, y el HMR cruza fronteras de paquete sin fricción. Es el patrón recomendado para todo lo que solo se consume dentro del monorepo.

Hay un matiz de tipos que conviene anticipar: en un paquete JIT, TypeScript resuelve los tipos directamente del fuente, así que el consumidor ve los tipos exactos sin que nadie genere .d.ts. En un paquete compilado, en cambio, los tipos viajan como archivos .d.ts emitidos en el build, y su fidelidad depende de que el paquete los genere bien.

El sabor compilado es lo contrario: el paquete tiene su propio script de build que emite dist/ con JavaScript y sus .d.ts, y exports apunta ahí. Lo necesitas cuando el paquete se va a publicar en npm —los consumidores externos no van a transpilar tu fuente—, cuando cruza una frontera de herramienta que no entiende TypeScript, o cuando quieres aislar el paquete de la config del consumidor. El coste es un paso de build más en el grafo de tareas, justo lo que en la próxima lección veremos que hay que cachear.

// packages/sdk/package.json  (paquete compilado: expone dist)
{
  "name": "@acme/sdk",
  "exports": { ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" } },
  "scripts": { "build": "tsup src/index.ts --format esm --dts" }
}

La dirección del grafo

Un monorepo sano no es una maraña donde todo importa de todo: es un grafo dirigido acíclico con capas. Las apps dependen de los paquetes; los paquetes de más alto nivel dependen de los de más bajo nivel; y nadie —nunca— importa de apps/. Si un paquete de packages/ necesita algo que vive en una app, ese algo está en el sitio equivocado y debe bajar a un paquete.

flowchart TD
W[apps web] --> F[packages features]
A[apps admin] --> F
F --> UI[packages ui]
F --> U[packages utils]
UI --> U
T[tooling tsconfig y eslint] -.-> W
T -.-> A
T -.-> F
style W fill:#89b4fa,color:#11111b
style A fill:#89b4fa,color:#11111b
style U fill:#a6e3a1,color:#11111b

Dos reglas sostienen esta forma. La primera es la aciclicidad: si ui importa de features y features importa de ui, tienes un ciclo, y los ciclos rompen el orden topológico del que dependen la instalación, el build y la caché. La segunda es el layering: se decide qué capa puede importar de qué capa —por ejemplo, features puede usar ui, pero ui nunca usa features— y esa regla se hace cumplir con tooling, no con buena voluntad. Nx tiene sus module boundaries con etiquetas; con ESLint existen reglas de fronteras; el punto es que la topología deseada esté verificada por una máquina, porque en un repo con cuarenta paquetes ningún humano la mantiene en la cabeza.

Convenciones que escalan

A partir de cierto tamaño, la coherencia importa más que cualquier optimización puntual. Un puñado de convenciones separan el monorepo que crece con gracia del que colapsa bajo su propio peso.

• Scope obligatorio. Todo paquete lleva @acme/*. El nombre es su identidad en el grafo y en los --filter; la carpeta es un mero detalle de disco. Nombre de paquete y nombre de carpeta deben ir alineados para que nadie tenga que adivinar dónde vive @acme/ui.
• private en las apps. Cinturón y tirantes contra la publicación accidental.
• API pública explícita. Un paquete expone lo que quiere que se use vía exports, no todo su árbol de archivos. Evita el barrel gigante que reexporta el paquete entero: sabotea el tree shaking y crea dependencias fantasma. La superficie pública es un contrato, no un accidente de qué archivos existen.
• tooling/ compartido. El tsconfig base, la config de lint y de formato viven una vez y se extienden. Un cambio de regla se propaga a todo el repo sin copiar y pegar.

// tooling/tsconfig/base.json consumido por un paquete
{ "extends": "@acme/tsconfig/base.json", "include": ["src"] }

El workspace:* en un paquete de tooling/ es la misma idea aplicada a la configuración: @acme/tsconfig no se publica, se enlaza, y editar la regla base se propaga a sus consumidores en el acto. La configuración deja de ser texto copiado y pasa a ser una dependencia más del grafo, con las mismas garantías de fuente única que el código de ejecución.

La suma de estas convenciones produce un efecto que no se ve hasta que falta: cualquiera puede abrir un paquete cualquiera y saber, sin preguntar, dónde está su entrada, qué expone, de qué depende y cómo se comprueba. Esa previsibilidad es el verdadero producto de la estructura.