Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/nxsjs/nxspub

Automated release tool tailored for modern multi-branch workflows
https://github.com/nxsjs/nxspub

angular automatic changelog git-hooks nxsjs nxspub publish release version workflow

Last synced: 2 days ago
JSON representation

Automated release tool tailored for modern multi-branch workflows

Awesome Lists containing this project

README 

          


  

    nxspub logo

  






  


    Made by NxsJs

    npm version

    license

  





## Nxspub



`nxspub` is a release automation CLI for npm packages and pnpm workspaces.



It handles:



- commit-message linting

- branch-based version policies

- changelog generation

- git tagging and pushing

- npm publishing

- monorepo release propagation



The project assumes a Conventional Commits workflow and is designed for multi-branch release lines such as `main`, `alpha`, `beta`, and `rc`.



## Installation



```bash

pnpm add -D nxspub

```



## Quick Start



### 1. Add scripts



```json

{

  "scripts": {

    "check": "tsc --incremental --noEmit",

    "postinstall": "nxspub git-hooks",

    "version": "nxspub version",

    "release": "nxspub release"

  }

}

```



### 2. Add minimal config



You can place config in `package.json`:



```json

{

  "nxspub": {

    "git-hooks": {

      "pre-commit": "pnpm lint-staged && pnpm check"

    }

  }

}

```



Or use `nxspub.config.ts`:



```ts

import { defineConfig } from 'nxspub'



export default defineConfig({

  branches: {

    main: 'latest',

    master: 'latest',

    alpha: 'preminor',

    beta: 'preminor',

    rc: 'preminor',

  },

  'git-hooks': {

    'pre-commit': 'pnpm lint-staged && pnpm check',

  },

})

```



### 3. Install hooks



```bash

pnpm exec nxspub git-hooks

```



### 4. Release flow



```bash

pnpm version

pnpm release

```



`nxspub version` updates versions, changelogs, commits the release, and creates tags.



`nxspub release` builds the package and publishes it to npm.



## Core Concepts



### Branch Policies



Each branch can define what kind of release it is allowed to produce.



Example:



```ts

branches: {

  main: 'latest',

  alpha: 'preminor',

  beta: 'preminor',

  hotfix: 'patch',

}

```



Available branch policy types:



- `major`

- `minor`

- `patch`

- `latest`

- `premajor`

- `preminor`

- `prepatch`



Practical effect:



- `latest` allows normal stable releases.

- `pre*` branches generate prerelease versions such as `1.2.0-alpha.0`.

- restrictive branches such as `patch` prevent larger bumps from being released on that branch.



### Commit-Based Versioning



By default, `nxspub` maps commit messages to SemVer bumps:



- `major`: `feat(scope)!:`, `feat!:`, `BREAKING CHANGE:`

- `minor`: `feat:`, `feat(scope):`

- `patch`: `fix:`, `perf:`, `refactor:`



Default patterns are configurable through `versioning`.



### Changelog Generation



`nxspub` parses conventional commit messages and generates grouped changelog sections such as:



- `Features`

- `Bug Fixes`

- `Performance Improvements`

- `Refactors`

- `Reverts`



It also:



- links commits, pull requests, and issues

- extracts `BREAKING CHANGE:` details

- appends contributor sections

- archives oversized or major-version changelogs



You can restrict changelog writes to specific branches:



```ts

changelog: {

  writeOnBranches: ['main', 'master']

}

```



When running `nxspub version` on non-allowed branches, nxspub writes draft files under `.nxspub/changelog-drafts/*`.  

When you later run `nxspub version` on an allowed branch, matching drafts are auto-imported and deduplicated.

Drafts that are behind/ahead of current target version are kept and reported as warnings, so they are not silently dropped.



You can audit draft health manually:



```bash

nxspub draft-doctor --cwd . --target 1.3.0

```



You can also prune stale drafts (versions behind the current target):



```bash

nxspub draft-doctor --cwd . --target 1.3.0 --prune

```



`nxspub version` and `nxspub release` also use a repository lock file under Git metadata (for example `.git/nxspub/version.lock`) to prevent concurrent pipelines from mutating version/tag state at the same time.



## Configuration



### Full Example



```ts

import { defineConfig } from 'nxspub'



export default defineConfig({

  workspace: {

    mode: 'locked',

    passive: 'patch',

  },

  branches: {

    main: 'latest',

    master: 'latest',

    alpha: 'preminor',

    beta: 'preminor',

    rc: 'preminor',

  },

  versioning: {

    major: [/(\w+)\((.+)\)!:/, /(\w+)!:/, /BREAKING CHANGE:/],

    minor: [/feat\((.+)\):/, /feat:/],

    patch: [

      /fix\((.+)\):/,

      /fix:/,

      /perf\((.+)\):/,

      /perf:/,

      /refactor\((.+)\):/,

      /refactor:/,

    ],

  },

  changelog: {

    writeOnBranches: ['main', 'master'],

    labels: {

      feat: 'Features',

      fix: 'Bug Fixes',

      perf: 'Performance Improvements',

      refactor: 'Refactors',

      revert: 'Reverts',

      deps: 'Dependencies',

    },

  },

  lint: {

    'commit-msg': {

      pattern:

        /^(revert: )?(feat|fix|docs|dx|style|refactor|perf|test|workflow|build|ci|chore|types|wip|release)(\([^)]+\))?(!)?: .{1,50}/,

      message: 'Invalid commit message format.',

    },

  },

  'git-hooks': {

    'pre-commit': 'pnpm lint-staged && pnpm check',

    'commit-msg': 'pnpm exec nxspub lint --edit "$1"',

  },

  scripts: {

    releaseBuild: 'pnpm run build',

  },

})

```



### Config Locations



`nxspub` reads config from:



1. `nxspub.config.ts`

2. `nxspub.config.mjs`

3. `nxspub.config.js`

4. `nxspub.config.cjs`

5. `package.json#nxspub`



File-based config is merged with `package.json#nxspub` and defaults.



### Workspace Options



```ts

workspace: {

  mode: 'locked' | 'independent',

  passive: 'patch' | 'follow' | 'none'

}

```



`mode`:



- `locked`: all packages receive the same next version

- `independent`: each package is versioned individually



`passive`:



- `patch`: dependents get a patch bump when internal dependencies change

- `follow`: dependents inherit the highest bump from changed dependencies

- `none`: internal dependency changes do not trigger passive bumps



## Commands



### `nxspub git-hooks`



Install configured hooks into `.git/hooks`.



Options:



- `--cwd `: run against a target repository instead of the current shell directory

- `--dry`: preview generated hook content without writing files



Example:



```bash

pnpm exec nxspub git-hooks --cwd ./packages/app --dry

```



### `nxspub lint --edit `



Validate a commit message file, typically from the `commit-msg` hook.



Options:



- `--cwd `: resolve relative paths and config from a target repository

- `--edit `: path to the commit message file



Example:



```bash

pnpm exec nxspub lint --edit .git/COMMIT_EDITMSG

```



### `nxspub version`



Calculate the next version, update `package.json`, generate changelog content, create a release commit, create tags, and push to remote.



Options:



- `--cwd `: operate on a target repository

- `--dry`: preview version and changelog changes without writing files



Example:



```bash

pnpm exec nxspub version --dry

pnpm exec nxspub version --cwd /path/to/repo

```



### `nxspub release`



Build and publish a package or workspace.



Options:



- `--cwd `: operate on a target repository

- `--dry`: run publish in preview mode

- `--provenance`: pass `--provenance` to `pnpm publish`

- `--registry [url]`: override the npm registry

- `--access [access]`: publish access, default `public`

- `--tag [tag]`: override the npm dist-tag

- `--branch `: override detected branch name

- `--skipBuild`: skip the build step

- `--skipSync`: skip remote synchronization checks



Example:



```bash

pnpm exec nxspub release --dry

pnpm exec nxspub release --registry https://registry.npmjs.org

pnpm exec nxspub release --cwd /path/to/repo --branch main

```



### `nxspub console`



Interactive release console. It includes all previous preview capabilities (read-only release computation + risk checks) and web/API mode.



Options:



- `--cwd `: operate on a target repository

- `--json`: print machine-readable preview output

- `--branch `: simulate policy/checks on a target branch

- `--web`: start local preview web console

- `--host `: web bind host, default `127.0.0.1`

- `--port `: web bind port, default `4173`

- `--open`: open browser after web service starts

- `--readonly-strict`: disable write endpoints (for example draft prune and snapshot save/delete)

- `--allow-remote`: required when `--host 0.0.0.0`

- `--api-only`: serve API endpoints only, without web static assets



Feature flag (rollout/rollback):



- `NXSPUB_CONSOLE_WEB_ENABLED=false` disables `console --web` startup globally



Examples:



```bash

pnpm exec nxspub console --json

pnpm exec nxspub console --branch alpha --json

pnpm exec nxspub console --web --open

pnpm exec nxspub console --web --api-only --port 4173

```



#### Preview Web Workflow



Build frontend assets:



```bash

pnpm run console:web:build

```



Run web preview server:



```bash

pnpm exec nxspub console --web --host 127.0.0.1 --port 4173

```



Preview web stack:



- Server: Nitro HTTP layer (`h3`) hosted by `nxspub console --web`

- Client: React + Vite with TailwindCSS styling

- UI language: auto-detects browser language (`zh*` -> Chinese, otherwise English)



Run API-only mode (for custom frontend or proxy):



```bash

pnpm exec nxspub console --web --api-only --host 127.0.0.1 --port 4173

```



All `/api/*` requests require header:



```txt

x-nxspub-console-token: 

```



Diagnostic bundle export endpoints:



- `GET /api/export.bundle?format=json`

- `GET /api/export.bundle?format=zip`



Bundle includes runtime context, preview result, checks report, and draft health data for troubleshooting.



Web console also supports branch-to-branch comparison (for example `main` vs `alpha`) to inspect target version and release scope differences.

Workspace mode includes a layered dependency propagation panel to inspect internal dependency edges and passive bump reasons.



Snapshot endpoints:



- `GET /api/snapshots` list saved snapshots

- `POST /api/snapshots` save current comparison snapshot

- `GET /api/snapshots/:id` load snapshot payload

- `DELETE /api/snapshots/:id` delete a saved snapshot



Snapshots are stored under `.nxspub/preview-snapshots`.



Realtime status stream:



- `GET /api/events?token=` (Server-Sent Events)



## Git Hook Setup



Typical hook setup:



```json

{

  "nxspub": {

    "git-hooks": {

      "pre-commit": "pnpm lint-staged && pnpm check",

      "commit-msg": "pnpm exec nxspub lint --edit \"$1\""

    }

  }

}

```



If `commit-msg` is not configured, `nxspub git-hooks` injects a default one automatically.



## Monorepo Behavior



Workspace support is implemented.



`nxspub` scans workspace packages from:



- `pnpm-workspace.yaml`

- `package.json#workspaces`



For workspace releases it will:



- detect changed packages from git history

- compute release bumps per package

- propagate dependency-driven bumps

- update internal dependency ranges

- generate per-package changelogs

- generate a root changelog summary

- create package tags and global tags



## `--cwd` Support



All commands support `--cwd`.



Use it when:



- running `nxspub` from outside the target repository

- operating on a nested package from a larger shell session

- automating releases from scripts or CI runners with a shared working directory



Example:



```bash

pnpm exec nxspub version --cwd /absolute/path/to/repo

pnpm exec nxspub release --cwd /absolute/path/to/repo

```



`--cwd` affects:



- config loading

- git branch detection

- git history lookup

- repository URL lookup

- changelog link generation

- package and workspace scanning



## Requirements and Assumptions



- Node.js `>=20`

- pnpm `>=9.12.3`

- git repository with a configured `origin`

- Conventional Commits discipline

- clean working tree before `version` and `release`



## Typical CI Usage



```bash

pnpm install --frozen-lockfile

pnpm run check

pnpm test

pnpm exec nxspub version --cwd .

pnpm exec nxspub release --cwd . --provenance

```



If your CI already guarantees branch state and fetch depth, `--skipSync` can be used deliberately, but it weakens the preflight safety checks.



## Troubleshooting



### Branch not configured



If you see an error like:



```text

Admission Denied: Branch "feature/x" not configured.

```



Add the branch pattern to `branches`, or override the branch explicitly with:



```bash

pnpm exec nxspub release --branch main

```



### No version bump detected



If `nxspub version` reports no version-triggering commits:



- check your commit messages

- ensure the commits are after the last release commit

- verify your custom `versioning` regex rules



### Publish skipped



If publish is skipped, `nxspub` has determined that the target package version is already present in the registry.



## Development



```bash

pnpm install

pnpm run check

pnpm test

pnpm run lint

```



## Resources



- [Learn Nxspub](https://nxsjs.com)

- [npm package](https://www.npmjs.com/package/nxspub)



## Contribution



Read the [Contributing Guide](https://github.com/nxsjs/nxspub/blob/main/.github/CONTRIBUTING.md) before opening a pull request.





  




Note: showing the first 500 contributors only due to GitHub image size limits.