Gestión de paquetes privados con Verdaccio: una solución eficiente para proyectos personales y colaborativos

Cómo implementar un registry privado de npm usando Verdaccio, sus ventajas para mantener paquetes internos y cómo desplegarlo en local o en la nube. Durante el desarrollo de varios proyectos personales, noté un patrón recurrente: funciones utilitarias, filtros reutilizables para MongoDB y lógica repetida entre servicios. Compartir este tipo de código entre múltiples repositorios sin publicarlo en el registro público de npm se volvió una necesidad. En ese contexto, decidí explorar una solución para crear un registro de paquetes privado que me permitiera gestionar dependencias internas de forma segura y controlada. Así que me puse a buscar una forma de empaquetar y reutilizar ese código sin subirlo a npm público. Quería algo rápido, privado, simple y siempre Software Libre. Ahí fue cuando me topé con Verdaccio, y honestamente, me vino como anillo al dedo. ¿Qué es Verdaccio? Verdaccio es un registro npm privado y liviano, que puede ser desplegado fácilmente en local o en la nube. Permite almacenar, compartir y consumir paquetes npm sin depender del ecosistema público. Es ideal para organizaciones o desarrolladores que requieren: Compartir librerías internas sin hacerlas públicas. Controlar el acceso mediante autenticación. Tener un entorno seguro para pruebas antes de publicar en npmjs.org. Instalación rápida con Docker Para evaluarlo de forma local, ejecuté el siguiente comando: docker run -it --rm --name verdaccio -p 4873:4873 verdaccio/verdaccio Esto inicia el servidor en http://localhost:4873. Para un entorno persistente: docker run -d \ --name verdaccio \ -p 4873:4873 \ -v $(pwd)/storage:/verdaccio/storage \ -v $(pwd)/conf:/verdaccio/conf \ verdaccio/verdaccio Esto mantiene tanto los paquetes como la configuración, incluso tras reiniciar el contenedor. Configuración básica (config.yaml) La configuración de Verdaccio se encuentra en el archivo config.yaml. A continuación, una configuración mínima para comenzar: auth: para controlar acceso. Usa bcrypt si vas a crear usuarios. uplinks: para seguir teniendo acceso a los paquetes públicos de npm. packages: puedes controlar qué usuarios o grupos pueden publicar o acceder a qué paquetes. Ejemplo muy básico: storage: ./storage auth: htpasswd: file: ./htpasswd algorithm: bcrypt uplinks: npmjs: url: https://registry.npmjs.org/ packages: '@/': access: $authenticated publish: $authenticated '**': access: $authenticated publish: $authenticated log: level: info Esto permite autenticación básica, acceso y publicación para usuarios autenticados, y reenvía los paquetes que no estén en tu registry a npmjs. Dockerfile personalizado para producción En lugar de usar directamente la imagen base de Verdaccio, puedes crear una imagen personalizada que incluya tu configuración y lógica de arranque: FROM verdaccio/verdaccio:5 # Set working directory WORKDIR /verdaccio # Copy config files and startup script COPY config.yaml /verdaccio/conf/config.yaml COPY start.sh /verdaccio/start.sh # Expose the default Verdaccio port and Railway's PORT EXPOSE 4873 EXPOSE 80 # Set environment variables ENV NODE_ENV=production # Command to run the application using our config file CMD /bin/sh -c "verdaccio --config /verdaccio/conf/config.yaml --listen 0.0.0.0:4873" Este enfoque te permite tener control total sobre el entorno de Verdaccio: Personalizas el archivo config.yaml para definir autenticación, permisos y uplinks. Puedes añadir un start.sh para tareas como generar usuarios o pre-cargar paquetes. Facilita el despliegue en Railway u otras plataformas que esperan un CMD claro y abierto en 0.0.0.0. Si estás usando Railway, basta con conectar tu repo y configurar la variable de entorno PORT=4873 si lo necesitas explícitamente. Publicación y consumo de paquetes Crear un usuario: npm adduser --registry http://localhost:4873 Publicar un paquete: npm publish --registry http://localhost:4873 Instalar desde otro proyecto: npm install @tu-nombre/mi-paquete --registry http://localhost:4873 Despliegue en la nube (Railway o VPS) Una vez validado localmente, puedes desplegar Verdaccio en servicios como Railway, Render o un VPS. En mi caso, utilicé Railway junto a un túnel de Cloudflare para evitar configuraciones de DNS o puertos abiertos. Recomendaciones: Usa volúmenes persistentes para storage y conf. Protege el acceso al registro mediante HTTPS y autenticación. Agrega plugins para métricas, dashboards o SSO si tu entorno lo requiere. Manejo de tokens En entornos CI/CD o instalaciones automatizadas, puedes usar un .npmrc con token para autenticarte: @tu-nombre:registry=https://turegistro.com/ //turegistro.com/:_authToken=TOKEN_GENERADO Puedes generar este token usando npm login o npm token create si tu servidor lo permite.

May 4, 2025 - 05:28

Gestión de paquetes privados con Verdaccio: una solución eficiente para proyectos personales y colaborativos

Cómo implementar un registry privado de npm usando Verdaccio, sus ventajas para mantener paquetes internos y cómo desplegarlo en local o en la nube.

Durante el desarrollo de varios proyectos personales, noté un patrón recurrente: funciones utilitarias, filtros reutilizables para MongoDB y lógica repetida entre servicios. Compartir este tipo de código entre múltiples repositorios sin publicarlo en el registro público de npm se volvió una necesidad. En ese contexto, decidí explorar una solución para crear un registro de paquetes privado que me permitiera gestionar dependencias internas de forma segura y controlada.

Así que me puse a buscar una forma de empaquetar y reutilizar ese código sin subirlo a npm público. Quería algo rápido, privado, simple y siempre Software Libre. Ahí fue cuando me topé con Verdaccio, y honestamente, me vino como anillo al dedo.

¿Qué es Verdaccio?

Verdaccio es un registro npm privado y liviano, que puede ser desplegado fácilmente en local o en la nube. Permite almacenar, compartir y consumir paquetes npm sin depender del ecosistema público. Es ideal para organizaciones o desarrolladores que requieren:

Compartir librerías internas sin hacerlas públicas.
Controlar el acceso mediante autenticación.
Tener un entorno seguro para pruebas antes de publicar en npmjs.org.

Instalación rápida con Docker

Para evaluarlo de forma local, ejecuté el siguiente comando:

docker run -it --rm --name verdaccio -p 4873:4873 verdaccio/verdaccio

Esto inicia el servidor en http://localhost:4873. Para un entorno persistente:

docker run -d \
  --name verdaccio \
  -p 4873:4873 \
  -v $(pwd)/storage:/verdaccio/storage \
  -v $(pwd)/conf:/verdaccio/conf \
  verdaccio/verdaccio

Esto mantiene tanto los paquetes como la configuración, incluso tras reiniciar el contenedor.

Configuración básica (config.yaml)
La configuración de Verdaccio se encuentra en el archivo config.yaml. A continuación, una configuración mínima para comenzar:

auth: para controlar acceso. Usa bcrypt si vas a crear usuarios.
uplinks: para seguir teniendo acceso a los paquetes públicos de npm.
packages: puedes controlar qué usuarios o grupos pueden publicar o acceder a qué paquetes.

Ejemplo muy básico:

storage: ./storage

auth:
  htpasswd:
    file: ./htpasswd
    algorithm: bcrypt

uplinks:
  npmjs:
    url: https://registry.npmjs.org/

packages:
  '@*/*':
    access: $authenticated
    publish: $authenticated

  '**':
    access: $authenticated
    publish: $authenticated

log:
  level: info

Esto permite autenticación básica, acceso y publicación para usuarios autenticados, y reenvía los paquetes que no estén en tu registry a npmjs.

Dockerfile personalizado para producción

En lugar de usar directamente la imagen base de Verdaccio, puedes crear una imagen personalizada que incluya tu configuración y lógica de arranque:

FROM verdaccio/verdaccio:5

# Set working directory
WORKDIR /verdaccio

# Copy config files and startup script
COPY config.yaml /verdaccio/conf/config.yaml
COPY start.sh /verdaccio/start.sh

# Expose the default Verdaccio port and Railway's PORT
EXPOSE 4873
EXPOSE 80

# Set environment variables
ENV NODE_ENV=production

# Command to run the application using our config file
CMD /bin/sh -c "verdaccio --config /verdaccio/conf/config.yaml --listen 0.0.0.0:4873"

Este enfoque te permite tener control total sobre el entorno de Verdaccio:

Personalizas el archivo config.yaml para definir autenticación, permisos y uplinks.
Puedes añadir un start.sh para tareas como generar usuarios o pre-cargar paquetes.
Facilita el despliegue en Railway u otras plataformas que esperan un CMD claro y abierto en 0.0.0.0.

Si estás usando Railway, basta con conectar tu repo y configurar la variable de entorno PORT=4873 si lo necesitas explícitamente.

Publicación y consumo de paquetes

Crear un usuario:

npm adduser --registry http://localhost:4873

Publicar un paquete:

npm publish --registry http://localhost:4873

Instalar desde otro proyecto:

npm install @tu-nombre/mi-paquete --registry http://localhost:4873

Despliegue en la nube (Railway o VPS)

Una vez validado localmente, puedes desplegar Verdaccio en servicios como Railway, Render o un VPS. En mi caso, utilicé Railway junto a un túnel de Cloudflare para evitar configuraciones de DNS o puertos abiertos.

Recomendaciones:

Usa volúmenes persistentes para storage y conf.
Protege el acceso al registro mediante HTTPS y autenticación.
Agrega plugins para métricas, dashboards o SSO si tu entorno lo requiere.

Manejo de tokens

En entornos CI/CD o instalaciones automatizadas, puedes usar un .npmrc con token para autenticarte:

@tu-nombre:registry=https://turegistro.com/
//turegistro.com/:_authToken=TOKEN_GENERADO

Puedes generar este token usando npm login o npm token create si tu servidor lo permite.

Conclusiones

Verdaccio ha sido una herramienta clave para mantener mi ecosistema de paquetes organizado, modular y seguro. Me permite escalar mis proyectos sin duplicar código ni exponer lógica interna a npm público.