Create and Publish an npm package [guide]

It takes only a few steps to create and publish an npm package.

Setting up Environment and Project.

  1. Installing Node.js and npm:
    This is the first step in setting up the environment for creating an npm package. Node.js is a JavaScript runtime that allows you to run JavaScript code on your computer, while npm is a package manager that helps you manage the dependencies and other aspects of your project.

  2. Creating a new directory for the project:
    Next, create a new directory for your project and navigate into it. This will be the location where all the files for your package will be stored.

  3. Initializing the project as an npm module:
    Once you're in the project directory, run the command npm init to create a package.json file. This file contains important information about your package, such as its name, version, and dependencies.

  4. Keep your package name scoped. such as @user/package_name or @org/package_name.

    GitHub packages only support scoped package name.

  5. Add more details such as ......

  6. Add publishConfig.

       "publishConfig": {
         "access": "public"
       },
    

    Example package.json:

     {
       "name": "@user/package_name",
       "version": "1.0.0",
       "description": "A simple description for your package.",
       "author": "John Doe <user@mail.com>",
       "main": "src/index.js",
       "homepage": "https://github.com/user/package_name",
       "repository": {
         "type": "git",
         "url": "git@github.com:user/package_name.git"
       },
       "private": false,
       "keywords": ["some","keywords","related","to","package"],
       "publishConfig": {
         "access": "public"
       },
     }
    
  7. Installing any necessary dependencies for the module:
    if your module needs any external libraries, you can use npm to install them by running npm install <library name>

Building a Module.

  1. Writing the code for the module and organizing it into appropriate files and directories:
    The next step is to write the code for your package. The code should be organized into appropriate files and directories to make it easy to understand and maintain.

  2. Defining the entry point for the module in the package.json file:

    In package.json, you need to define the main file of your package that will be executed when someone requires it.

  3. Transpiling or compiling the code as necessary:
    If your code uses newer JavaScript features that may not be supported by older environments, you will need to transpile or compile it to a more compatible format.

  4. Creating a build script to automate the building process:
    To automate the build process, you can create a script in package.json, this script can be executed using npm run <script name>

  5. Testing the built module to ensure it functions as intended:

    Before publishing your package, it's important to test it thoroughly to ensure it works as intended. This will help catch any bugs or issues before they are released to the public.

Publishing the Module.

  1. Logging in to an npm account and creating a new version of the module:

    To publish your package to the npm registry, you'll need to log in to your npm account using npm login. If you don't have an account, you can create one by running npm adduser.

  2. Creating the documentation and README for the module:
    Make sure to create documentation and README for your package with any relevant information and usage instructions. This will help others understand how to use your package and what it does.

  3. Publishing the module to the npm registry:
    Once you're logged in, you can publish your package by running the command npm publish. This will make it available for others to download and use.

  4. Best practices for package naming, versioning and documentation:
    Follow best practices for package naming, versioning and documentation, for example, Package names should be unique and meaningful, version numbers should follow semantic versioning and make sure to have a README file that explains how to use your package.

Adding CI/CD Pipeline for Automation (GitHub Actions).

  1. Setting up a GitHub Actions workflow to automatically build, test, and publish the module on changes to the code

  2. Configuring the workflow to run the necessary commands, such as npm test and npm publish

  3. Setting up GitHub Actions secrets for authentication with npm.

    NPM_TOKEN

    you can get it from npmjs.com

  4. GH_TOKEN , you can get it from GitHub.

    GitHub token with package read and write permission.

Workflow:

name: Node.js Package

on:
  release:
    types: [created]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 16
      - run: npm ci
      - run: npm test

  publish-npm:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 16
          registry-url: https://registry.npmjs.org/
      - run: npm ci
      - run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{secrets.NPM_TOKEN}}

  publish-gpr:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 16
          registry-url: https://npm.pkg.github.com/
      - run: npm ci
      - run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{secrets.GH_TOKEN}}