Introducing Capver: Version Management for Capacitor

If you've ever shipped a Capacitor app and had to manually update version numbers in three different files across three different platforms, you know how easy it is for things to get out of sync. Capver is an open-source CLI tool that manages your app versions across iOS, Android, and web in a single command. In this post, we'll walk you through what it does and how it works.

The Problem

Every Capacitor project stores version information in multiple places. iOS uses CFBundleShortVersionString and CFBundleVersion in project.pbxproj, Android uses versionName and versionCode in build.gradle, and web relies on the version field in package.json.

When it's time to release a new version, you have to update all of these files manually — and keep them in sync. Miss one, and you might end up with a version mismatch that causes build failures, app store rejections, or confused users running different versions on different platforms.

This problem only gets worse as your release cadence increases.

Meet Capver

Capver is a lightweight CLI tool built specifically for Capacitor projects. It reads and writes version numbers across all platforms so you don't have to touch each file by hand.

You can install it via npm:

npm install -D @capawesome/capver

Once installed, you can check the current version across all platforms with a single command:

npx capver get

If any platform is out of sync, Capver will let you know right away.

Key Commands

Capver provides a small, focused set of commands that cover the most common versioning tasks:

Viewing and Setting Versions

• capver get — Displays the current version for each platform and warns you if they're out of sync.
• capver set <version> — Sets a specific version (e.g., 1.2.0) across iOS, Android, and web at once.
• capver sync — Detects the highest version across all platforms and syncs everything to match it.

Bumping Versions

• capver major — Bumps the major version (e.g., 1.2.3 → 2.0.0).
• capver minor — Bumps the minor version (e.g., 1.2.3 → 1.3.0).
• capver patch — Bumps the patch version (e.g., 1.2.3 → 1.2.4).
• capver hotfix — Increments the hotfix version on mobile platforms only, without changing the semantic version.

Debugging

• capver doctor — Prints system information like Node.js version, OS, and CLI version to help with troubleshooting.

Hotfix Versioning

One feature worth highlighting is hotfix support. Sometimes you need to push a quick fix to your mobile apps without bumping the public-facing version number. Capver handles this by incrementing a separate hotfix digit in the mobile build number while leaving the semantic version (major.minor.patch) unchanged.

This is especially useful when using over-the-air update tools where you want to differentiate between builds without changing what users see in the app store.

Configurable Build Number Patterns

On mobile platforms, Capver generates build numbers from your version using a configurable pattern. The default pattern is MMmmmpphh, where each letter represents a digit:

• M — Major version
• m — Minor version
• p — Patch version
• h — Hotfix version

For example, version 1.23.4 with hotfix 5 produces the build number 102300405.

You can customize this pattern in your package.json:

{
  "capver": {
    "pattern": "MMmmmpphh"
  }
}

This gives you control over how much space each version component gets, so you can adapt it to your project's versioning needs.

Integrations

Since Capver is a simple CLI, it's easy to integrate into your existing release workflow — whether that's a CI/CD pipeline, a custom script, or a versioning tool.

One example is commit-and-tag-version, which handles automatic versioning, changelog generation, and Git tagging based on conventional commits. By adding a postbump hook to your package.json, Capver automatically syncs all platform versions whenever the version is bumped:

{
  "scripts": {
    "release": "commit-and-tag-version --commit-all"
  },
  "commit-and-tag-version": {
    "scripts": {
      "postbump": "npx @capawesome/capver set $(node -p \"require('./package.json').version\") && git add android/app/build.gradle ios/App/App/Info.plist"
    }
  }
}

With this setup, running npm run release bumps the version in package.json, generates the changelog, and then Capver updates all platform files automatically — all in a single step.

Try Capver

Capver is open source under the MIT license and available on npm and GitHub. Give it a try in your next Capacitor project and let us know what you think.

Subscribe to the Capawesome Newsletter

Final Thoughts

Managing app versions across multiple platforms doesn't have to be a manual chore. Capver gives you a single source of truth for your Capacitor project's version, reducing the risk of mismatches and saving time on every release.

If you have questions or feedback, join the Capawesome Discord server — we'd love to hear from you. And if you want to stay up to date with the latest news, subscribe to the Capawesome newsletter.