DEV Community

Carlos Henrique
Carlos Henrique

Posted on

Publishing a Private Package on GitHub Packages

Recently at work, I encountered the need to publish a package privately. After evaluating some options, I realized that the best way to do this was by using GitHub Packages.

What is GitHub Packages?

GitHub Packages allows you to store packages of various types (such as npm, Maven, Docker, etc.) directly on GitHub. You can make them public or private, depending on your project’s needs. You can learn more here.

Step 1: Setting up the project and requirements

First, you need to have a repository on GitHub where your package will be stored. To ensure the package is private, make sure the repository is private.

Step 2: Creating your package

  1. Creating the package.json: Replace <your-user-or-organization> with the desired user or organization.
npm init --scope=@<your-user-or-organization>
Enter fullscreen mode Exit fullscreen mode

This will generate a package.json file with the name field already formatted with the scope. Using my GitHub profile as an example:

{
  "name": "@carloshendvpm/my-package",
  "version": "1.0.0",
  "description": "My private package on GitHub Packages",
  ...
}
Enter fullscreen mode Exit fullscreen mode

Step 3: Configuring the registry for GitHub Packages

Now, you need to ensure that npm knows you want to publish this package to GitHub Packages, not to the public npm registry. To do this, add the publishConfig field to your package.json:

"publishConfig": {
  "registry": "https://npm.pkg.github.com/"
}
Enter fullscreen mode Exit fullscreen mode

This tells npm to use GitHub Packages as the publication destination. Your package.json should now look like this:

{
  "name": "@carloshendvpm/my-package",
  "version": "1.0.0",
  "type": "module",
  "repository": {
    "url": "https://github.com/carloshendvpm/my-package.git"
  },
  "dependencies": {
    ...
  },
  "devDependencies": {
    ...
  },
  "publishConfig": {
    "registry": "https://npm.pkg.github.com/"
  }
}
Enter fullscreen mode Exit fullscreen mode

Step 4: Using GitHub Actions to publish the package

Create a directory named .github/workflows inside your project. Inside the workflows directory, create a file named publish.yml with the following content:

name: Publish package to GitHub Packages
on:
  release:
    types: [published]
  workflow_dispatch:
jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v3
        with:
          node-version: '20.x'
          registry-url: 'https://npm.pkg.github.com'
          scope: '@carloshendvpm'
      - name: Install dependencies
        run: npm install
      - name: Publish package
        run: npm publish --access restricted
        env:
          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
Enter fullscreen mode Exit fullscreen mode

This action will only be executed when a new release is created. You can modify this behavior as per your preferences. I’ve also used the workflow_dispatch event, which allows you to manually trigger the action from GitHub's interface. It's important to note that the GITHUB_TOKEN is automatically generated by GitHub. You can learn more about it here.

Step 5: Creating the new release

New release github

Fill in the tag information and create the new release. This will trigger the action to execute.

Step 6: Using the package in your projects

Before installing the package, follow these steps:

  1. Create a personal access token on GitHub. This token will allow you to authenticate with the GitHub API and install your package. Go to Settings / Developer Settings / Personal Access Tokens and generate a new token with read permissions.

  2. In the project where the package will be used, create a .npmrc file in the root directory.

  3. Add the following configuration to your .npmrc file, replacing <GITHUB_TOKEN> with the token you generated:

//npm.pkg.github.com/:_authToken=<GITHUB_TOKEN>
@organizationName:registry=https://npm.pkg.github.com
Enter fullscreen mode Exit fullscreen mode
  1. Now, you can install the package in your project using:
  • Via package.json:
"@carloshendvpm/my-package": "1.0.0"
Enter fullscreen mode Exit fullscreen mode
  • Via terminal:
npm install @carloshendvpm/my-package@1.0.0
Enter fullscreen mode Exit fullscreen mode

Conclusion

I hope this was helpful in some way. Soon, I plan to share a complete guide on creating a package using the Svelte Library. If you have any suggestions or notice any mistakes, feel free to comment or correct me. German version soon...

Top comments (7)

Collapse
 
thiteago profile image
Thiago David • Edited

That's a very very useful article, tks for sharing

Collapse
 
carloshendvpm profile image
Carlos Henrique

Thank you Thiago, I hope that it help you sometime!

Collapse
 
pedro_leonardo_970735a7d4 profile image
Pedro Leonardo

crazyyy crazy, you helped me so much

Collapse
 
pedro_leonardo_970735a7d4 profile image
Pedro Leonardo

easy understand, great article

Collapse
 
ernanej profile image
Ernane Ferreira

great article, thanks for that!

Collapse
 
carloshendvpm profile image
Carlos Henrique

It means a lot, thanks for the help as well!

Collapse
 
pedro_boahora profile image
Pedro Boa Hora

Very well-explained article, it definitely helped me.

Some comments may only be visible to logged-in visitors. Sign in to view all comments.