Get ready for the first release

Requirements

Verso requires Node.js 22.18 or newer and supports these platforms:

The target repository also needs Git, at least one supported package manifest, and a named branch with an upstream. A real release is rejected when the local branch is behind that upstream.

Install Verso

Add Verso at the project root with your preferred package manager:

pnpm add -D @amamo/verso

npm install -D @amamo/verso

yarn add -D @amamo/verso

bun add -d @amamo/verso

The reference pages write commands as verso ... so their arguments stay independent of a package manager. Invoke the locally installed executable through your package manager or an existing project task.

Decide whether a config is needed

For a single package, a root package.json, package.json5, package.yaml, or package.yml is enough. With no explicit --config, Verso uses built-in single-package defaults.

For a workspace, generate verso.toml:

verso init

The initializer selects workspace mode only when it finds packages/*/package.json; otherwise it creates a single-package config. Override that narrow detection when necessary:

verso init --workspaceverso init --single

init refuses to replace an existing file. Use --force only when replacing it is intentional.

Inspect release readiness

Run the first check through the package manager that installed Verso:

pnpm exec verso doctor

npm exec --package=@amamo/verso -- verso doctor

yarn exec verso doctor

bunx --no-install verso doctor

doctor checks config loading, package discovery, the current version, shared package and Cargo versions, the changelog parent directory, and the named branch's upstream. It returns a nonzero exit status when any check fails. The remaining examples use verso as shorthand for the same local executable. Automation can consume the checks as JSON:

verso doctor --json

Preview one exact version

Start with an explicit target so the preview is reproducible:

verso --dry-run --version 1.4.0

The plan lists version files, the optional changelog, configured hooks, warnings, commit and tag templates, and the exact shape of the Git commands. It performs no writes, hooks, commits, tags, or pushes. JSON output is available only in dry-run mode:

verso --dry-run --version 1.4.0 --json

Run the release

Interactive mode offers stable and prerelease choices, then asks before files, commit, tag, and push:

verso

Automation should provide the exact SemVer and opt into all confirmations:

verso --version 1.4.0 --yes

--yes skips confirmations; it never chooses a version. Read Release workflow before automating a repository with hooks or a relaxed worktree policy.