Release Process

The release flow lives in three places: scripts/publish.js, .github/workflows/publish.yml, and the four packages' package.json files.

Versioning convention

All four packages release together with the same version number on the same day:

@ackplus/nest-auth
@ackplus/nest-auth-client
@ackplus/nest-auth-react
@ackplus/nest-auth-contracts

Mixing versions across the four is not supported.

Beta tags

Pre-stable releases use the beta tag with monotonic counter: 2.0.0-beta.26, 2.0.0-beta.27, etc. Install with pnpm add @ackplus/nest-auth@beta to opt into the latest beta.

A 2.0.0 (no tag) release ships when the public API is judged stable.

Manual release — `scripts/publish.js`

node scripts/publish.js

The script prompts for the bump kind:

patch — bug fixes, no API changes (e.g. 2.0.0-beta.26 → 2.0.0-beta.27)
minor — additive features (e.g. 2.0.0-beta.26 → 2.1.0-beta.0)
major — breaking changes
prerelease — bumps the beta counter

It bumps every package's package.json, builds them in dependency order, and runs pnpm publish. Two-factor auth on npm is required.

CI release — `.github/workflows/publish.yml`

Triggered on pushes to tags matching v*:

git tag v2.0.0-beta.27
git push origin v2.0.0-beta.27

The workflow:

Installs and builds all packages.
Runs tests.
Publishes to npm with provenance.
Triggers the docs site rebuild (docs.yml).

The docs site's GitHub Actions workflow (.github/workflows/docs.yml) builds on every push to main that touches apps/docs/** or any of the four packages. It also re-runs the auto-generation pipeline (TypeDoc + OpenAPI + SQL snapshots), so the API Reference and Database Setup pages stay in sync with the latest code.

One-time GitHub Pages setup

Before the first deploy works, an admin needs to flip one switch in the repo:

Go to Settings → Pages on ack-solutions/nest-auth.
Under Build and deployment, set Source to GitHub Actions.
Save.

That's it. The next push to main (or a manual run via Actions → Deploy Docs to GitHub Pages → Run workflow) publishes the site at https://ack-solutions.github.io/nest-auth/.

The workflow needs no secrets — GITHUB_TOKEN is enough because the pages: write and id-token: write permissions are scoped on the job.

Custom domain (optional)

To serve at docs.ackplus.com instead of ack-solutions.github.io/nest-auth/:

Add a CNAME record at your DNS provider pointing docs.ackplus.com → ack-solutions.github.io.
In Settings → Pages → Custom domain, enter docs.ackplus.com and save.
Set the env var GITHUB_PAGES_USER_SITE=true on the docs build step in docs.yml — custom-domain Pages serves from the root, not a subpath, and the basePath logic in next.config.mjs keys off this flag.

Verifying a release

After publish:

pnpm view @ackplus/nest-auth versions --json | tail -5
pnpm view @ackplus/nest-auth dist-tags

The dist-tags should show latest (stable) and beta (most recent pre-release).

Hotfixing

For urgent fixes against a stable release while main has unreleased work:

Check out the tag of the buggy stable: git checkout v2.0.0.
Branch: git checkout -b hotfix/2.0.1.
Apply the fix, bump to 2.0.1, push the tag.
Cherry-pick the fix back into main.