Plugins

Versu's build-system support is delivered through adapter plugins. The core engine knows how to analyze commits and calculate versions; plugins teach it how to discover modules and write versions for a specific build system.

Official Plugins

Plugin	Adapter ID	Build System	Auto-detected when
@versu/plugin-gradle	gradle	Gradle (Groovy & Kotlin DSL)	Gradle build/settings files in the repository root
@versu/plugin-maven	maven	Maven	pom.xml in the repository root
@versu/plugin-node	node	Node.js (npm, yarn, pnpm workspaces)	package.json in the repository root

In addition, core ships a built-in manual adapter that requires no plugin - you describe your project structure yourself in a project-information.json file. See Custom Adapters.

Installing Plugins

Plugins are regular npm packages. Install them next to whichever Versu interface you use:

With Core

npm install @versu/core @versu/plugin-node

With CLI

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

The CLI also provides plugin management commands:

versu plugin install @versu/plugin-node    # local
versu plugin install @versu/plugin-node -g # global
versu plugin list
versu plugin uninstall @versu/plugin-node

The GitHub Action ships only the core engine, so plugins need to be installed in the job before the action runs (e.g., npm i -g @versu/plugin-gradle as a workflow step) - locally in the checked-out workspace or globally, both are discovered.

How Plugins Are Discovered

When Versu runs, plugins are loaded in one of two ways:

1. Explicit list - if your configuration file declares a plugins array, only those packages are loaded:

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

2. Auto-detection - with no plugins configuration, Versu scans node_modules (local and global) for packages matching these name patterns:

   • versu-plugin-*
   • @*/versu-plugin-*
   • @versu/plugin-*

TIP

Explicitly listing plugins is recommended for performance and reliability - it avoids scanning and guarantees the right plugins are loaded.

How the Adapter Is Chosen

Each plugin contributes one or more adapters. At startup, Versu asks each adapter whether it can handle the repository (each adapter checks for its build-system-specific files):

• If you pass --adapter <id> (or the adapter runner option), auto-detection is skipped and that adapter is used directly.
• Otherwise the first adapter that accepts the project wins. The manual adapter has the lowest precedence, so it only applies when a project-information.json file exists and no other adapter matched.

Writing Your Own Plugin

Any npm package following the naming patterns above and default-exporting a PluginContract works as a Versu plugin. See:

• Plugin Development - Package structure, contract and publishing
• Custom Adapters - Implementing the adapter interfaces

Next Steps

• Gradle Plugin - Detailed Gradle adapter documentation
• CLI - Plugin management commands
• Configuration File - The plugins option

---

Need help? Check the FAQ or open an issue.