Publishing a Private Package on GitHub Packages

#npm #github #githubactions

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

Creating the package.json: Replace <your-user-or-organization> with the desired user or organization.

npm init --scope=@<your-user-or-organization>

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",
  ...
}

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/"
}

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/"
  }
}

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 }}

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

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:

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.
In the project where the package will be used, create a .npmrc file in the root directory.
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

Now, you can install the package in your project using:

Via package.json:

"@carloshendvpm/my-package": "1.0.0"

Via terminal:

npm install @carloshendvpm/my-package@1.0.0

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...