Using semantic-release in Nx monorepo

In Nx monorepos, semantic-release automates versioning and release processes. By following commit message patterns, it manages version increments, generates release notes, and fits seamlessly into CI/CD pipelines for efficient development.

Fully automated version management and package publishing

The semantic release is an automated versioning and release management approach that follows semantic versioning principles to increment software versions based on the nature of changes (major, minor, patch) by analyzing commit messages, ensuring consistent and predictable versioning, and often integrating with CI/CD pipelines to streamline the release process and reduce manual efforts

How does it work?

Semantic release works by automating the process of determining when and how to increment a software version and when to make a new release. Here’s a simplified overview of how it works:

• Commit Messages: Developers follow conventional commit messages to indicate the nature of their changes. For example, using specific keywords like “feat” for new features, “fix” for bug fixes, and “break” for breaking changes.

• Semantic Versioning: The semantic release tool analyzes these commit messages and identifies the type of change. In our example, “feat” represents a minor change, “fix” is a patch change, and “break” signifies a major change.

• Release Notes: The tool extracts information from commit messages to generate release notes.
• Changelog Generation: The semantic release tool parses these commit messages to generate a changelog that summarizes the changes in a user-friendly format. It groups the changes by the type of commit (e.g., new features, bug fixes, breaking changes).
• Publishing: With the version and release notes ready, the tool can automatically publish the new release to a package repository or distribution channel.
• CI/CD Integration: This entire process can be integrated into your CI/CD pipeline. So, whenever developers push new commits or merge in the main branch, the semantic release tool can automatically determine the version, generate release notes, and publish the release without manual intervention.

How to install it?

1. Nx plugin for versioning by using jscutlery/semver, the source is here https://github.com/jscutlery/semver#jscutlerysemver

npm install -D @jscutlery/semver

nx g @jscutlery/semver:install

2. The target version for each project in the project.json file should be as follows:

"version": {
  "executor": "@jscutlery/semver:version",
  "options": {
    "baseBranch": "HEAD:main",
    "preset": "conventional",
    "tagPrefix": "APP_NAME_",
    "push": true,
    "trackDeps": true,
    "commitMessageFormat": "chore({projectName}): release version {version} [skip ci]"
  }
}

3. The .gitlab-ci.yml file should be as follows:

stages:
  - release

release:
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
  stage: release
  image: node:16.13.2
  before_script:
    - git config --global user.name "GitLab Bot"
    - git config --global user.email "gituser@example.com"
    - git remote set-url origin https://semantic:${GITLAB_TOKEN}@gitlab.example.com/software/semantic-release-nx.git
  script:
    - npm ci
    - npx nx affected --target=version --base=last-release --parallel=1
    - git tag -f last-release
    - git push origin last-release --force -o ci.skip

4. Optional: If you want to preview the app version within the app, you can create a package.json file in each project directory where you want to have it.

{
  "version": "0.7.0"
}

then import the version from package.json.

import {version} from '../../package.json'

and then add the following config in the tsconfig.base.json

"resolveJsonModule": true,

DEV hints:

Please use conventional commit messages.

Don’t run the nx version script locally.

Don’t add manual tags locally.

Don’t change the CHANGELOG locally.

Conclusion:

Semantic-release simplifies versioning in Nx monorepos. It uses commit messages for version control, produces informative release notes, and integrates smoothly with CI/CD workflows. Adopt semantic-release for streamlined version control and effortless package releases in your development cycle.