Skip to main content
Capgo logo

Capgo Semver Tester

Check semantic versioning compatibility for your Capacitor app updates

The version your installed app reports to Capgo, from config or native app metadata.

Enter two semantic versions to see comparison

What "Local Version" means

Local Version is the version already on the device when it asks the update server for a bundle. In a Capacitor app, that value can come from CapacitorUpdater.version in capacitor.config.*. If that setting is not present, the plugin falls back to the native app version from iOS or Android. Do not assume it is your package.json version unless your build copies that value into config or native metadata.

Capacitor config

Set CapacitorUpdater.version when you want one explicit version sent by the app.

Pro: easy to keep the same across iOS and Android builds.

Con: stale config can report the wrong version if you forget to update it before a native release.

Native app version

Use the platform version, such as iOS CFBundleShortVersionString or Android versionName.

Pro: matches the binary users installed from TestFlight, App Store, Play Store, or internal testing.

Con: changing it requires a native build and can differ by platform if release settings drift.

Bundle targeting

Compare it with remote bundle versions, channel semver rules, or upload constraints such as --native-version.

Pro: prevents sending JavaScript that needs newer native code to old app binaries.

Con: rules that are too strict can block valid updates until the channel or bundle metadata is adjusted.

For this tester, enter the version the device would report as local, then compare it with the remote bundle version you want Capgo to deliver.

Why Capgo uses Semantic Versioning

Semantic Versioning is the most widely adopted versioning standard in software development. By using semver, Capgo ensures compatibility and safety when delivering live updates to your Capacitor apps.

The semver standard allows Capgo to understand exactly what changes are included in each update:

  • Patch updates (1.0.0 → 1.0.1): Bug fixes, safe to apply automatically
  • Minor updates (1.0.0 → 1.1.0): New features, backward compatible
  • Major updates (1.0.0 → 2.0.0): Breaking changes, require native app store release

This prevents Capgo from ever sending an incompatible update to your native code, protecting your users from crashes and ensuring your app remains stable.

Flexible Semver Strategies: Beyond Basic Versioning

While semver is strict about its core format, you can extend it for your team's needs using pre-release identifiers and build metadata:

🏷️ Build Metadata (+) - The "Cosmetic" Layer

1.2.0+20240315.142530
Timestamp for deployment tracking
1.2.0+ui.refresh.dark-mode
UI update description for design team
1.2.0+build.4729.commit.a1b2c3d
CI/CD build number and git commit

Important: Build metadata is ignored in version precedence - 1.2.0+anything equals 1.2.0 for Capgo's update logic.

🔧 Pre-release Identifiers (-) - Development Channels

1.3.0-beta.1
Beta testing channel
1.3.0-hotfix.payment
Urgent fix branch
1.3.0-feature.newapi
Feature branch testing

Note: Pre-release versions have lower precedence - 1.3.0-beta.1 < 1.3.0

🎯 Hybrid Approach - Best of Both Worlds

1.3.0-rc.1+ui.redesign.20240315
Release candidate with UI metadata and timestamp

Real-World Semver Use Cases & Team Strategies

🚀 Startup / Fast Development

0.1.0 - First MVP release
0.2.0-beta.1 - New feature testing
0.2.0+ui.v2 - UI redesign metadata
1.0.0 - Production ready

Use 0.x.x for pre-1.0 development, metadata for design tracking

🏢 Enterprise / Regulated

2.1.0 → Quarterly release
2.1.1+sec.patch.cve2024 → Security patch with tracking
2.2.0-rc.1+audit.ready → Pre-audit release candidate

Strict semver with compliance metadata

🎮 Gaming / Creative Apps

1.0.0+season.winter.2024 → Seasonal content
1.1.0+event.halloween → Event-driven features
1.2.0+assets.hd.remaster → Asset updates

Creative metadata for content tracking

⚡ Hotfix Strategy

1.2.0 → Current production
1.2.1-hotfix.payment → Critical bug fix
1.2.1+urgent.20240315.1430 → Released with timestamp

Pre-release for testing, metadata for deployment tracking

🌍 Multi-Platform Strategy

1.3.0+ios.optimized → iOS-specific optimizations
1.3.0+android.material3 → Android design updates
1.3.0+web.pwa.ready → PWA capabilities

Same version, platform-specific metadata

🔄 CI/CD Integration

1.4.0-alpha.1+build.123 → Automated pre-release
1.4.0+deploy.staging.456 → Staging deployment
1.4.0+prod.final.789 → Production deployment

Automated versioning with deployment metadata

💡 Pro Tips:
  • Use build metadata (+) for tracking, timestamps, or cosmetic info that doesn't affect compatibility
  • Use pre-release identifiers (-) for development channels that need different update precedence
  • Combine both for maximum flexibility: 1.2.0-beta.1+ui.dark.theme.20240315
  • Remember: Capgo respects semver precedence rules, so plan your channel strategy accordingly

Important: Capgo uses strict semantic versioning

Unlike npm's semver implementation, Capgo follows the official SemVer specification strictly. npm's node-semver has known deviations from the spec, which can cause unexpected behavior.

For example, npm treats versions like 1.0.0-alpha.1 differently than the specification requires. See our reported issue and attempted fix that was never merged.

Valid Semantic Versions

1.0.0 ✓ Standard release
2.1.3-alpha ✓ Pre-release
1.0.0-beta.1 ✓ Pre-release with number
1.0.0+build.1 ✓ Build metadata
1.0.0-rc.1+build.1 ✓ Complete version

Invalid Semantic Versions

v1.0.0 ✗ Leading 'v' not allowed
1.0 ✗ Missing patch version
1.0.0.0 ✗ Too many version parts
1.0.0- ✗ Empty pre-release
1.0.0+ ✗ Empty build metadata

Capgo Update Behavior

✓ Patch updates are automatically applied (1.0.0 → 1.0.1)
✓ Minor updates require channel configuration (1.0.0 → 1.1.0)
✗ Major updates require native app store release (1.0.0 → 2.0.0)
⚠ Pre-release versions require explicit configuration

This tool follows the official Semantic Versioning specification unlike npm's implementation.