NPM Packaging - Publishing to Github (Part - 1)

[nakamume]

Github Packages gives you registries for commonly used packages, such as Node(npm), Docker, RubyGems, Apache Maven, Gradle.

In this issue, we'll explore how to publish node packages using npm to Github and how to consume npm packages from Github.

Let's start with writing a very simple node package

1. Create a github repo my-node-package (or whatever name you prefer 😉)
2. Clone the repo and add your main JS file there

   # <SCOPE> should be replaced by your github username or organization name.
   git clone [email protected]:<SCOPE>/my-node-package.git && cd my-node-package
   touch index.js

3. Add code for your package. In my case, my package would just return You have successfully installed and ran nakamume's rei package. So, the index.js file would look like

   module.exports = function rei() {
   return "You have successfully installed and ran nakamume's rei package";
   };
   

4. Let's add a package.json file. This is the only required file for a package.

   {
    "name": "@<SCOPE>/my-node-package",
    "version": "1.0.0",
    "description": "This is an example node package",
    "repository": "https://github.com/<SCOPE>/my-node-package",
    "main": "index.js",
    "publishConfig": {
       "registry": "https://npm.pkg.github.com"
     }
   }
   

   Here name is scoped package name, version is package's version in semantic notation, repository is the github repo you created in Step 1 (if your repo is private your package would be private otherwise your package will be public), main is the entry point for the package, in our case it's index.js file, and publishConfig would tell the npm about the target registry for publishing.
5. That's it. We have written our example package. In next section, let's see how to publish it.

Publishing the package

1. Create a PAT(personal access token) from Github with repo and write:packages permissions.
2. Do npm login using your github username as username and PAT as password.

   npm login --scope=@<SCOPE> --registry=https://npm.pkg.github.com
   

3. voilà! We are ready to publish.

   # update your package's major, minor or patch version
   npm version major
   # publish it
   npm publish
   

Installing package from Github

1. As we did in last section, login to github packages(required if installing a private package). And append the following config for github registry in your npmrc file

   @<SCOPE>:registry=https://npm.pkg.github.com
   

   Remember the scope? It's github org or user id.
2. That's it! Run npm install <package-name> to install.

If you are interested, join me in issue 2, where we'll explore how to add unit tests for our package and to make use of github actions to run those tests and then publish.