Basic Setup Example

A complete example of setting up Versu for a simple npm project.

Project Structure

my-library/
├── src/
│   └── index.ts
├── package.json
├── versu.config.js        # Optional
└── CHANGELOG.md           # Generated by Versu

Step-by-Step Setup

1. Install Versu

Install the CLI and the Node adapter plugin as dev dependencies:

npm install -D @versu/cli @versu/plugin-node

2. Create the Configuration (optional)

Versu works with zero configuration - the Node adapter is auto-detected from package.json and sensible defaults apply. Explicitly listing the plugin is still recommended:

// versu.config.js
export default {
  plugins: ["@versu/plugin-node"],
};

3. Write Conventional Commits

Versu determines version bumps from your commit messages:

git commit -m "feat: add parse function"     # minor bump
git commit -m "fix: handle empty input"      # patch bump
git commit -m "feat!: rename public API"     # major bump

See Conventional Commits for the full format.

4. Preview with a Dry Run

npx versu run --dry-run

This analyzes commits since the last release and reports the calculated bump without touching any file or git history. For a project at 1.2.3 with one feat commit you'll see 1.2.3 → 1.3.0.

5. Release

npx versu run

A single run will:

1. Update the version field in package.json (1.2.3 → 1.3.0)
2. Generate or update CHANGELOG.md from the commits
3. Commit the changes and push them to the remote
4. Create and push the release tag

TIP

Prefer to keep control over pushing? Use --no-push-changes and/or --no-create-tags and do it yourself.

6. Automate It (optional)

Run the same flow on every push to main with the GitHub Action:

name: Release

on:
  push:
    branches: [main]

permissions:
  contents: write

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0 # Full history - required for commit analysis

      - name: Setup Node
        uses: actions/setup-node@v6
        with:
          node-version: 24

      # Install the adapter plugin for your build system
      - name: Install Versu Node Plugin
        run: npm i -g @versu/plugin-node

      - name: Version project
        uses: versuhq/versu@v3

Next Steps

• Monorepo Setup - Multi-module example
• Configuration Guide - Detailed configuration
• GitHub Actions - Automated releases

---

Ready to handle multiple modules? Check out the Monorepo Setup example!