Publicar: el flujo de npm publish

Publicar un paquete es, en esencia, un acto irreversible: en cuanto una versión existe en el registro, cualquier instalación del planeta puede depender de ella y ya no podrás alterarla sin romper builds ajenos. Entender con precisión qué hace npm publish —qué compila, qué empaqueta, qué calcula, qué sube— separa a quien expone su trabajo con control quirúrgico de quien filtra secretos y basura sin enterarse. Aquí está el flujo, capa por capa.

Qué ocurre en npm publish

Cuando invocas npm publish, el cliente no “sube tu carpeta”: ejecuta una secuencia determinista de fases. Primero resuelve credenciales leyendo el .npmrc en cascada —proyecto, usuario, global— para obtener el token de autenticación; en 2026 lo habitual en CI es el trusted publishing con OIDC, sin tokens de larga vida almacenados.

Después empaqueta el árbol de trabajo en un tarball comprimido con gzip —el .tgz— aplicando las reglas de inclusión, calcula su integridad y lo sube con un HTTP PUT. El registro valida que esa versión exacta no exista ya —la regla de inmutabilidad— y actualiza el packument, el JSON maestro que describe todas las versiones del paquete.

El pipeline, desglosado, atraviesa fases nítidas:

• Credenciales: lee el token del .npmrc en cascada, o usa OIDC en CI.
• Scripts: dispara prepublishOnly, prepare y prepack antes de empaquetar.
• Empaquetado: comprime el árbol ya filtrado en un tarball .tgz.
• Integridad: calcula el hash SHA-512 en formato SRI, el sha512-... del lockfile.
• Subida: hace un HTTP PUT con el tarball y el documento de metadatos.
• Validación: rechaza versiones repetidas y mueve el dist-tag latest.

flowchart LR
A[npm publish] --> B[scripts prepublishOnly y prepack]
B --> C[empaqueta tarball tgz]
C --> D[integridad sha512 SRI]
D --> E[HTTP PUT al registro]
E --> F[valida version no repetida]
F --> G[actualiza packument y latest]
style A fill:#89b4fa,color:#11111b
style D fill:#cba6f7,color:#11111b
style G fill:#a6e3a1,color:#11111b

Los scripts de ciclo de vida

Entre “tengo el código” y “el tarball está sellado” corre una coreografía de scripts que conviene no confundir, porque un error de encuadre publica artefactos a medio construir. Si compilas en un script que no se ejecuta antes de empaquetar, subes un dist viejo o vacío sin que nada te avise. Cada gancho tiene un momento y un propósito exactos:

• prepare: corre antes de empaquetar —y también al instalar desde un repositorio git—; es el lugar canónico para compilar el dist.
• prepublishOnly: corre solo en publish, nunca en un install; ideal para los tests y el lint que solo tienen sentido al liberar.
• prepack y postpack: envuelven el momento exacto del empaquetado.
• postpublish: corre tras subir con éxito; útil para anuncios o limpieza.

La regla segura es repartir responsabilidades: genera el build en prepare, pon las verificaciones de release en prepublishOnly, y confirma siempre con un ensayo antes de liberar. Observar qué scripts se disparan y en qué orden es la mejor defensa contra publicar un artefacto incompleto.

# el orden efectivo, simplificado:
# prepublishOnly -> prepare -> prepack -> [empaqueta] -> postpack -> [sube] -> publish -> postpublish
npm publish --dry-run

Qué se sube: files frente a .npmignore

El tarball rara vez coincide con tu carpeta. npm ofrece dos mecanismos opuestos para decidir su contenido. El campo files en package.json es una lista de permitidos: solo entra lo que enumeras, y es la opción recomendada por explícita y segura por defecto.

El fichero .npmignore es una lista de excluidos, con la sintaxis de .gitignore: entra todo salvo lo que vetes. Si .npmignore no existe, npm recurre a tu .gitignore como denylist, un detalle que sorprende a muchos.

Por encima de ambos hay reglas inamovibles. Siempre viajan, los listes o no: el package.json, el README, la LICENSE, y los ficheros apuntados por main y por bin. Y siempre quedan fuera, aunque los incluyas: node_modules y .git por peso y seguridad, .npmrc porque podría contener tu token, y package-lock.json porque no tiene sentido dentro de una dependencia. El patrón profesional es declarar un files mínimo que apunte al dist:

{
  "name": "@acme/widget",
  "version": "2.1.0",
  "type": "module",
  "files": ["dist", "!dist/**/*.test.js"],
  "main": "./dist/index.js",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.js"
    }
  }
}

Los patrones negados con ! permiten refinar dentro del allowlist —aquí, excluir los tests transpilados que se colaron en dist—. La regla mental es simple: si dudas de si un fichero viajará, no lo dejes al azar de un denylist; enuméralo en files y verifícalo.

npm pack: inspeccionar antes de publicar

La herramienta que cierra el bucle es npm pack: genera el mismo tarball que subiría publish, pero lo deja en disco sin exponer nada. Con --dry-run ni siquiera escribe el fichero; solo imprime el manifiesto de lo que contendría.

Y npm publish --dry-run simula la publicación completa —scripts, reglas de inclusión, tamaño final— sin tocar el registro. Es tu red de seguridad obligatoria antes de un acto irreversible.

# lista el contenido exacto del tarball sin escribir nada
npm pack --dry-run

# simula la publicacion completa: scripts, reglas, tamano final
npm publish --dry-run

# inspecciona un tarball ya generado
tar -tzf acme-widget-2.1.0.tgz

El informe condensa lo que importa auditar:

• package size: los bytes comprimidos que descarga quien instala.
• unpacked size: lo que ocupa ya instalado en disco.
• total files: cuántos ficheros viajan; un salto inesperado delata un intruso.
• shasum e integrity: las huellas que verificará cada instalación futura.

En 2026 la inspección va más allá del tamaño: publint valida que tu campo exports y tus extensiones sean coherentes con ESM y CJS, y arethetypeswrong (el binario attw) comprueba que los tipos se resuelvan bien bajo cada estrategia de módulos. Ambos se corren sobre el tarball, no sobre el árbol de trabajo, para auditar exactamente lo que verá quien instale.