Publishing your private npm packages to Gitlab NPM Registry

Configure npm, yarn, lerna to publish packages to Gitlab Package Registry and use them as dependencies in your project

Ever thought of publishing a package to a 3rd-party npm registry?

If yes, then you’ve come to the right place.

In this article, I’ll give a brief intro to the Gitlab NPM Registry followed by a guide to publish your private npm packages to Gitlab NPM Registry using different package managers.

So, let’s begin with the intro first.

Introduction to Gitlab NPM Registry

Gitlab provides a feature to its users, called Gitlab Package Registry, which allows us to store public/private artifacts including npm, maven, go, or python packages.

As we’re focusing just on the npm artifacts for this post, you can read more about Gitlab Package Registry here.

Now let’s move on to how you can store npm packages in the Gitlab Package Registry.

Assuming you already have a Gitlab project created. If not, please create one before moving on to the steps.

Step 1: Enable the Gitlab Package Registry

The first step in the process is to enable the Gitlab Package Registry for your project.

1. Open up your project’s Settings > General > Visibility, project features, permissions.
2. Enable the packages feature and click on Save Changes for the changes to take effect.

Step 2: Setup Authentication for Package Registry

You need to authenticate yourself to the Gitlab NPM Registry in order to install/publish packages.

You can either authenticate using a Personal Access Token with the api scope selected or using a Deploy Token with the read_package_registry and write_package_registry permissions.

To create a Deploy Token:

• Open up your Project Settings > Repository > Deploy Tokens.
• Enter the required details and provide the read_package_registry and write_package_registry permissions to install/publish packages to the registry.
• You’ll see a username and a token.

• Copy your token immediately and keep it safe as you won’t be able to access it again.
• We’ll use this token later to authenticate against the package registry.

Step 3 (Optional): Create a new project

If you haven’t already created a project, use the following command to create a new project:

Create a new nodejs project using different package managers

Step 4: Update package information

Gitlab NPM Registry supports only scoped packages. So make sure the package name contains the scope name which should be your project or group’s name in this case.

For example, if your project url is https://gitlab.com/my-org/my-project, the root namespace is my-org. So you must use my-org as the scope name for your package.

Scope names are case sensitive as your username or org name may contain uppercase characters.

Update the following information in your package.json file:

1. Update the package name so that the name property conforms to the following:

"name": "@my-org/my-package-name"

2. Add the following publishConfig to your package.json:

Gitlab NPM Registry Publish Config

3. Replace the project id with your own project id.

You can find your own project id using the Project overview > Details section.

If you’re using `yarn workspaces` or `lerna` make sure you update the package.json for every package/workspace in your project with it’s respective package name and publish config.

Step 5: Configure your .npmrc

Remember we created an auth token in step2, now it’s time to use that token to authenticate against the registry.
You need to configure your .npmrc in order to point to and authenticate to any 3rd party package registry, like Gitlab Package Registry, in our case.

1. Create a .npmrc at the root of your project.
2. Add the following lines to your .npmrc :

NPM Config for Gitlab NPM Registry

Step 6: Publish your package

All the steps discussed above are just a one-time setup for your project.

Now, you just need to run a command using your package manager whenever you want to publish a new package or an update to an existing package.

To publish your package using different package managers, use the following commands:

Make sure you replace $AUTH_TOKEN with the token copied earlier in Step 2 or create a local environment variable (this is recommended) named GITLAB_AUTH_TOKEN with the token copied earlier as the value. You don’t need to provide the token value with the publish command every time if you create an environment variable with the same name.

You can also keep your .bashrc or .zshrc clutter-free by limiting environment variables to specific projects.

To know how you can create per-project environment variables, check out this article about direnv — a tool to create project-specific environment variables.

A guide to manage your environment variables in a better way using direnv

That’s all.

You just need this 6-step setup to start publishing to the Gitlab NPM Registry.

If you would like to get a hands-on, head over to this sample repository which I just created.

Shivam Arora / gitlab-npm-registry-demo · GitLab

You can also checkout how the package registry looks like and how you can install those packages as dependencies in other projects by visiting this project’s Package Registry and going into the package details.

But wait, there’s something more that might be useful.

Addons:

I would like to introduce some additional things which may not apply to everyone but might be useful for those in need.

1. Publishing packages through Gitlab CI

If you’re publishing packages to the registry through CI you need to provide your auth token in the publish step.

But if you’re using Gitlab CI, you can use the CI_JOB_TOKEN already provided under Gitlab CI to publish packages without creating an additional personal access token or deploy token in Step 2.

In that case, just replace the publish command with the following:

Note: The CI_JOB_TOKEN inherits the permissions of the user that generates the pipeline. So make sure everyone in your team who can generate a pipeline leading to package publishing has the permissions to publish a package. Otherwise, you’ve to use the personal access token or deploy token created earlier in Step 2.

2. Additional Config for Lerna

If you’re using a monorepo to contain multiple packages and are using lerna as the package manager to maintain the monorepo and package publishing, you need to provide the registry config in lerna.json .

Add the following config in your lerna.json :

3. Additional Config for Yarn Workspaces

If you’re using yarn workspaces to maintain a package monorepo, you need to provide publishConfig at the root package.json .

Add the publishConfigin your root package.json so your yarn workspace root config looks like this:

That’s it for today.

I hope you liked this blog and it was helpful for you.