Install NPM Packages From GitHub

When working with Node.js, it may happen that the package, or package version, you're looking for has not (yet) been published on the npm registry, but its source code is publicly available on a hosting platform such as GitHub.

Similarly, you may have created a private package hosted on GitHub that you don't want to make publicly available by publishing it on the npm registry.

The short answer

To install a public or privately owned package available on GitHub in an existing project, you can use the npm install command with the URL of the remote repository as follows:

Which will, under the hood, download the repository and all of its submodules on your local machine using the git clone command, and add it to the dependencies object of the  package.json file located at the root of your project.

For example:

Note that you can also use, as an alternative to the https protocol, any of  git, git+ssh, git+https, or git+file.

For example:

Installing a package from a locally cloned repository

Alternatively, if you’ve already cloned the repository on your local machine, you can install it within your project using its relative or absolute path as follows:

Note that if the repository sits outside the root of your project, npm will not install the package dependencies in the node_modules directory of the project, but will create a symbolic link to the repository’s directory instead.

Also note that when deploying your project on a different machine, running npm install is likely to fail if the repository is not re-cloned at the same location specified in the package.json file.

Installing a package version based on a GitHub branch or a commit

When working with remote repositories, the npm install command will, by default, download and install the latest commit on the main branch (or master) of the repository.

To install the latest commit of another branch instead, you can specify which branch to use with the following syntax:

For example:

Installing a specific version using a commit hash

To install a package version based on a specific commit, you can specify the commit hash as follows:

For example:

Installing a specific version using semantic versioning

To install a package version based on a specific tag or tag range, you can specify a semver expression as follows:

Which will make npm look for any tags matching that range in the remote repository, as it would for a package published on the npm registry.

For example:

Publishing a package from GitHub to the npm registry

If you’re the owner of a repository containing a valid npm package, you can publish it on the npm registry using the following steps.

Step 1: Create an npm account

First, create an account on the npm platform by visiting the following link: https://www.npmjs.com/signup.

Step 2: Log in to your account

Log in to your account using the npm login command:

Which will generate an .npmrc file in your home directory containing your npm credentials.

Step 3: Clone the package repository

Clone the package repository on your local machine using the git clone command and navigate into it using the cd command:

Step 4: Publish your package on the registry

Upload your package on the npm registry using the npm publish command:

Which should generate the following log confirming that the package has been successfully published.

Step 5: Test your package

Verify that your package is working by installing it using the npm install command: