npm packages in the package registry

  //<domain_name>/api/v4/projects/<project_id>/packages/npm/:_authToken="${NPM_TOKEN}"

//<domain_name>/api/v4/packages/npm/:_authToken="${NPM_TOKEN}"

//<domain_name>/api/v4/groups/<group_id>/-/packages/npm/:_authToken="${NPM_TOKEN}"

//<domain_name>/api/v4/projects/<project_id>/packages/npm/:_authToken="${NPM_TOKEN}"

npm config set -- //<domain_name>/:_authToken=<token>

npm config set -- //<domain_name>/api/v4/packages/npm/:_authToken=<token>

npm config set -- //<domain_name>/api/v4/groups/<group_id>/-/packages/npm/:_authToken=<token>

npm config set -- //<domain_name>/api/v4/projects/<project_id>/packages/npm/:_authToken=<token>

https://gitlab.example.com/api/v4/projects/<project_id>/packages/npm/

@scope:registry=https://gitlab.example.com/api/v4/projects/<project_id>/packages/npm/ //gitlab.example.com/api/v4/projects/<project_id>/packages/npm/:_authToken="${NPM_TOKEN}"

//<domain_name>/api/v4/packages/npm/:_authToken="${NPM_TOKEN}"
```0

:::TabTitle `package.json`

Add a `publishConfig` section to your `package.json`:

```shell
//<domain_name>/api/v4/packages/npm/:_authToken="${NPM_TOKEN}"
```1

::EndTabs

Replace `@scope` with your package's scope.

### For installing packages

When you install packages, you can use project, group, or instance endpoints. The URL structure varies accordingly.
To configure these URLs, use one of these methods:

::Tabs

:::TabTitle `.npmrc` file

Create or edit the `.npmrc` file in your project root. Use the appropriate URL based on your needs:

- For a project:

  ```shell
  @scope:registry=https://gitlab.example.com/api/v4/projects/<project_id>/packages/npm/

//<domain_name>/api/v4/packages/npm/:_authToken="${NPM_TOKEN}"
```2

### Publish a package with the command line

After you [configure authentication](#authenticate-to-the-package-registry), publish the NPM package with:

```shell
//<domain_name>/api/v4/packages/npm/:_authToken="${NPM_TOKEN}"
```3

If you're using an `.npmrc` file for authentication, set the expected environment variables:

```shell
//<domain_name>/api/v4/packages/npm/:_authToken="${NPM_TOKEN}"
```4

If the uploaded package has more than one `package.json` file, only the first one found is used, and the others are ignored.

### Publish a package with a CI/CD pipeline

When publishing by using a CI/CD pipeline, you can use the
[predefined variables](../../../ci/variables/predefined_variables.md) `${CI_PROJECT_ID}` and `${CI_JOB_TOKEN}`
to authenticate with your project's package registry. GitLab uses these variables to create a `.npmrc` file
for authentication during execution of your CI/CD job.

NOTE:
When you generate the `.npmrc` file, do not specify the port after `${CI_SERVER_HOST}` if it is a default port.
`http` URLs default to `80`, and `https` URLs default to `443`.

In the GitLab project containing your `package.json`, edit or create a `.gitlab-ci.yml` file. For example:

```shell
//<domain_name>/api/v4/packages/npm/:_authToken="${NPM_TOKEN}"
```5

Replace `@scope` with the [scope](https://docs.npmjs.com/cli/v10/using-npm/scope/) of the package that is being published.

Your package is published to the package registry when the `publish-npm` job in your pipeline runs.

## Install a package

If multiple packages have the same name and version, when you install a package, the most recently published package is retrieved.

You can install a package from a GitLab project, group, or instance:

- **Instance**: Use when you have many npm packages in different GitLab groups or in their own namespace.
- **Group**: Use when you have many npm packages in different projects in the same GitLab group.
- **Project**: Use when you have few npm packages and they are not in the same GitLab group.

### Install from an instance

Prerequisites:

- The package was published according to the scoped [naming convention](#naming-convention).

1. [Authenticate to the package registry](#authenticate-to-the-package-registry).
1. Set the registry:

   ```shell
   npm config set @scope:registry https://<domain_name>.com/api/v4/packages/npm/

//<domain_name>/api/v4/packages/npm/:_authToken="${NPM_TOKEN}"
```6

The CLI also accepts version ranges for `@scope/package`. For example:

```shell
//<domain_name>/api/v4/packages/npm/:_authToken="${NPM_TOKEN}"
```7

When a package is deprecated, its status will be updated to `deprecated`.

### Remove deprecation warning

To remove a package's deprecation warning, specify `""` (an empty string) for the message. For example:

```shell
//<domain_name>/api/v4/packages/npm/:_authToken="${NPM_TOKEN}"
```8

When a package's deprecation warning is removed, its status will be updated to `default`.

## Helpful hints

### 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. Replace `@my-other-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.

```shell
//<domain_name>/api/v4/packages/npm/:_authToken="${NPM_TOKEN}"
```9

### npm metadata

The GitLab package registry exposes the following attributes to the npm client.
These are similar to the [abbreviated metadata format](https://github.com/npm/registry/blob/main/docs/responses/package-metadata.md#abbreviated-version-object):

- `name`
- `versions`
  - `name`
  - `version`
  - `deprecated`
  - `dependencies`
  - `devDependencies`
  - `bundleDependencies`
  - `peerDependencies`
  - `bin`
  - `directories`
  - `dist`
  - `engines`
  - `_hasShrinkwrap`
  - `hasInstallScript`: `true` if this version has the install scripts.

### Add npm distribution tags

You can add [distribution tags](https://docs.npmjs.com/cli/dist-tag/) to newly-published packages.
Tags are optional and can be assigned to only one package at a time.

When you publish a package without a tag, the `latest` tag is added by default.
When you install a package without specifying the tag or version, the `latest` tag is used.

Examples of the supported `dist-tag` commands:

```shell
//<domain_name>/api/v4/groups/<group_id>/-/packages/npm/:_authToken="${NPM_TOKEN}"
```0

#### From CI/CD

> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/258835) in GitLab 15.10.

You can use a [`CI_JOB_TOKEN`](../../../ci/jobs/ci_job_token.md) or [deploy token](../../project/deploy_tokens/index.md)
to run `npm dist-tag` commands in a GitLab CI/CD job.

Prerequisites:

- You have npm version 6.9.1 or later. In earlier versions, deleting distribution tags fails due to a bug in npm 6.9.0.

For example:

```shell
//<domain_name>/api/v4/groups/<group_id>/-/packages/npm/:_authToken="${NPM_TOKEN}"
```1

### Supported CLI commands

The GitLab npm repository supports the following commands for the npm CLI (`npm`) and yarn CLI
(`yarn`):

- `npm install`: Install npm packages.
- `npm publish`: Publish an npm package to the registry.
- `npm dist-tag add`: Add a dist-tag to an npm package.
- `npm dist-tag ls`: List dist-tags for a package.
- `npm dist-tag rm`: Delete a dist-tag.
- `npm ci`: Install npm packages directly from your `package-lock.json` file.
- `npm view`: Show package metadata.
- `npm pack`: Create a tarball from a package.
- `npm deprecate`: Deprecate a version of a package.

## Troubleshooting

### npm logs don't display correctly

You might encounter an error that says:

```shell
//<domain_name>/api/v4/groups/<group_id>/-/packages/npm/:_authToken="${NPM_TOKEN}"
```2

If the log doesn't appear in the `.npm/_logs/` directory, you can copy the
log to your root directory and view it there:

```shell
//<domain_name>/api/v4/groups/<group_id>/-/packages/npm/:_authToken="${NPM_TOKEN}"
```3

The npm log is copied to `/root/.npm/_logs/` as an artifact.

### `404 Not Found` errors are happening on `npm install` or `yarn`

Using `CI_JOB_TOKEN` to install npm packages with dependencies in another project gives you 404 Not Found errors. You need to authenticate with a token that has access to the package and all its dependencies.

If the package and its dependencies are in separate projects but in the same group, you can use a
[group deploy token](../../project/deploy_tokens/index.md#create-a-deploy-token):

```shell
//<domain_name>/api/v4/groups/<group_id>/-/packages/npm/:_authToken="${NPM_TOKEN}"
```4

If the package and its dependencies are spread across multiple groups, you can use a [personal access token](../../profile/personal_access_tokens.md)
from a user that has access to all the groups or individual projects:

```shell
//<domain_name>/api/v4/groups/<group_id>/-/packages/npm/:_authToken="${NPM_TOKEN}"
```5

WARNING:
Personal access tokens must be treated carefully. Read our [token security considerations](../../../security/tokens/index.md#security-considerations)
for guidance on managing personal access tokens (for example, setting a short expiry and using minimal scopes).

### `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 `@scope/my-package`, then your `package.json` file
should look like:

```shell
//<domain_name>/api/v4/groups/<group_id>/-/packages/npm/:_authToken="${NPM_TOKEN}"
```6

And the `.npmrc` file should look like:

```shell
//<domain_name>/api/v4/groups/<group_id>/-/packages/npm/:_authToken="${NPM_TOKEN}"
```7

### `npm install` returns `npm ERR! 403 Forbidden`

If you get this error, ensure that:

- The package registry is enabled in your project settings. Although the package registry is enabled by default, it's possible to [disable it](../package_registry/index.md#disable-the-package-registry).
- Your token is not expired and has appropriate permissions.
- A package with the same name or version doesn't already exist within the given scope.
- The scoped packages URL includes a trailing slash:
  - Correct: `//gitlab.example.com/api/v4/packages/npm/`
  - Incorrect: `//gitlab.example.com/api/v4/packages/npm`

### `npm publish` returns `npm ERR! 400 Bad Request`

If you get this error, one of the following problems could be causing it.

### Package name does not meet the naming convention

Your package name may not meet the [`@scope/package-name` package naming convention](#naming-convention).

Ensure the name meets the convention exactly, including the case. Then try to publish again.

### Package already exists

Your package has already been published to another project in the same root namespace and therefore cannot be published again using the same name.

This is also true even if the prior published package shares the same name, but not the version.

### Package JSON file is too large

Make sure that your `package.json` file does not exceed `20,000` characters.