npm-workspaces-publish-tool

A CLI tool for automating npm package publishing in monorepositories. This tool handles dependency resolution, version validation, build sequencing, and safe publishing with workspace dependency management. Note this is designed for use for mono-repos and will not work for projects without npm workspaces.

Features

• Automatic dependency graph analysis (topological sorting)
• Smart change detection since last release
• Version validation and increment checking
• Git status verification (prevents publishing with uncommitted changes)
• Workspace dependency management (converts * dependencies to exact versions during publish)
• Dry run mode for testing publish workflow
• Build sequencing in dependency order
• Safe rollback of package.json files after publishing

Installation

npm install -g npm-workspaces-publish-tool

Usage

nw-publish [--dry-run] [--registry <url>] [--auto-tick] [--anchor-tag-suffix <suffix>] [--allow-no-upstream]

Command Options

• --dry-run: Runs validation and preview without actual publishing
• --registry <url>: (Optional) NPM registry URL to publish scoped packages to
• --auto-tick: Automatically increment patch versions for packages that need version bumps
• --anchor-tag-suffix <suffix>: (Optional) Suffix to append to git tags (e.g., -rc creates tags like v1.2.3-rc)
• --allow-no-upstream: Allow publishing from branches without upstream tracking (see CI/CD Usage)

Workflow

1. Validation Phase

   • Builds packages in dependency order
   • Verifies all modified packages have incremented versions
   • Ensures git status is clean
   • Checks for unpushed commits

2. Publishing Phase

   • Replaces workspace * dependencies with exact versions
   • Publishes packages in topological order
   • Restores original package.json files after publishing

CI/CD Usage

Publishing from New Branches

By default, the tool requires branches to have upstream tracking configured (via git push -u origin <branch>). This is a safety check for manual usage to prevent accidentally publishing from local-only branches.

However, in CI/CD pipelines that create new release branches dynamically, you can use the --allow-no-upstream flag:

# CI/CD pipeline example
nw-publish --allow-no-upstream --anchor-tag-suffix=-rc

When the flag is set:

• The tool will automatically set upstream tracking when pushing tags
• No manual git push -u is required beforehand
• The branch and tags will be pushed together

When to use:

• CI/CD pipelines that create new release branches (e.g., RELEASE/v1.2.3)
• Automated release workflows where the branch doesn't exist on remote yet

When not to use:

• Manual publishing from your local machine (push your branch first instead)

Safety notes:

• The flag only bypasses the "no upstream" check
• The tool still validates:
  • Clean git status (no uncommitted changes)
  • Unpushed commits (if upstream exists)
  • Version increments
  • Build success

Requirements

• Node.js 16+
• Git
• npm workspaces monorepo structure
• All packages must have valid semver versions
• Build scripts defined in package.json (if needed)

License

MIT © Jonathan Kelsey