How to Publish an NPM Package to GitLab's Package Registry

August 22, 2022

In this tutorial, I'll walk you through the process of publishing an NPM package using GitLab's Package Registry within a private repository. This approach allows you to manage private packages efficiently while leveraging GitLab's robust security features.

Prerequisites

Before we begin, make sure you have:

  • Node.js (latest version)
  • Package manager (npm or yarn)
  • GitLab account with a private repository
  • A code editor (VSCode or similar)

1. Setting Up a Monorepo with Lerna

We'll use Lerna to manage a monorepo structure with Yarn workspaces. This provides a clean way to organize multiple packages.

First, create and initialize your project:

Example.bash
1mkdir my-project
2cd my-project
3npx lerna init
4

2. Configuring Lerna

Now, let's configure Lerna by updating the lerna.json file:

Example.json
1{
2  "packages": ["packages/*"],
3  "npmClient": "yarn",
4  "useWorkspaces": true,
5  "version": "independent",
6  "command": {
7    "publish": {
8      "registry": "https://gitlab.com/api/v4/projects/<your-project-id>/packages/npm/"
9    }
10  }
11}
12
13// Finding Your Project ID**: Navigate to your GitLab repository settings. The Project ID is the number in the URL after the slash:
14-> https://gitlab.com/<your_user>/<your_repository>/edit
15
16// Project ID:
17-> 123456
18

3. Creating Your Package

Now, let's create a package within your monorepo:

Example.bash
1cd packages
2mkdir my-lib
3cd my-lib
4yarn init # or npm init or pnpm init
5

After initializing the package, open its package.json file and add these important configurations:

Example.json
1{
2  "name": "@my-project/my-lib",
3  "version": "0.1.0",
4  // ... other package.json properties
5  "publishConfig": {
6    "@my-project:registry": "https://gitlab.com/api/v4/projects/<your-project-id>/packages/npm/"
7  },
8  "sideEffects": false
9}
10

4. Setting Up NPM Configuration

Return to the project root directory and create an .npmrc file to configure access to the GitLab Package Registry:

Example.bash
1cd ../..  # Return to project root
2touch .npmrc
3

Add the following configuration to your .npmrc file:

Example.bash
1@my-project:registry=https://gitlab.com/api/v4/packages/npm/
2//gitlab.com/api/v4/packages/npm/:_authToken=${AUTH_TOKEN_GITLAB}
3//gitlab.com/api/v4/projects/<project_id>/packages/npm/:_authToken=${AUTH_TOKEN_GITLAB}
4

5. Creating a GitLab Access Token

To authenticate with GitLab's Package Registry, you need to create an access token:

  1. Go to your GitLab repository
  2. Navigate to Settings > Access Tokens
  3. Create a new token with these permissions:
    • api (for API access)
    • read_registry and write_registry (for Package Registry access)
  4. Give your token a descriptive name and set an expiration date
  5. Copy the generated token - you'll only see it once!

6. Publishing Your Package

With everything set up, you can now publish your package to GitLab's Package Registry:

Example.bash
1# Set your authentication token as an environment variable
2export AUTH_TOKEN_GITLAB=<your_token_value>
3
4# Build and publish
5yarn build && lerna publish --yes
6

If successful, you'll see your package in the GitLab repository under the Packages & Registries tab.

7. Using Your Published Package

To use your published package in another project:

  1. Create an .npmrc file in the root of your consuming project:
Example.bash
1@my-project:registry=https://gitlab.com/api/v4/projects/<project-id>/packages/npm/
2//gitlab.com/api/v4/projects/<project-id>/packages/npm/:_authToken=${AUTH_TOKEN_GITLAB}
3
  1. Install your package:
Example.bash
1yarn add @my-project/my-lib
2# or
3npm install @my-project/my-lib
4

Security Best Practices

  • Never commit your .npmrc file with the actual token value
  • Use environment variables to inject your tokens
  • Consider adding .npmrc to your .gitignore file
  • Set appropriate token expiration dates
  • Use the minimum required permissions for your tokens

Troubleshooting Tips

  • Authentication failures: Check that your token has the correct permissions
  • Package not found: Verify project ID and package namespace match
  • Publishing errors: Ensure package version is updated before republishing

Thank you for reading! I hope this guide helps you successfully publish your packages to GitLab's Package Registry. If you have any questions or suggestions, feel free to leave a comment below.