Imagine que você é um chef executivo. Para garantir que todos os restaurantes da sua rede produzam os mesmos pratos deliciosos, você desenvolveu uma série de “molhos secretos”. Você deseja que esses molhos sejam enviados para cada filial, mas não pode permitir que qualquer transeunte os leve embora.

No mundo do desenvolvimento de software, esses molhos secretos são os “pacotes privados” internos da empresa.

À medida que os projetos crescem, é provável que você tenha experimentado essa frustração: duplicar o mesmo componente de interface de usuário ou função utilitária em cada projeto, ou lutar com Git Submodules até questionar suas escolhas de vida. Na verdade, tudo o que você precisa é de uma “Despensa Privada (Private NPM Registry)”. Hoje, discutiremos como usar o pnpm para publicar pacotes no GitLab, para que os membros da equipe possam instalá-los como pacotes de código aberto com um único comando.

Por que você precisa de Pacotes Privados e Scopes?

No universo do Node.js, os pacotes privados devem ter um “sobrenome” — este é o Scope.

Por exemplo, se a sua empresa se chama @my-company, o nome do seu pacote pode ser algo como: @my-company/ui-kit. Com esse sobrenome, quando o pnpm o vir, ele não procurará sem rumo no npmjs.org. Em vez disso, ele irá direto para os pontos de coordenação especificados pela sua empresa.

Decisão Chave: Group Level vs. Project Level

No GitLab, isso é como decidir onde armazenar seus temperos:

Configurando o “Passaporte”: Access Tokens e Variáveis de Ambiente

Para entrar no celeiro subterrâneo, primeiro você precisa obter um “cartão de acesso”.

1. Vá para Settings > Access Tokens no GitLab.
2. Solicite um Token, marcando as permissões read_api (para download) e write_package_registry (para publicação).
3. Importante: Assim que tiver o Token, nunca o escreva diretamente no seu código ou arquivo .npmrc! Isso é como deixar a chave do cofre na porta.

A abordagem mais profissional é escondê-lo em “variáveis de ambiente”. Adicione esta linha ao seu terminal Mac ou Linux (por exemplo, ~/.zshrc):

export GITLAB_TOKEN="seu_token_do_GitLab"

Dessa forma, o sistema anexará automaticamente as credenciais para você, tornando-o seguro e conveniente ao mesmo thời.

Configurações de Navegação: A Essência do .npmrc

Em seguida, criaremos um mapa de navegação, .npmrc, na raiz do projeto para dizer ao pnpm para onde ir:

# Para qualquer coisa que comece com @my-company, vá para o GitLab
@my-company:registry=https://gitlab.com/api/v4/groups/<YOUR_GROUP_ID>/-/packages/npm/

# Configure a autenticação do cartão de acesso (lendo a variável de ambiente que acabamos de definir)
//gitlab.com/api/v4/groups/<YOUR_GROUP_ID>/-/packages/npm/:_authToken="${GITLAB_TOKEN}"

Basta trocar o Group ID da sua empresa e o caminho estará pavimentado!

A Milha Final Antes da Publicação: A Arte do Empacotamento

Muitas pessoas correm para publicar depois de configurar a conexão, apenas para carregar acidentalmente arquivos de teste ou até mesmo configurações secretas. É aqui que o campo files no package.json se torna útil.

Este é um conceito 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, recomenda-se usar o comando pnpm pack para desempacotar e verificar o conteúdo localmente. Quando tudo parecer bem, execute o pnpm publish com confiança!

Conclusão

Construir uma despensa privada não é difícil. As chaves são:

1. Solicitar um Token e protegê-lo com variáveis de ambiente.
2. Configurar o mapa de navegação .npmrc correto.
3. Usar o campo files no package.json para um envio preciso.

Ao dominar este fluxo de trabalho, você pode tornar a reutilização de código da sua empresa profissional, segura e elegante. Agora, vá construir sua própria cozinha central!

Reference

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