Repository files navigation

semantic-release plugin to publish anpm package.

$ npm install @semantic-release/npm -D

The plugin can be configured in thesemantic-release configuration file:

{"plugins": ["@semantic-release/commit-analyzer","@semantic-release/release-notes-generator","@semantic-release/npm"]}

When publishing to theofficial registry, it is recommended to publish with authentication intended for automation:

• For improved security, and since access tokens have recently had theirmaximum lifetimes restricted,trusted publishing is recommended when publishing from asupported CI provider
• Granular access tokens are recommended when publishing from a CI provider that is not supported by npm for trusted publishing, and can be set viaenvironment variables.Because these access tokens expire, rotation will need to be accounted for in this scenario.

To leverage trusted publishing and publish with provenance from GitHub Actions, theid-token: write permission is required to be enabled on the job:

permissions:id-token:write# to enable use of OIDC for trusted publishing and npm provenance

It's also worth noting that if you are using semantic-release to its fullest with a GitHub release, GitHub comments,and other features, thenmore permissions are required to be enabled on this job:

permissions:contents:write# to be able to publish a GitHub releaseissues:write# to be able to comment on released issuespull-requests:write# to be able to comment on released pull requestsid-token:write# to enable use of OIDC for trusted publishing and npm provenance

Refer to theGitHub Actions recipe for npm package provenance for the full CI job's YAML code example.

To leverage trusted publishing and publish with provenance from GitLab Pipelines,NPM_ID_TOKEN needs to be added as an entry underid_tokens in the job definition with an audience ofnpm:registry.npmjs.org:

id_tokens:NPM_ID_TOKEN:aud:"npm:registry.npmjs.org"

See thenpm documentation for more details about configuring pipeline details

Token authentication isrequired and can be set viaenvironment variables.Granular access tokens are recommended in this scenario, since trusted publishing is not available from all CI providers.Because these access tokens expire, rotation will need to be accounted for in your process.

Token authentication isrequired and can be set viaenvironment variables.See the documentation for your registry for details on how to create a token for automation.

Note: ThepkgRoot directory must contain apackage.json. The version will be updated only in thepackage.json andnpm-shrinkwrap.json within thepkgRoot directory.

Note: If you use ashareable configuration that defines one of these options you can set it tofalse in yoursemantic-release configuration in order to use the default value.

The plugin uses thenpm CLI which will read the configuration from.npmrc. Seenpm config for the option list.

Theregistry can be configured via the npm environment variableNPM_CONFIG_REGISTRY and will take precedence over the configuration in.npmrc.

Theregistry,dist-tag, andprovenance can be configured underpublishConfig in thepackage.json:

{"publishConfig": {"registry":"https://registry.npmjs.org/","tag":"latest","provenance":true  }}

Notes:

• The presence of an.npmrc file will override any specified environment variables.
• The presence ofregistry ordist-tag underpublishConfig in thepackage.json will take precedence over the configuration in.npmrc andNPM_CONFIG_REGISTRY

ThenpmPublish andtarballDir option can be used to skip the publishing to thenpm registry and instead, release the package tarball with another plugin. For example with the@semantic-release/github plugin:

{"plugins": ["@semantic-release/commit-analyzer","@semantic-release/release-notes-generator",    ["@semantic-release/npm",      {"npmPublish":false,"tarballDir":"dist"      }    ],    ["@semantic-release/github",      {"assets":"dist/*.tgz"      }    ]  ]}

When publishing from a sub-directory with thepkgRoot option, thepackage.json andnpm-shrinkwrap.json updated with the new version can be moved to another directory with apostversion. For example with the@semantic-release/git plugin:

{"plugins": ["@semantic-release/commit-analyzer","@semantic-release/release-notes-generator",    ["@semantic-release/npm",      {"pkgRoot":"dist"      }    ],    ["@semantic-release/git",      {"assets": ["package.json","npm-shrinkwrap.json"]      }    ]  ]}

{"scripts": {"postversion":"cp -r package.json .. && cp -r npm-shrinkwrap.json .."  }}