¿Estás intentando usar Paquetes Privados en el proyecto de tu empresa pero estás atascado en la configuración de .npmrc?

¿Por qué sigues obteniendo 404 Not Found incluso después de configurar el Token?

Cuando la empresa tiene múltiples equipos y múltiples paquetes (por ejemplo, @frontend, @backend), ¿cómo gestionas .npmrc con elegancia?

Derribando los dos mitos de .npmrc

Para entender .npmrc, primero necesitas entender cómo funciona.

En pocas palabras, su lógica central son solo dos cosas: Mapeo de Alcance (Scope Mapping) y Autenticación.

1. Mapeo de Alcance (Scope Mapping)

Esto le dice a npm: Cuando veas un paquete que comienza con @company, no vayas al npmjs.org oficial, ve a nuestro GitLab Registry especificado.

@company:registry=https://gitlab.com/api/v4/groups/100/-/packages/npm/

2. Autenticación (Authentication)

Con la dirección, también necesitas una llave. La llave es tu AuthToken.

Aquí hay una regla súper crucial: La URL del Registry y la ruta del AuthToken deben “coincidir exactamente”.

# ✅ Correcto: La ruta es exactamente la misma que el registry definido arriba
//gitlab.com/api/v4/groups/100/-/packages/npm/:_authToken=${GITLAB_TOKEN}

# ❌ Incorrecto: La ruta no coincide, esto causará un fallo de permisos
//gitlab.com/api/v4/:_authToken=${GITLAB_TOKEN}

Mucha gente falla en la configuración a menudo porque la ruta tiene una barra extra o le falta un nivel.

Infierno de Dependencias y Errores 404

La situación más dolorosa es: Instalas el paquete A, que depende del paquete B (también privado), y luego npm escupe un 404 Not Found.

¿Por qué sucede esto? Eso es porque cuando npm resuelve dependencias, si no hay una relación correcta, se pierde.

Especialmente cuando tienes dos Alcances diferentes (por ejemplo, @team-a y @team-b) en diferentes Grupos de GitLab, .npmrc se vuelve extremadamente complejo y difícil de mantener. Además, diferentes Registries pueden necesitar diferentes Tokens, solo gestionar estas variables de entorno es agotador.

¿Hay una manera más inteligente?

Solución Recomendada: Unified Download Group Registry y Independent Publish Project Registry

¿Por qué hacer esto?

Configuración en Acción

Puedes copiar directamente esta plantilla:

¡Recuerda entregar la tarea de proteger el Token a las variables de entorno, absolutamente no codifiques el Token en el código!

# .npmrc
# @company scope usa registry a nivel de grupo
# Todos los paquetes @company/* se instalarán desde este registry
@company:registry=https://gitlab.com/api/v4/groups/YOUR_GROUP_ID/-/packages/npm/

# Configuración de autenticación de GitLab npm registry
# Usar token de autenticación común de gitlab.com (cubre todas las solicitudes a nivel de grupo y proyecto)
//gitlab.com/api/v4/groups/YOUR_GROUP_ID/-/packages/npm/:_authToken=${GITLAB_NPM_TOKEN}
# Usar registry del proyecto para publicar paquetes
//gitlab.com/api/v4/projects/YOUR_PROJECT_ID/packages/npm/:_authToken=${GITLAB_NPM_TOKEN}


# Otros paquetes públicos todavía van al registry oficial
registry=https://registry.npmjs.org/

Configura publishConfig en package.json para publicar el paquete en el GitLab Project Registry correspondiente.

{
  "name": "@company/my-package",
  "publishConfig": {
    "@company:registry": "https://gitlab.com/api/v4/projects/YOUR_PROJECT_ID/packages/npm/"
  }
}

Conclusión

A través de la estrategia de “Unified Download Group Registry” e “Independent Publish Project Registry”, podemos reducir significativamente los costos de mantenimiento y hacer que el flujo de desarrollo sea más fluido.

Dominando estas lógicas, ¡GitLab NPM Registry será un asistente poderoso en el proceso de desarrollo de tu empresa!