Use Bitbucket for hosting private npm modules

Nodejs

Goal of this tutorial: Show you how to add a Node module as an NPM dependency from a private bitbucket repository. This solution is team friendly meaning it works when you have multiple people on your team. Hopefully I can save you some money by preventing you from buy github private organization access or NPM's private module service. Skip to installation section to get straight to the solution.

Estimated Reading: 10-15 minutes

Overview

For my latest project, I wanted a config repo that could be shared across many different modules. I needed an npm module that could used across any of the 3 web apps and amongst the multitude of microservices for the project.

Attempted Solution

At first I tried adding this line to the depencies list in package.json:

"flightfutres-config": "git+https://[email protected]/flightfutures/flightfutures-config.git",

This seemed to work fine at first. As long I was logged into the git account for dontmesswithabeer, I was able to download the package just fine. The problem arose when I my teammates tried to set up the development environment. Since I obviously wasn't going to give them my git credentials and if everyone changed the username in the link, we'd all have different package.jsons and that would get annoying real quick. I had to find another solution.

Solution

Use SSH keys. SSH keys allow you to generate a private public key on your computer and register your public key on the private repositiory. Multiple public keys can be registered, meaning the solution works for multiple teammates and the link is the same for everyone trying to download using SSH.
https://superuser.com/questions/121307/is-it-reasonable-to-have-multiple-ssh-keys

This is how you add the private SSH dependency in your pacakge.json:

"flightfutures-config": "ssh://bitbucket.org/flightfutures/flightfutures-config.git"

Now follow these instructions to add you SSH Key to the private repository you wish to use as a dependency. Anyone who wants to use this repo as a dependency needs to register their ssh key.

Better Security

I decided that since I already have two active git accounts with sensitive information, and have also registered my keys for other purposes, I wanted to have a more secure solution. Instead of sharing my existing public key, I created a node module that utilizes some bash scripts to setup my bitbucket project specific key. Here's a discussion on the security of multiple SSH keys and here's the github for the module I made.

How it works

Hooks into npms preinstall. Before installing new npm packages, npm will run a script inside of the bitbucket-private-npm module that sets your project-ssh-key file to the primary ssh key by creating a ~/.ssh/config file. This file says use project-ssh-key when making an ssh conection with bitbucket.org. If there was already an existing config file, it is copied and moved into a temporary file. Now npm can download your private dep. After npm install runs, a cleanup script in the module is executed by adding a hook to postinstall. This hook simply cleans up any changes the preinstall script made to you're ~/.ssh folder. If you don't have a project specific key, the bitbucket-private-npm module will walk you through creating one.

Installation

First add the module to your dependencies.

npm i -S bitbucket-private-npm

Next add your private module to the optionalDependencies of your package.json. We use an optional dependency because on first npm install the bitbucket-private-npm module will not be installed yet and thus can't be used in the pre and post install hooks. The optionalDependency will not cause a process exit when the dependency fails to install.

  "optionalDependencies": {
    "flightfutures-config": "ssh://bitbucket.org/flightfutures/flightfutures-config.git"
  },

Next add these lines to your scripts in package.json, create the scripts key if you don't have it already. Replace flightfutures with the name of your project. The name of your project determines the filenames for the SSH keys. So if your project name is flightfutures, your keys will be saved as flightfutures-bitbucket.pub and flightfutures-bitbucket.

  "scripts": {
    "setupssh": "bpn=./node_modules/bitbucket-private-npm; [ -d $bpn ] && node $bpn setupSsh flightfutures || echo 'bitbucket-private-npm not installed yet'",
    "cleanupssh": "bpn=./node_modules/bitbucket-private-npm; node $bpn cleanupSsh flightfutures",
  }

Now run npm i and it will eventually walk you through creating your new SSH key-pair and adding it to bitbucket. Try npm i --ignore-optional if you're having any issues. Once you finish creating your keys, npm will finish. Run npm install once more to download the private package. That's it!