Private NPM repository, Github Packages and Heroku

It took a while to put together this simple, on the first look, combination.

Problem: Node project, hosted on Heroku, that needs access to a private NPM repository on Github.

Solution that worked for me is below. I will use fake repository name @foo/bar in this guide where foo - organization/user name on Github, and bar - a repository name, e.g. https://github.com/foo/bar

1. Publish private NPM repository on Github Packages #

Generate a new personal access token (PAT) on Github #

It will be used to authenticate the private package in your consumer project. To create a PAT got to go to Settings -> Developer Settings > Personal Access Token -> Generate new token.

Select the scopes of repo, write:packages and click on the Generate token button.

Make sure to save this token in a secure place, e.g. your password manager - you will need it later.

Modyfy your private repo's package.json: #

Add name and semantic version, if it's not there yet:

  "name": "@foo/bar",
  "version": "1.0.0",

Add registry information:

  "publishConfig": {
    "registry": "https://npm.pkg.github.com/foo"
  },
  "repository": {
    "type": "git",
    "url": "ssh://git@github.com:foo/bar.git",
    "directory": "@foo/bar"
  }

Add .npmrc file #

The private repository needs to configure an alternate registry with access tokens - Github Packages in our case. Create .npmrc config with the following content:

; Use NPM registry by default
//registry.npmjs.org/

; GitHub Packages registry for your org's packages
@foo:registry=https://npm.pkg.github.com/
//npm.pkg.github.com/:_authToken=${NPM_AUTH_TOKEN}

Add the personal access token #

Make sure your environment has NPM_AUTH_TOKEN variable - the toke from step 1, you can use the following command to export it:

export NPM_AUTH_TOKEN=token

Publish your package #

To publish your package you will need to login to Github Packages with your Github user's credentials on your local machine:

npm login --scope=@foo --registry=https://npm.pkg.github.com

Once logged in, type npm publish, then you will be able to find your package under Packages tab in your organization homepage on Githib, or https://github.com/orgs/foo/packages

2. Include private repository in your consuming project #

Add .npmrc file in your project #

Copy .npmrc file from your private repository (step 1.3) to you consuming project (same content).

This file tells NPM to build packages belonging to @foo from a custom registry.

Add the token #

Make sure your environment has NPM_AUTH_TOKEN (your personal access token from step 1):

export NPM_AUTH_TOKEN=token

Install your private package #

npm install @foo/bar

It should like the following in your package.json:

  "dependencies": {
    "@foo/bar": "1.0.0"
  }

Use a package in you code #

Now you should be able to use this repository in your code:

import Module from "@foo/bar/path/to/module";

3. Enable on Heroku #

According to Heroku documentation to enable access to private NPM package on Heroku you need:

  1. .npmrc file (which we already added to your project in previous step)
  2. adding the token as a config var in your Heroku app

Go to Dashboard -> your app -> Settings -> Config Vars and add NPM_AUTH_TOKEN and its value.

4. Enable on Github Actions #

Add access token to Github actions (if actions are used):

Modify action config #

Add the environment variable into your action .yml file:

env:
  NPM_AUTH_TOKEN: $

Add token to Github secrets #

Go to Organization -> Settings -> Secrets -> Actions on Github and add a new secret NPM_AUTH_TOKEN with your personal access token value.

Links: