1. Overview
npm is a package management tool that allows us to install libraries, frameworks, and other tools when working with JavaScript. With npm, we can easily access publicly published Node.js projects for development. However, not all packages are available in the npmjs registry.
In this tutorial, we’ll explore how to install an npm package directly from a public GitHub repository.
2. Prerequisites
Before we begin, let’s ensure we’ve installed node.js, npm, and git.
We should note that a GitHub account is necessary if we’re using npm packages from GitHub private repositories.
2.1. Installing node.js and npm
Before we proceed, let’s update our system’s installed packages first:
$ sudo apt update
This helps ensure that we’re using the latest versions.
Let’s now install node.js and npm:
$ sudo apt install -y nodejs npm
Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
The following packages were automatically installed and are no longer required:
...
2.2. Installing git
Installing git on a Debian Linux system is straightforward:
$ sudo apt install -y git
...
Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
The following packages were automatically installed and are no longer required:
This command installs git on our system. In addition, the -y option automatically approves any prompts, making the installation process faster.
3. Basic npm Installation From GitHub
Installing an npm package directly from a GitHub repository enables us to access and use the latest code even before it’s available on the npm registry. This can be particularly handy for testing or debugging new features that have only been committed to the repository.
Using the npm tool, we can install a Node.js project from a public GitHub repository as a dependency. For example, we can use the latest code for express.js. Let’s see how to do it.
3.1. Using HTTPS URL
First, let’s install an npm package from a GitHub repository using an https URL:
$ npm install https://github.com/expressjs/express
added 67 packages in 16s
12 packages are looking for funding
run `npm fund` for details
The output from the example indicates that we’ve successfully installed the express.js package from its GitHub repository using npm. Also, it says that the number of packages installed is 67.
3.2. Using git URL
Alternatively, we can use the git URL format. The git URL achieves the same result as the HTTPS URL method. However, it uses a special URL format:
$ npm install git+https://github.com/expressjs/express
up to date, audited 68 packages in 9s
12 packages are looking for funding
run `npm fund` for details
found 0 vulnerabilities
Aside from the successful installation, the output shows an audit confirming that the installed packages are up-to-date. Moreover, it also performed a security check on the existing packages, discovering 0 vulnerabilities.
3.3. Using Shortcut URL
Additionally, npm supports a shortcut URL format. For example, let’s use a shortcut URL format to install express.js from GitHub:
$ npm install expressjs/express
...
This method performs the same action as before. It assumes that we’re referring to a repo on github.com.
4. Advanced Installation From a Branch, Tag, or Commit
Sometimes, we may need to install a specific version, like a branch, tag, or commit of a package.
With npm, we can use the branch name of the GitHub repository to install a branch as a package. This can be achieved by appending the branch name to the URL after a hash symbol. For example, let’s install the release-branch-diagram branch:
$ npm install https://github.com/expressjs/express#release-branch-diagram
The package was successfully installed from the release-branch-diagram branch on the express.js GitHub repository.
We can apply the same pattern for tags:
$ npm install https://github.com/expressjs/express#4.18.0
And, to install a commit, we use its SHA:
$ npm install https://github.com/expressjs/express#d97d79ed9a25099ec4f0537ad8bf2a9378350a6b
5. npm Installation From a Private GitHub Repository
We can also install an npm package from a private GitHub repository, but there are a few prerequisites. First, we need to have a GitHub account with appropriate permissions for the repository. Additionally, we need to authenticate to GitHub using either a Personal Access Token (PAT) or Secure Shell (ssh) to ensure a successful installation.
5.1. Using a GitHub Personal Access Token
To install packages from a private repository, we need to configure npm to use our GitHub token. We can achieve this by creating a .npmrc file in the root directory of the project and adding the following configuration line:
$ sudo echo "//npm.pkg.github.com/:_authToken=github_pat_11BGNPQCQ0FQH52tVAPSkO_" > .npmrc
This configuration line tells npm to use github_pat_11BGNPQCQ0FQH52tVAPSkO_ as the token when accessing npm.pkg.github.com for installing packages.
Next, let’s install the npm package from a private repository:
$ npm install git+https://github.com/EbukaNduka/Data_Converter.git
changed 1 package, and audited 81 packages in 26s
12 packages are looking for funding
run `npm fund` for details
...
Here, the npm package was installed within the .npmrc file environment. However, directly including the PAT in the URL of the repo is also possible:
$ npm install https://[email protected]/EbukaNduka/Data_Converter
5.2. Using ssh
Alternatively, we can use ssh to install an npm package from a private repository. However, to do this, we first need to generate an ssh key pair:
$ ssh-keygen -t rsa -b 4096 -C "[email protected]"
Generating public/private rsa key pair
...
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /home/kali/.ssh/id_rsa
Your public key has been saved in /home/kali/.ssh/id_rsa.pub
The key fingerprint is:
...
After generating the ssh keys, we need to add the public key to the GitHub repository. This action ensures secure authentication when accessing the private repository.
Now, let’s retrieve the public key:
$ cat ~/.ssh/id_rsa.pub
ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAACAQCYlOMMBC8XBB9Gg4ikb2SGc8l+FZyQr7zEXv1NvRKeOQfwZzoLJA5YQhM9coufNcts/qs0WBEfqqfRJyWYwjSTMC5MKaMZPfKRxkDgkgxmIvo1fv7nko1TsMIdSXRyIrthUoM3fLBvh1EJ1s2iuBcEEOQKQMD1dOlyelMt2Updwp4EJHeY16Aou8IOmuH6Zuw/M3pvZUaO+Ed6WlqAtidW8JpWTZYIi+065Th3skxBEep7lLBaAjQ1MscsiLKV== [email protected]
After our ssh key is added and authenticated, let’s now proceed to install the npm package:
$ npm install git+ssh://[email protected]:EbukaNduka/Data_Converter.git
changed 1 package, and audited 81 packages in 19s
...
After executing the command, npm clones the repository using ssh and installs the package along with its dependencies on our machine.
6. GitHub vs. Regular npm Dependencies in package.json
Regular npm dependencies and those from GitHub serve the same function. They install the required packages on our local machine. However, they differ in how they are referenced in the package.json file and where npm fetches them from.
Let’s see an example showing how regular dependencies look in the package.json file:
$ cat package.json
...
],
"license": "MIT",
"repository": "expressjs/express",
"homepage": "http://expressjs.com/",
"keywords": [
"express",
"framework",
"sinatra",
"web",
"http",
"rest",
"restful",
"router",
"app",
"api"
],
...
On the other hand, let’s see how dependencies from GitHub look in the package.json file:
$ cat package.json
{
"dependencies": {
"express": "github:expressjs/express#d97d79ed9a25099ec4f0537ad8bf2a9378350a6b"
}
}
From the first example, we can see that the dependencies were installed directly from the npm registry. In contrast, the second example shows a dependency being installed from a GitHub repository. This includes the repository URL and a specific branch, tag, or commit hash.
7. Conclusion
In this article, we covered several ways to install npm packages directly from a public and private GitHub repository.
We saw how to install a specific version, including a branch, tag, or commit of a package.