semantic-release-yarn

A semantic-release plugin to publish npm packages with Yarn. Comes with built-in support for monorepos.

 {
   "branches": ["main"],
   "plugins": [
     "@semantic-release/commit-analyzer",
     "@semantic-release/release-notes-generator",
-    "@semantic-release/npm",
+    "semantic-release-yarn",
     "@semantic-release/github",
     "@semantic-release/git"
   ]
 }

Table of contents

• Install
• Usage
• NPM registry authentication
• Monorepo support
• Configuration
  • Environment variables
  • .yarnrc.yml file
  • package.json file
  • Plugin options
• Examples
  • Only create package tarball
• Plugin steps
• Development
  • Roadmap
• Credits

Install

yarn add --dev semantic-release-yarn

Note: this plugin only works with Yarn 2 and higher.

Usage

Use this plugin instead of the default @semantic-release/npm. The plugin must be added in the semantic-release configuration, for example:

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

NPM registry authentication

Providing a NPM access token in your configuration is required and can be set either via environment variables or the .yarnrc.yml file.

Make sure your access token has write access to the package you want to publish:

• When using a classic/legacy token, it must be either:
  • A "Publish" token if you're not using 2FA or if 2FA is disabled for write operations (The "Require two-factor authentication for write actions" is unchecked in your 2FA settings)
  • An "Automation" token if 2FA is enabled for write operations (The "Require two-factor authentication for write actions" is checked in your 2FA settings)
• When using a granular access token make sure it has "Read and write" permissions on the package you want to publish.

Note: only the npmAuthToken is supported. The legacy npmAuthIdent (username:password) authentication is strongly discouraged and not supported by this plugin.

Monorepo support

Currently, simple monorepo versioning and publishing is supported. All workspaces versions will be aligned (a.k.a. fixed/locked mode) and when a new release is due, all workspaces will be published to the NPM registry.

Monorepos are detected by the presence of a workspaces option in the root package.json file, for example:

{
  "workspaces": ["packages/*"]
}

You can set the mainWorkspace plugin option to use in notifications of new releases (e.g. in issue and pull request comments made by the @semantic-release/github plugin.

See our roadmap for further implementation status.

Configuration

Environment variables

Variable	Description
YARN_NPM_AUTH_TOKEN	NPM access token. Translates to the npmAuthToken .yarnrc.yml option.
YARN_NPM_PUBLISH_REGISTRY	NPM registry to use. Translates to the npmPublishRegistry .yarnrc.yml option.

Most other Yarn options could be specified as environment variables as well. Just prefix the names and write them in snake case. Refer to the Yarnrc files documentation to see all options.

Note: the configuration set by environment variables will take precedence over configuration set in the .yarnrc.yml file.

.yarnrc.yml file

Options can also be set in a .yarnrc.yml file. See Yarnrc files for the complete list of option.

package.json file

The registry can be configured in the package.json and will take precedence over the configuration in environment variables and the .yarnrc.yml file:

{
  "publishConfig": {
    "registry": "https://registry.npmjs.org/"
  }
}

Note: the @semantic-release/npm plugin supports setting the publishConfig.tag option. However, Yarn 2 doesn't seem to > support this.

Plugin options

These options can be added to the semantic-release configuration, for example:

{
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    [
      "semantic-release-yarn",
      {
        "npmPublish": false
      }
    ],
    "@semantic-release/github"
  ]
}

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 and no monorepo is detected, true otherwise.
pkgRoot	Directory path to publish.	.
tarballDir	Directory path in which to write the package tarball. If false the tarball is not kept on the file system.
mainWorkspace	Name of monorepo workspace to be used in release info

Note: the pkgRoot directory must contain a package.json. The version will be updated only in the package.json within the pkgRoot directory.

Examples

Only create package tarball

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",
    [
      "semantic-release-yarn",
      {
        "npmPublish": false,
        "tarballDir": "dist"
      }
    ],
    [
      "@semantic-release/github",
      {
        "assets": "dist/*.tgz"
      }
    ]
  ]
}

Plugin steps

Step	Description
verifyConditions	Verify Yarn 2 or higher is installed, verify the presence of a NPM auth token (either in an environment variable or an .yarnrc.yml file) and verify the authentication method is valid.
prepare	Update the package.json version and create the package tarball.
addChannel	Add a tag for the release.
publish	Publish to the npm registry.

Development

After cloning this repository, optionally install husky so you never commit incorrectly formatted code:

yarn husky install

Roadmap

• Monorepo support
  • Support for fixed versions
  • Support for private/non-private root package
  • Support for channels
  • Support for release information for each workspace
  • Support for independant versions (probably impossible without custom analyze-commits plugin)
• Get rid of CJS build once upstream PR 2607 lands
• Since we're using the latest AggregateError package, semantic-release is not picking up our error stack and we get a generic error message instead of a well formatted one. Hope this can be fixed once upstream PR #2631 lands

Credits

©️ Copyright 2022 Joram van den Boezem
♻️ Licensed under the MIT license
⚡ Powered by Node.js and TypeScript (and a lot of amazing open source packages)
🚀 This plugin is forked from the core @semantic-release/npm plugin.