-[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
---
# 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.
> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Core in 13.3.
With the GitLab NPM Registry, every
project can have its own space to store NPM packages.
Publish NPM packages in your project's Package Registry. Then install the
packages whenever you need to use them as a dependency.
Only [scoped](https://docs.npmjs.com/misc/scope) packages are supported.
## Enabling the NPM Registry
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.
## Build an NPM package
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
get familiar with the package naming convention.
If you already use NPM and know how to build your own packages, go to
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
JavaScript project. This is a quickstart if you are new to NPM packages. If you
are already using NPM and understand how to build your own packages, move on to
the [next section](#authenticating-to-the-gitlab-npm-registry).
Install Node.js and NPM in your local development environment by following
the instructions at [npmjs.com](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm).
### Installing NPM
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
When installation is complete, verify you can use NPM in your terminal by
running:
```shell
npm --version
```
You should see the NPM version printed in the output:
The NPM version is shown in the output:
```plaintext
6.10.3
```
### Installing Yarn
### Install Yarn
You may want to install and use Yarn as an alternative to NPM. Follow the
instructions at [yarnpkg.com](https://classic.yarnpkg.com/en/docs/install) to install on
your development environment.
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).
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
yarn --version
```
You should see the version printed like so:
The Yarn version is shown in the output:
```plaintext
1.19.1
```
### Creating a project
### Create a project
Understanding how to create a full JavaScript project is outside the scope of
this guide but you can initialize a new empty package by creating and navigating
to an empty directory and using the following command:
To create a project:
```shell
npm init
```
1. Create an empty directory.
1. Go to the directory and initialize an empty package by running:
Or if you're using Yarn:
```shell
npm init
```
```shell
yarn init
```
Or if you're using Yarn:
```shell
yarn init
```
This takes you through a series of questions to produce a `package.json`
file, which is required for all NPM packages. The most important question is the
package name. NPM packages must [follow the naming convention](#package-naming-convention)
and be scoped to the project or group where the registry exists.
1. Enter responses to the questions. Ensure the **package name** follows
the [naming convention](#package-naming-convention) and is 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
the GitLab registry. To get started, you need to set up authentication and then
configure GitLab as a remote registry.
A `package.json` file is created.
## 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,
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).
To authenticate to the Package Registry, you must use one of the following:
CAUTION: **Two-factor authentication (2FA) is only supported with personal access tokens:**
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.
- A [personal access token](../../../user/profile/personal_access_tokens.md)
(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),
set your NPM configuration:
```shell
# 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.com/api/v4/packages/npm/
# Set URL for your scoped packages
# For example, a package named `@foo/bar` uses 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
This regex allows almost all of the characters that NPM allows, with a few exceptions (for example, `~` is not allowed).
DANGER: **Warning:**
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`.
The regex also allows for capital letters, while NPM does not. Capital letters are needed because the scope must be
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`:
It allows for capital letters, while NPM does not, and allows for almost all of the
characters NPM allows with a few exceptions (`~` is not allowed).
## Publishing packages with the same name or version
NOTE: **Note:**
Capital letters are needed because the scope is required to be
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.
You cannot publish a package if a package of the same name and version already exists.
You must delete the existing package first.
CAUTION: **When updating the path of a user/group or transferring a (sub)group/project:**
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.
This aligns with npmjs.org's behavior. However, npmjs.org does not ever let you publish
the same version more than once, even if it has been deleted.
Now, you can configure your project to authenticate with the GitLab NPM
Registry.
## Install a package
## 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
inside a JavaScript project. If you haven't already, set the
URL for scoped packages. You can do this with the following command:
1. Set the URL for scoped packages by running:
```shell
npm config set @foo:registry https://gitlab.com/api/v4/packages/npm/
```
Replace `@foo` with your scope.
```shell
npm config set @foo:registry https://gitlab.example.com/api/v4/packages/npm/
```
Next, you need to ensure [authentication](#authenticating-to-the-gitlab-npm-registry)
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:
Replace `@foo` with your scope.
```shell
npm install @my-project-scope/my-package
```
1. Ensure [authentication](#authenticate-to-the-package-registry) is configured.
Or if you're using Yarn:
1. In your project, to install a package, run:
```shell
yarn add @my-project-scope/my-package
```
```shell
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).
### Installing packages from other organizations
### Install NPM packages from other organizations
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}`
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.
- 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.
If you get this error, ensure that:
CAUTION: **Warning:**
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 is not expired and has appropriate permissions.
-[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:
