2020-06-23 00:09:42 +05:30
---
stage: Package
group: Package
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
---
2020-10-24 23:57:45 +05:30
# GitLab NPM Registry
2019-12-04 20:38:33 +05:30
2020-10-24 23:57:45 +05:30
> - [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.
2019-12-04 20:38:33 +05:30
With the GitLab NPM Registry, every
project can have its own space to store NPM packages.
2020-01-01 13:55:28 +05:30
![GitLab NPM Registry ](img/npm_package_view_v12_5.png )
2019-12-04 20:38:33 +05:30
NOTE: **Note:**
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
2020-10-24 23:57:45 +05:30
[enabled support for the NPM registry ](../../../administration/packages/index.md ).
2019-12-04 20:38:33 +05:30
2020-10-24 23:57:45 +05:30
Enabling the NPM registry makes it available for all new projects
2019-12-04 20:38:33 +05:30
by default. To enable it for existing projects, or if you want to disable it:
2020-07-28 23:09:34 +05:30
1. Navigate to your project's **Settings > General > Visibility, project features, permissions** .
2019-12-04 20:38:33 +05:30
1. Find the Packages feature and enable or disable it.
1. Click on **Save changes** for the changes to take effect.
2020-05-24 23:13:21 +05:30
You should then be able to see the **Packages & Registries** section on the left sidebar.
2019-12-04 20:38:33 +05:30
Before proceeding to authenticating with the GitLab NPM Registry, you should
get familiar with the package naming convention.
2020-03-13 15:44:24 +05:30
## Getting started
2019-12-04 20:38:33 +05:30
2020-10-24 23:57:45 +05:30
This section covers how to install NPM (or Yarn) and build a package for your
2020-03-13 15:44:24 +05:30
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 ).
2019-12-04 20:38:33 +05:30
2020-03-13 15:44:24 +05:30
### Installing NPM
2019-12-04 20:38:33 +05:30
2020-03-13 15:44:24 +05:30
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.
2020-01-01 13:55:28 +05:30
2020-03-13 15:44:24 +05:30
Once installation is complete, verify you can use NPM in your terminal by
running:
```shell
npm --version
2020-01-01 13:55:28 +05:30
```
2020-03-13 15:44:24 +05:30
You should see the NPM version printed in the output:
2020-04-08 14:13:33 +05:30
```plaintext
2020-03-13 15:44:24 +05:30
6.10.3
2020-01-01 13:55:28 +05:30
```
2020-03-13 15:44:24 +05:30
### Installing Yarn
2020-01-01 13:55:28 +05:30
2020-03-13 15:44:24 +05:30
You may want to install and use Yarn as an alternative to NPM. Follow the
2020-04-22 19:07:51 +05:30
instructions at [yarnpkg.com ](https://classic.yarnpkg.com/en/docs/install ) to install on
2020-03-13 15:44:24 +05:30
your development environment.
2020-01-01 13:55:28 +05:30
2020-03-13 15:44:24 +05:30
Once installed, you can verify that Yarn is available with the following command:
2019-12-26 22:10:19 +05:30
2020-03-13 15:44:24 +05:30
```shell
yarn --version
```
You should see the version printed like so:
2020-04-08 14:13:33 +05:30
```plaintext
2020-03-13 15:44:24 +05:30
1.19.1
```
### Creating 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:
```shell
npm init
```
Or if you're using Yarn:
```shell
yarn init
```
2020-10-24 23:57:45 +05:30
This takes you through a series of questions to produce a `package.json`
2020-03-13 15:44:24 +05:30
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.
Once you have completed the setup, you are now ready to upload your package to
2020-10-24 23:57:45 +05:30
the GitLab registry. To get started, you need to set up authentication and then
2020-03-13 15:44:24 +05:30
configure GitLab as a remote registry.
2019-12-04 20:38:33 +05:30
## Authenticating to the GitLab NPM Registry
If a project is private or you want to upload an NPM package to GitLab,
2020-10-24 23:57:45 +05:30
you need to provide credentials for authentication. [Personal access tokens ](../../profile/personal_access_tokens.md )
2020-05-24 23:13:21 +05:30
and [deploy tokens ](../../project/deploy_tokens/index.md )
2020-03-13 15:44:24 +05:30
are preferred, but support is available for [OAuth tokens ](../../../api/oauth2.md#resource-owner-password-credentials-flow ).
2019-12-04 20:38:33 +05:30
2020-05-24 23:13:21 +05:30
CAUTION: **Two-factor authentication (2FA) is only supported with personal access tokens:**
2020-10-24 23:57:45 +05:30
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.
2019-12-04 20:38:33 +05:30
2020-05-24 23:13:21 +05:30
### Authenticating with a personal access token or deploy token
2019-12-04 20:38:33 +05:30
2020-05-24 23:13:21 +05:30
To authenticate with a [personal access token ](../../profile/personal_access_tokens.md ) or [deploy token ](../../project/deploy_tokens/index.md ),
2020-03-13 15:44:24 +05:30
set your NPM configuration:
2019-12-04 20:38:33 +05:30
2020-03-13 15:44:24 +05:30
```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/
2019-12-04 20:38:33 +05:30
2020-03-13 15:44:24 +05:30
# Add the token for the scoped packages URL. This will allow you to download
# `@foo/` packages from private projects.
2020-04-08 14:13:33 +05:30
npm config set '//gitlab.com/api/v4/packages/npm/:_authToken' "< your_token > "
2019-12-04 20:38:33 +05:30
2020-03-13 15:44:24 +05:30
# Add token for uploading to the registry. Replace <your_project_id>
# with the project you want your package to be uploaded to.
2020-04-08 14:13:33 +05:30
npm config set '//gitlab.com/api/v4/projects/< your_project_id > /packages/npm/:_authToken' "< your_token > "
2019-12-04 20:38:33 +05:30
```
Replace `<your_project_id>` with your project ID which can be found on the home page
2020-05-24 23:13:21 +05:30
of your project and `<your_token>` with your personal access token or deploy token.
2019-12-04 20:38:33 +05:30
2020-04-08 14:13:33 +05:30
If you have a self-managed GitLab installation, replace `gitlab.com` with your
2019-12-04 20:38:33 +05:30
domain name.
You should now be able to download and upload NPM packages to your project.
NOTE: **Note:**
2020-04-22 19:07:51 +05:30
If you encounter an error message with [Yarn ](https://classic.yarnpkg.com/en/ ), see the
2019-12-04 20:38:33 +05:30
[troubleshooting section ](#troubleshooting ).
2019-12-21 20:55:43 +05:30
### Using variables to avoid hard-coding auth token values
2020-03-13 15:44:24 +05:30
To avoid hard-coding the `authToken` value, you may use a variables in its place:
2019-12-21 20:55:43 +05:30
2020-03-13 15:44:24 +05:30
```shell
npm config set '//gitlab.com/api/v4/projects/< your_project_id > /packages/npm/:_authToken' "${NPM_TOKEN}"
npm config set '//gitlab.com/api/v4/packages/npm/:_authToken' "${NPM_TOKEN}"
2019-12-21 20:55:43 +05:30
```
Then, you could run `npm publish` either locally or via GitLab CI/CD:
- **Locally:** Export `NPM_TOKEN` before publishing:
2020-03-13 15:44:24 +05:30
```shell
2019-12-21 20:55:43 +05:30
NPM_TOKEN=< your_token > npm publish
```
- **GitLab CI/CD:** Set an `NPM_TOKEN` [variable ](../../../ci/variables/README.md )
under your project's **Settings > CI/CD > Variables** .
2020-01-01 13:55:28 +05:30
2019-12-26 22:10:19 +05:30
### Authenticating with a CI job token
2020-06-23 00:09:42 +05:30
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9104) in GitLab Premium 12.5.
2019-12-26 22:10:19 +05:30
2020-05-24 23:13:21 +05:30
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.
2020-10-24 23:57:45 +05:30
The token inherits the permissions of the user that generates the pipeline.
2019-12-26 22:10:19 +05:30
2020-01-01 13:55:28 +05:30
Add a corresponding section to your `.npmrc` file:
2019-12-26 22:10:19 +05:30
```ini
@foo:registry =https://gitlab.com/api/v4/packages/npm/
2020-03-13 15:44:24 +05:30
//gitlab.com/api/v4/packages/npm/:_authToken=${CI_JOB_TOKEN}
//gitlab.com/api/v4/projects/${CI_PROJECT_ID}/packages/npm/:_authToken=${CI_JOB_TOKEN}
2019-12-26 22:10:19 +05:30
```
2019-12-21 20:55:43 +05:30
2019-12-04 20:38:33 +05:30
## Uploading packages
2020-10-24 23:57:45 +05:30
Before you can upload a package, you need to specify the registry
2019-12-04 20:38:33 +05:30
for NPM. To do this, add the following section to the bottom of `package.json` :
```json
2020-03-13 15:44:24 +05:30
"publishConfig": {
"@foo:registry":"https://gitlab.com/api/v4/projects/< your_project_id > /packages/npm/"
}
2019-12-04 20:38:33 +05:30
```
Replace `<your_project_id>` with your project ID, which can be found on the home
page of your project, and replace `@foo` with your own scope.
2020-04-08 14:13:33 +05:30
If you have a self-managed GitLab installation, replace `gitlab.com` with your
2019-12-04 20:38:33 +05:30
domain name.
Once you have enabled it and set up [authentication ](#authenticating-to-the-gitlab-npm-registry ),
you can upload an NPM package to your project:
2020-03-13 15:44:24 +05:30
```shell
2019-12-04 20:38:33 +05:30
npm publish
```
2020-05-24 23:13:21 +05:30
You can then navigate to your project's **Packages & Registries** page and see the uploaded
2019-12-04 20:38:33 +05:30
packages or even delete them.
2020-10-24 23:57:45 +05:30
Attempting to publish a package with a name that already exists within
a given scope causes a `403 Forbidden!` error.
2019-12-04 20:38:33 +05:30
## Uploading a package with the same version twice
2020-01-01 13:55:28 +05:30
You cannot upload a package with the same name and version twice, unless you
delete the existing package first. This aligns with npmjs.org's behavior, with
the exception that npmjs.org does not allow users to ever publish the same version
more than once, even if it has been deleted.
2019-12-04 20:38:33 +05:30
2020-03-13 15:44:24 +05:30
## Package naming convention
**Packages must be scoped in the root namespace of the project**. The package
name may be anything but it is preferred that the project name be used unless
it is not possible due to a naming collision. For example:
| Project | Package | Supported |
| ---------------------- | ----------------------- | --------- |
| `foo/bar` | `@foo/bar` | Yes |
| `foo/bar/baz` | `@foo/baz` | Yes |
| `foo/bar/buz` | `@foo/anything` | Yes |
| `gitlab-org/gitlab` | `@gitlab-org/gitlab` | Yes |
| `gitlab-org/gitlab` | `@foo/bar` | No |
The regex that is used for naming is validating all package names from all package managers:
2020-04-22 19:07:51 +05:30
```plaintext
2020-03-13 15:44:24 +05:30
/\A\@?(([\w\-\.\+]*)\/)*([\w\-\.]+)@?(([\w\-\.\+]*)\/)*([\w\-\.]*)\z/
```
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).
2020-07-28 23:09:34 +05:30
NOTE: **Note:**
Capital letters are needed because the scope is required to be
2020-03-13 15:44:24 +05:30
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:**
2020-10-24 23:57:45 +05:30
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.
2020-03-13 15:44:24 +05:30
Now, you can configure your project to authenticate with the GitLab NPM
Registry.
## Installing a package
2020-04-22 19:07:51 +05:30
NPM packages are commonly installed using the `npm` or `yarn` commands
2020-10-24 23:57:45 +05:30
inside a JavaScript project. If you haven't already, set the
2020-03-13 15:44:24 +05:30
URL for scoped packages. You can do this with the following command:
```shell
npm config set @foo:registry https://gitlab.com/api/v4/packages/npm/
```
2020-10-24 23:57:45 +05:30
Replace `@foo` with your scope.
2020-03-13 15:44:24 +05:30
2020-10-24 23:57:45 +05:30
Next, you need to ensure [authentication ](#authenticating-to-the-gitlab-npm-registry )
2020-03-13 15:44:24 +05:30
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
npm install @my -project-scope/my-package
```
Or if you're using Yarn:
```shell
yarn add @my -project-scope/my-package
```
2020-04-08 14:13:33 +05:30
### Forwarding requests to npmjs.org
2020-06-23 00:09:42 +05:30
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/55344) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.9.
2020-04-08 14:13:33 +05:30
2020-10-24 23:57:45 +05:30
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/ ).
2020-04-08 14:13:33 +05:30
Administrators can disable this behavior in the [Continuous Integration settings ](../../admin_area/settings/continuous_integration.md ).
2020-03-13 15:44:24 +05:30
## Removing a package
In the packages view of your project page, you can delete packages by clicking
the red trash icons or by clicking the **Delete** button on the package details
page.
## Publishing a package with CI/CD
2020-04-22 19:07:51 +05:30
To work with NPM commands within [GitLab CI/CD ](./../../../ci/README.md ), you can use
2020-05-24 23:13:21 +05:30
`CI_JOB_TOKEN` in place of the personal access token or deploy token in your commands.
2020-03-13 15:44:24 +05:30
2020-04-08 14:13:33 +05:30
A simple example `.gitlab-ci.yml` file for publishing NPM packages:
2020-03-13 15:44:24 +05:30
2020-05-24 23:13:21 +05:30
```yaml
2020-03-13 15:44:24 +05:30
image: node:latest
stages:
- deploy
deploy:
stage: deploy
script:
2020-07-28 23:09:34 +05:30
- echo '//gitlab.com/api/v4/projects/${CI_PROJECT_ID}/packages/npm/:_authToken=${CI_JOB_TOKEN}'>.npmrc
2020-03-13 15:44:24 +05:30
- npm publish
```
2020-07-28 23:09:34 +05:30
Learn more about [using `CI_JOB_TOKEN` to authenticate to the GitLab NPM registry ](#authenticating-with-a-ci-job-token ).
2019-12-04 20:38:33 +05:30
## Troubleshooting
### Error running yarn with NPM registry
2020-04-22 19:07:51 +05:30
If you are using [yarn ](https://classic.yarnpkg.com/en/ ) with the NPM registry, you may get
2019-12-04 20:38:33 +05:30
an error message like:
2020-03-13 15:44:24 +05:30
```shell
2019-12-04 20:38:33 +05:30
yarn install v1.15.2
warning package.json: No license field
info No lockfile found.
warning XXX: No license field
[1/4] 🔍 Resolving packages...
[2/4] 🚚 Fetching packages...
error An unexpected error occurred: "https://gitlab.com/api/v4/projects/XXX/packages/npm/XXX/XXX/-/XXX/XXX-X.X.X.tgz: Request failed \"404 Not Found\"".
info If you think this is a bug, please open a bug report with the information provided in "/Users/XXX/gitlab-migration/module-util/yarn-error.log".
2020-04-22 19:07:51 +05:30
info Visit https://classic.yarnpkg.com/en/docs/cli/install for documentation about this command
2019-12-04 20:38:33 +05:30
```
2020-03-13 15:44:24 +05:30
In this case, try adding this to your `.npmrc` file (and replace `<your_token>`
2020-05-24 23:13:21 +05:30
with your personal access token or deploy token):
2019-12-04 20:38:33 +05:30
2020-05-24 23:13:21 +05:30
```plaintext
2020-03-13 15:44:24 +05:30
//gitlab.com/api/v4/projects/:_authToken=< your_token >
2019-12-04 20:38:33 +05:30
```
2019-12-21 20:55:43 +05:30
### `npm publish` targets default NPM registry (`registry.npmjs.org`)
Ensure that your package scope is set consistently in your `package.json` and `.npmrc` files.
For example, if your project name in GitLab is `foo/my-package` , then your `package.json` file
should look like:
```json
{
"name": "@foo/my-package",
"version": "1.0.0",
"description": "Example package for GitLab NPM registry",
"publishConfig": {
"@foo:registry":"https://gitlab.com/api/v4/projects/< your_project_id > /packages/npm/"
}
}
```
And the `.npmrc` file should look like:
```ini
2020-03-13 15:44:24 +05:30
//gitlab.com/api/v4/projects/< your_project_id > /packages/npm/:_authToken=< your_token >
//gitlab.com/api/v4/packages/npm/:_authToken=< your_token >
2019-12-21 20:55:43 +05:30
@foo:registry =https://gitlab.com/api/v4/packages/npm/
```
2020-01-01 13:55:28 +05:30
2020-03-13 15:44:24 +05:30
### `npm install` returns `Error: Failed to replace env in config: ${NPM_TOKEN}`
2020-10-24 23:57:45 +05:30
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 ):
2020-03-13 15:44:24 +05:30
```shell
NPM_TOKEN=< your_token > npm install
```
2020-05-24 23:13:21 +05:30
### `npm install` returns `npm ERR! 403 Forbidden`
- Check that your token is not expired and has appropriate permissions.
- 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`
2020-01-01 13:55:28 +05:30
## NPM dependencies metadata
2020-06-23 00:09:42 +05:30
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11867) in GitLab Premium 12.6.
2020-01-01 13:55:28 +05:30
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
2020-03-13 15:44:24 +05:30
## NPM distribution tags
2020-06-23 00:09:42 +05:30
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9425) in GitLab Premium 12.8.
2020-03-13 15:44:24 +05:30
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
```
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.