Versioning
Four version numbers, and which to change when.
Four version numbers are in play, and they are easy to confuse because three of them live in the same file.
| Number | Whose | Answers |
|---|---|---|
version in manifest.json | Your plugin's | Which release of your plugin is this? |
apiVersion in manifest.json | The plugin protocol | Which plugin contract does it speak? |
minAppVersion in manifest.json | Fluxta's | What is the oldest app that can run it? |
@fluxta/sdk in package.json | The SDK's | Which library are you building against? |
version
An ordinary SemVer version that you own. Bump it for every release; that is what makes Fluxta offer an update.
A published version is permanent. Its number is never reused, even if the release is withdrawn, and users are always offered the newest published version with no way to pick an older one. A broken release is fixed by publishing a higher version, never by pulling the broken one.
Practically: keep the number moving forward, and never re-publish a number already used.
apiVersion
The version of the contract between plugins and Fluxta: what the manifest can declare, and what the SDK and the app say to each other.
It is currently 1, and 1 is the only accepted value. It is not a range
and not a minimum. A manifest declaring anything else fails to load with
UNSUPPORTED_API_VERSION, and a manifest omitting it fails with MISSING_FIELD.
In both cases the plugin does not appear at all.
This number is not chosen; it is copied from whatever the current contract is. It changes only when the contract itself changes incompatibly, which has not happened yet.
minAppVersion
Your declaration of the oldest Fluxta that can run this plugin. Required to publish, and it must be valid SemVer.
Raise it when the plugin starts relying on something an older app does not have. When unsure, the safe answer is the version being developed against.
Compatibility is enforced by the app, not by the Marketplace. A plugin needing a newer Fluxta than the user has stays visible with its requirement shown, rather than quietly vanishing, so the user can see why they cannot install it.
An update is different. A user who already has the plugin, on a Fluxta
older than the new version's minAppVersion, keeps the version they have and
is not offered the update — the Marketplace tells them why instead. Once they
update Fluxta, the update is offered as usual.
fluxta validate also checks this against a running Fluxta, if one is
discoverable, and warns with HOST_VERSION_TOO_OLD when the declaration is
higher than the app on the same machine.
The SDK version
@fluxta/sdk has its own SemVer line, and it is not the same number as
apiVersion. A new SDK major is about the TypeScript API a plugin is written
against; apiVersion is about what Fluxta accepts.
Upgrading the SDK does not change the manifest. Adding a manifest field does not require a new SDK. The two move independently.
Which one do I change?
| You did this | Change this |
|---|---|
| Fixed a bug, added a feature, anything at all | version |
| Started using a newer Fluxta capability | version and minAppVersion |
Upgraded @fluxta/sdk | version — and minAppVersion if the new SDK needs a newer app |
| Nothing — the contract changed under you | apiVersion, when a new one is announced |
Stored settings
Version numbers do not protect data a plugin already saved. Settings persist across updates, so a user upgrading from 1.0 to 2.0 hands the new code whatever 1.0 wrote.
Nothing migrates that automatically. Read stored settings defensively, treat missing and unexpected fields as normal, and where the shape has to change, prefer adding an optional field over repurposing an existing one.