|
| 1 | +# Configure Custom Registries |
| 2 | + |
| 3 | +To publish JavaScript packages, Nx Release uses the `npm` CLI under the hood, which defaults to publishing to the `npm` registry (`https://registry.npmjs.org/`). If you need to publish to a different registry, you can configure the registry in the `.npmrc` file in the root of your workspace or at the project level in the project configuration. |
| 4 | + |
| 5 | +## Set the Registry in the Root .npmrc File |
| 6 | + |
| 7 | +The easiest way to configure a custom registry is to set it in the `npm` configuration via the root `.npmrc` file. This file is located in the root of your workspace, and Nx Release will use it for publishing all projects. To set the registry, add the 'registry' property to your root `.npmrc` file: |
| 8 | + |
| 9 | +```bash .npmrc |
| 10 | +registry=https://my-custom-registry.com/ |
| 11 | +``` |
| 12 | + |
| 13 | +### Authenticate to the Registry in CI |
| 14 | + |
| 15 | +To authenticate with a custom registry in CI, you can add authentication tokens to the `.npmrc` file: |
| 16 | + |
| 17 | +```bash .npmrc |
| 18 | +registry=https://my-custom-registry.com/ |
| 19 | +//my-custom-registry.com/:_authToken=<TOKEN> |
| 20 | +``` |
| 21 | + |
| 22 | +See the [npm documentation](https://docs.npmjs.com/cli/v10/configuring-npm/npmrc#auth-related-configuration) for more information. |
| 23 | + |
| 24 | +## Configure Multiple Registries |
| 25 | + |
| 26 | +The recommended way to determine which registry packages are published to is by using [npm scopes](https://docs.npmjs.com/cli/v10/using-npm/scope). All packages with a name that starts with your scope will be published to the registry specified in the `.npmrc` file for that scope. Consider the following example: |
| 27 | + |
| 28 | +```bash .npmrc |
| 29 | +@my-scope:registry=https://my-custom-registry.com/ |
| 30 | +//my-custom-registry.com/:_authToken=<TOKEN> |
| 31 | + |
| 32 | +@other-scope:registry=https://my-other-registry.com/ |
| 33 | +//my-other-registry.com/:_authToken=<OTHER_TOKEN> |
| 34 | + |
| 35 | +registry=https://my-default-registry.com/ |
| 36 | +//my-default-registry.com/:_authToken=<DEFAULT_TOKEN> |
| 37 | +``` |
| 38 | + |
| 39 | +With the above `.npmrc`, the following packages would be published to the specified registries: |
| 40 | + |
| 41 | +- `@my-scope/pkg-1` -> `https://my-custom-registry.com/` |
| 42 | +- `@other-scope/pkg-2` -> `https://my-other-registry.com/` |
| 43 | +- `pkg-3` -> `https://my-default-registry.com/` |
| 44 | + |
| 45 | +## Specify an Alternate Registry for a Single Package |
| 46 | + |
| 47 | +In some cases, you may want to configure the registry on a per-package basis instead of by scope. This can be done by setting options in the project's configuration. |
| 48 | + |
| 49 | +{% callout type="info" title="Authentication" %} |
| 50 | +All registries set for specific packages must still have authentication tokens set in the root `.npmrc` file for publishing in CI. See [Authenticate to the Registry in CI](#authenticate-to-the-registry-in-ci) for an example. |
| 51 | +{% /callout %} |
| 52 | + |
| 53 | +### Set the Registry in the Project Configuration |
| 54 | + |
| 55 | +The project configuration for Nx Release is in two parts - one for the version step and one for the publish step. |
| 56 | + |
| 57 | +#### Update the Version Step |
| 58 | + |
| 59 | +The version step of Nx Release is responsible for determining the new version of the package. If you have set the `version.generatorOptions.currentVersionResolver` to 'registry', then Nx Release will check the remote registry for the current version of the package. |
| 60 | + |
| 61 | +**Note:** If you do not use the 'registry' current version resolver, then this step is not needed. |
| 62 | + |
| 63 | +To set custom registry options for the current version lookup, add the registry and/or tag to the `currentVersionResolverMetadata` in the project configuration: |
| 64 | + |
| 65 | +```json project.json |
| 66 | +{ |
| 67 | + "name": "pkg-5", |
| 68 | + "sourceRoot": "...", |
| 69 | + "targets": { |
| 70 | + ... |
| 71 | + }, |
| 72 | + "release": { |
| 73 | + "version": { |
| 74 | + "generatorOptions": { |
| 75 | + "currentVersionResolverMetadata": { |
| 76 | + "registry": "https://my-unique-registry.com/", |
| 77 | + "tag": "next" |
| 78 | + } |
| 79 | + } |
| 80 | + } |
| 81 | + } |
| 82 | +} |
| 83 | +``` |
| 84 | + |
| 85 | +#### Update the Publish Step |
| 86 | + |
| 87 | +The publish step of Nx Release is responsible for publishing the package to the registry. To set custom registry options for publishing, you can add the `registry` and/or `tag` options for the `nx-release-publish` target in the project configuration: |
| 88 | + |
| 89 | +```json project.json |
| 90 | +{ |
| 91 | + "name": "pkg-5", |
| 92 | + "sourceRoot": "...", |
| 93 | + "targets": { |
| 94 | + ..., |
| 95 | + "nx-release-publish": { |
| 96 | + "options": { |
| 97 | + "registry": "https://my-unique-registry.com/", |
| 98 | + "tag": "next" |
| 99 | + } |
| 100 | + } |
| 101 | + } |
| 102 | +} |
| 103 | +``` |
| 104 | + |
| 105 | +### Set the Registry in the Package Manifest |
| 106 | + |
| 107 | +{% callout type="caution" title="Caution" %} |
| 108 | +It is not recommended to set the registry for a package in the 'publishConfig' property of its 'package.json' file. 'npm publish' will always prefer the registry from the 'publishConfig' over the '--registry' argument. Because of this, the '--registry' CLI and programmatic API options of Nx Release will no longer be able to override the registry for purposes such as publishing locally for end to end testing. |
| 109 | +{% /callout %} |
0 commit comments