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:

 $ npm ls <package-name>

Run in Warp

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:

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


Run in Warp

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:

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

Run in Warp

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:

$ npm install /path/to/repository

Run in Warp

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:

$ npm install <url>#<branch>

Run in Warp

For example:

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

Run in Warp

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:

 $ npm install <url>#<hash>

Run in Warp

For example:

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


Run in Warp

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: 

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

Run in Warp

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:

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

Run in Warp

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:

$ npm login

Run in Warp

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:

$ git clone [email protected]:<user>/<repository>
$ cd <repository>

Run in Warp

Step 4: Publish your package on the registry

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

 $ npm publish

Run in Warp

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

 npm notice Publishing to https://registry.npmjs.org/
+ @username/[email protected]

Run in Warp

Step 5: Test your package

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

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

Run in Warp