Quick Start

Get Versu running in your project in 5 minutes.

Prerequisites

Before starting, make sure you have:

• ✅ Node.js 24+ installed
• ✅ A Git repository initialized
• ✅ Your project follows Conventional Commits

Step 1: Install Versu

In case you want to use Versu as a local dev dependency:

npm install -D @versu/cli

Or install it globally to use it across multiple projects or system-wide:

npm install -g @versu/cli

Step 2: Install Plugins

Versu uses plugins to detect your project type and manage versioning. Install the appropriate plugins for your project. For example, if you're using Gradle:

npm install -g @versu/plugin-gradle

Step 3: Create Configuration

Versu can work with zero configuration by automatically searching for installed plugins.

However, for performance and reliability reasons, as well as to enable advanced features, it's recommended to create a versu.config.js file in your project with at least the plugins array to explicitly specify which plugins to use.

versu.config.js

export default {
  plugins: [
    // Add plugins here (e.g., npm, gradle, etc.)
    "@versu/plugin-gradle",
  ],
};

Step 4: Run Versu

If you installed Versu globally you can run:

versu run

You can also run it using npx:

npx @versu/cli run

INFO

If you have a local or global installation in your system, npx will search for the local version first and fallback to the global one if not found.

Versu will:

1. Analyze your commit history
2. Determine version bumps
3. Update version files
4. Generate changelogs
5. Display results

Step 5: Results

Versu will create or update:

• Version related files based on your plugins

  (e.g. package.json, gradle.properties, etc.)

• CHANGELOG.md files per module and a root one if you have multiple modules

• Commit messages and tags for your new versions

TIP

You can execute with --dry-run flag to see what changes would be made without actually modifying any files. This is a great way to preview the results before applying them.

Common Commands

# Check what will be versioned
versu run --dry-run

# Generate specific pre-release
versu run --prerelease-mode --prerelease-id alpha

Next Steps

• Configuration Guide - Customize Versu behavior
• Concepts - Understand Conventional Commits
• GitHub Action - Automate versioning in CI/CD

Troubleshooting

No versions bumped?

Check that your commits follow Conventional Commits. Example:

feat: add new feature    # ✓ Triggers minor bump
fix: resolve bug         # ✓ Triggers patch bump
docs: update README      # ✓ Triggers patch bump (default - configurable)

Also make sure there are new commits since the last release tag - if nothing changed, there is nothing to bump.

Dependencies not updated?

Plugins are responsible for identifying project structure and its dependencies. If you have a multi-module project, make sure your plugins are correctly configured to recognize the relationships between modules.

You can enable debug logging to see how Versu is analyzing your project:

DEBUG=versu* versu run #...

Still stuck?

• Check Examples
• Read API Documentation
• Open an issue on GitHub