How to publish a new npm package on the GitHub Registry, and what is the difference between NPM and GitHub Registry?

GitHub + NPM

How to publish a new npm package on the GitHub Registry, and what is the difference between NPM and GitHub Registry?

Publish and install the package from Github Registry with the help of NPM, YARN and PNPM.

The Github Registry provides similar functionality to npmjs. In other words, you say Github Registry is a strong alternative to the npmjs registry.

There is no big difference between NPM and GitHub Registry. The basic difference is pricing and managing code. In the NPM Registry, you can not manage code like GitHub. GitHub provides many features like GitHub action, Integrated IDE, issue or bug handling, discussion, etc. It gives you flexibility, and other hand NPM does not do that.

Why developer does not use GitHub Registry?

The main reason is NPM Registry is more popular compared to GitHub Registry.

If you use GitHub Registry in your project, you need some configuration, which creates fear among developers.

Who can use GitHub Registry?

According to My experience, if you have a small or big organization, Startup or company and you, your team and your company built a tool or software for the open source community, then no doubt, NPM Registry is a good fit.

But if you and your team build software for personal use, Github Register is a Good choice. In one Githhub paid plan, you handle so much stuff and do not need to pay an extra amount to NPM.

How to publish a new npm package on the GitHub Registry

Publishing a new package on GitHub Registry is similar to NPM Registry. But the only key difference between NPM and Github Registry is a login.

Steps

· Create a demo NPM package
· Log in with Github Registry
· Genrate the Github Token
· Configuration or integration of GitHub Registry
∘ Package.json file
∘ .npmrc file
· Publish the NPM package on Github Registry
∘ How to found NPM to publish the package on GitHub?
· How to update the package?
· Setup GitHub Action
· How to Add Environment variables in Github Repository.
· How do you Install the NPM package from Github Registry?
∘ Installation Setup
∘ Config NPM package path or location in .npmrc
∘ Where we find the NAMESPACE
∘ Login to Your GitHub registry account
· Conclusion

Create a demo NPM package

Firstly we create a demo NPM project and publish it on Github Registry.

1. Firstly Create a new empty mkdir demo-dithub-registryfolder
2. then enter cd demo-dithub-registry folder using cd command
3. run npm init command to create a basic structure for the demo project.

{
  "name": "@frontendweb3/demo-github-registry",
  "version": "1.0.0",
  "description": "demo npm package to publish on github registry",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "repository": {
    "type": "git",
    "url": "https://github.com/frontendweb3/demo-github-registry.git"
  },
  "keywords": [
    "demo"
  ],
  "author": "Rajdeep singh",
  "license": "MIT",
  "bugs": {
    "url": "https://github.com/frontendweb3/demo-github-registry/issues"
  },
  "homepage": "https://github.com/frontendweb3/demo-github-registry#readme"
}

Inside the demo folder, create a new index.js file with the following code.

// index.js 

export function demo() {
  console.log("hello from github registry");
}

Then run git init command inside the project to initialize the git. Git is the version control system or software.

You can also create a readme.md file in your project.

Log in with Github Registry

Before publishing the package on the GitHub registry, we must log in first with the following command. Otherwise, you can not publish your package on the GitHub registry.

npm login --scope=@githubusername --registry=https://npm.pkg.github.com

The scope contains a GitHub personal or origination username. It tells GitHub where you publish the package on GitHub personal or origination account.

$ npm login --scope=@frontendweb3 --registry=https://npm.pkg.github.com
npm WARN adduser `adduser` will be split into `login` and `register` in a future version. `adduser` will become an alias of `register`. `login` (currently an alias) will become its own command.
npm notice Log in on https://npm.pkg.github.com/
Username: officialrajdeepsingh
Password: 
Email: (this IS public) radewala.2@gmail.com
Logged in as officialrajdeepsingh to scope @frontendweb3 on https://npm.pkg.github.com/.

The Github Password is not working; you need a GitHub token. Without a token, you can not log in with the Github registry.

Genrate the Github Token

Firstly goto setting > click on developer setting button

Create a token for the GitHub registry

Click the Tokens ( classic ) button.

Create a token for the GitHub registry

Click on generate new toke and then click the classic button again

Create a token for the GitHub registry

Enter basic information like name, Expiration date and most importantly, give the package to read and write permission.

Create a token for the GitHub registry.

The last step is copying and using the GitHub token to log in with the GitHub registry and save your token for further use.

Configuration or integration Github Registry

For configuration, we need to change two places.

1. Package.json file
2. .npmrc file

Package.json file

By default npm publish command publish your package on the NPM registry. To change the default registry, we need to add some additional properties in package.json file.

Make sure to define the publishConfig property inside the package.json file. publishConfig take the registry URL.

// package.json
 
{
  
  "publishConfig": {
    "registry": "https://npm.pkg.github.com/your-or-orgination-username"
  },
 
 }

For example, My organization registry URL looks like this.

"registry": "https://npm.pkg.github.com/frontendweb3"

.npmrc file

Inside your root folder, create a new .npmrc file and then paste two lines of code in your .npmrc .

registry=https://npm.pkg.github.com/your-or-orgination-username
//npm.pkg.github.com/:_authToken=Paste-Your-Copy-Token-Here

Now your configuration is complete. The part is to publish the package on the GitHub registry.

Publish the NPM package on Github Registry

Now the time is to publish our package on the GitHub registry for that run npm publish command.

The npm publish command output look like this.

$ npm publish
npm notice 
npm notice 📦  @frontendweb3/demo-github-registry@1.0.0
npm notice === Tarball Contents === 
npm notice 72B  index.js    
npm notice 684B package.json
npm notice 51B  readme.md   
npm notice === Tarball Details === 
npm notice name:          @frontendweb3/demo-github-registry          
npm notice version:       1.0.0                                       
npm notice filename:      @frontendweb3/demo-github-registry-1.0.0.tgz
npm notice package size:  526 B                                       
npm notice unpacked size: 807 B                                       
npm notice shasum:        d63727fe6d4379591d5b33dd86be2bf1b6b3d9cd    
npm notice integrity:     sha512-rpS/ZCeFi7V4m[...]QOC3PDEpwpIEw==    
npm notice total files:   3                                           
npm notice 
npm notice Publishing to https://npm.pkg.github.com/
+ @frontendweb3/demo-github-registry@1.0.0

How to found NPM to publish the package on GitHub?

Go to your GitHub repository.

Publish the new package to GitHub Registry

Click on the npm package.

Publish the new package to GitHub Registry

Your publish npm package looks like on the GitHub registry.

How to update the package?

When you change anything inside your package. Before running thenpm publish command, firstly, you need to change the npm package version. Then run the npm publish command. Otherwise, your package does not update.

// package.json

{ "version": "1.0.1",}

You face this type of error.

$ npm publish
npm notice 
npm notice 📦  @frontendweb3/demo-github-registry@1.0.1
npm notice === Tarball Contents === 
npm notice 644B .github/workflows/publish.yml
npm notice 72B  index.js                     
npm notice 684B package.json                 
npm notice 78B  readme.md                    
npm notice === Tarball Details === 
npm notice name:          @frontendweb3/demo-github-registry          
npm notice version:       1.0.1                                       
npm notice filename:      @frontendweb3/demo-github-registry-1.0.1.tgz
npm notice package size:  852 B                                       
npm notice unpacked size: 1.5 kB                                      
npm notice shasum:        3e46c706e986fb61edc0ae9de69a77991190a664    
npm notice integrity:     sha512-O5aQM1qOwqUwM[...]3/THOnuODzQtQ==    
npm notice total files:   4                                           
npm notice 
npm notice Publishing to https://npm.pkg.github.com/
npm ERR! code EPUBLISHCONFLICT
npm ERR! publish fail Cannot publish over existing version.
npm ERR! publish fail Update the 'version' field in package.json and try again
.
npm ERR! publish fail 
npm ERR! publish fail To automatically increment version numbers, see:
npm ERR! publish fail     npm help version

npm ERR! A complete log of this run can be found in:
npm ERR!     /home/rajdeepsingh/.npm/_logs/2023-05-16T14_26_04_375Z-debug-0.lo
g

Setup GitHub Action

GitHub workflow Action help to automate the npm package when we push anything on the main branch.

name: Publish package to GitHub Packages
on:
  push:
    branches:
      - main
jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
    steps:
      - uses: actions/checkout@v3

      # Setup .npmrc file to publish to GitHub Packages
      - uses: actions/setup-node@v3
        with:
          node-version: "16.x"
          registry-url: "https://npm.pkg.github.com"
          
          # Defaults to the user or organization that owns the workflow file
          scope: "@your-or-orgination-username"
      
      - run: npm ci
      - run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.REGISTRY_TOKEN }}

The actions/setup-node@v3 action help to create a .npmrc file automatically with scope.

The last step is to add REGISTRY_TOKEN Environment variable in your GitHub repository.

How to Add Environment variable in Github Repository.

Creating environment variables is a very easy process. It takes less than one minute.

Go to your GitHub repository and click on the settings tab.

Add Environment variable in Github Repository

Click on the settings tab on your GitHub repository.

Add the Environment variable in Github Repository.

Then click on the Secrets and Variables tab and click again on the Action button.

Add Environment variable in Github Repository

Click on the New Repository secret button.

Add the Environment variable in Github Repository.

Enter your environment variable name and Paste your copy Github Token in the Secret box and click on Add submit button.

Now your GitHub Action setup is complete. Whenever you push on the main repository branch. GitHub automatically triggers GitHub action, and it publishes or updates your npm package.

How do you Install the NPM package from Github Registry?

Installing the NPM package from the GitHub Registry is very easy to like. But first, you need to log in with a GitHub Registry account.

Installation Setup

1. Config NPM package path or location in .npmrc
2. Login to Your GitHub registry account

Config NPM package path or location in .npmrc

Firstly we tell the NPM where our package is located on GitHub. For that, we create new .npmrc file inside your project root level.

.npmrc

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

You can change or Replace your NAMESPACE with the username of the user or organization account to which the package will be scoped.

Where we find the NAMESPACE

How to Find Github NAMESPACE

You can find the NAMESPACE in the installation command. For example, your package installation command looks like this.

npm install @frontendweb3/demo-github-registry@1.0.1

The frontendweb3 is your NAMESPACE value that is put inside the .npmrc file. Your .npmrc file looks like this.

# .npmrc

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

You can also add multiple Github package registry URLs in .npmrc file.

# .npmrc

## First 
@frontendweb3:registry=https://npm.pkg.github.com

## Second
@lexacode:registry=https://npm.pkg.github.com

Login to Your GitHub registry account

The last step is login, and I am ready to explain How to log in with the GitHub repository.

npm login --scope=NAMESPACE --registry=https://npm.pkg.github.com

Change the NAMESPACE with your GitHub user and organization username.

 $ npm login --scope=@frontendweb3 --registry=https://npm.pkg.github.com
npm WARN adduser `adduser` will be split into `login` and `register` in a future version. `adduser` will become an alias of `register`. `login` (currently an alias) will become its own command.
npm notice Log in on https://npm.pkg.github.com/
Username: officialrajdeepsingh
Password: 
Email: (this IS public) radewala.2@gmail.com
Logged in as officialrajdeepsingh to scope @frontendweb3 on https://npm.pkg.github.com/.

Now you can easily install packages with NPM, YARN and PNPM commands from the GitHub registry.

npm install @frontendweb3/demo-github-registry@1.0.1

Error 1

If you face an error like this, you do not log in with a GitHub registry account.

npm notice New major version of npm available! 8.15.0 -> 9.6.6
➜  workspace git:(master) ✗ npm install @frontendweb3/demo-github-registry@1.0.1
npm ERR! code E401
npm ERR! 401 Unauthorized - GET https://npm.pkg.github.com/@frontendweb3%2fdemo-github-registry - authentication token not provided

npm ERR! A complete log of this run can be found in:
npm ERR!     /project/home/officialrajdeepsingh/.cache/npm/_logs/2023-05-17T10_52_40_814Z-debug-0.log
➜  workspace git:(master) ✗ 

How to resolve ERR_PNPM_REGISTRIES_MISMATCH Error in PNPM?

ERR_PNPM_REGISTRIES_MISMATCH

If you face ERR_PNPM_REGISTRIES_MISMATCH Error, the solution is very easy.

1. First, run the pnpm install command
2. If the error is not solved, then run the pnpm install -g command in your project and then rerun the pnpm install command and your error is resolved.

Conclusion

Github registry is a good fit for startups and companies; you can manage everything in one place and do not need to pay NPMJS. The best part is that GitHub gives you a free plan to add an unlimited contribution. For that, NPMJS charge you 7 dollar per month.

The only downside I face is the configuration required during the npm package installation from the GitHub registry.

I hope the Github team resolve the installation configuration issue in future And developer easily install packages for the GitHub repository like npmjs.

You can share and follow us on Twitter and Linkedin. If you like my work, please read more content on the officialrajdeepsingh.dev, frontend web, and Sign up for a free newsletter.

You can also check out awesome-next, a curated list of awesome Next.js-based libraries that help build small and large-scale applications with next.js.