@jscutlery/semver
Nx plugin for versioning using SemVer and CHANGELOG generation powered by Conventional Commits.
Setup
Install
Using Nx:
npm install -D @jscutlery/semver
nx g @jscutlery/semver:install
Using Angular CLI:
ng add @jscutlery/semver
This package allows you to manage your monorepo using one of two modes: Synced or Independent.
Independent mode (default)
Allow multiple projects to be versioned independently. This way you release only what you want and consumers don't get updates they don't need. This allows small, rapid and incremental adoption of your packages.
Synced mode
Allow multiple projects to be versioned in a synced/locked mode. Use this if you want to automatically tie all package versions together. This mode is useful when you are working with only one product. One issue with this approach is that a major change in any project will result in all projects having a new major version.
Usage
Release
Independent mode
Release project independently by running:
nx run my-project:version [...options]
You can leverage the built-in affected command to only version changed packages:
nx affected --target version [...options]
Synced mode
Release multiple projects at once:
nx run workspace:version [...options]
When run, this executor does the following:
- Retrieve the current version of affected projects.
- Bump versions based on your commits.
- Generates CHANGELOGs based on your commits (uses conventional-changelog-angular under the hood).
- Creates a new commit including your
package.json
files and updated CHANGELOGs. - Creates new tags with the new versions number.
- Push the releases (if enabled).
Available options:
name | type | default | description |
---|---|---|---|
--dryRun |
bool |
false |
run with dry mode |
--noVerify |
bool |
false |
skip git hooks |
--push |
bool |
false |
push the release against git origin |
--syncVersions |
bool |
false |
lock/sync versions between projects |
--skipRootChangelog |
bool |
false |
skip generating root changelog (sync mode only) |
--skipProjectChangelog |
bool |
false |
skip generating project changelog (sync mode only) |
--changelogHeader |
string |
null |
custom Markdown header for changelogs |
--origin |
string |
'origin' |
push against git remote repository |
--baseBranch |
string |
'main' |
push against git base branch |
--releaseAs |
string |
null |
specify the level of change |
--preid |
string |
null |
prerelease identifier |
--versionTagPrefix |
string |
null |
specify the tag prefix |
--postTargets |
string[] |
[] |
specify a list of target to execute post-release |
Configuration using the file
Note that you can define the options you want to customize using the workspace.json
file, eg:
{
"executor": "@jscutlery/semver:version",
"options": {
"baseBranch": "master",
"versionTagPrefix": "${target}@"
}
}
Specify the level of change
The --releaseAs
option allows you to release a project with a version that is incremented by a specified level.
Level can be one of major
, minor
, patch
, premajor
, preminor
, prepatch
, or prerelease
, for instance:
nx run workspace:version --releaseAs=major
nx run workspace:version --releaseAs=minor
nx run workspace:version --releaseAs=patch
nx run workspace:version --releaseAs=prerelease --preid=alpha
nx run workspace:version --releaseAs=prerelease --preid=beta
Tag prefix customization
The --versionTagPrefix
option allows you to customize the tag prefix.
With the sync mode the tag prefix is set to "v"
by default, which is resolved to v0.0.1
for example. Note that only one tag is created for the whole workspace.
With independent mode the tag prefix uses the context target value, the default value is "${target}-"
which is resolved to my-project-0.0.1
for example. Note that each project in the workspace is versioned with its own tag.
Post-targets
The --postTargets
option allows you to run targets post-release. This is particularly handful for publishing packages on a registry when a new version was created. Here is a configuration example for my-project library:
{
"targets": {
"version": {
"executor": "@jscutlery/semver:version",
"options": {
"postTargets": ["my-project:github"]
}
},
"github": {
"executor": "@jscutlery/semver:github",
"options": {
"tag": "${tag}",
"files": ["./libs/my-project/CHANGELOG.md"]
}
}
}
}
The postTargets
option will call @jscutlery/semver:github
post-release and resolve options using the interpolation ${variable}
notation.
Resolved options:
project
version
tag
tagPrefix
noVerify
dryRun
remote
baseBranch
Built-in post-targets:
@jscutlery/semver:github
GiHub Release Support
CI/CD usage
GitHub Actions
Here is an example running semver in a GitHub workflow:
name: default
on:
push:
branches:
- 'master'
jobs:
release:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
with:
fetch-depth: 0
- name: git config
run: |
git config user.name "${GITHUB_ACTOR}"
git config user.email "${GITHUB_ACTOR}@users.noreply.github.com"
- run: yarn install --frozen-lockfile
- run: yarn nx version my-project --push --baseBranch master
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
You can found the complete example here.
Changelog
For new features or breaking changes see the changelog.
Contributors
This project follows the all-contributors specification.
License
This project is MIT licensed.