Release Workspaces 🚀

Automated versioning and publishing of npm workspace projects

Table of Contents:

• About
• Assumptions
• Usage
  • Config File
    • metadata
    • npm
    • git
    • hooks
  • CLI Options
    • Release Flags
    • Config Flags
• Cheatsheet
• Clarifications & Gotchas
• Roadmap

About

release-workspaces brings the power of Release It! to monorepos. All built with npm workspaces in mind. Using this utility, you can do the following:

• Version packages
• Publish packages
• Commit, tag, and push to remote
• And More*!

*See roadmap

Scope & Goals

One of the key benefits of npm workspaces is running commands across packages, and managing inter-package dependencies. However, like non-workspace projects, versioning and publishing is more or less a very manual process.

It's therefore not in the perview of this package to interact with behavior beyond versioning and publishing.

Assumptions

This tool assumes a few things about your workflow:

• You're logged into NPM from your terminal environment
• You're using npm workspaces (npm 7.x)
• All your packages will use the same version for each release

Usage

release-workspaces is used primarily as a command line integration tool combined with an optional configuration file.

The basic requirement is to have a version field defined in your root package.json (you can alternatively add metadata.version to your config file). This will be the version of your packages, and is automatically updated for you after a release succeeds.

Using the tool can be as simple as this:

$ release-workspaces --increment major
# or
$ release-workspaces -i major

With only a version field in your root package.json, mind you!

Here's a more complex example of incrementing packages from prerelease, to release candidate, to minor version.

$ release-workspaces -i preminor --preid alpha # 0.1.0 -> 0.2.0-alpha.0
$ release-workspaces -i prerelease # 0.2.0-alpha.1
$ release-workspaces -i prerelease --preid rc --npm-tag next # 0.2.0-rc.0 @ next
$ release-workspaces -i minor # 0.2.0

Config File

While the tool runs with sensible defaults, you can create a configuration of your own to customize execution.

Define the config in one of two ways:

• .release-workspaces.json file in monorepo root
• "release-workspaces" field of package.json

metadata

Basic data about your project.

Defaults:

{
  "metadata": {
    "version": ""
  }
}

npm

Configures how to run npm operations (increment version & publish).

Defaults:

{
  "npm": {
    "increment": true,
    "publish": true
  }
}

NOTE: Setting both increment and publish to false is a valid configuration if you only wish to tag the latest commit.

git

Configures how to run git operations (commit, tag, push). Use ${version} in string values to insert the new version when processed.

Defaults:

{
  "git": {
    "requireCleanDir": true,
    "requireSync": true,
    "skipChecks": false,
    "commitMessage": "Release ${version}",
    "tagMessage": "Release ${version}",
    "commit": true,
    "tag": true,
    "push": true
  }
}

hooks

Configures the tool to run scripts during the execution lifecycle. If you need to run an npm lifecycle script such as preversion or prepublishOnly, define them in the individual package's package.json to have them trigger automatically at the corresponding step.

Available hooks:

• preincrement, postincrement: Runs before/after packages are versioned
• prepublish, postpublish: Runs before/after packages are published
• precommit, postcommit: Runs before/after publish artifacts are committed
• pretag, posttag: Runs before/after a release tag is generated
• prepush, postpush: Runs before/after the commit is pushed to the remote (does not run if both config.git.commit and config.git.tag are false)

CLI Options

Arguments passed through the CLI will be passed verbatim to and validated by semver under the hood.

Release Flags

Name	Type	Description
--increment, -i	string	The release increment. E.g. minor, prepatch, prerelease, etc.
--increment-to, -s	string	A specific version to publish. E.g., 3.0.0, 3.0.0-rc.2, etc.
--preid, -p	string	Sets the prerelease id. E.g. alpha, rc, etc.
--npm-tag, -n	string	If given, sets the npm publish tag. Otherwise uses the preid. E.g. next.
--dry-run, -d	boolean	Prints normal output but doesn't execute.
--verbose, -b	boolean	Prints all commands and mutating script calls (can be used with --dry-run/-d).

Note that if --npm-tag isn't given, then the tool will fall back to the value given for --preid, else it will use latest.

Similarly, if you run a git-only release (no version, no publish), the tool will fall back to the current version of your packages.

Config Flags

Using config options via CLI will override your config. Useful for one-off releases and otherwise augmenting a base configuration for release types (alpha release, release candidate, no-increment publish, etc).

You can use any of the existing config options as CLI flags by using the formula --<key>.<property> [value]. E.g., change the default or user-configured commit message: --git.commitMessage "chore: release \${version}" or disable all git checks with --git.skipChecks.

Similarly, you can negate any boolean option by prepending --no- to it. E.g., --no-git.requireCleanDir.

Cheatsheet

Here are a few handy examples of how to achieve certain release results with CLI flags. Replace minor with your intended release increment.

Description	Example
Do everything	$ release-workspaces -i minor
Prerelease	$ release-workspaces -i preminor -p alpha
Increment prerelease	$ release-workspaces -i prerelease
Update prerelease id w/ npm tag	$ release-workspaces -i prerelease -p rc -n next
Increment to a specific version	$ release-workspaces -s 3.0.0
Skip npm version	$ release-workspaces --no-npm.increment
Skip npm publish	$ release-workspaces -i minor --no-npm.publish
Skip all npm operations	$ release-workspaces --no-npm.increment --no-npm.publish
Skip clean directory check	$ release-workspaces -i minor --no-git.requireCleanDir
Skip git sync check	$ release-workspaces -i minor --no-git.requireSync
Skip all git checks	$ release-workspaces -i minor --git.skipChecks
Skip git operation	$ release-workspaces -i minor --no-git.[commit/tag/push]
Set custom messaging	$ release-workspaces -i minor --git.[commitMessage/tagMessage] "Custom msg for \${version}"

Clarifications & Gotchas

There are some contradictory or otherwise unclear config combinations to note.

• config.git.push is ignored if both config.git.commit and config.git.tag are false.
• --increment-to/-s is ignored if config.npm.increment is false.
• --increment-to/-s will override --increment/-i.
• --increment-to/-s, if valid version, will automatically be parsed for an npm tag during the publish step. You can optionally provide --npm-tag to override this.

Roadmap

• Rollback changes if failures occur mid-release
• Automate GitHub/GitLab releases
• Release in CI