-[Container Registry](../user/packages/container_registry/index.md)(`$CI_REGISTRY_PASSWORD` is actually `$CI_JOB_TOKEN`, but this may change in the future)
-[Container Registry](../user/packages/container_registry/index.md)(`$CI_REGISTRY_PASSWORD` is actually `$CI_JOB_TOKEN`, but this may change in the future)
info:To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers
info:To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers
---
---
# GitLab NPM Registry
# NPM packages in the Package Registry
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5934) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.7.
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5934) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.7.
> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Core in 13.3.
> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Core in 13.3.
With the GitLab NPM Registry, every
Publish NPM packages in your project's Package Registry. Then install the
project can have its own space to store NPM packages.
packages whenever you need to use them as a dependency.
Only [scoped](https://docs.npmjs.com/misc/scope) packages are supported.
Only [scoped](https://docs.npmjs.com/misc/scope) packages are supported.
## Enabling the NPM Registry
## Build an NPM package
NOTE: **Note:**
This option is available only if your GitLab administrator has
[enabled support for the NPM registry](../../../administration/packages/index.md).
Enabling the NPM registry makes it available for all new projects
by default. To enable it for existing projects, or if you want to disable it:
1. Navigate to your project's **Settings > General > Visibility, project features, permissions**.
1. Find the Packages feature and enable or disable it.
1. Click on **Save changes** for the changes to take effect.
You should then be able to see the **Packages & Registries** section on the left sidebar.
This section covers how to install NPM or Yarn and build a package for your
JavaScript project.
Before proceeding to authenticating with the GitLab NPM Registry, you should
If you already use NPM and know how to build your own packages, go to
get familiar with the package naming convention.
the [next section](#authenticate-to-the-package-registry).
## Getting started
### Install NPM
This section covers how to install NPM (or Yarn) and build a package for your
Install Node.js and NPM in your local development environment by following
JavaScript project. This is a quickstart if you are new to NPM packages. If you
the instructions at [npmjs.com](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm).
are already using NPM and understand how to build your own packages, move on to
the [next section](#authenticating-to-the-gitlab-npm-registry).
### Installing NPM
When installation is complete, verify you can use NPM in your terminal by
Follow the instructions at [npmjs.com](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) to download and install Node.js and
NPM to your local development environment.
Once installation is complete, verify you can use NPM in your terminal by
running:
running:
```shell
```shell
npm --version
npm --version
```
```
You should see the NPM version printed in the output:
The NPM version is shown in the output:
```plaintext
```plaintext
6.10.3
6.10.3
```
```
### Installing Yarn
### Install Yarn
You may want to install and use Yarn as an alternative to NPM. Follow the
As an alternative to NPM, you can install Yarn in your local environment by following the
instructions at [yarnpkg.com](https://classic.yarnpkg.com/en/docs/install) to install on
instructions at [yarnpkg.com](https://classic.yarnpkg.com/en/docs/install).
your development environment.
Once installed, you can verify that Yarn is available with the following command:
When installation is complete, verify you can use Yarn in your terminal by
running:
```shell
```shell
yarn --version
yarn --version
```
```
You should see the version printed like so:
The Yarn version is shown in the output:
```plaintext
```plaintext
1.19.1
1.19.1
```
```
### Creating a project
### Create a project
Understanding how to create a full JavaScript project is outside the scope of
To create a project:
this guide but you can initialize a new empty package by creating and navigating
to an empty directory and using the following command:
```shell
1. Create an empty directory.
npm init
1. Go to the directory and initialize an empty package by running:
```
Or if you're using Yarn:
```shell
npm init
```
```shell
Or if you're using Yarn:
yarn init
```
```shell
yarn init
```
This takes you through a series of questions to produce a `package.json`
1. Enter responses to the questions. Ensure the **package name** follows
file, which is required for all NPM packages. The most important question is the
the [naming convention](#package-naming-convention) and is scoped to the
package name. NPM packages must [follow the naming convention](#package-naming-convention)
project or group where the registry exists.
and be scoped to the project or group where the registry exists.
Once you have completed the setup, you are now ready to upload your package to
A `package.json` file is created.
the GitLab registry. To get started, you need to set up authentication and then
configure GitLab as a remote registry.
## Authenticating to the GitLab NPM Registry
## Authenticate to the Package Registry
If a project is private or you want to upload an NPM package to GitLab,
To authenticate to the Package Registry, you must use one of the following:
you need to provide credentials for authentication. [Personal access tokens](../../profile/personal_access_tokens.md)
and [deploy tokens](../../project/deploy_tokens/index.md)
are preferred, but support is available for [OAuth tokens](../../../api/oauth2.md#resource-owner-password-credentials-flow).
CAUTION: **Two-factor authentication (2FA) is only supported with personal access tokens:**
- A [personal access token](../../../user/profile/personal_access_tokens.md)
If you have 2FA enabled, you need to use a [personal access token](../../profile/personal_access_tokens.md) with OAuth headers with the scope set to `api` or a [deploy token](../../project/deploy_tokens/index.md) with `read_package_registry` or `write_package_registry` scopes. Standard OAuth tokens cannot authenticate to the GitLab NPM Registry.
(required for two-factor authentication (2FA)), with the scope set to `api`.
- A [deploy token](./../../project/deploy_tokens/index.md), with the scope set to `read_package_registry`, `write_package_registry`, or both.
- It's not recommended, but you can use [OAuth tokens](../../../api/oauth2.md#resource-owner-password-credentials-flow).
Standard OAuth tokens cannot authenticate to the GitLab NPM Registry. You must use a personal access token with OAuth headers.
- A [CI job token](#authenticate-with-a-ci-job-token).
### Authenticating with a personal access token or deploy token
### Authenticate with a personal access token or deploy token
To authenticate with a [personal access token](../../profile/personal_access_tokens.md) or [deploy token](../../project/deploy_tokens/index.md),
To authenticate with a [personal access token](../../profile/personal_access_tokens.md) or [deploy token](../../project/deploy_tokens/index.md),
set your NPM configuration:
set your NPM configuration:
```shell
```shell
# Set URL for your scoped packages.
# Set URL for your scoped packages
# For example package with name `@foo/bar` will use this URL for download
# For example, a package named `@foo/bar` uses this URL for download
npm config set @foo:registry https://gitlab.com/api/v4/packages/npm/
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
# Add the token for the scoped packages URL
# `@foo/` packages from private projects.
# Use this to download `@foo/` packages from private projects
This regex allows almost all of the characters that NPM allows, with a few exceptions (for example, `~` is not allowed).
DANGER: **Warning:**
The regex also allows for capital letters, while NPM does not. Capital letters are needed because the scope must be
Due to a [bug in NPM](https://github.com/npm/cli/issues/1994), version `7.x` and later do not respect the `publishConfig` entry in the `package.json` file. To publish, you must use an earlier version of NPM, or temporarily set your `.npmrc` scope to `@foo:registry=https://gitlab.example.com/api/v4/projects/<project_id>/packages/npm`.
identical to the root namespace of the project.
CAUTION: **Caution:**
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.
Before you can upload a package, you need to specify the registry
## Publish an NPM package
Before you can publish a package, you must specify the registry
for NPM. To do this, add the following section to the bottom of `package.json`:
for NPM. To do this, add the following section to the bottom of `package.json`:
It allows for capital letters, while NPM does not, and allows for almost all of the
## Publishing packages with the same name or version
characters NPM allows with a few exceptions (`~` is not allowed).
NOTE: **Note:**
You cannot publish a package if a package of the same name and version already exists.
Capital letters are needed because the scope is required to be
You must delete the existing package first.
identical to the top level namespace of the project. So, for example, if your
project path is `My-Group/project-foo`, your package must be named `@My-Group/any-package-name`.
`@my-group/any-package-name` will not work.
CAUTION: **When updating the path of a user/group or transferring a (sub)group/project:**
This aligns with npmjs.org's behavior. However, npmjs.org does not ever let you publish
Make sure to remove any NPM packages first. You cannot update the root namespace of a project with NPM packages. Don't forget to update your `.npmrc` files to follow the above naming convention and run `npm publish` if necessary.
the same version more than once, even if it has been deleted.
Now, you can configure your project to authenticate with the GitLab NPM
## Install a package
Registry.
## Installing a package
NPM packages are commonly-installed by using the `npm` or `yarn` commands
in a JavaScript project.
NPM packages are commonly installed using the `npm` or `yarn` commands
1. Set the URL for scoped packages by running:
inside a JavaScript project. If you haven't already, set the
URL for scoped packages. You can do this with the following command:
```shell
```shell
npm config set @foo:registry https://gitlab.com/api/v4/packages/npm/
npm config set @foo:registry https://gitlab.example.com/api/v4/packages/npm/
```
```
Replace `@foo` with your scope.
Next, you need to ensure [authentication](#authenticating-to-the-gitlab-npm-registry)
Replace `@foo` with your scope.
is setup so you can successfully install the package. Once this has been
completed, you can run the following command inside your project to install a
package:
```shell
1. Ensure [authentication](#authenticate-to-the-package-registry) is configured.
npm install @my-project-scope/my-package
```
Or if you're using Yarn:
1. In your project, to install a package, run:
```shell
```shell
yarn add @my-project-scope/my-package
npm install @my-project-scope/my-package
```
```
### Forwarding requests to npmjs.org
Or if you're using Yarn:
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/55344) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.9.
```shell
yarn add @my-project-scope/my-package
```
By default, when an NPM package is not found in the GitLab NPM Registry, the request is forwarded to [npmjs.com](https://www.npmjs.com/).
In [GitLab 12.9 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/55344),
when an NPM package is not found in the Package Registry, the request is forwarded to [npmjs.com](https://www.npmjs.com/).
Administrators can disable this behavior in the [Continuous Integration settings](../../admin_area/settings/continuous_integration.md).
Administrators can disable this behavior in the [Continuous Integration settings](../../admin_area/settings/continuous_integration.md).
### Installing packages from other organizations
### Install NPM packages from other organizations
You can route package requests to organizations and users outside of GitLab.
You can route package requests to organizations and users outside of GitLab.
To do this, add lines to your `.npmrc` file, replacing `my-org` with the namespace or group that owns your project's repository. The name is case-sensitive and must match the name of your group or namespace exactly.
To do this, add lines to your `.npmrc` file. Replace `my-org` with the namespace or group that owns your project's repository,
and use your organization's URL. The name is case-sensitive and must match the name of your group or namespace exactly.
### `npm install` returns `Error: Failed to replace env in config: ${NPM_TOKEN}`
### `npm install` returns `Error: Failed to replace env in config: ${NPM_TOKEN}`
You do not need a token to run `npm install` unless your project is private (the token is only required to publish). If the `.npmrc` file was checked in with a reference to `$NPM_TOKEN`, you can remove it. If you prefer to leave the reference in, you need to set a value prior to running `npm install` or set the value using [GitLab environment variables](./../../../ci/variables/README.md):
You do not need a token to run `npm install` unless your project is private. The token is only required to publish. If the `.npmrc` file was checked in with a reference to `$NPM_TOKEN`, you can remove it. If you prefer to leave the reference in, you must set a value prior to running `npm install` or set the value by using [GitLab environment variables](./../../../ci/variables/README.md):
- Check that your token is not expired and has appropriate permissions.
If you get this error, ensure that:
- Check that [your token does not begin with `-`](https://gitlab.com/gitlab-org/gitlab/-/issues/235473).
- Check if you have attempted to publish a package with a name that already exists within a given scope.
- Ensure the scoped packages URL includes a trailing slash:
- Correct: `//gitlab.com/api/v4/packages/npm/`
- Incorrect: `//gitlab.com/api/v4/packages/npm`
## NPM dependencies metadata
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11867) in GitLab Premium 12.6.
Starting from GitLab 12.6, new packages published to the GitLab NPM Registry expose the following attributes to the NPM client:
- name
- version
- dist-tags
- dependencies
- dependencies
- devDependencies
- bundleDependencies
- peerDependencies
- deprecated
## NPM distribution tags
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9425) in GitLab Premium 12.8.
You can add [distribution tags](https://docs.npmjs.com/cli/dist-tag) for newly published packages.
They follow NPM's convention where they are optional, and each tag can only be assigned to one
package at a time. The `latest` tag is added by default when a package is published without a tag.
The same applies to installing a package without specifying the tag or version.
Examples of the supported `dist-tag` commands and using tags in general:
```shell
npm publish @scope/package --tag# Publish new package with new tag
npm dist-tag add @scope/package@version my-tag # Add a tag to an existing package
npm dist-tag ls @scope/package # List all tags under the package
npm dist-tag rm @scope/package@version my-tag # Delete a tag from the package
npm install @scope/package@my-tag # Install a specific tag
```
NOTE: **Note:**
You cannot use your `CI_JOB_TOKEN` or deploy token with the `npm dist-tag` commands. View [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/258835) for details.
CAUTION: **Warning:**
- Your token is not expired and has appropriate permissions.
Due to a bug in NPM 6.9.0, deleting dist tags fails. Make sure your NPM version is greater than 6.9.1.
-[Your token does not begin with `-`](https://gitlab.com/gitlab-org/gitlab/-/issues/235473).
- A package with the same name doesn't already exist within the given scope.
- The scoped packages URL includes a trailing slash:
