8 - Publicación de paquetes

Objetivo del tema

Te guiaré por el proceso de preparar, publicar y mantener un paquete en el registro de npm: desde la creación de la estructura hasta las políticas para actualizar o despublicar versiones de forma responsable.

8.1 Crear un paquete propio

Antes de publicar, crea una carpeta con el código fuente y define el manifiesto usando npm init. Incluye un archivo de entrada (por ejemplo index.js) y un README con instrucciones de uso.

npm init -y

Ajusta campos como name, description, author y license. Si planeas que otros consuman el paquete, publica la documentación en el README y configura el campo main con el archivo que exporta la funcionalidad principal.

Registro en npm

8.2 Registro en npm (npm login)

Necesitas una cuenta en el registro para publicar. Regístrate en npmjs.com y luego autentícate desde la terminal con npm login.

npm login
Username: tu-usuario
Password: ********
Email: (this IS public) tu-email@example.com
Token de acceso npm

npm guarda un token de acceso en ~/.npmrc. Si empleas autenticación en dos pasos, deberás ingresar el código adicional. En entornos automatizados puedes usar tokens de acceso con permisos limitados.

8.3 Publicar un paquete (npm publish)

Una vez autenticado y listo el paquete, ejecuta npm publish. Por defecto la publicación es pública; si trabajas en una organización con un registro privado, ajusta el archivo .npmrc para apuntar al registry correcto.

npm publish
  • El nombre del paquete debe ser único en el registro público. Para nombres ya ocupados utiliza un scope (por ejemplo @tuusuario/mi-paquete).
  • Revisa que los archivos publicados sean sólo los necesarios. Controla esto con los campos files o .npmignore.
  • Si recibes errores de versión, verifica que el campo version aumente siguiendo las reglas de SemVer.

8.4 Actualizar versión de un paquete (npm version)

Para lanzar una nueva versión usa npm version. Este comando incrementa el número en package.json, crea una etiqueta y permite publicar la nueva versión.

npm version patch   # 1.0.0 -> 1.0.1
npm version minor   # 1.0.0 -> 1.1.0
npm version major   # 1.0.0 -> 2.0.0

Después de ejecutar npm version, publica la actualización con npm publish. Si el paquete utiliza Git, npm creará commits y tags automáticamente (puedes deshabilitarlo con --no-git-tag-version). Documenta los cambios en un changelog para que los usuarios conozcan las mejoras o rupturas.

8.5 Despublicar un paquete (npm unpublish)

Despublicar debe ser la última alternativa, porque puede afectar a otros proyectos que dependan de tu paquete. Consulta la política actualizada en npm unpublish policy.

  • npm unpublish paquete@versión permite retirar una versión concreta dentro de las primeras 72 horas desde su publicación.
  • Para proyectos muy usados, considera marcar la versión como deprecated con npm deprecate en lugar de eliminarla.
  • Si la publicación fue un error grave, abre un ticket con el soporte de npm siguiendo las pautas de la política.
# Despublicar una versión reciente
npm unpublish @tuusuario/mi-paquete@1.0.1

# Marcar una versión como obsoleta sin quitarla
npm deprecate @tuusuario/mi-paquete@1.0.1 "Uso no recomendado por bug crítico"

Resumen didáctico

Para compartir tu paquete con la comunidad define una estructura clara, autentícate en el registro, publica con npm publish y sigue buenas prácticas de versionado mediante npm version. Despublica solo cuando sea imprescindible y comunica los cambios a tus usuarios para mantener la confianza en tu proyecto.

Retornar