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 [.inline-code]npm install[.inline-code] command with the URL of the remote repository as follows:

 $ npm ls <package-name>

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

For example:

{"dependencies": {
    "express": "https://github.com/expressjs/express"
  }
}

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

For example:

$ npm install git+ssh://github.com/expressjs/express

[#install-locally-cloned-package]Installing a package from a locally cloned repository[#install-locally-cloned-package]

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:

$ npm install /path/to/repository

Note that if the repository sits outside the root of your project, [.inline-code]npm[.inline-code] will not install the package dependencies in the [.inline-code]node_modules[.inline-code] 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 [.inline-code]npm install[.inline-code] is likely to fail if the repository is not re-cloned at the same location specified in the [.inline-code]package.json[.inline-code] file.

[#remote-package-by-branch]Installing a package version based on a GitHub branch or a commit[#remote-package-by-branch]

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

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

$ npm install <url>#<branch>

For example:

$ npm install https://github.com/expressjs/express#develop

[#remote-package-by-commit]Installing a specific version using a commit hash[#remote-package-by-commit]

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

 $ npm install <url>#<hash>

For example:

 $ npm install 
https://github.com/expressjs/express#f540c3b0195393974d4875a410f4c00a07a2ab60

[#remote-package-by-tag]Installing a specific version using semantic versioning[#remote-package-by-tag]

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

 $ npm install <url>#semver:<semver>

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

For example:

 $ npm install https://github.com/expressjs/express#semver:4.18.2

[#publish-to-npm-registry]Publishing a package from GitHub to the npm registry[#publish-to-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 [.inline-code]npm login[.inline-code] command:

$ npm login

Which will generate an [.inline-code].npmrc[.inline-code] 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 [.inline-code]git clone[.inline-code] command and navigate into it using the [.inline-code]cd[.inline-code] command:

$ git clone git@github.com:<user>/<repository>
$ cd <repository>

Step 4: Publish your package on the registry

Upload your package on the npm registry using the [.inline-code]npm publish[.inline-code] command:

 $ npm publish

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

 npm notice Publishing to https://registry.npmjs.org/
+ @username/my-package@1.0.0

Step 5: Test your package

Verify that your package is working by installing it using the [.inline-code]npm install[.inline-code] command:

 $ npm install --save @username/my-package