Skip to main content

NPM com SSH | NPM

Como usar repositórios Git privados como módulos NPM

💡 Usando repositórios Git privados como módulos NPM​

Uma das funcionalidades mais interessantes — e pouco conhecidas — do NPM é a capacidade de instalar repositórios Git diretamente através do comando:

npm install git+ssh://<username>@<hostname>:<path>

🚨 O problema​

Quando você instala pacotes dessa forma, o nome de usuário SSH é salvo dentro do arquivo package.json, o que torna essa dependência inutilizável para o restante da equipe.

Por exemplo, após executar o comando acima, o seu package.json pode ficar assim:

"dependencies": {
  "lodash": "^4.0.0",
  "privateModule": "git+ssh://dudemullet@server.com"
}

📌 Exemplo de package.json com dependência de repositório Git privado.

O problema é que, se esse package.json for commitado, outros desenvolvedores não conseguirão rodar npm install, pois não terão as credenciais SSH do usuário dudemullet.

🧭 A solução: ajudando o SSH​

A dica está no protocolo da URL: git+ssh. O NPM está utilizando duas ferramentas diferentes — Git e SSH — para acessar o conteúdo do módulo. Logo, se conseguirmos acessar o módulo sem precisar colocar as credenciais na URL, o problema estará resolvido.

Felizmente, o SSH possui uma maneira muito prática de configurar isso: o arquivo ~/.ssh/config.

⚙️ Exemplo de configuração ~/.ssh/config​

# Este é um comentário
Host server.com
    User foo
    HostName server.com
    IdentityFile ~/.ssh/foo

Com esse arquivo de configuração, podemos executar:

ssh server.com

E o SSH saberá que deve conectar-se ao host server.com usando o usuário foo e a chave privada ~/.ssh/foo.

Agora, o verdadeiro benefício é que também podemos executar:

npm install -s git+ssh://server.com:/path/to/privateModule.git

E o package.json será atualizado com:

"dependencies": {
  "lodash": "^4.0.0",
  "privateModule": "git+ssh://server.com:/path/to/privateModule.git"
}

🎉 Sem nomes de usuário ou credenciais no código!

⚠️ O ponto de atenção​

Neste ponto, você provavelmente está feliz por ter resolvido um problema enorme, mas há um detalhe importante:

Todo desenvolvedor que utilizar esse método precisa ter o mesmo alias configurado no arquivo ~/.ssh/config.

Caso contrário, o SSH não saberá quais credenciais usar para qual servidor ¯*(ツ)*/¯

📌 Importante: Isso não significa que os desenvolvedores devem compartilhar suas chaves privadas!

🧑‍💻 Exemplo de configurações diferentes entre desenvolvedores​

Dev1 – ~/.ssh/config

Host server.com
    User foo
    HostName server.com
    IdentityFile ~/.ssh/myIdentityFile

Dev2 – ~/.ssh/config

Host server.com
    User foo
    HostName server.com
    IdentityFile ~/.ssh/id_rsa

Host github.com
    User bar
    HostName github.com
    IdentityFile ~/.ssh/id_rsa

✅ Cada desenvolvedor mantém suas próprias chaves privadas, mas compartilham a mesma configuração de alias (server.com), permitindo instalar os módulos privados corretamente.

🏷️ Versionamento​

Há uma diferença importante quando usamos este método: Como estamos instalando diretamente de um repositório Git, não podemos usar versionamento semântico (semver) como ^1.0.0.

Em vez disso, precisamos especificar uma referência Git — chamada de commit-ish, que pode ser:

  • um branch
  • um hash de commit
  • uma tag

🔖 Exemplos de instalação com referência (commit-ish)​

Instalar a versão que o branch dev aponta:

npm install --save git+ssh://server.com:/path/to/privateModule.git#dev

Instalar a versão apontada pela tag v1.0.4:

npm install --save git+ssh://server.com:/path/to/privateModule.git#v1.0.4

Instalar a versão específica de um commit:

npm install --save git+ssh://server.com:/path/to/privateModule.git#1b1d8f5

📚 Informações úteis​

🧩 Em resumo:

  • Evite colocar credenciais SSH diretamente no package.json.
  • Configure aliases no ~/.ssh/config.
  • Use referências Git (branch, tag ou commit) em vez de versões semver.
  • Cada dev mantém suas chaves privadas, mas compartilha os mesmos aliases.