1 | # @semantic-release/npm
|
2 |
|
3 | [**semantic-release**](https://github.com/semantic-release/semantic-release) plugin to publish a [npm](https://www.npmjs.com) package.
|
4 |
|
5 | [![Build Status](https://github.com/semantic-release/npm/workflows/Test/badge.svg)](https://github.com/semantic-release/npm/actions?query=workflow%3ATest+branch%3Amaster) [![npm latest version](https://img.shields.io/npm/v/@semantic-release/npm/latest.svg)](https://www.npmjs.com/package/@semantic-release/npm)
|
6 | [![npm next version](https://img.shields.io/npm/v/@semantic-release/npm/next.svg)](https://www.npmjs.com/package/@semantic-release/npm)
|
7 | [![npm beta version](https://img.shields.io/npm/v/@semantic-release/npm/beta.svg)](https://www.npmjs.com/package/@semantic-release/npm)
|
8 |
|
9 | | Step | Description |
|
10 | |--------------------|-------------|
|
11 | | `verifyConditions` | Verify the presence of the `NPM_TOKEN` environment variable, create or update the `.npmrc` file with the token and verify the token is valid. |
|
12 | | `prepare` | Update the `package.json` version and [create](https://docs.npmjs.com/cli/pack) the npm package tarball. |
|
13 | | `addChannel` | [Add a release to a dist-tag](https://docs.npmjs.com/cli/dist-tag). |
|
14 | | `publish` | [Publish the npm package](https://docs.npmjs.com/cli/publish) to the registry. |
|
15 |
|
16 | ## Install
|
17 |
|
18 | ```bash
|
19 | $ npm install @semantic-release/npm -D
|
20 | ```
|
21 |
|
22 | ## Usage
|
23 |
|
24 | The plugin can be configured in the [**semantic-release** configuration file](https://github.com/semantic-release/semantic-release/blob/master/docs/usage/configuration.md#configuration):
|
25 |
|
26 | ```json
|
27 | {
|
28 | "plugins": [
|
29 | "@semantic-release/commit-analyzer",
|
30 | "@semantic-release/release-notes-generator",
|
31 | "@semantic-release/npm",
|
32 | ]
|
33 | }
|
34 | ```
|
35 |
|
36 | ## Configuration
|
37 |
|
38 | ### Npm registry authentication
|
39 |
|
40 | The npm authentication configuration is **required** and can be set via [environment variables](#environment-variables).
|
41 |
|
42 | Both the [token](https://docs.npmjs.com/getting-started/working_with_tokens) and the legacy (`username`, `password` and `email`) authentication are supported. It is recommended to use the [token](https://docs.npmjs.com/getting-started/working_with_tokens) authentication. The legacy authentication is supported as the alternative npm registries [Artifactory](https://www.jfrog.com/open-source/#os-arti) and [npm-registry-couchapp](https://github.com/npm/npm-registry-couchapp) only supports that form of authentication.
|
43 |
|
44 | **Note**: Only the `auth-only` [level of npm two-factor authentication](https://docs.npmjs.com/getting-started/using-two-factor-authentication#levels-of-authentication) is supported, **semantic-release** will not work with the default `auth-and-writes` level.
|
45 |
|
46 | ### Environment variables
|
47 |
|
48 | | Variable | Description |
|
49 | | -------------- | ----------------------------------------------------------------------------------------------------------------------------- |
|
50 | | `NPM_TOKEN` | Npm token created via [npm token create](https://docs.npmjs.com/getting-started/working_with_tokens#how-to-create-new-tokens) |
|
51 | | `NPM_USERNAME` | Npm username created via [npm adduser](https://docs.npmjs.com/cli/adduser) or on [npmjs.com](https://www.npmjs.com) |
|
52 | | `NPM_PASSWORD` | Password of the npm user. |
|
53 | | `NPM_EMAIL` | Email address associated with the npm user |
|
54 |
|
55 | Use either `NPM_TOKEN` for token authentication or `NPM_USERNAME`, `NPM_PASSWORD` and `NPM_EMAIL` for legacy authentication
|
56 |
|
57 | ### Options
|
58 |
|
59 | | Options | Description | Default |
|
60 | |--------------|---------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------|
|
61 | | `npmPublish` | Whether to publish the `npm` package to the registry. If `false` the `package.json` version will still be updated. | `false` if the `package.json` [private](https://docs.npmjs.com/files/package.json#private) property is `true`, `true` otherwise. |
|
62 | | `pkgRoot` | Directory path to publish. | `.` |
|
63 | | `tarballDir` | Directory path in which to write the the package tarball. If `false` the tarball is not be kept on the file system. | `false` |
|
64 |
|
65 | **Note**: The `pkgRoot` directory must contains a `package.json`. The version will be updated only in the `package.json` and `npm-shrinkwrap.json` within the `pkgRoot` directory.
|
66 |
|
67 | **Note**: If you use a [shareable configuration](https://github.com/semantic-release/semantic-release/blob/master/docs/usage/shareable-configurations.md#shareable-configurations) that defines one of these options you can set it to `false` in your [**semantic-release** configuration](https://github.com/semantic-release/semantic-release/blob/master/docs/usage/configuration.md#configuration) in order to use the default value.
|
68 |
|
69 | ### Npm configuration
|
70 |
|
71 | The plugin uses the [`npm` CLI](https://github.com/npm/cli) which will read the configuration from [`.npmrc`](https://docs.npmjs.com/files/npmrc). See [`npm config`](https://docs.npmjs.com/misc/config) for the option list.
|
72 |
|
73 | The [`registry`](https://docs.npmjs.com/misc/registry) can be configured via the npm environment variable `NPM_CONFIG_REGISTRY` and will take precedence over the configuration in `.npmrc`.
|
74 |
|
75 | The [`registry`](https://docs.npmjs.com/misc/registry) and [`dist-tag`](https://docs.npmjs.com/cli/dist-tag) can be configured in the `package.json` and will take precedence over the configuration in `.npmrc` and `NPM_CONFIG_REGISTRY`:
|
76 | ```json
|
77 | {
|
78 | "publishConfig": {
|
79 | "registry": "https://registry.npmjs.org/",
|
80 | "tag": "latest"
|
81 | }
|
82 | }
|
83 | ```
|
84 |
|
85 | ### Examples
|
86 |
|
87 | The `npmPublish` and `tarballDir` option can be used to skip the publishing to the `npm` registry and instead, release the package tarball with another plugin. For example with the [@semantic-release/github](https://github.com/semantic-release/github) plugin:
|
88 |
|
89 | ```json
|
90 | {
|
91 | "plugins": [
|
92 | "@semantic-release/commit-analyzer",
|
93 | "@semantic-release/release-notes-generator",
|
94 | ["@semantic-release/npm", {
|
95 | "npmPublish": false,
|
96 | "tarballDir": "dist",
|
97 | }],
|
98 | ["@semantic-release/github", {
|
99 | "assets": "dist/*.tgz"
|
100 | }]
|
101 | ]
|
102 | }
|
103 | ```
|
104 |
|
105 | When publishing from a sub-directory with the `pkgRoot` option, the `package.json` and `npm-shrinkwrap.json` updated with the new version can be moved to another directory with a `postpublish` [npm script](https://docs.npmjs.com/misc/scripts). For example with the [@semantic-release/git](https://github.com/semantic-release/git) plugin:
|
106 |
|
107 | ```json
|
108 | {
|
109 | "plugins": [
|
110 | "@semantic-release/commit-analyzer",
|
111 | "@semantic-release/release-notes-generator",
|
112 | ["@semantic-release/npm", {
|
113 | "pkgRoot": "dist",
|
114 | }],
|
115 | ["@semantic-release/git", {
|
116 | "assets": ["package.json", "npm-shrinkwrap.json"]
|
117 | }]
|
118 | ]
|
119 | }
|
120 | ```
|
121 | ```json
|
122 | {
|
123 | "scripts": {
|
124 | "postpublish": "cp -r package.json .. && cp -r npm-shrinkwrap.json .."
|
125 | }
|
126 | }
|
127 | ```
|