@anolilab/semantic-release-pnpm

v5.0.0

Published

a month ago

Semantic-release plugin to publish a npm package with pnpm.

Install

npm install @anolilab/semantic-release-pnpm

yarn add @anolilab/semantic-release-pnpm

pnpm add @anolilab/semantic-release-pnpm

Usage

The plugin can be configured in the semantic-release configuration file:

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

Steps that are used

| Step | Description | | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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. | | prepare | Update the package.json version and create the npm package tarball. | | addChannel | Add a release to a dist-tag. | | publish | Publish the npm package to the registry. |

Configuration

npm registry authentication

Official Registry

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

For improved security, and since access tokens have recently had their maximum lifetimes restricted, trusted publishing is recommended when publishing from a supported 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 via environment variables. Because these access tokens expire, rotation will need to be accounted for in this scenario.

[!NOTE] When using trusted publishing, provenance attestations are automatically generated for your packages without requiring provenance to be explicitly enabled.

[!IMPORTANT] 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:
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.
Use the setup-npm-trusted-publish tool to automatically create and publish a placeholder package for OIDC setup purposes.
After the initial package exists, you can configure OIDC trusted publishing at https://www.npmjs.com/package/<package-name>/access and then use semantic-release for all future releases.

[!TIP] 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.

Trusted publishing from GitHub Actions

To leverage trusted publishing and publish with provenance from GitHub Actions, the id-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, then more permissions are required to be enabled on this job:

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

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

Trusted publishing for GitLab Pipelines

To 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:

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

See the npm documentation for more details about configuring pipeline details

Unsupported CI providers

Token authentication is required and can be set via environment 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.

Alternative Registries

Token authentication is required and can be set via environment variables. See the documentation for your registry for details on how to create a token for automation.

npm provenance

When using trusted publishing to the official npm registry, provenance attestations are automatically generated for your packages without requiring provenance to be explicitly enabled.

For alternative registries or when using token-based authentication, provenance can be configured through the other configuration options exposed by npm. Provenance applies specifically to publishing, so configure it under publishConfig within the package.json:

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

Environment variables

| Variable | Description | | ----------- | ----------------------------------------------------------------------------------------------------------------------------- | | NPM_TOKEN | Npm token created via npm token create |

Options

| Options | Description | Default | | --------------- | ------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------- | | 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 property is true, true otherwise. | | pkgRoot | Directory path to publish. | . | | tarballDir | Directory path in which to write the package tarball. If false the tarball is not be kept on the file system. | false | | publishBranch | The primary branch of the repository which is used for publishing the latest changes. | master and main |

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.

Note: If you use a shareable configuration that defines one of these options you can set it to false in your semantic-release configuration in order to use the default value.

npm configuration

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

The registry can be configured via the npm environment variable NPM_CONFIG_REGISTRY and will take precedence over the configuration in .npmrc.

The registry and dist-tag can be configured under publishConfig in the package.json:

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

Notes:

The presence of an .npmrc file will override any specified environment variables.
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

Examples

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 plugin:

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

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 postversion. For example with the @semantic-release/git plugin:

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

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

@semantic-release/npm - 🚢 semantic-release plugin to publish a npm package
semantic-release-yarn - 🧶 A semantic-release plugin to publish npm packages with Yarn. Comes with built-in support for monorepos.

Supported Node.js Versions

Libraries in this ecosystem make the best effort to track Node.js’ release schedule. Here’s a post on why we think this is important.

Contributing

If you would like to help take a look at the list of issues and check our Contributing guidelines.

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.

Credits

Made with ❤️ at Anolilab

This is an open source project and will always remain free to use. If you think it's cool, please star it 🌟. Anolilab is a Development and AI Studio. Contact us at [email protected] if you need any help with these technologies or just want to say hi!

License

The anolilab semantic-release-pnpm is open-sourced software licensed under the MIT