nx-release

This library contains executors and generators

Your go-to open-source library for effortless semantic releases of NPM libraries within a monorepo. This repository provides generators and executors for a fully automated release setup that contains commit analyzation, automated versioning, changelog generation and publishing.

The library provides generators and executors:

• Generators
• Executors

Table of Contents generated with DocToc

• Getting started
  • Installation
  • Configuring the workspace
  • GitHub repository setup
    • 1. Provide access tokens
    • 2. Actions write permissions
• Generators
  • configure
  • configure-workspace
  • configure-library
  • configure-libraries
  • generate-gh-actions
  • generate-release-config
• Executors
  • npm-publish
  • update-version
  • build-update-publish
  • Contributors ✨

Getting started

Installation

npm i -D nx-release

Configuring the workspace

To configure your Nx workspace for releasing you can invoke the main generator provided by nx-release.

npx nx g nx-release:configure

This comman will prompt all the required options.

GitHub repository setup

To enable full automated releases you have to configure your GitHub repository in two steps:

1. Provide access tokens

To enable fully automated release we need access rights to publish the artifact to npm and to commit back to your repository. Therefore you have to provide the following tokens as action secrets.

To create a action secret navigate to your GitHub repoistory / Settings / Secrets and Variables / Actions / New Repository secret

Here you have to provide the following two secrets:

• GH_TOKEN: repo scope
• NPM_TOKEN: scope CI automation

Those tokens will then be picked up and provided as environment variables by the release.yml generated by nx-release.

2. Actions write permissions

Since our workflow will commit back release artifacts such as CHANGELOG, tags and update versions inside the package.json our actions need write permissions. To give GitHub actions write permissions navigate again to your repository then go to Settings / Actions / General / Workflow Permissions / Read and write permissions / Save.

Generators

The provided generators help you setup automated library releasing in an existing NX workspace. This process works for all kind of libraries since its framework agnostic. The following generators are provided:

configure

The configure workspace generator allows you to setup the workspace plus the libraries of you choice. Internally this generator calls the configure-workspace as well as the configure-libraries generator. The generator can be invoked with the following command:

npx nx g nx-release:configure

The generators provides the follwing options:

option	description	default	prompted
installDeps	Should we install semantic-release and all the required plugins	true	yes
generateReleaseConfig	Should we generate a semantic-release configuration at the root of your workspace	true	yes
generateGhActions	Should we generate GitHub actions for feature branches and releases	true	yes
publicPublishConfig	Should we add public publish config for your library	true	Yes

configure-workspace

npx nx g nx-release:configure-workspace

The configure-workspace generator allows you to setup automated releases on a workspace level only. The generator will then prompt the following options:

option	description	default	prompted
installDeps	Should we install semantic-release and all the required plugins	true	yes
generateReleaseConfig	Should we generate a semantic-release configuration at the root of your workspace	true	yes
generateGhActions	Should we generate GitHub actions for feature branches and releases	True	yes

configure-library

npx nx g nx-release:configure-library

The configure-librarygenerator sets up a library for semantic release. When setting up the library it will use some of the executors provided by nx-release.

option	description	default	prompted
publicPublishConfig	Should we add public publish config for your library	true	yes
libName	The name of the library that should be configured		only if nothing is passed initially

configure-libraries

npx nx g nx-release:configure-libraries

The configure-librariesgenerator sets up a multiple libraries for semantic release. When setting up the libraries it will use some of the executors provided by nx-release.

option	description	default	prompted
publicPublishConfig	Should we add public publish config for your library	true	yes
libName	The name of the library that should be configured		will be prompted during execution

generate-gh-actions

npx nx g nx-release:generate-gh-actions

This generator can be used to generate two workflow files for automated releasing. This generator will generate the following two files:

• ci.yml (this file configures a pipeline that is run on Pull request)
• release.yml (file that releases the library / by default it has to be triggered manually)

generate-release-config

npx nx g nx-release:generate-release-config

This generator generates a release.config.js file at the root of your project.

Executors

npm-publish

As the name indicates the npm-publish generator can be used to publish a library to NPM. To do so the executor requires a NPM_TOKEN to be present as a Node environment variable.

update-version

This executor updates the package.json version in the specified library. The executor requires the following config options.The update-version executor expects a VERSION env variable to be present.

build-update-publish

This executor combines the previous two executors and additionally performs a release.

This command expects a valid NPM token to be present as a NPM_TOKEN environment variable and the new release version to be present as a VERSION variable.

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Nivek 💻

Add your contributions

This project follows the all-contributors specification. Contributions of any kind welcome!