build: add workspace versioning script

Author: cwillisf

package-lock.json

@@ -14,7 +14,8 @@
     "build-monorepo": "cross-env-shell ./scripts/build-monorepo.sh",
     "prepare": "husky install",
     "build": "cross-env NODE_ENV=production npm run --workspaces build",
-    "clean": "npm run --workspaces clean"
+    "clean": "npm run --workspaces clean",
+    "version": "cross-env-shell ./scripts/npm-version.sh"
   },
   "config": {
     "commitizen": {
@@ -30,6 +31,7 @@
   "devDependencies": {
     "@commitlint/cli": "17.8.1",
     "@commitlint/config-conventional": "17.8.1",
+    "cross-env": "7.0.3",
     "husky": "8.0.3",
     "npm": "10.9.2",
     "ts-node": "10.9.2"

package.json

@@ -0,0 +1,47 @@
+#!/usr/bin/env bash
+
+# `npm version 1.2.3` does the following:
+# 1. Update `/package.json` and `/package-lock.json` with the new version
+# 2. `git add package.json package-lock.json`
+# 3. `git commit -m 1.2.3`
+# 4. `git --no-replace-objects tag -m 1.2.3 v1.2.3`
+
+# `npm --workspaces version 1.2.3` changes step 1 to update the version of each workspace but NOT the root.
+# The other steps are executed as-is: step 2 will say there's nothing to commit and the process will stop.
+# The version numbers in `/packages/*/package.json` will be updated but not committed.
+
+# `npm --workspaces --include-workspace-root version 1.2.3` changes step 1 to update the version of each workspace AND
+# the root. However, the remaining steps are still unaltered. You'll end up with a commit that only updates the
+# workspace root, and the version numbers in `/packages/*/package.json` will be updated but not committed.
+
+# Fortunately, npm runs the `version` script as part of this process. Unfortunately, the script runs after
+# `/package.json` and `/package-lock.json` are updated, but before `/packages/*/package.json` are updated. That
+# means the `--workspaces` flag isn't helping, and we need to update workspace versions ourselves. We can do that with
+# `npm --workspaces version --no-git-tag-version ${npm_package_version}` and then stage the files.
+
+# (Props to this post: <https://blog.chlod.net/technical/easy-npm-version-synchronization-for-monorepos/>)
+
+# BUT WAIT!
+
+# What about `--no-git-tag-version`? The normal behavior for `npm version` in that case is to adjust version numbers
+# but not stage or commit anything. If this script stages `/packages/*/package.json` in that case, that's no good.
+
+# The only way I've found to detect `--no-git-tag-version` is to check for the existence of an environment variable
+# called `npm_config_git_tag_version`. Unfortunately, it's considered "true" when the value is an empty string, so we
+# need to check for that as well. Big thanks to this StackOverflow answer: <https://serverfault.com/a/382740>
+# TL;DR: `[ -z "${npm_config_git_tag_version+set}" ]` is test we want.
+
+# So, the plan is:
+# 1. The user should run `npm version 1.2.3`
+# 2. npm will update `/package.json` and `/package-lock.json` for the workspace root
+# 3. npm will run this script (it should be set as the `version` script in `/package.json`)
+# 4. This script will stage `/packages/*/package.json` if `npm_config_git_tag_version` exists
+# 5. npm will choose whether to commit / tag afterward on its own
+
+npm --workspaces version --no-git-tag-version "${npm_package_version}"
+
+if [ -z "${npm_config_git_tag_version+set}" ]; then
+    npm query .workspace | jq -r '.[].location' | while read WS; do
+        git add "$WS/package.json"
+    done
+fi