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...
Top comments (7)
That's a very very useful article, tks for sharing
Thank you Thiago, I hope that it help you sometime!
crazyyy crazy, you helped me so much
easy understand, great article
great article, thanks for that!
It means a lot, thanks for the help as well!
Very well-explained article, it definitely helped me.
Some comments may only be visible to logged-in visitors. Sign in to view all comments.