Skip to content

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

License

Notifications You must be signed in to change notification settings

hongaar/semantic-release-yarn

Repository files navigation

semantic-release-yarn npm

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

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.

About

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

Topics

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages