Sitaram Rathi

Posted on Feb 28, 2022 • Edited on Jan 3

Private NPM package for internal use in your organisation using github package registry and github actions.

#javascript #node #github #npm

There are 3 things which we have to do for publishing our package successfully.

Configuring package.json of the package
Making and Configuring .npmrc file
Generating and adding github access token in your package repository

Step 1 :- Make a new github repository. If you want to keep your package private, create a private repository.

Step 2 :- Initialize a new node-js project in your local machine. Run npm init -y in your project directory to initialize the project with npm.

Step 3 :- Now you can install all additionally required packages using npm i <package-name>. For this tutorial, I have tried to install the dotenv package.

Step 4 :- Now configure the package.json file for your package as shown below.

{
 "name": "@your_github_username/your_package_repo_name",
 "version": "1.0.0",
 "description": "a test github package",
 "main": "index.js",
 "publishConfig": {
   "@your_github_username:registry": "https://npm.pkg.github.com"
 },
 "scripts": {
   "test": "echo \"Error: no test specified\" && exit 1"
 },
 "repository": {
   "url":"git://github.com/your_github_username/your_package_repo_name.git"
 },
 "author": "Your Name",
 "license": "ISC",
 "dependencies": {
   "dotenv": "^16.0.0"
 }
}

Replace your_github_username with your github account username, your_package_repo_name with the name of the repository that you made for your package, add your name as author and make sure to match the schema shown under publishConfig field.

Step 5 :- Now make a .npmrc file in the root of your package folder and add the following to it.

@your_github_username:registry=https://npm.pkg.github.com/

Replace your_github_username with your github username. Your folder structure will look like this.

Step 6 :- Make .gitignore, Readme.md and index.js and add relevant content to them.

Step 7 :- Now in my index.js I’ve added below code to use my testFunc Function in any other github repo. You can export as many functions as you want from module.exports to use in other projects from your published github package.

require("dotenv").config()

module.exports.testFunc = (name) => {
   console.log(`Hello ${name}! From test pkg`)
}

Step 8 :- Make a folder named .github and make another folder named workflows inside it. Now make a yaml file inside workflows with the name npm-publish-github-packages.yml. Your directory structure should look something like this

Step 9 :- Paste the following in the npm-publish-github-packages.yml file.

name: your_package_repo_name

on:
 push:
   branches:
     - master

jobs:
 publish-gpr:
   runs-on: ubuntu-latest
   steps:
     - uses: actions/checkout@v2
     - uses: actions/setup-node@v1
       with:
         node-version: 16
         registry-url: https://npm.pkg.github.com/
         scope: '@your_github_username'
     - run: npm install
     - run: npm publish
       env:
         NODE_AUTH_TOKEN: ${{secrets.NODE_GITHUB_TOKEN}}

Replace your_github_username with your github account username, your_package_repo_name with your github package repo name which you made. I’ve chosen my master branch on which github action is runned to publish my package whenever code is pushed in it, you can go with it or choose any other branch by entering its name in place of master.

Step 10 :- Now as you can see in the last line of your yaml file we are using secrets.NODE_GITHUB_TOKEN to give permissions to github action for read, write and publish our package and for that we need to add a secret token in the secrets of your package github repo and for it let’s first generate our token. Go to your github account settings in it’s sidebar and at the very bottom you will find Developer settings .

After clicking Personal access tokens select Generate new token button.

Step 11 :- In the Note Input add any name of your choice like - github-package-generating. From the expiry dropdown, select your use case time after which you want your token to expire. If you want to use your package for a long time you can select No expiration. In the permissions below checkmark permissions for repo and write:packages as shown below.

Now click on generate token and copy your token. Make sure to save it somewhere safely as we’ll need it in future.

Step 12 :- Open your github package repo and go to its Settings.

In the repository settings sidebar under Secrets dropdown, select Actions as shown below.

Now click on the New repository secret button and you will see these input fields.

Now in the Name input field Enter Name as NODE_GITHUB_TOKEN and in the Value input field paste your github access token which you generated in the last step.

We are done with the 3 important steps for publishing your github package.

Before publishing your package make sure you read about Semantic Versioning and change your package’s version name in package.json whenever you push your code to the master branch and republish it.

Now commit your code, add your github repo remote url and push your code with the origin branch as master. If you perform the above steps correctly you will see the github action running on master branch and your package will be published successfully and you’ll see a green checkmark next to your github action if it ran successfully.

Your package is now published. Now let’s see how to use it in your projects.

Step 1 :- Add .npmrc file in your project’s root directory where you want to use your package and add the following lines in it. Remember to update your_github_package_account_username with the username of github account under which that package is published and your_github_read_access_token with the access token which you can generate from your Github Developer Settings in the same way we generated a token above. Enable the read:packages permissions. You should now be able to install your published package in your project.

NOTE :- If your project repo is under the same github account in which your package is published, you can use the same github token that you used to publish your github package.

@your_github_package_account_username:registry=https://npm.pkg.github.com/
//npm.pkg.github.com/:_authToken=your_github_read_access_token

Step 2 :- You can install it in your project using the methods below.
Install from the command line:

npm install @your_github_username/your_package_name

Or this to install a specific version

npm install @your_github_username/your_package_name@version

Replace your_github_username with your github username, your_package_name with your published package name and version with the published version of your package. i.e. npm install @srrathi/my-package@1.3.0

Install via package.json:
Adding below in your package.json dependencies.

"@your_github_username/your_package_name": "version"

And that’s it !. If you face any issues regarding the above please comment below. I’ll try my best to resolve it.

😄 About Me

I’m Sitaram Rathi, a Full-stack Developer focused on back-end development. I'm pursuing my B.Tech in CSE from Nit Hamirpur. I love working on projects and problems which make me push my limits and learn something new. You can connect with me here.