Capítulo 7: Mantenimiento del monorepo con Syncpack y buenas prácticas

Herramientas clave para el mantenimiento

Configurar Syncpack

Desde la raíz de tu proyecto:

pnpm add -D syncpack -w

En tu package.json de la raíz, añade los scripts útiles:

"scripts": {
  "deps:check": "syncpack list --types \"!local\"",
  "deps:fix": "syncpack fix --types \"!local\"",
  "deps:update": "syncpack update --types \"!local\""
}

Estos scripts te permitirán:

• Detectar versiones duplicadas de una misma librería.
• Alinear todas las versiones a la más común.
• Forzar actualizaciones o verificar cambios en pull requests.

Ejemplo de uso

pnpm deps:check            # Listar dependencias inconsistentes
pnpm deps:fix              # Forzar que todas usen la misma versión
pnpm deps:update           # Actualizar automáticamente todas a su última versión

Consejo: Añade deps:update-check al workflow de CI si quieres que falle cuando alguien introduce versiones no sincronizadas.

Limpieza de builds

En el package.json de la raíz añadiremos los scripts para limpiar los outputs de build:

"scripts": {
  "clean": "turbo run clean && rm -rf node_modules",
  "clean:all": "find . -name \"node_modules\" -type d -prune -exec rm -rf '{}' +"
}

Y, lo siguiente en el package.json de cada paquete:

"scripts": {
  "clean": "rm -rf dist"
}

Ahora, para eliminar todos los dist/ y node_modules/ de forma segura podemos ejecutar:

pnpm clean

Buenas prácticas para un monorepo saludable

1. Usa workspace:* para dependencias internas

Asegúrate de que los paquetes internos estén conectados:

"@myui/tsconfig": "workspace:*"

Esto evita errores de versiones y facilita testing cruzado.

2. Evita dependencias duplicadas entre root y paquetes

No pongas react, eslint, jest, etc. como dependencia en cada paquete. Decláralas en el package.json raíz, y usa peerDependencies si necesitas indicar que se requiere algo pero no incluirlo en el build.

3. Usa turbo run con filtros para scripts por paquete

pnpm build --filter @myui/hero

O para múltiples builds:

pnpm build --filter=./packages/*

4. Ten una convención para los nombres

Usa un scope coherente: @myui/button, @myui/input…

Además, mantén la estructura homogénea en cada paquete:

[paquete]/
  ├── src/
  ├── tsconfig.json
  ├── tsconfig.build.json
  ├── .swcrc
  └── README.md

5. Añade un README.md en cada paquete

Explica lo siguiente:

• Qué hace
• Cómo se usa
• Props principales
• Ejemplos
• Dependencias