Você está preso na configuração do .npmrc porque o projeto da sua empresa precisa usar Pacotes Privados?

Por que ele ainda mostra 404 Not Found mesmo que o Token esteja configurado?

Quando uma empresa tem várias equipes e vários pacotes (por exemplo, @frontend, @backend), como você pode gerenciar o .npmrc de forma elegante?

Desmistificando os dois mitos do .npmrc

Para entender o .npmrc, você primeiro precisa entender como ele funciona.

Simplificando, sua lógica central se resume a duas coisas: Mapeamento de Escopo (Scope Mapping) e Autenticação (Authentication).

1. Mapeamento de Escopo (Scope Mapping)

Isso diz ao npm: Quando você vir um pacote começando com @company, não o procure no npmjs.org oficial, mas vá para o nosso GitLab Registry especificado.

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

2. Autenticação (Authentication)

Com o endereço, você também precisa de uma chave. A chave é o seu AuthToken.

Aqui está uma regra super crítica: A URL do Registry e o caminho do AuthToken devem “corresponder exatamente”.

# ✅ Correto: O caminho é exatamente o mesmo que o registry definido acima
//gitlab.com/api/v4/groups/100/-/packages/npm/:_authToken=${GITLAB_TOKEN}

# ❌ Incorreto: O caminho não corresponde, o que causará falha de permissão
//gitlab.com/api/v4/:_authToken=${GITLAB_TOKEN}

Muitas pessoas falham na configuração frequentemente devido a uma barra extra ou falta de um nível no caminho.

Inferno de Dependências e Erros 404

A situação mais dolorosa é: Você instala o pacote A, que depende do pacote B (também privado), e então o npm cospe um 404 Not Found.

Por que isso acontece? Isso ocorre porque o npm se perde ao resolver dependências se não houver uma correspondência correta.

Especialmente quando você tem dois Escopos diferentes (por exemplo, @team-a e @team-b) em Grupos GitLab diferentes, o .npmrc pode se tornar extremamente complicado e difícil de manter. Juntamente com o fato de que Registries diferentes podem exigir Tokens diferentes, gerenciar essas variáveis de ambiente por si só é suficiente para te encher.

Existe uma maneira mais inteligente?

Solução Recomendada: Group Registry de Download Unificado & Project Registry de Publicação Independente

Por que fazer isso?

Configuração em Ação

Você pode copiar este modelo diretamente:

Lembre-se de entregar o trabalho de proteger Tokens para variáveis de ambiente, nunca codifique Tokens diretamente no código!

# .npmrc
# Token de autenticação de nível de domínio geral (abrange todas as solicitações de instalação de nível de grupo e projeto)
//gitlab.com/:_authToken=${GITLAB_NPM_TOKEN}

# Para publicação: token de autenticação de nível de projeto (npm publish requer correspondência exata de caminho)
//gitlab.com/api/v4/projects/YOUR_PROJECT_ID/packages/npm/:_authToken=${GITLAB_NPM_TOKEN}

# escopo @company usa registry de nível de grupo
# Todos os pacotes @company/* serão instalados a partir deste registry
@company:registry=https://gitlab.com/api/v4/groups/YOUR_GROUP_ID/-/packages/npm/

# Outros pacotes públicos ainda vão para a biblioteca oficial
registry=https://registry.npmjs.org/

Configure o publishConfig no package.json para publicar o pacote no GitLab Project Registry correspondente.

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

Conclusão

Através da estratégia de “Group Registry de Download Unificado” e “Project Registry de Publicação Independente”, podemos reduzir significativamente os custos de manutenção e tornar o processo de desenvolvimento mais suave.

Dominando essas lógicas, o GitLab NPM Registry será um ajudante poderoso no processo de desenvolvimento da sua empresa!