Tropiezos y soluciones al migrar un monorrepo de pnpm a Nub
makedream27 de julio de 2026
0
Computing/Software
Comments (0)
Log in to leave a comment
No posts yet
makedreammakedreamLog in to leave a comment
No posts yet
El ecosistema de Node.js está agotado. Un entorno de construcción apilado con capas de tsx, dotenv-cli, nvm y pnpm es pesado, y cada vez que actualizas algo, los scripts se enredan. Cuando apareció Nub, un toolkit integrado desarrollado en Rust que prometía empaquetar este desastre de paquetes en un solo binario, honestamente me pareció algo positivo pero sospechoso.
Al cambiar un monorrepo real pnpm-workspace de producción a Nub, resultó ser bastante atractivo. Sin embargo, nunca hay una transición completamente fluida. Surgieron obstáculos de inmediato en la práctica, como conflictos de dependencias, políticas de bloqueo de seguridad de 24 horas y problemas con la separación de la caché de CI.
aube, el motor de paquetes de Nub, reconoce al instante el pnpm-workspace.yaml existente y las workspaces de package.json. Como promete compatibilidad a nivel de bytes con el esquema v9 de pnpm-lock.yaml, utiliza por defecto la estructura existente de la Virtual Store (node_modules/.store/).
El problema son las herramientas antiguas que asumen implícitamente una estructura aplanada (hoisted) de node_modules. Si las ejecutas justo después de la migración, fallan arrojando un error MODULE_NOT_FOUND. Para hacer que el servicio funcione de inmediato, debes comenzar desplegando el árbol de paquetes con la opción --node-linker hoisted.
Con una instalación Warm que aplica caché, el modo GVS predeterminado tarda 346 ms. El modo Hoisted tarda 1461 ms, siendo más de 4 veces más lento, pero sigue siendo más de 2 veces más rápido que los 3453 ms de pnpm v10+. Al principio, es más cómodo asegurar la compatibilidad con el modo Hoisted y luego migrar al modo GVS predeterminado a medida que eliminas las dependencias de herramientas antiguas.
`bash
#!/usr/bin/env bash
set -euo pipefail
echo "==> [1/4] Comprobando el binario de Nub"
if ! command -v nub &> /dev/null; then
echo "Error: Nub no está instalado. Ejecuta primero 'npm i -g @nubjs/nub'."
exit 1
fi
echo "==> [2/4] Verificando el esquema de pnpm-lock.yaml"
if [ -f "pnpm-lock.yaml" ]; then
nub pm use nub
fi
echo "==> [3/4] Especificando el motor de ejecución en package.json"
node -e '
const fs = require("fs");
const pkg = JSON.parse(fs.readFileSync("package.json", "utf8"));
pkg.devEngines = pkg.devEngines || {};
pkg.devEngines.packageManager = {
name: "nub",
version: "^0.4.0",
onFail: "warn"
};
fs.writeFileSync("package.json", JSON.stringify(pkg, null, 2) + "\n");
'
echo "==> [4/4] Generando Lockfile"
nub install --frozen-lockfile=false
`
Si conviertes pnpm-lock.yaml a nub.lock con este script, puedes ahorrar más de 2 horas a la semana que antes perdías solucionando fallos al modificar scripts.
Nub tiene una política de seguridad bastante estricta. Bloquea por defecto los scripts de ciclo de vida y arroja ERR_NUB_TRUST_DOWNGRADE si no hay una firma de Provenance de npm. Lo más desconcertante es la opción minimumReleaseAge. Considera que las versiones de paquetes publicadas hace menos de 24 horas están en estado de espera de verificación de seguridad y bloquea su instalación.
Normalmente es un gran escudo de defensa, pero se convierte en un muro de lamentaciones cuando surge una vulnerabilidad zero-day y necesitas desplegar de inmediato una versión con parche lanzada hace 1 hora. En este caso, debes especificar los paquetes con permiso de script de construcción en el package.json raíz y desbloquearlos mediante comandos.
`json
{
"name": "@org/monorepo-root",
"private": true,
"allowBuilds": {
"esbuild": true,
"sharp": true,
"@fast-cve/patch-pkg": true
}
}
`
El flujo para omitir y aplicar un paquete de hotfix bloqueado es el siguiente:
`bash
nub add --allow-build=@fast-cve/patch-pkg @fast-cve/patch-pkg@1.0.1-hotfix
nub approve-builds
`
Al ejecutar nub approve-builds, se desbloquea la lista y la construcción continúa de inmediato. Los paquetes registrados como código malicioso (MAL-*) en la base de datos de OSV no se pueden desbloquear ni siquiera con este comando, por lo que en ese caso deberás buscar una versión alternativa superior.
Para maximizar la velocidad de CI/CD, es necesario conocer las rutas de caché de Nub. El binario de Node se almacena en ~/.cache/nub/node/<version>/, y el CAS (Content-Addressable Store) de paquetes se divide entre ~/.cache/nub/ y node_modules/.store/.
En las construcciones multi-stage de Docker, se debe utilizar el montaje de caché de BuildKit para aislar completamente la capa de instalación y así aprovechar el efecto de la caché.
`dockerfile
FROM ghcr.io/nubjs/nub:latest AS base
WORKDIR /app
FROM base AS dependencies
COPY package.json nub.lock pnpm-workspace.yaml ./
COPY packages/core/package.json ./packages/core/
COPY packages/api/package.json ./packages/api/
RUN --mount=type=cache,target=/root/.cache/nub
nub ci --prefer-offline
FROM dependencies AS builder
COPY . .
RUN nub run build --filter=@org/api
FROM node:22-alpine AS runner
WORKDIR /app
ENV NODE_ENV=production
COPY --from=builder /app/packages/api/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
EXPOSE 3000
CMD ["node", "dist/index.js"]
`
En GitHub Actions, se usa nubjs/setup-nub@v0 en lugar de actions/setup-node.
`yaml
name: CI
on:
push:
branches: [main]
pull_request:
branches: [main]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: nubjs/setup-nub@v0
with:
cache: true
- run: nub ci
- run: nub -r run build
- run: nub -r run test
`
La velocidad de nub ci combinada con setup-nub y la caché ronda los 346 ms. En comparación con el pnpm tradicional (3453 ms), el tiempo de instalación de paquetes en el pipeline se reduce drásticamente, cortando a la mitad el tiempo total de construcción en CI. Al ver la factura de la infraestructura cloud a fin de mes, definitivamente te sentirás mejor.
Nub incluye un transpilador en memoria basado en oxc, por lo que ejecuta código TypeScript directamente sin necesidad de tsx o ts-node. También lee los archivos .env por su cuenta. Al eliminar la sobrecarga de arranque del proceso de Node.js que aparecía cada vez que usabas pnpm run (442.7 ms), el tiempo de ejecución de scripts de nub run cae hasta los 14.7 ms. La diferencia se siente bastante.
Para evitar la fragmentación de versiones de Node.js entre los miembros del equipo, basta con colocar un archivo .node-version en la raíz.
`bash
echo "22.15.0" > .node-version
nub src/index.ts
`
En Node 22.15.0 o superior, gracias al module.registerHooks() síncrono, la latencia de arranque en frío se elimina por completo. Cuando llega un nuevo miembro al equipo, la forma más limpia de configurar su entorno de una vez sin explicaciones complejas es preparar un script de automatización.
`bash
#!/usr/bin/env bash
set -euo pipefail
echo "==> Iniciando la configuración del entorno de desarrollo"
if ! command -v nub &> /dev/null; then
if command -v brew &> /dev/null; then
brew install nubjs/tap/nub
else
npm install -g --ignore-scripts=false @nubjs/nub
fi
fi
nub pm shim
nub node install
nub install
if [ ! -f ".env.local" ] && [ -f ".env.example" ]; then
cp .env.example .env.local
fi
echo "==> Configuración completada. Ejecuta con 'nub run dev'."
`
Si ejecutas nub pm shim, incluso si ingresas por costumbre pnpm install o npm run, el ejecutor de Nub lo interceptará y procesará. Además de reducir la sobrecarga de ejecución de la CLI de pnpm exec (191 ms) a nubx (11 ms), te ahorrarás unas 2 horas a la semana de depuración escuchando frases como "en mi computadora no funciona".