\n \n Daniel Bannert's open source work is supported by the community on GitHub Sponsors\n \n
\n
\n\n---\n\n## Install\n\n```sh\nnpm install @anolilab/semantic-release-pnpm\n```\n\n```sh\nyarn add @anolilab/semantic-release-pnpm\n```\n\n```sh\npnpm add @anolilab/semantic-release-pnpm\n```\n\n## Usage\n\nThe plugin can be configured in the [**semantic-release** configuration file](https://github.com/semantic-release/semantic-release/blob/master/docs/usage/configuration.md#configuration):\n\n```json\n{\n \"plugins\": [\"@semantic-release/commit-analyzer\", \"@semantic-release/release-notes-generator\", \"@anolilab/semantic-release-pnpm\"]\n}\n```\n\n## Steps that are used\n\n| Step | Description |\n| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `verifyConditions` | Verify the presence of the `NPM_TOKEN` environment variable, or an `.npmrc` file, and verify the authentication method is valid. Results are cached per registry/auth combination to prevent throttling in monorepos. |\n| `prepare` | Update the `package.json` version and [create](https://docs.npmjs.com/cli/pack) the npm package tarball. |\n| `addChannel` | [Add a release to a dist-tag](https://docs.npmjs.com/cli/dist-tag). |\n| `publish` | [Publish the npm package](https://docs.npmjs.com/cli/publish) to the registry. |\n\n## Configuration\n\n### npm registry authentication\n\n#### Official Registry\n\nWhen publishing to the [official registry](https://registry.npmjs.org/), it is recommended to publish with authentication intended for automation:\n\n- For improved security, and since access tokens have recently had their [maximum lifetimes restricted](https://github.blog/changelog/2025-09-29-strengthening-npm-security-important-changes-to-authentication-and-token-management/),\n [trusted publishing](https://docs.npmjs.com/trusted-publishers) is recommended when publishing from a [supported CI provider](https://docs.npmjs.com/trusted-publishers#supported-cicd-providers)\n- [Granular access tokens](https://docs.npmjs.com/creating-and-viewing-access-tokens#creating-granular-access-tokens-on-the-website) are recommended when publishing from a CI provider that is not supported by npm for trusted publishing, and can be set via [environment variables](#environment-variables).\n Because these access tokens expire, rotation will need to be accounted for in this scenario.\n\n> [!NOTE]\n> When using trusted publishing, provenance attestations are automatically generated for your packages without requiring provenance to be explicitly enabled.\n\n> [!IMPORTANT]\n> **First-time releases with OIDC**: npm requires a package to exist before you can configure OIDC trusted publishing. If you're releasing a package for the first time with OIDC, you have two options:\n>\n> 1. Publish a dummy version manually first (e.g., `pnpm publish --tag dummy`), then configure OIDC trusted publishing, and then use semantic-release for subsequent releases.\n> 2. Use the [`setup-npm-trusted-publish`](https://github.com/azu/setup-npm-trusted-publish) tool to automatically create and publish a placeholder package for OIDC setup purposes.\n>\n> After the initial package exists, you can configure OIDC trusted publishing at `https://www.npmjs.com/package//access` and then use semantic-release for all future releases.\n\n> [!TIP]\n> **Monorepo Performance**: The plugin automatically caches authentication verification results per registry/auth token combination. This prevents throttling when verifying multiple packages in monorepos, as `pnpm whoami` is only called once per unique registry/authentication context rather than once per package.\n\n##### Trusted publishing from GitHub Actions\n\nTo leverage trusted publishing and publish with provenance from GitHub Actions, the `id-token: write` permission is required to be enabled on the job:\n\n```yaml\npermissions:\n id-token: write # to enable use of OIDC for trusted publishing and npm provenance\n```\n\nIt's also worth noting that if you are using semantic-release to its fullest with a GitHub release, GitHub comments,\nand other features, then [more permissions are required](https://github.com/semantic-release/github#github-authentication) to be enabled on this job:\n\n```yaml\npermissions:\n contents: write # to be able to publish a GitHub release\n issues: write # to be able to comment on released issues\n pull-requests: write # to be able to comment on released pull requests\n id-token: write # to enable use of OIDC for trusted publishing and npm provenance\n```\n\nRefer to the [GitHub Actions recipe for npm package provenance](https://semantic-release.gitbook.io/semantic-release/recipes/ci-configurations/github-actions#.github-workflows-release.yml-configuration-for-node-projects) for the full CI job's YAML code example.\n\n##### Trusted publishing for GitLab Pipelines\n\nTo leverage trusted publishing and publish with provenance from GitLab Pipelines, `NPM_ID_TOKEN` needs to be added as an entry under `id_tokens` in the job definition with an audience of `npm:registry.npmjs.org`:\n\n```yaml\nid_tokens:\n NPM_ID_TOKEN:\n aud: \"npm:registry.npmjs.org\"\n```\n\nSee the [npm documentation for more details about configuring pipeline details](https://docs.npmjs.com/trusted-publishers#gitlab-cicd-configuration)\n\n##### Trusted publishing for CircleCI\n\nTo use trusted publishing in [CircleCI](https://docs.npmjs.com/trusted-publishers#circleci-configuration) you need to set the environment variable `NPM_ID_TOKEN` to an NPM Identity Token:\n\n```yaml\njobs:\n semantic-release:\n steps:\n # ...\n - run:\n name: Semantic Release with Trusted Publishing via OIDC\n command: |\n # Fetch the OIDC token with the correct audience for npm\n export NPM_ID_TOKEN=$(circleci run oidc get --claims '{\"aud\": \"npm:registry.npmjs.org\"}')\n # Run semantic release\n npx semantic-release\n```\n\n##### Generic Trusted Publishing\n\nThe generic mechanism for trusted publishing is to set the `NPM_ID_TOKEN` environment variable to an OIDC identity token. This approach works with any CI platform that has implemented trusted publishing support with npm but does not have specific built-in support in this plugin. If token exchange fails, it will fall back to using token authentication.\n\n##### Unsupported CI providers\n\nToken authentication is **required** and can be set via [environment variables](#environment-variables).\n[Granular access tokens](https://docs.npmjs.com/creating-and-viewing-access-tokens#creating-granular-access-tokens-on-the-website) are recommended in this scenario, since trusted publishing is not available from all CI providers.\nBecause these access tokens expire, rotation will need to be accounted for in your process.\n\n#### Alternative Registries\n\nToken authentication is **required** and can be set via [environment variables](#environment-variables).\nSee the documentation for your registry for details on how to create a token for automation.\n\n### npm provenance\n\nWhen using trusted publishing to the official npm registry, provenance attestations are automatically generated for your packages without requiring provenance to be explicitly enabled.\n\nFor alternative registries or when using token-based authentication, provenance can be configured through the [other configuration options exposed by npm](https://docs.npmjs.com/generating-provenance-statements#using-third-party-package-publishing-tools).\nProvenance applies specifically to publishing, so configure it under `publishConfig` within the `package.json`:\n\n```json\n{\n \"publishConfig\": {\n \"registry\": \"https://registry.npmjs.org/\",\n \"tag\": \"latest\",\n \"provenance\": true\n }\n}\n```\n\n### Environment variables\n\n| Variable | Description |\n| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `NPM_TOKEN` | Npm token created via [npm token create](https://docs.npmjs.com/getting-started/working_with_tokens#how-to-create-new-tokens) |\n| `NPM_ID_TOKEN` | OIDC identity token for [trusted publishing](https://docs.npmjs.com/trusted-publishers). Must be configured in your CI job (see [GitLab](#trusted-publishing-for-gitlab-pipelines), [CircleCI](#trusted-publishing-for-circleci)). Takes priority over CI-specific token retrieval when set. |\n\n### Options\n\n| Options | Description | Default |\n| --------------- | ------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------- |\n| `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. |\n| `pkgRoot` | Directory path to publish. | `.` |\n| `tarballDir` | Directory path in which to write the package tarball. If `false` the tarball is not be kept on the file system. | `false` |\n| `publishBranch` | The primary branch of the repository which is used for publishing the latest changes. | [master and main](https://pnpm.io/cli/publish#--publish-branch-branch) |\n\n**Note**: The `pkgRoot` directory must contain a `package.json`. The version will be updated only in the `package.json` and `npm-shrinkwrap.json` within the `pkgRoot` directory.\n\n**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.\n\n### npm configuration\n\nThe 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.\n\nThe [`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`.\n\nThe [`registry`](https://docs.npmjs.com/misc/registry) and [`dist-tag`](https://docs.npmjs.com/cli/dist-tag) can be configured under `publishConfig` in the `package.json`:\n\n```json\n{\n \"publishConfig\": {\n \"registry\": \"https://registry.npmjs.org/\",\n \"tag\": \"latest\"\n }\n}\n```\n\n**Notes**:\n\n- The presence of an `.npmrc` file will override any specified environment variables.\n- The presence of `registry` or `dist-tag` under `publishConfig` in the `package.json` will take precedence over the configuration in `.npmrc` and `NPM_CONFIG_REGISTRY`\n\n### Examples\n\nThe `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:\n\n```json\n{\n \"plugins\": [\n \"@semantic-release/commit-analyzer\",\n \"@semantic-release/release-notes-generator\",\n [\n \"@anolilab/semantic-release-pnpm\",\n {\n \"npmPublish\": false,\n \"tarballDir\": \"dist\"\n }\n ],\n [\n \"@semantic-release/github\",\n {\n \"assets\": \"dist/*.tgz\"\n }\n ]\n ]\n}\n```\n\nWhen 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 `postversion`. For example with the [@semantic-release/git](https://github.com/semantic-release/git) plugin:\n\n```json\n{\n \"plugins\": [\n \"@semantic-release/commit-analyzer\",\n \"@semantic-release/release-notes-generator\",\n [\n \"@anolilab/semantic-release-pnpm\",\n {\n \"pkgRoot\": \"dist\"\n }\n ],\n [\n \"@semantic-release/git\",\n {\n \"assets\": [\"package.json\", \"npm-shrinkwrap.json\"]\n }\n ]\n ]\n}\n```\n\n```json\n{\n \"scripts\": {\n \"postversion\": \"cp -r package.json .. && cp -r npm-shrinkwrap.json ..\"\n }\n}\n```\n\n## Related\n\n- [@semantic-release/npm](https://github.com/semantic-release/npm) - 🚢 semantic-release plugin to publish a npm package\n- [semantic-release-yarn](https://github.com/hongaar/semantic-release-yarn) - 🧶 A semantic-release plugin to publish npm packages with Yarn. Comes with built-in support for monorepos.\n\n## Supported Node.js Versions\n\nLibraries in this ecosystem make the best effort to track [Node.js’ release schedule](https://github.com/nodejs/release#release-schedule).\nHere’s [a post on why we think this is important](https://medium.com/the-node-js-collection/maintainers-should-consider-following-node-js-release-schedule-ab08ed4de71a).\n\n## Contributing\n\nIf you would like to help take a look at the [list of issues](https://github.com/anolilab/semantic-release/issues) and check our [Contributing](.github/CONTRIBUTING.md) guidelines.\n\n> **Note:** please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.\n\n## Credits\n\n- [Daniel Bannert](https://github.com/prisis)\n- [All Contributors](https://github.com/anolilab/semantic-release/graphs/contributors)\n\n## Made with ❤️ at Anolilab\n\nThis is an open source project and will always remain free to use. If you think it's cool, please star it 🌟. [Anolilab](https://www.anolilab.com/open-source) is a Development and AI Studio. Contact us at [hello@anolilab.com](mailto:hello@anolilab.com) if you need any help with these technologies or just want to say hi!\n\n## License\n\nThe anolilab semantic-release-pnpm is open-sourced software licensed under the [MIT][license-url]\n\n\n\n[license-badge]: https://img.shields.io/npm/l/@anolilab/semantic-release-pnpm?style=for-the-badge\n[license]: https://github.com/anolilab/multi-semantic-release/blob/main/LICENSE\n[npm-downloads-badge]: https://img.shields.io/npm/dm/@anolilab/semantic-release-pnpm?style=for-the-badge\n[npm-downloads]: https://www.npmjs.com/package/@anolilab/semantic-release-pnpm\n[prs-welcome-badge]: https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=for-the-badge\n[prs-welcome]: https://github.com/anolilab/multi-semantic-release/blob/main/.github/CONTRIBUTING.md\n[chat-badge]: https://img.shields.io/discord/902465130518949899.svg?style=for-the-badge\n[chat]: https://discord.gg/eajEZvk2PG\n[typescript-badge]: https://img.shields.io/badge/Typescript-294E80.svg?style=for-the-badge&logo=typescript\n[typescript-url]: https://www.typescriptlang.org/\n[license-url]: LICENSE.md\n","readmeFilename":""}
![\"semantic-release-pnpm\"](\"__assets__/package-og.svg\")
\n\n