Deploying Node Packages to GitHub Packages
Node.js is one of the most popular backend frameworks that is used extensively for developing web applications and APIs.
Like Python, Node.js can call upon a wide variety of libraries and packages hosted by a package manager called npm. The npm registry is a large public database of JavaScript software and packages from which packages can be download.
Npm is also a command line client which can be used to install, update, and uninstall packages among many other functions.
Node packages are typically minified JavaScript code contained in a project along with a package.json file. The package.json file is a config file written for all node projects, which specifies the name of the project, the author, and most importantly, the list of packages that indicate the project’s dependencies. You read that right, even node packages have dependencies on other packages and that can be coupled into a single node package. The version number mentioned in the package.json file is extremely essential while publishing a package.
But what does GitHub have to do with npm packages?
Before we answer that question, let us understand what Git and GitHub are.
Git is an open-source, distributed version control system designed for tracking changes in a project. It is popularly used for coordinating work among programmers collaboratively developing source code during software development. GitHub, simply put, is a cloud-based hosting service that helps you manage Git repositories.
Like the npm registry, GitHub has its own platform, called GitHub Packages, for managing packages, containers and other dependencies. GitHub Packages offers registries for commonly used package managers like npm, Apache Maven, RubyGems, Gradle, Docker and NuGet. The advantage of using GitHub Packages is it helps keep all the source code and packages in the same place and can be integrated with GitHub APIs, GitHub Actions and webhooks to create an end-to-end DevOps workflow.
Coming to our question posed above, we can manage our source code with versioning and publish our npm package with GitHub Packages. Without further ado, let us dive into deploying our Node packages on GitHub. In this article, we will be dealing with publishing private node articles.
The package.json
For the purpose of this article, we will assume that you have the source code for your package completed. As mentioned earlier, the package.json file is the most important file required while publishing your package. There are a few important points to be noted while writing your package.json file:
1. Package Name
While you may have already decided on a name for your package, there are a couple of things to keep in mind for the name:
- The package name must be the same as the repository name on GitHub.
- You will have to prefix the repository owner’s name followed by a forward slash(/) to the name of the package like so
2. Package Version
One of the most important points is the package version. You may follow any versioning system you want but adding the version is essential. Keep in mind that once you publish the package for the first time, you will need to change the version number in the package.json file for any further updates to the package.
3. Author
This is quite self-explanatory so be sure to add your name as the author.
4. Repository
An essential part of publishing to GitHub packages is mentioning the repository in which your source code is saved. Not giving this will throw an error when you try to publish your package. Once again, the name of the repository must be the same as that of your package.
5. Publish Config and Registry
Keeping the most important one for the last, mentioning the registry is of utmost importance if you want to publish your package to GitHub Packages. By default, the package will use the npm registry and hence the registry needs to be specified in the package.json file like so.
This line tells npm to publish the package in GitHub Packages registry and not the default npm registry.
Optionally, you can also add a license to your package. To know more about the various licenses, visit Licensing a repository — GitHub Docs.
To put it together, this is a basic idea of how your package.json file should look.
Once you complete the package.json and are ready to publish your package, commit and push the changes into your repository.
GitHub Actions
The next step to publishing your package is setting up GitHub Actions to automatically publish your package every time you commit changes to your repository. GitHub Actions is a tool provided by GitHub to automate software workflows.
To set up GitHub Actions, you need to create a YAML file which defines the processes to be executed as part of your workflow. Open your repository on GitHub and select Actions from the tab at the top.
On selecting Actions, you will get a screen like the one below.
You will notice that there is an existing GitHub Action in the Marketplace called “Publish Node.js Package to GitHub Packages”. You can configure this Action or you can choose to “set up a workflow yourself”.
In this article, I will show you a custom YAML file used to deploy packages. Please note that this custom YAML file is derived from the one in the Marketplace from which the testing part of deployment has been removed as it is out of the scope of this article.
The YAML file I have written is given below. You will find that the workflow is setup to run “on pushing” to the master branch. You can also setup other triggers which are explained here.
As part of the steps, we will be doing a checkout of the latest source code, followed by setting up version 16 of Node. You will notice here that the registry is specified again along with the scope or repository owner. Once Node is setup, we run a single command “npm publish” which reads the package.json defined earlier and publishes your package in the GitHub Packages npm registry.
The env parameter specifies the environment variable required to run this workflow. The environment variable required is the GITHUB_TOKEN secret which is already predefined and does not need to be added specifically. You can also add any additional environment variables required to run this code in the GitHub Action secrets and define them here.
Once you complete this, click on Start Commit and your Node Package should get published to GitHub Packages.
Installing the Published Node Package
Publishing your package is one step but installing it and importing it is equally important. A few things to be considered here is that your node packages are published under a private repository and hence requires authentication while installing the package.
If you have published the package in a personal account, only you will have access to this package. If you have published it from an organization account, all the members of your organization will have access to the package. For the authentication, you will need a GitHub Personal Access Token.
To create a Personal Access Token, click on your profile image to get a dropdown like the one shown in the image and click on Settings.
In the Settings page, on the left-hand side, click on Developer settings at the bottom and select Personal Access Tokens. On this page, click on Generate new token.
Fill in the necessary details along with the expiry and make sure to add read:packages to the scopes. Click on Generate Token. You will see the token on the next page. Save this token as the token will not be displayed again.
Once you get your token, open the project where you want to use this Node package. Add a .npmrc file to define the npm registry for the particular organization/owner. The content for your file will be as follows.
The purpose of this file is to inform npm which registry to look at, to retrieve your package. The ${PERSONAL_ACCESS_TOKEN} is an environment variable that needs to be defined with the value of your GitHub Personal Access Token. The command to create the environment variable is defined below.
Windows:
$env:PERSONAL_ACCESS_TOKEN = ‘your-github-personal-access-token'
Linux:
export PERSONAL_ACCESS_TOKEN=your-github-personal-access-token
Once you create the environment variable and the .npmrc file, you will have to add your package to package.json as a dependency.
On adding your package to the project dependencies, you need to install the dependencies using
npm install
This will install your package to your project.
What Next?
Once you create your first package version, you can add updates to your package and commit your changes to GitHub. This will trigger the GitHub Actions and will update your package version in the registry. Please note that you need to change your version number in the package.json file every time you update the package.
If you want to make static changes(README.md) to the package without affecting the source code and publishing the package again, you need to add a comment [skip actions] to avoid publishing the package again with the same version.
krtrimaIQ Cognitive Solutions is an agile start-up with the attitude and power of an enterprise, focused on applying Data Science, Cognitive Science and NextGen BI to build the Intelligent Enterprise. In Sanskrit, “krtrima” means “artificial”, and “IQ” is the Intelligent Quotient.
To know more about what we do, check out our website, and follow us on LinkedIn, and Twitter.
