Automated NPM publishing via GitHub Actions with semver

[PaulGrimshaw]

Summary

Set up automated NPM publishing on every merge to main, using GitHub Actions and semantic versioning.

Problem

Currently there is no automated publish pipeline. Publishing is manual, error-prone, and version bumps are ad-hoc.

Requirements

• Every merge to main triggers an NPM publish of changed packages
• Versions follow semver (major / minor / patch)
• Works with the existing Lerna monorepo (publishes only changed packages)
• GitHub Actions-based

Key Design Decision: How to Determine Semver Bump

This is the core question to resolve. Leading approaches:

Option A — Conventional Commits + automated detection

Use Conventional Commits to encode intent in commit messages:

• fix: → patch
• feat: → minor
• feat!: / BREAKING CHANGE: → major

Tools like Lerna (with --conventional-commits), changesets, or semantic-release can parse these and auto-bump versions.

Option B — Changesets

Use @changesets/cli — developers add a "changeset" file per PR describing the bump type. A GitHub Action consumes these on merge.

Option C — Manual version bump in PR

Developer explicitly bumps package.json version in the PR. CI just publishes whatever version is in the package.

Recommendation: Evaluate Options A and B. Conventional Commits + Lerna's built-in support is the lowest-friction path given we already use Lerna, but Changesets is the most popular choice in the JS ecosystem for monorepos.

Implementation Scope

1. Research & decide on the versioning strategy (A, B, or C above)
2. Enforce commit conventions (if Option A) — add commitlint + husky, or a CI check
3. Create GitHub Actions workflow that:
   • Triggers on push/merge to main
   • Builds & tests all packages
   • Determines version bumps
   • Publishes changed packages to NPM
4. Set up NPM token as a GitHub Actions secret (NPM_TOKEN)
5. Handle monorepo — only publish packages that actually changed
6. Tag releases in git (e.g. @dcb-es/event-store@1.2.3)

Acceptance Criteria

• Merging to main automatically publishes changed packages to NPM
• Version bumps follow semver based on the chosen strategy
• Only changed packages are published (not the whole monorepo)
• Git tags created for each release
• Failed builds/tests block publishing
• Process documented in README or CONTRIBUTING.md

[PaulGrimshaw]

Dependencies / Ordering Note

This issue has two prerequisites that should be completed first:

1. chore: migrate from Lerna + Yarn to pnpm workspaces #25 — migrate from Lerna + Yarn to pnpm workspaces — the current Lerna/Yarn setup is dated and pnpm is the modern standard. This should land first as it changes the entire build/workspace foundation.
2. chore: adopt Changesets for release management and changelogs #28 — adopt Changesets for release management — Changesets works natively with pnpm workspaces and is the community standard for monorepo versioning. This effectively answers the "how do we decide semver bumps" question in this issue (Option B — Changesets).

Suggested order: #25 → #28 → #41 (this issue becomes mostly just the GitHub Actions workflow wiring, since Changesets handles the versioning logic).