Publicar paquetes privados

Pier acepta el flujo estándar de npm publish tanto para paquetes con scope (@org/name) como sin scope (name). El protocolo es el PUT al estilo de CouchDB con _attachments — el mismo formato de transferencia que cada CLI de npm envía a npmjs.org.

Publicar un paquete con scope

# package.json
{
  "name": "@your-org/my-lib",
  "version": "1.0.0",
  "publishConfig": {
    "registry": "https://YOUR-PIER-HOST/registry/npm/"
  }
}

npm publish
# published @your-org/[email protected]

publishConfig es la forma estándar de fijar el destino de publicación de un paquete sin cambiar el registro global. Si no lo defines, npm usa el registry de tu .npmrc.

Publicar un paquete sin scope

Mismo flujo, sin @scope/:

# package.json
{
  "name": "my-internal-lib",
  "version": "1.0.0"
}

npm publish --registry=https://YOUR-PIER-HOST/registry/npm/

Los paquetes privados sin scope colisionan con el espacio de nombres público si además tienes el proxy upstream activado. Si my-internal-lib ya existe en npmjs.org, Pier igualmente acepta tu publicación, y tu versión privada eclipsa la entrada del proxy. Recomendamos nombres con scope (@your-org/…) para mayor claridad.

Verificación de integridad

Si tu CLI envía dist.integrity en el cuerpo de la publicación, Pier lo compara con el sha512 del tarball subido y rechaza las discrepancias con un 400. Si no se envía, Pier calcula la integridad a partir de los bytes y la almacena. En cualquier caso, cada tarball almacenado tiene un sha512 verificado.

Dist-tags

npm dist-tag add @your-org/[email protected] beta
npm dist-tag ls @your-org/my-lib
# latest: 1.2.0
# beta: 1.2.0
npm dist-tag rm @your-org/my-lib beta

latest es el único dist-tag obligatorio. Puedes tener cualquier número de etiquetas con nombre apuntando a cualquier versión.

Deprecar una versión

npm deprecate @your-org/[email protected] "use 1.2.x"

El mensaje de deprecación queda en npm_versions.manifest_json.deprecated, aparece en la página de detalle del paquete y se muestra en los clientes con npm warn durante la instalación. Para revertir la deprecación, pasa un mensaje vacío:

npm deprecate @your-org/[email protected] ""

Despublicar

# single version
npm unpublish @your-org/[email protected]

# whole package
npm unpublish @your-org/my-lib --force

Pier elimina la fila de la versión (o la fila del paquete + todas las versiones para una despublicación de paquete completo), borra el tarball del disco y escribe una lápida (tombstone) para que volver a publicar el mismo nombre+versión sea rechazado — igual que la política de npm.

Unpublish es la única operación destructiva accesible desde el CLI. Ten cuidado — no hay deshacer.

Autenticación para publicar

npm publish envía el token bearer desde .npmrc:

//YOUR-PIER-HOST/registry/npm/:_authToken=pier_npm_…

O usa npm login --auth-type=web para hacer el flujo de navegador al estilo OAuth (con aplicación de 2FA):

npm login --auth-type=web --registry=https://YOUR-PIER-HOST/registry/npm/
# Opens the browser → authenticate in Pier panel → token in .npmrc

Errores comunes

• E409 Conflict — estás volviendo a publicar una versión que ya existe. Incrementa la versión en package.json. (Consulta Solución de problemas para la lista completa.)
• 401 Unauthorized — token ausente o revocado. Genera uno nuevo en Packages → Manage tokens.
• 400 attachment name mismatch — tu CLI está enviando una clave _attachments inesperada. La mayoría de los clientes envían @scope/name-version.tgz (completo) o name-version.tgz (corto) — Pier acepta ambos.

Próximos pasos

• Integración con CI — automatiza la publicación desde tu pipeline de compilación.
• Guías por cliente — particularidades de publicación específicas de cada cliente.