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 analysis, automated versioning, changelog generation, and publishing.
The library provides generators and executors:
- Generators
- Executors
Table of Contents generated with DocToc
npm i -D nx-release
To configure your Nx workspace for releasing, you can invoke the main generator provided by nx-release.
npx nx g nx-release:configure
This command will prompt all the required options.
To enable full automated releases, you have to configure your GitHub repository in two steps:
To enable a fully automated release, we need access rights to publish the artifact to npm and commit back to your repository. Therefore you have to provide the following tokens as action secrets.
To create an action secret navigate to your GitHub repository / 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.
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.
The provided generators help you set up an automated library-releasing process in an existing NX workspace. This process works for all kinds of libraries since it's framework-agnostic. The following generators are provided:
The configure workspace generator allows you to set up the workspace plus the libraries of your 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 provide 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 |
| publicPublishConfig | Should we add public publish config for your library | true | Yes |
npx nx g nx-release:configure-workspace
The configure-workspace generator allows you to set up 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 |
npx nx g nx-release:configure-library
The configure-library generator 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 |
npx nx g nx-release:configure-libraries
The configure-libraries generator sets up 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 |
npx nx g nx-release:generate-gh-actions
This generator can be used to generate two workflow files for automated releases. 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)
npx nx g nx-release:generate-release-config
This generator generates a release.config.js file at the root of your project.
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.
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.
This executor combines the previous two executors and additionally performs a release.
This command expects a valid NPM token to be present as an NPM_TOKEN environment variable and the new release version to be present as a VERSION variable.
Thanks goes to these wonderful people (emoji key):
 Ajit Panigrahi 📖 |
 Can Serkan UREN 💻 🤔 |
 Nivek 💻 |
||||||
Add your contributions
|
||||||
This project follows the all-contributors specification. Contributions of any kind are welcome!