Cómo sabe npm cuál es tu paquete: name, version y dist-tags

Cuando publicas por primera vez en npmjs.com surge la duda: ¿cómo sabe npm que ese tarball es tu paquete y no otro? No adivina nada. La identidad sale de tu package.json y el registro guarda quién publicó qué. Lo cuento con el caso real de tabernaculo, que acabo de publicar.

1. La identidad está en package.json

{ "name": "tabernaculo", "version": "0.2.0" }

• name: el nombre público, único en todo npmjs.com. Al publicar la 0.1.0 por primera vez, el nombre estaba libre y quedó reservado a mi cuenta. Desde entonces, solo yo (o a quien añada como maintainer) puede subir algo llamado tabernaculo.
• version: la edición concreta. Es inmutable: una vez publicado 0.1.0, nadie —ni yo— puede volver a subir otro contenido con ese número. Por eso la siguiente fue 0.2.0.

2. Qué hace publish por debajo

1. Lee name + version y empaqueta los ficheros (según el campo files, más README y package.json siempre).
2. Se autentica con tu token (~/.npmrc) → el registry sabe quién publica.
3. Comprueba: ¿existe ya name@version? Si existe → error (cannot publish over existing). Si el name es nuevo → lo registra a tu cuenta.
4. Guarda el tarball y mueve el tag latest a la versión recién publicada.

Eso es todo lo que “sabe” npm: una tabla nombre → versiones → tarballs, más quién tiene permiso sobre cada nombre.

Nota: bun publish ignora el token de ~/.npmrc y abre un flujo de auth por navegador. Para publicar de forma no interactiva usé npm publish (respeta el token), y como mi token solo permite staging, el flujo real fue npm stage publish --otp=<código> + aprobar en la web de npm. Directo es imposible con ese token (E_STAGE_REQUIRED).

3. Cómo lo encuentra después

• npm view tabernaculo, npm install tabernaculo o npx tabernaculo → el cliente pregunta al registry por el nombre y descarga el tarball de la versión pedida (o latest).
• npx además lee el campo bin ("tabernaculo": "./src/main.ts") para saber qué fichero ejecutar.

Prueba de consumidor real, en un directorio limpio:

npx -y tabernaculo@0.2.0 clis
# descarga el 0.2.0 y lista los 8 CLIs soportados

4. Dist-tags: probar sin romper latest

Un dist-tag es una etiqueta que apunta a una versión, un alias móvil:

tabernaculo:
  versions: 0.1.0, 0.2.0
  dist-tags: { latest: 0.2.0 }

latest es lo que se instala sin pedir versión. Para probar la 0.3.0 con unos pocos sin afectar al resto:

# pre-release: semver la ordena ANTES que 0.3.0
npm version 0.3.0-beta.0 --no-git-tag-version

# se publica con tag beta → latest SIGUE en 0.2.0
npm stage publish --tag beta --otp=<código>

npm dist-tag ls tabernaculo   # ver los tags
npx tabernaculo@beta ...      # los testers reciben la beta
npx tabernaculo ...           # el resto sigue en la estable

# promocionar a estable sin republicar nada:
npm dist-tag add tabernaculo@0.3.0 latest
npm dist-tag rm tabernaculo beta

Reglas prácticas:

1. Mover un tag no sube nada: solo cambia a qué versión apunta. Barato y reversible.
2. Sin --tag, todo va a latest: una beta publicada sin tag contaminaría la estable.
3. Los tags viven en el registry, no en tu repo: no hay nada que commitear por ellos.

Resumen