Deixe o npm escolher o registro pelo escopo do pacote, não pela VPN

Conectar a VPN não deveria significar editar a configuração de registro do npm duas vezes por dia. Uma entrada de escopo num ficheiro de configuração ao nível do projeto pode enviar os pacotes da empresa para um registro e todo o resto para o público, sem comutações e sem uma substituição esquecida numa sexta-feira à tarde. O problema é que isto resolve apenas a nomenclatura; o roteamento, as credenciais e a precedência de configuração são três coisas separadas que falham cada uma à sua maneira.

Dois nomes, dois destinos

Um nome de pacote npm ou tem um escopo ou não tem. Um nome com escopo começa por um sinal @ e um identificador de escopo, e é esse identificador que a configuração pode mapear. Nada mais no pacote importa para o mapeamento. O registro nunca vê um pedido com base em o pacote ser interno ou público; vê apenas um nome.

Assim, o ficheiro abaixo expressa duas intenções em três linhas: os pacotes públicos vão para o registro público, e os pacotes sob o escopo da empresa vão para o registro da empresa com um token para esse host.

registry=https://registry.npmjs.org/
@acme:registry=https://packages.corp.example/
//packages.corp.example/:_authToken=${NPM_TOKEN}

Substitua o escopo, o host e o nome da variável pelo que a organização fornece realmente. A estrutura é o que importa, não os valores de exemplo. Duas linhas de configuração transportam toda a política, por isso vale a pena entendê-las em vez de as copiar.

Mantenha o mapeamento e a rede em compartimentos separados na cabeça. Uma entrada de escopo não pode tornar acessível um host inacessível, e um túnel a funcionar não pode dizer ao npm a que registro pertence um pacote.

Escreva o ficheiro na ordem correta

Coloque o ficheiro do projeto em primeiro lugar no seu raciocínio, embora o npm leia vários ficheiros. Um .npmrc no diretório do projeto é o que os seus colegas herdam através do repositório, por isso deve expressar a política partilhada e não o seu token pessoal. Esse ficheiro é também o que um revisor vai ler. Mantenha-o suficientemente pequeno para ser revisto num relance.

Deixe a linha registry predefinida a apontar para o registro público, a menos que a organização tenha decidido o contrário. Removê-la faz com que a máquina dependa do que diz o ficheiro ao nível do utilizador, e é exatamente esse o tipo de dependência implícita que produz resultados diferentes em dois portáteis.

A linha de escopo não é um curinga. Um nome fora do escopo continua a usar o valor predefinido, e é esse o comportamento que quer para cada dependência que não escreveu você mesmo.

Verifique para o que o ficheiro resolve antes de o confirmar, usando um nome de pacote descartável em vez de uma instalação real, para que um erro não custe nada.

As credenciais pertencem a um host, não a um projeto

As entradas de autenticação estão associadas a um host de registro e, onde o registro precisa, a um caminho. É por isso que a linha do token começa com a barra dupla e o host em vez do escopo. Assim que vir o host nessa posição, o resto da linha deixa de parecer pontuação arbitrária. É um endereço, e o token está ligado a ele.

Usar uma variável de ambiente mantém o token literal fora do ficheiro no repositório. Não torna o token invisível em todo o lado; continua a aparecer no ambiente do processo, e um comando que imprima a configuração pode revelá-lo.

Forneça a variável através do mecanismo local ou de credenciais de CI que a organização aprovar, e nunca cole um token real num exemplo que possa ser copiado para a documentação.

Se houver dois registros em jogo, cada um recebe a sua própria entrada. Uma única configuração de token não qualificada é, no melhor caso, ambígua e, no pior, enviada para o host errado.

Quando ganha o registro errado

A configuração é em camadas, e o valor em vigor não é necessariamente o valor no ficheiro que acabou de editar. As configurações do projeto, do utilizador, as globais e as variáveis de ambiente participam todas. É essa estratificação que faz uma correção funcionar na sua máquina e não no contentor de um colega. É também a razão pela qual vale a pena imprimir o valor efetivo antes de discutir sobre ele.

A variável de ambiente é o culpado habitual em CI, onde uma tarefa define o registro uma vez e cada passo seguinte herda-o. O segundo mais comum é um ficheiro ao nível do utilizador na máquina de um programador que substitui o que o repositório diz.

Imprima a configuração efetiva e o registro resolvido para um nome com escopo e outro sem escopo antes de depurar qualquer outra coisa. Se essas duas respostas são o que espera, o problema é a rede; se não são, o problema é a configuração e nenhum trabalho com a VPN ajudará.

Lista de verificação antes de confirmar

Confirme que o nome de escopo corresponde aos pacotes realmente publicados, que o registro predefinido é explícito e que a linha do token indica o host correto. Um erro de escrita no escopo produz a falha mais estranha de todas, porque o pacote resolve-se a partir do registro público e devolve o módulo de outra pessoa com o mesmo nome. Verifique o nome antes de depurar o token.

Confirme que o registro privado é acessível a partir da máquina no contexto que executa a instalação, não apenas a partir do seu navegador. Essa distinção importa quando um proxy ou um contentor tem um roteamento diferente do seu shell.

Depois confirme o comportamento num checkout limpo sem pacotes em cache. Uma instalação nova é o único teste que mostra o que um colega novo vai experimentar.