---
title: 'npm Package Registry'
license: 'Apache-2.0'
origin_url: 'https://github.com/go-gitea/gitea/blob/e865de1e9d65dc09797d165a51c8e705d2a86030/docs/content/usage/packages/npm.en-us.md'
---

Publish [npm](https://www.npmjs.com/) packages for your user or organization.

## Requirements

To work with the npm package registry, you need [Node.js](https://nodejs.org/en/download/) coupled with a package manager such as [Yarn](https://classic.yarnpkg.com/en/docs/install) or [npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm/) itself.

The registry supports [scoped](https://docs.npmjs.com/misc/scope/) and unscoped packages.

The following examples use the `npm` tool with the scope `@test` and username `testuser`.

## Configuring the package registry

To register the package registry with npm, you need to configure a new package source and provide the package owner's token.

```shell
npm config set {scope}:registry https://forgejo.example.com/api/packages/{owner}/npm/
npm config set -- '//forgejo.example.com/api/packages/{owner}/npm/:_authToken' "{owner_token}"
```

**NOTE:** in the example below (`npm config set -- '//forgejo...`) the leading scheme, `https:`, is intentionally missing. It must not be included. The following is **incorrect**: `npm config set -- 'https://forgejo...` as the npm config only uses a URI fragment in the config. [Examples](https://docs.npmjs.com/cli/configuring-npm/npmrc#auth-related-configuration)

| Parameter | Description                                                           |
| --------- | --------------------------------------------------------------------- |
| `scope`   | The scope of the packages.                                            |
| `owner`   | The owner of the package.                                             |
| `token`   | The owner's [personal access token](../../api-usage/#authentication). |

For example:

```shell
npm config set @test:registry https://forgejo.example.com/api/packages/testuser/npm/
npm config set -- '//forgejo.example.com/api/packages/testuser/npm/:_authToken' "{personal_access_token}"
```

or without scope:

```shell
npm config set registry https://forgejo.example.com/api/packages/testuser/npm/
npm config set -- '//forgejo.example.com/api/packages/testuser/npm/:_authToken' "{personal_access_token}"
```

## Publish a package

When publishing a package, npm uses configs and defaults if the arguments are not specified in the command or project. The following commands demonstrate a default publish, publishing to a specific registry, and a specific scope and registry:

```shell
npm publish
npm publish --registry={SERVER_URL}/api/packages/{owner}/npm/ 
npm publish --scope=@{scope} --registry={SERVER_URL}/api/packages/{owner}/npm/
```

You cannot publish a package if a package of the same name and version already exists. First, you must delete that version of the existing package, either in UI at `SERVER_URL/OWNER/-/packages/npm/PACKAGE_NAME/PACKAGE_VERSION/settings` or `unpublish` in CLI.

## Unpublish a package

Delete a package by running the following command:

```shell
npm unpublish {package_name}[@{package_version}]
```

| Parameter         | Description          |
| ----------------- | -------------------- |
| `package_name`    | The package name.    |
| `package_version` | The package version. |

For example:

```shell
npm unpublish @test/test_package
npm unpublish @test/test_package@1.0.0
```

Note: This behavior is different than the public npm repository. Once you delete or unpublish a package, you can re-publish a package with the same name and version immediately.

## Install a package

To install a package from the package registry, execute the following command:

```shell
npm install {package_name}
```

| Parameter      | Description       |
| -------------- | ----------------- |
| `package_name` | The package name. |

For example:

```shell
npm install @test/test_package
```

## Tag a package

The registry supports [version tags](https://docs.npmjs.com/adding-dist-tags-to-packages/) which can be managed by `npm dist-tag`:

```shell
npm dist-tag add {package_name}@{version} {tag}
```

| Parameter      | Description                 |
| -------------- | --------------------------- |
| `package_name` | The package name.           |
| `version`      | The version of the package. |
| `tag`          | The tag name.               |

For example:

```shell
npm dist-tag add test_package@1.0.2 release
```

The tag name must not be a valid version. All tag names which are parsable as a version are rejected.

## Search packages

The registry supports [searching](https://docs.npmjs.com/cli/v7/commands/npm-search/) but does not support special search qualifiers like `author:forgejo`.

## Supported commands

```
npm install
npm ci
npm publish
npm unpublish
npm dist-tag
npm view
npm search
```

## Troubleshooting

Run these commands before the command that fails:

```shell
npm config set loglevel verbose   #The default log level is notice
npm config ls -l                  #Lists the full config, including defaults.  User config is at the bottom.
```

The [npm CLI Docs](https://docs.npmjs.com/cli) may help you find missing config settings required prior to the failing command. Incorrect [Auth-related config](https://docs.npmjs.com/cli/configuring-npm/npmrc#auth-related-configuration) can silently/cryptically fail at the default log level.

## Forgejo Actions Example

```yaml
jobs:
  publish:
    name: Publish to Forgejo NPM registry
    runs-on: docker
    permissions:
      contents: read
      packages: write
    steps:
      - name: set npm config
        # See note above about using {server_uri_fragment}, i.e. '//code.forgejo.org'
        # DO NOT USE ${{secrets.FORGEJO_TOKEN}}, use the owner's token!
        run: |
          npm config set @{scope}:registry ${{github.SERVER_URL}}/api/packages/{owner}/npm/
          npm config set "{server_uri_fragment}/api/packages/{owner}/npm/:_authToken=${{secrets.OWNER_TOKEN}}"
      - name: Checkout repo
        uses: actions/checkout@v4
      - name: Install Dependencies
        run: npm install
      - name: Build
        run: npm run build
      # WARNING: The following commented step will override the default CA settings (null == only use known CAs) and prevent npm from communicating with the public npm registry
      # To undo it, add another step: 'run: npm config set cafile='
      #- name: Only if using a self-signed cert
      #  run: npm config set cafile {location of ca-cert.pem}
      - name: Publish to registry
        run: npm publish --scope=@{scope} --registry=${{github.SERVER_URL}}/api/packages/{owner}/npm/
```