---
description: Release a shared-version JavaScript project with an inspectable plan and an atomic Git handoff.
---

# Release a JavaScript project as one version

Verso is a release CLI for repositories whose JavaScript packages move together. It discovers
the release manifests, writes one target version, optionally prepends a Conventional Commit changelog,
creates an annotated tag, and pushes the current upstream branch and that exact tag atomically.

Install Verso in the repository you want to release:

<InstallTabs dev packageName="@amamo/verso" />

Continue with [Getting started](/getting-started/) to run `doctor` through the package manager that
installed Verso and preview an exact release plan.

<Callout variant="tip" title="The release boundary is intentionally small">
  Verso prepares and records a release. It does not publish packages, create a GitHub Release, or
  replace CI. Put project checks in hooks and let tag-triggered CI own credentials and publishing.
</Callout>

## The contract

```text
verso.toml + package manifests + Git history
  -> validate config, versions, worktree, branch, and upstream
  -> choose one SemVer target
  -> update package manifests, configured Cargo files, and changelog
  -> create release commit and annotated tag
  -> git push --atomic <upstream> <branch> <exact-tag>
```

| Verso owns                                      | Your repository owns                              |
| ----------------------------------------------- | ------------------------------------------------- |
| Package discovery and shared-version checks     | Tests, builds, and policy checks invoked by hooks |
| JSON, JSON5, YAML, Cargo, and changelog updates | Registry credentials and package publication      |
| Release commit, annotated tag, and atomic push  | Tag-triggered artifacts and GitHub Releases       |
| Dry-run and stage-aware local rollback          | Recovery decisions after a successful remote push |

## When Verso fits

Use Verso when every releasable package shares one version and one Git tag. A single-package project
also works without a config file when its root contains a supported package manifest.

Choose a different release model when packages version independently, when publishing must happen
inside the local transaction, or when your remote cannot accept atomic pushes.

## Safety model

- `verso doctor` checks the repository without starting a release.
- `verso --dry-run` prints files, hooks, and Git commands without writes or mutating Git commands.
- Real releases require a named branch with an upstream that is not ahead of the local branch.
- By default, the worktree must be clean. The relaxed mode still requires a clean index and clean
  release files.
- Execution errors before the push trigger stage-aware cleanup. User cancellation deliberately keeps
  already-completed stages so visible work is not discarded.
- A push error keeps the local commit and tag. An `after_push` hook error happens after the remote has
  accepted both refs.

## Continue

<CardGrid>
  <Card title="Getting started">
    [Install Verso and preview a first release.](/getting-started/)
  </Card>
  <Card title="Release workflow">
    [Understand confirmations, recovery boundaries, and the CI handoff.](/release-workflow/)
  </Card>
  <Card title="Configuration">[Review every key and package discovery rule.](/configuration/)</Card>
  <Card title="CLI reference">
    [Find command syntax, JSON output, and exit behavior.](/cli-reference/)
  </Card>
</CardGrid>