Imagina que eres un chef ejecutivo. Para asegurar que todos los restaurantes de tu cadena produzcan los mismos platos deliciosos, has desarrollado una serie de “salsas secretas”. Quieres que estas salsas se envíen a cada sucursal, pero no puedes permitir que cualquier transeúnte se las lleve.

In el mundo del desarrollo de software, estas salsas secretas son los “paquetes privados” internos de la empresa.

A medida que los proyectos crecen, es probable que hayas experimentado esta frustración: duplicar el mismo componente de interfaz de usuario o función de utilidad en cada proyecto, o luchar con Git Submodules hasta cuestionar las decisiones de tu vida. De hecho, todo lo que necesitas es una “Despensa Privada (Private NPM Registry)”. Hoy discutiremos cómo usar pnpm para publicar paquetes en GitLab, para que los miembros del equipo puedan instalarlos como paquetes de código abierto con un solo comando.

¿Por qué necesitas paquetes privados y Scopes?

En el universo de Node.js, los paquetes privados deben tener un “apellido”: este es el Scope.

Por ejemplo, si tu empresa se llama @my-company, el nombre de tu paquete podría verse así: @my-company/ui-kit. Con este apellido, cuando pnpm lo vea, no buscará sin rumbo en npmjs.org. En su lugar, se dirigirá directamente a los puntos de coordinación de la empresa que hayas especificado.

Decisión clave: Group Level vs. Project Level

En GitLab, esto es como decidir dónde guardar tus condimentos:

Configuración del “Pasaporte”: Access Tokens y variables de entorno

Para entrar en el granero subterráneo, primero necesitas obtener una “tarjeta de acceso”.

1. Ve a Settings > Access Tokens en GitLab.
2. Solicita un Token, marcando los permisos read_api (para descargar) y write_package_registry (para publicar).
3. Importante: Una vez que tengas el Token, ¡nunca lo escribas directamente en tu código o archivo .npmrc! Eso es como dejar la llave de la caja fuerte en la puerta.

El enfoque más profesional es ocultarlo en “variables de entorno”. Agrega esta línea a tu terminal de Mac o Linux (por ejemplo, ~/.zshrc):

export GITLAB_TOKEN="tu_token_de_GitLab"

De esta manera, el sistema adjuntará automáticamente las credenciales por ti, lo que lo hace seguro y conveniente.

Configuración de navegación: La esencia de .npmrc

A continuación, crearemos un mapa de navegación, .npmrc, en la raíz del proyecto para decirle a pnpm a dónde ir:

# Para cualquier cosa que comience con @my-company, ve a GitLab
@my-company:registry=https://gitlab.com/api/v4/groups/<YOUR_GROUP_ID>/-/packages/npm/

# Configura la autenticación de la tarjeta de acceso (leyendo la variable de entorno que acabamos de establecer)
//gitlab.com/api/v4/groups/<YOUR_GROUP_ID>/-/packages/npm/:_authToken="${GITLAB_TOKEN}"

¡Solo cambia el Group ID de tu empresa y el camino estará pavimentado!

La última milla antes de publicar: El arte del empaquetado

Muchas personas se apresuran a publicar después de configurar la conexión, solo para cargar accidentalmente archivos de prueba o incluso configuraciones secretas. Aquí es donde el campo files en package.json resulta útil.

Este es un concepto de “allowlist” (lista de permitidos):

{
  "name": "@my-company/lib-1",
  "files": [
    "dist"
  ],
  "publishConfig": {
    "registry": "https://gitlab.com/api/v4/projects/<YOUR_PROJECT_ID>/packages/npm/"
  }
}

Antes de publicar, se recomienda usar el comando pnpm pack para desempacar y verificar el contenido localmente. Una vez que todo se vea bien, ¡ejecuta con confianza pnpm publish!

Conclusión

Construir una despensa privada no es difícil. Las claves son:

1. Solicitar un Token y protegerlo con variables de entorno.
2. Configurar el mapa de navegación .npmrc correcto.
3. Usar el campo files en package.json para un envío preciso.

Al dominar este flujo de trabajo, puedes hacer que la reutilización del código de tu empresa sea profesional, segura y elegante. ¡Ahora ve a construir tu propia cocina central!

Reference

• package.json | npm Docs
• Package registry | GitLab Docs