GitHub Packages supports multiple different types of package registries. In this post, I will be discussing the package registry for Node Package Manager (NPM). This registry allows you to publish NPM packages either to your personal GitHub Account or to a GitHub Organization. It supports both public and private packages.
Quick Notes
Let's quickly go over a few things that you'll need to know when working with the GitHub Packages NPM Registry:
The address of the registry is: https://npm.pkg.github.com
It only supports 'scoped' NPM packages, meaning the package is scoped to either a GitHub account or a GitHub organization. (you may need to update the name of your package in your package.json file to include a scope)
Both package names and package scopes must be lowercase
It supports granular permissions (not all GitHub Packages Registries do)
The tarball for your NPM package must be smaller than 256 MB in size
When you first publish a package, the default visibility is private, but you can change this after the fact
Optionally, one of your GitHub Repos can be linked to the package and designated as the "source" repo
It only supports authentication using a GitHub Personal Access Token (Classic)
Personal Access Tokens & GITHUB_TOKEN
Let's go over that last bullet point above in some more detail. When authenticating to GitHub Packages it only supports GitHub classic PATs.
There is one exception where you don't need to use a classic PAT. If you are interacting with the NPM registry from a GitHub Workflow, then you can use the default GITHUB_TOKEN from the repo where your workflow resides. This token operates as a special type of PAT that has access to GitHub Packages. The next logical question might be, "why don't I just use a GitHub App token, instead?" Unfortunately, you can NOT use Installation Access Tokens generated by a GitHub App (source). For more information about the various types of GitHub tokens, see my previous article.
One final note, a GITHUB_TOKEN can NOT be used to create a brand new NPM package from scratch that is scoped to an Organization. It works perfectly fine to create new NPM packages that are scoped to user accounts. With that being said, after an organization-scoped NPM package has been created, you can then grant access to individual repositories after the fact. At that point, those repositories can use their own GITHUB_TOKEN to interact with the package.
Default Package Settings
The values included in your package.json file will determine the initial settings that are applied to the package once it is published. This only applies if you use PAT auth. Whereas if you use GITHUB_TOKEN auth, then the package settings will always be the same. See the diagram above for a full breakdown of the settings initially applied to packages.
Using GitHub Actions
If you use GitHub Actions then you have the benefit of being able to use the official Setup-Node action. This action is helpful in a number of ways. Say you were to use the task with the following options:
This will configure the GitHub Runner in the following way:
It will automatically create a temporary .npmrc file on the runner, so you don't need to worry about creating and maintaining that file yourself.
The .npmrc file is a config file used by NPM, you can find more information about it here.
It will configure the .npmrc file to point at the GitHub Packages NPM Registry
It will configure the .npmrc file with a scope of the nnellans GitHub Account
It will configure the .npmrc file with an authentication token, but instead of storing a token directly in the file, it will only make a reference to an environment variable named NODE_AUTH_TOKEN. It will be your responsibility to set the value for this environment variable
Full example GitHub Workflow to publish a NPM package:
Summary
That was a quick intro and overview into using NPM Packages with the GitHub Packages NPM Registry. Let me know if you'd like me to cover the other types of GitHub Packages Registries in the future.