shaharkazaz / semver

Nx plugin to automate semantic versioning and CHANGELOG generation.

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

@jscutlery/semver NPM package @jscutlery/semver coverage status


Nx plugin for versioning using SemVer and CHANGELOG generation powered by Conventional Commits.



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.



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:

  1. Retrieve the current version of affected projects.
  2. Bump versions based on your commits.
  3. Generates CHANGELOGs based on your commits (uses conventional-changelog-angular under the hood).
  4. Creates a new commit including your package.json files and updated CHANGELOGs.
  5. Creates new tags with the new versions number.
  6. Push the releases (if enabled).
  7. Run post-targets.

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.


The --postTargets option allows you to run targets post-release. This is particularly handful for publishing packages on a registry or scheduling any other task.

Here is a configuration example using @jscutlery/semver:github to create GitHub Release 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/"]

The postTargets option declare my-project:github target which run @jscutlery/semver:github executor. Note that options using the interpolation notation ${variable} are resolved with their corresponding value.

Resolved options:

  • project
  • version
  • tag
  • tagPrefix
  • noVerify
  • dryRun
  • remote
  • baseBranch

Built-in post-targets:

CI/CD usage

GitHub Actions

Here is an example running semver in a GitHub workflow:

name: default

      - 'master'

    runs-on: ubuntu-latest
      - uses: actions/checkout@v2
          fetch-depth: 0
      - name: git config
        run: |
          git config "${GITHUB_ACTOR}"
          git config "${GITHUB_ACTOR}"
      - run: yarn install --frozen-lockfile
      - run: yarn nx version my-project --push --baseBranch master
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

You can found the complete example here.


For new features or breaking changes see the changelog.


This project follows the all-contributors specification.

Younes Jaaidi

πŸ› πŸ’» πŸ“– πŸ’‘ πŸ€”

Edouard Bozon

πŸ› πŸ’» πŸ“– πŸ’‘ πŸ€”

Gleb Mikheev


Richard Lea



πŸ› πŸ’»




πŸ’» πŸ€”

Sylvain Arnouts



πŸ’» πŸ€”

Shahar Kazaz


MiloΕ‘ Lajtman

πŸ› πŸ’»

Charley Bodkin


Jeffrey Bosch



This project is MIT licensed.

ezoic increase your site revenue


Nx plugin to automate semantic versioning and CHANGELOG generation.

License:MIT License


Language:TypeScript 98.8%Language:JavaScript 1.1%Language:Shell 0.1%