{"id":13847204,"url":"https://github.com/TheUnderScorer/nx-semantic-release","last_synced_at":"2025-07-12T08:31:25.802Z","repository":{"id":38341078,"uuid":"435794321","full_name":"TheUnderScorer/nx-semantic-release","owner":"TheUnderScorer","description":"Package for automated releases for nx built on semantic-release","archived":false,"fork":false,"pushed_at":"2024-08-17T11:01:30.000Z","size":1343,"stargazers_count":94,"open_issues_count":3,"forks_count":22,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-07-07T10:36:46.290Z","etag":null,"topics":["monorepo","nx-plugin","semantic-release","semver"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/TheUnderScorer.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-12-07T08:08:07.000Z","updated_at":"2025-05-16T06:33:13.000Z","dependencies_parsed_at":"2024-01-15T20:49:07.543Z","dependency_job_id":"ea94eb77-4938-4e6e-96a5-2728be500c54","html_url":"https://github.com/TheUnderScorer/nx-semantic-release","commit_stats":null,"previous_names":[],"tags_count":45,"template":false,"template_full_name":null,"purl":"pkg:github/TheUnderScorer/nx-semantic-release","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheUnderScorer%2Fnx-semantic-release","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheUnderScorer%2Fnx-semantic-release/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheUnderScorer%2Fnx-semantic-release/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheUnderScorer%2Fnx-semantic-release/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TheUnderScorer","download_url":"https://codeload.github.com/TheUnderScorer/nx-semantic-release/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheUnderScorer%2Fnx-semantic-release/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264962209,"owners_count":23689761,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["monorepo","nx-plugin","semantic-release","semver"],"created_at":"2024-08-04T18:01:13.098Z","updated_at":"2025-07-12T08:31:25.113Z","avatar_url":"https://github.com/TheUnderScorer.png","language":"TypeScript","funding_links":["https://www.buymeacoffee.com/theunderscorer"],"categories":["TypeScript","others"],"sub_categories":[],"readme":"# @theunderscorer/nx-semantic-release\n\n[nx](https://nx.dev/) plugin for automated releases, powered\nby [semantic-release](https://github.com/semantic-release/semantic-release)\n\n## How it works\n\nUnder the hood, it uses project graph from nx to analyze commits for every configured project and filters out these commits that doesn't affect given project or it's dependencies.\n\n\u003ca href=\"https://www.buymeacoffee.com/theunderscorer\" target=\"_blank\"\u003e\u003cimg src=\"https://cdn.buymeacoffee.com/buttons/v2/default-violet.png\" alt=\"Buy Me A Coffee\" style=\"height: 60px !important;width: 217px !important;\" \u003e\u003c/a\u003e\n\n## Installation\n\nRun:\n\n```shell\nnpm install -D @theunderscorer/nx-semantic-release\nnx g @theunderscorer/nx-semantic-release:install\n```\n\nFor now this package supports only \u003cb\u003eIndependent\u003c/b\u003e versioning mode, synced mode is planned to be added soon.\n\n## Usage\n\nIn order to release your projects, add this executor to your configuration file (ex. `project.json`), bare minimal\nconfiguration looks like this:\n\n```json\n{\n \"semantic-release\": {\n \"executor\": \"@theunderscorer/nx-semantic-release:semantic-release\"\n }\n}\n```\n\n\u003e Hint: You can also use our generator `nx g @theunderscorer/nx-semantic-release:setup-project $PROJECT_NAME` to generate this configuration.\n\nAfter running this, the executor will do the following:\n\n* Filter commits retrieved by semantic-release in order to find only these that affects selected project or it's\n dependencies.\n* Perform semantic-release using following plugins (in this order:)\n * @semantic-release/commit-analyzer\n * @semantic-release/release-notes-generator\n * @semantic-release/changelog\n * @semantic-release/npm\n * @semantic-release/git\n * @semantic-release/github\n* The result will be a fully versioned project. If you are releasing it as npm package, the package will be built,\n version in package.json will be updated and package itself will be published.\n\n## Configuration\n\nOptions can be configured in 3 ways:\n\n1. **cli**: Passing them on the cli command\n2. **config file:** Including them in a global `nxrelease` config file in the root of your monorepo (see below)\n3. **project:** Within the options section of the executor for each project (`project.json`)\n\nMultiple configurations are fully supported, allowing for global configuration options in the config file and then project specific overrides in the `project.json`. Options merged in the following order of precedence:\n\n```\ncli flags \u003e project \u003e config file \u003e defaults\n```\n\n_Note:_ Object/Array type options are shallowly merged. For example, if gitAssets is set in both the config file and the project options, the whole of the project options version will be used and the config file option will be discarded.\n\n### Configuration file\n\nnx-semantic-release's options can be set globally via either:\n\n* a `nxrelease` key in the project's `package.json` file\n* a `.nxreleaserc` file, written in YAML or JSON, with optional extensions: `.yaml`/`.yml`/`.json`/`.js`\n* a `nxrelease.config.js` file that exports an object\n\nThe following examples are all the same.\n\n* Via `nxrelease` key in the monorepo `package.json` file:\n\n```json\n{\n \"nxrelease\": {\n \"repositoryUrl\": \"https://github.com/TheUnderScorer/nx-semantic-release\"\n }\n}\n```\n\n* Via `.nxreleaserc` YAML file:\n\n```yaml\n---\nrepositoryUrl: 'https://github.com/TheUnderScorer/nx-semantic-release'\n```\n\n* Via `nxrelease.config.js` file:\n\n```js\nmodule.exports = {\n repositoryUrl: 'https://github.com/TheUnderScorer/nx-semantic-release',\n};\n```\n\n* Via CLI arguments:\n\n```\n$ nx semantic-release app-c --repositoryUrl \"https://github.com/TheUnderScorer/nx-semantic-release\"\n```\n\n### Available Options\n\n| name | type | default | required | description |\n|----------------|--------------------|-------------------------------------------------------------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| dryRun | boolean | false | no | See what commands would be run, without committing to git or updating files |\n| ci | boolean | true | no | Set to false to skip CI checks. |\n| changelog | boolean | true | no | Whether to generate changelog. |\n| changelogFile | string | ${PROJECT_DIR}/CHANGELOG.md | yes | Path to changelog file. |\n| repositoryUrl | string | repositoryUrl | no | The URL of the repository to release from. |\n| tagFormat | string | ${PROJECT_NAME}-v${version} | no | Tag format to use. You can refer to [semantic-release configuration](https://github.com/semantic-release/semantic-release/blob/master/docs/usage/configuration.md#tagformat) |\n| npm | boolean | true | no | Whether to bump package.json version and publish to registry (if package is public). |\n| git | boolean | true | no | Whether to create git commit representing the new version. Setting to false disables the [@semantic-release/git](https://github.com/semantic-release/git) plugin. |\n| github | boolean | true | no | Whether to create github release. |\n| githubOptions | object | {} | no | Options for [@semantic-release/github](https://github.com/semantic-release/github) plugin |\n| buildTarget | string | | no | The target of the build command. If your package is public and you want to release it to npm as part of release, you have to provide it. Plugin will use it to build your package and set version in package.json before releasing it to npm registry. |\n| outputPath | string | ${WORKSPACE_DIR}/\u003c`outputPath` from `options` of the specified `buildTarget`\u003e | no | The path to the output directory. Provide that if your package is public and you want to publish it into npm. |\n| commitMessage | string | chore(release): ${nextRelease.version} [skip ci]\\\\n\\\\n${nextRelease.notes} | no | The commit message to use when committing the release. You can refer to [@semantic-release/git](https://github.com/semantic-release/git#options). |\n| gitAssets | string[] | | no | Path to additional assets that will be commited to git with current release. |\n| plugins | PluginSpec[] | | no | Additional plugins for semantic-release. Note: these plugins will be added before @semantic-release/git, which means that you can assets generated by them to git as well. Supports the same format as [semantic-release](https://github.com/semantic-release/semantic-release/blob/master/docs/usage/configuration.md#plugins) |\n| branches | BranchSpec[] | | no | Branches configuration for workflow release. Supports the same format as [semantic-release](https://github.com/semantic-release/semantic-release/blob/master/docs/usage/configuration.md#branches) |\n| packageJsonDir | string | ${PROJECT_DIR} | no | Path to package.json file (usable only if npm is true). Note: it should point to directory in which package.json can be found, not to file itself. |\n| parserOpts | object | | no | Parser options used by commit-analyzer and @semantic-release/release-notes-generator and @semantic-release/changelog |\n| writerOpts | object | | no | Writer options used by commit-analyzer and @semantic-release/release-notes-generator |\n| linkCompare | boolean | true | no | Whether to include a link to compare changes since previous release in the release note. |\n| linkReferences | boolean | true | no | Whether to include a link to issues and commits in the release note. |\n| releaseRules | string or object[] | | no | Release rules are used when deciding if the commits since the last release warrant a new release. Supports the same format as [@semantic-release/commit-analyzer](https://github.com/semantic-release/commit-analyzer#releaserules) |\n\n\n### Available Tokens\n\n| Token | Expands into |\n| --------------- | --------------------------------------------------------------------------------------------- |\n| ${RELATIVE_PROJECT_DIR} | Resolves to the current project relative directory within the current workspace (ex. `apps/app-a`) |\n| ${PROJECT_DIR} | Resolves to the current project directory (ex. `/Users/theunderscorer/nx-monorepo/apps/app-a`) |\n| ${PROJECT_NAME} | Resolves to the current project name (ex. `app-a`) |\n| ${WORKSPACE_DIR}| Resolves to the current workspace directory (ex. `/Users/theunderscorer/nx-monorepo`) |\n\n\nEvery available option support tokens - this included nested objects and arrays.\n\nYou may see other tokens like `${nextRelease.version}`, those are tokens that are replaced by semantic-release itself.\n\n\u003e \u003csup\u003e*\u003c/sup\u003e: The replacement of tokens in `plugins` only occurs for plugins which are specified with options, using [semantic-release's syntax](https://semantic-release.gitbook.io/semantic-release/usage/plugins#plugin-options-configuration)\n\u003e For example:\n\u003e ```\n\u003e plugins: [\n\u003e '@fake/plugin-without-options1', \n\u003e [\n\u003e '@semantic-release/exec',\n\u003e {\n\u003e prepareCmd: 'cp LICENSE dist/packages/${PROJECT_NAME} \u0026\u0026 cp README.md dist/packages/${PROJECT_NAME}',\n\u003e execCwd: '${WORKSPACE_DIR}',\n\u003e fakeStringArrayOption: ['${WORKSPACE_DIR}/src', '${WORKSPACE_DIR}/dist'],\n\u003e fakeBooleanOption: true,\n\u003e fakeNumberOption: 10\n\u003e }\n\u003e ],\n\u003e '@fake/plugin-without-options2', \n\u003e ]\n\u003e ```\n\u003e In above example, tokens will be replaced only for `@semantic-release/exec` plugin, and only for its `string|string[]` options, others will be left untouched.\n\n### Build target\n\nBy setting `buildTarget` option plugin will run your build executor as part of the release, which is useful if ex. you\nwant to publish released package to npm registry.\n\n## Skipping commits\n\nYou can skip commits for given projects using `[skip $PROJECT_NAME]` in its body. Ex:\n\n```\n feat: update something\n\n [skip my-app1]\n [skip my-app2]\n```\n\nDuring analysis this commit will be skipped for release pipeline for `my-app1`, `my-app2`.\nYou can also use `[skip all]` to skip commit for all projects or **one single** `[skip my-app1, my-app2]` to skip commits related to `my-app1`, `my-app2` at once.\n\n---\n\nAlternatively you can include only particular projects in given commit by using `[only $PROJECT_NAME]`. Ex:\n\n```\n feat: update something\n\n [only my-app1]\n [only my-app2]\n```\nDuring analysis this commit will be included only for release pipeline for `my-app`, `my-app2`.\nYou can also use **one single** `[skip my-app1, my-app2]` to skip commits related to `my-app1`, `my-app2` at once.\n\n## Releasing multiple apps/libraries at once\n\nYou can release multiple apps/libraries at once by using `nx run-many`:\n\n```shell\nnpx nx run-many --target=semantic-release --parallel=false\n```\n\u003e Note: `--parallel=false` is required to run tasks sequentially, otherwise `nx run-many` will run tasks in parallel and semantic-release will fail.\n\n## Gitlab support\n\nIn order to use this plugin on Gitlab, install `@semantic-release/gitlab@9.5.1` (\u003e= 10.0.0 is not supported for now due to ES format) and set the following in your configuration file:\n```json\n{\n \"plugins\": [\n \"@semantic-release/gitlab\"\n ],\n \"github\": false,\n}\n\n```\n\n## CI/CD\n\nExample of GitHub actions workflow:\n\n```yaml\nname: default\n\non:\n push:\n branches:\n - 'master'\n\njobs:\n release:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v2\n\n - name: configure git\n run: |\n git config user.name \"${GITHUB_ACTOR}\"\n git config user.email \"${GITHUB_ACTOR}@users.noreply.github.com\"\n\n - run: npm ci\n\n - run: npx nx run my-app:semantic-release\n env:\n GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}\n```\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FTheUnderScorer%2Fnx-semantic-release","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FTheUnderScorer%2Fnx-semantic-release","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FTheUnderScorer%2Fnx-semantic-release/lists"}