Versioning and compatibility

Two version streams matter to a partner package: the platform's lockstep @gauntlet/* version, and your package's own semver.

Current platform versions

Merchant apps in the field may run older platform versions than the current one. Your Appbrew contact can tell you which versions your target merchants are on.

Declaring compatibility

Declare the @gauntlet packages you import as peerDependencies with a floor, not exact pins and not wildcards:

{
  "peerDependencies": {
    "@gauntlet/state": ">=0.26.0",
    "@gauntlet/types": ">=0.26.0",
    "@gauntlet/analytics": ">=0.26.0"
  }
}

The floor is the oldest platform version you have actually tested against. Raise it when you start depending on newer platform APIs. That is a minor bump of your package at minimum.

0.27.0 is your real floor if you use the app extension host (app.actions.extend, app.components.register), the Result helpers, or implement a custom ICatalogProvider — the interface gained required methods in that release. See the 0.27.0 notes.

What platform bumps mean for you

The platform is versioned 0.x: expect that any platform release can contain breaking changes, and read the changelog for each one. When Appbrew asks you to validate against a new platform version:

1. Bump the whole @gauntlet set in your sample app to the new version.
2. Re-run your integration's flows (Testing your work).
3. If nothing changed for you, raise nothing; your floor still holds. If you adapted code, raise the floor and release.

Your own semver

• patch — fixes, no behavior or settings change.
• minor — new capabilities, new optional settings, raised platform floor.
• major — anything a merchant or Appbrew must act on: removed/renamed settings, changed block ids, changed event payloads.

Versions are immutable once published. There is no unpublish. Fix forward with a patch.