Versioning and Releases
This page is for maintainers. It covers how Arkstack versions its packages and starter templates, and how a release gets from main to npm. If you are upgrading an application, read Upgrading instead.
What gets released
One release publishes everything in the monorepo that has a public package:
| Part | Location | Published as |
|---|---|---|
| Framework packages | packages/* | @arkstack/* on npm |
| Project generator | create-arkstack | create-arkstack on npm |
| Starter templates | templates/* | Not published; downloaded from GitHub |
| Workspace root and tests | package.json, etc. | Private, versioned for bookkeeping only |
create-arkstack downloads the templates straight from the arkstack-hq/arkstack repository with giget, keeps the chosen templates/<kit> folder, and rewrites its workspace:^ and catalog: dependencies to real version ranges.
One version for everything
Arkstack uses a single, lockstep version. Every @arkstack/* package, create-arkstack, the templates and the workspace root carry the same version number, even when a package has no changes. Applications should therefore keep all @arkstack/* dependencies on the same version.
Lockstep keeps upgrades simple: a project is "on Arkstack 0.22.0", not on a mix of package versions that were never tested together.
The template version and the package version are the same number. A project scaffolded by [email protected] depends on ^0.22.0 of every @arkstack/* package it uses.
Choosing the version number
Arkstack follows semantic versioning. While it is below 1.0, the rules are:
| Bump | When |
|---|---|
Minor (0.21.x → 0.22.0) | A new package, driver or template; a new feature that changes what a template contains; any breaking change to a public API, config shape or template file apps are expected to edit. |
Patch (0.22.0 → 0.22.1) | Bug fixes, additive options with safe defaults, dependency bumps, docs. |
Major (1.0.0) | Reserved for the first stable release. |
Because applications depend on ^0.x.y, a caret range never crosses a minor version below 1.0. A minor release is the only place where a breaking change may land, and it must come with an entry in the upgrade guide.
Prefer deprecating over removing. When an API is renamed, keep the old name working and mark it deprecated in a minor release, as Hook.set() was when Hook.on() arrived in 0.20.0, then remove it in a later minor release.
Before releasing
- Make sure CI on
mainis green.ci.ymlruns lint and the full test suite against PostgreSQL on Node 22, 24 and 25. - Release changes that templates depend on promptly.
create-arkstackalways downloads the templates from the tip ofmain, while the dependencies it writes point at the last published version. A template onmainthat uses a package API that hasn't been published yet produces broken new projects until the next release. - Bump the third-party versions in the
catalogofpnpm-workspace.yamlif the release needs newer versions of resora, kanun, arkormx, clear-router or others. Templates andcreate-arkstackread their versions from there. - Update
CHANGELOG.md: rename the[Unreleased]section to[x.y.z] - YYYY-MM-DDand start a new, empty[Unreleased]above it. Keepdocs/more/changelog.md, the published copy, identical to it. - If the release has breaking changes or template changes apps should copy, add a section to Upgrading.
Do not edit version fields by hand. The release workflow sets them.
Publishing a release
Releases are cut from GitHub:
- Create a GitHub release on
mainwith a tag named after the version, with novprefix (for example0.22.0). - Publishing the release starts the Publish to NPM workflow (
.github/workflows/publish.yml).
The workflow can also be started by hand from the Actions tab with a version input, or by pushing a v* tag.
The workflow then:
- Checks out the release's target branch.
- Runs
pnpm prepare:release-version <version>, which setsversionin the root,create-arkstack, every template and every package, and rewrites the@arkstack/*ranges and catalog versions increate-arkstack/src/data.ts. - Builds the templates, the console and
create-arkstack, then runs lint, migrations and the full test suite. - Commits the version changes as
chore: prepare release v<version>and pushes them to the branch. - Runs
pnpm publish:packages, which publishes every@arkstack/*package andcreate-arkstackwith public access.
If any check fails, nothing is committed or published. Fix the problem on main, then run the workflow again from the Actions tab with the same version.
The workflow publishes under npm's default latest tag and has no prerelease channel yet. Don't release a prerelease version such as 0.23.0-beta.1 through it, because every user would get it.
Releasing by hand
scripts/release-order.mjs works out the publish order from the workspace dependency graph, so dependencies are published before the packages that use them:
node scripts/release-order.mjs order # print the order
node scripts/release-order.mjs publish # print the publish commands
node scripts/release-order.mjs publish --runUse it only when the workflow cannot run. Outside CI, each package's prepublishOnly builds the package first.
Recovering from a bad release
npm only allows unpublishing for a short time after a release, and never when other packages depend on the version. Point latest back at the last good version and deprecate the bad one instead:
node scripts/release-order.mjs fix --bad 0.22.1 --good 0.22.0 # print the commands
node scripts/release-order.mjs fix --bad 0.22.1 --good 0.22.0 --runThen ship the fix as a new patch release. If unpublishing is still possible, unpublish --bad <version> prints the commands in reverse dependency order.
Related packages
resora, kanun, arkormx and clear-router are released from their own repositories on their own version lines. Arkstack picks up their new versions through the catalog in pnpm-workspace.yaml, and a catalog bump goes in the next Arkstack release like any other change.
