| name | mongez-pkgist-versioning |
| description | Version-bump strategies for pkgist packages: `"auto"` / `"patch"` (default, bumps patch digit), `"minor"`, `"major"`, or any literal semver string. Standalone packages bump from their own current version. Families take the highest current version across all members and bump that, landing all members on the same new version. In a family build, intra-family dependencies (sibling deps written as `"*"` in source) are pinned to the exact shared release version in the published package.json.
|
Versioning
pkgist computes the next version per package from a strategy you pick, then writes it back to the source package.json before building.
The five strategies
| Strategy | What it does |
|---|
"auto" (default) | Bump the patch digit. 2.1.0 → 2.1.1 |
"patch" | Identical to "auto". Bump the patch digit |
"minor" | Bump minor, reset patch. 2.1.0 → 2.2.0 |
"major" | Bump major, reset minor + patch. 2.1.0 → 3.0.0 |
| Literal semver string | Use exactly this version. version: "3.0.0" → 3.0.0 |
Pre-release versions follow the same rules (semver-internal):
"patch" on 2.1.0-beta.1 → 2.1.0 (drops pre-release)- An explicit
"2.1.0-beta.2" is also valid
Overriding per run from the CLI
The same five strategies are available as a per-run CLI override via --bump, so you don't have to edit the version field in pkgist.config.ts for every release:
pkgist build @scope/utils --bump minor
pkgist build:family atom --bump 6.1.0
pkgist build:all --bump patch
--bump <strategy> takes the identical values to the config version field (auto / patch / minor / major / a literal semver) and overrides it for that invocation only — the config file is never mutated. For a standalone build it applies to every targeted package; for a family build it replaces the family's single shared version (the highest-current-member rule still applies when the strategy is a bump keyword). When --bump is omitted, the config version (or its "auto" default) is used.
Named --bump, not --version, because commander reserves --version for pkgist --version. See the cli skill's Per-run overrides section, and git-workflow for the paired --commit flag.
Standalone packages
{ name: "@scope/utils", root: "../utils", version: "auto" }
{ name: "@scope/utils", root: "../utils", version: "minor" }
{ name: "@scope/utils", root: "../utils", version: "3.0.0" }
Family packages
Families synchronize. The family picks the highest current version across all members, then bumps it. All members land on the same new version.
families: [
{ name: "atom-family", version: "patch", packages: [...] }
]
This means adding a new low-versioned package to a family is intentional surgery: it jumps to match the family on the first build. The family version is the compatibility contract — if you publish react-atom@6.0.0, every other family member must also be 6.0.0 so consumers can lock to one version.
Strategy on the family, not on members
version is family-level only. Family-member entries don't accept their own version — it's whatever the family decided.
families: [
{
name: "atom-family",
version: "minor",
packages: [
{ name: "@scope/atom", root: "../atom" },
{ name: "@scope/react-atom", root: "../react-atom" },
],
},
]
Intra-family dependency pinning
In a monorepo, sibling packages reference each other with "*" so the workspace links them to the local copy:
"dependencies": { "@scope/atom": "*" }
"*" must never reach npm — it lets a consumer resolve the sibling to any published version, which breaks the "whole family on one exact version" contract and risks pulling an incompatible release. So during a family build, pkgist rewrites every dependencies / peerDependencies entry whose name is another family member to the exact shared release version in the published package.json. The source file is never mutated — it keeps "*" for workspace linking (a fresh object is written for the build).
"dependencies": { "@scope/atom": "5.1.4" }
Rules:
- Family builds only. Standalone builds (
build / the standalone half of build:all) never pin — their deps publish verbatim.
- Applies to
dependencies and peerDependencies. (devDependencies are dropped from the build entirely; optionalDependencies are not carried into the published package.json.)
- Only family-member names are rewritten. Every non-member dependency keeps its original range exactly as written.
- The pin is the exact shared version string (e.g.
5.1.4) with no ^ / ~ — so an installed family resolves to one coherent, same-version set.
This is what makes the family version a true compatibility contract: members share it, and their cross-references resolve to it.
Picking the right strategy
This is a semantic question, not a pkgist one. The convention:
| When changes are | Use |
|---|
| Bug fixes, internal refactors, docs, lockfile/CI updates with NO API surface change | "patch" |
| Strictly additive: new exports, new optional params, new fields on result types | "minor" |
| Anything a consumer's code would have to change to absorb (removals, renames, signature changes, default-behavior flips, runtime deps bumped major) | "major" |
For families specifically: pick based on the most significant change in any member. If one family member made a breaking change, the family bumps major even if the others only had docs updates.
Explicit strings for unusual paths
The literal-string form unlocks:
- First 1.0.0 release:
version: "1.0.0" (rather than bumping 0.x.x)
- Re-publishing after a botched release:
version: "2.1.3" to overwrite intent (only works if npm hasn't seen this version — never use to "force overwrite" a published version, which npm prevents anyway)
- Pre-releases:
version: "2.0.0-beta.1", then "2.0.0-beta.2", then "2.0.0" for the final cut
- Hotfix lineage:
version: "1.2.3" to ship a patch on an old major if you've moved past it
