GitHub package — way to go for your private npm packages

03 August 2022
3.0 min read

Often happens that an npm package should be published to a secure registry. In many cases, organizations have their own and all the internal stuff goes there. But what to do if your organization does not have anything like that? Apparently, Github Packages are the way to go. In case your repository is private, its packages will be too! Below, I describe a simple workflow that I set today.

In this case, the packages are built and published in a pipeline operated by Github Actions. To set a workflow there, you would need to create a YAML file in the .github/workflows/ folder. This is mine, for a package called @yourscope/design-library.

name: Release library

      - main

    runs-on: ubuntu-latest
      - name: Checkout
        uses: actions/checkout@v3

      - name: Install NodeJS
        uses: actions/setup-node@v3
          node-version: "16"
          registry-url: ""
          scope: "@yourscope"

      ### Check in, install, and build as your project needs it

      - name: Release package
        run: |
          npm publish
          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Note that when publishing, there should be the NODE_AUTH_TOKEN environmental variable available. However, its value is GITHUB_TOKEN taken from secrets. You don't need to generate such a secret, your repository already has it in the background.

Another thing to spot is that when installing Node, you should define the npm registry and the scope. That can be done with additional parameters as shown in the code example.

How to release?

Releases are happening in a pipeline via GitHub Actions once the main branch is updated. Releases are successful if the version number is unique. Practically, that means that a design-system developer needs to change the version number to trigger the release. There is room for improvement — it would be much nicer not to run the publishing job if the package of such a version already exists.

How to get the package?

Authentification at GitHub Packages

The GitHub Package registry is not open, you should get an access to it. For that, you need to authenticate.

  1. Create your Personal Access Token at GitHub here
    • It's a good habit to have a separate token for each project
    • Name it using the Note field so that later you understand what the token is for
    • The token should at least have read:packages permission
    • Do not forget to copy the token after you have it generated
  2. Login to the npm registry:
    npm login --scope=@yourscope --registry=
    > Username: USERNAME
    > Password: TOKEN

For more information, follow the official GitHub documentation:

Installing the design-system package at the very first time

Before installation, you need to communicate that @yourscope npm packages should be taken from GitHub Packages. You can do it by adding an .npmrc file to the root of your project. The content of the file should be as the following:


Keep the .npmrc file under version control so that your colleagues also could get the packages from the right place.

Now, you can install the package:

npm install --save @yourscope/design-system


yarn add @yourscope/design-system

Installing project dependencies

If you have a project with @yourscope/design-system as a dependency, when being authorized, you should be able to install it together with all the other dependencies:

npm install



Did you notice a typo? Welcome to edit this page on GitHub. Thank you!

You can hire me and the whole Bridge-the-Gap team to set up, manage, develop, and champion your design system. I can align the design and development processes in your organisation for a larger business impact.

© Varya Stepanova 2024