npm packages in the Package Registry

Moved from GitLab Premium to GitLab Free in 13.3.

Publish npm packages in your project’s Package Registry. Then install the packages whenever you need to use them as a dependency.

Only scoped packages are supported.

For documentation of the specific API endpoints that the npm package manager client uses, see the npm API documentation.

caution
Never hardcode GitLab tokens (or any tokens) directly in .npmrc files or any other files that can be committed to a repository.

Build an npm package

This section covers how to install npm or Yarn and build a package for your JavaScript project.

If you already use npm and know how to build your own packages, go to the next section.

Install npm

Install Node.js and npm in your local development environment by following the instructions at npmjs.com.

When installation is complete, verify you can use npm in your terminal by running:

npm --version

The npm version is shown in the output:

6.10.3

Install Yarn

As an alternative to npm, you can install Yarn in your local environment by following the instructions at classic.yarnpkg.com.

When installation is complete, verify you can use Yarn in your terminal by running:

yarn --version

The Yarn version is shown in the output:

1.19.1

Create a project

To create a project:

  1. Create an empty directory.
  2. Go to the directory and initialize an empty package by running:

    npm init
    

    Or if you’re using Yarn:

    yarn init
    
  3. Enter responses to the questions. Ensure the package name follows the naming convention and is scoped to the project or group where the registry exists.

A package.json file is created.

Use the GitLab endpoint for npm packages

To use the GitLab endpoint for npm packages, choose an option:

  • Project-level: Use when you have few npm packages and they are not in the same GitLab group. The package naming convention is not enforced at this level. Instead, you should use a scope for your package. When you use a scope, the registry URL is updated only for that scope.
  • Instance-level: Use when you have many npm packages in different GitLab groups or in their own namespace. Be sure to comply with the package naming convention.

Some features such as publishing a package is only available on the project-level endpoint.

Authenticate to the Package Registry

You must authenticate with the Package Registry when the project is private. Public projects do not require authentication.

To authenticate, use one of the following:

  • A personal access token (required for two-factor authentication (2FA)), with the scope set to api.
  • A deploy token, with the scope set to read_package_registry, write_package_registry, or both.
  • It’s not recommended, but you can use OAuth tokens. Standard OAuth tokens cannot authenticate to the GitLab npm Registry. You must use a personal access token with OAuth headers.
  • A CI job token.
  • Your npm package name must be in the format of @scope/package-name. It must match exactly, including the case.

Authenticate with a personal access token or deploy token

To authenticate with the Package Registry, you need a personal access token or deploy token.

Project-level npm endpoint

To use the project-level npm endpoint, set your npm configuration:

# Set URL for your scoped packages.
# For example package with name `@foo/bar` will use this URL for download
npm config set @foo:registry https://gitlab.example.com/api/v4/projects/<your_project_id>/packages/npm/

# Add the token for the scoped packages URL. Replace <your_project_id>
# with the project where your package is located.
npm config set -- '//gitlab.example.com/api/v4/projects/<your_project_id>/packages/npm/:_authToken' "<your_token>"
  • <your_project_id> is your project ID, found on the project’s home page.
  • <your_token> is your personal access token or deploy token.
  • Replace gitlab.example.com with your domain name.

You should now be able to publish and install npm packages in your project.

If you encounter an error with Yarn, view troubleshooting steps.

Instance-level npm endpoint

To use the instance-level npm endpoint, set your npm configuration:

# Set URL for your scoped packages.
# For example package with name `@foo/bar` will use this URL for download
npm config set @foo:registry https://gitlab.example.com/api/v4/packages/npm/

# Add the token for the scoped packages URL. This will allow you to download
# `@foo/` packages from private projects.
npm config set -- '//gitlab.example.com/api/v4/packages/npm/:_authToken' "<your_token>"
  • <your_token> is your personal access token or deploy token.
  • Replace gitlab.example.com with your domain name.

You should now be able to install npm packages in your project.

If you encounter an error with Yarn, view troubleshooting steps.

Authenticate with a CI job token

Version history
  • Introduced in GitLab 12.5.
  • Moved from GitLab Premium to GitLab Free in 13.3.

If you’re using npm with GitLab CI/CD, a CI job token can be used instead of a personal access token or deploy token. The token inherits the permissions of the user that generates the pipeline.

Project-level npm endpoint

To use the project-level npm endpoint, add a corresponding section to your .npmrc file:

@foo:registry=https://gitlab.example.com/api/v4/projects/${CI_PROJECT_ID}/packages/npm/
//gitlab.example.com/api/v4/projects/${CI_PROJECT_ID}/packages/npm/:_authToken=${CI_JOB_TOKEN}

Instance-level npm endpoint

To use the instance-level npm endpoint, add a corresponding section to your .npmrc file:

@foo:registry=https://gitlab.example.com/api/v4/packages/npm/
//gitlab.example.com/api/v4/packages/npm/:_authToken=${CI_JOB_TOKEN}

Use variables to avoid hard-coding auth token values

To avoid hard-coding the authToken value, you may use a variable in its place:

npm config set -- '//gitlab.example.com/api/v4/projects/<your_project_id>/packages/npm/:_authToken' "${NPM_TOKEN}"
npm config set -- '//gitlab.example.com/api/v4/packages/npm/:_authToken' "${NPM_TOKEN}"

Then, you can run npm publish either locally or by using GitLab CI/CD.

  • Locally: Export NPM_TOKEN before publishing:

    NPM_TOKEN=<your_token> npm publish
    
  • GitLab CI/CD: Set an NPM_TOKEN CI/CD variable under your project’s Settings > CI/CD > Variables.

Working with private registries

When working with private repositories, you may want to configure additional settings to ensure a secure communication channel:

# Force npm to always require authentication when accessing the registry, even for GET requests.
npm config set always-auth true

Package naming convention

When you use the instance-level endpoint, only the packages with names in the format of @scope/package-name are available.

  • The @scope is the root namespace of the GitLab project. To follow npm’s convention, it should be lowercase. However, the GitLab package registry allows for uppercase. Before GitLab 13.10, the @scope had to be a case-sensitive match of the GitLab project’s root namespace. This was problematic because the npm public registry does not allow uppercase letters. GitLab 13.10 relaxes this requirement and translates uppercase in the GitLab @scope to lowercase for npm. For example, a package @MyScope/package-name in GitLab becomes @myscope/package-name for npm.
  • The package-name can be whatever you want.

For example, if your project is https://gitlab.example.com/my-org/engineering-group/team-amazing/analytics, the root namespace is my-org. When you publish a package, it must have my-org as the scope.

Project Package Supported
my-org/bar @my-org/bar Yes
my-org/bar/baz @my-org/baz Yes
My-Org/Bar/baz @my-org/Baz Yes
My-Org/Bar/baz @My-Org/Baz Yes
my-org/bar/buz @my-org/anything Yes
gitlab-org/gitlab @gitlab-org/gitlab Yes
gitlab-org/gitlab @foo/bar No

In GitLab, this regex validates all package names from all package managers:

/\A\@?(([\w\-\.\+]*)\/)*([\w\-\.]+)@?(([\w\-\.\+]*)\/)*([\w\-\.]*)\z/

This regex allows almost all of the characters that npm allows, with a few exceptions (for example, ~ is not allowed).

The regex also allows for capital letters, while npm does not.

Limitations

When you update the path of a user or group, or transfer a subgroup or project, you must remove any npm packages first. You cannot update the root namespace of a project with npm packages. Make sure you update your .npmrc files to follow the naming convention and run npm publish if necessary.

Publish an npm package

Prerequisites:

To upload an npm package to your project, run this command:

npm publish

To view the package, go to your project’s Packages & Registries.

You can also define "publishConfig" for your project in package.json. For example: