Two jobs hiding in one feature
“Check for updates” is two jobs. The first is discovery: is a newer version out? The second is installation: download it, verify it and replace the running app. Frameworks give you the second job. The first is mostly your decision, and it is the place licensing meets updates, because a paid product usually gives new versions only to people who are entitled to them.
Choose the mechanism
| Mechanism | What it does | What you provide |
|---|---|---|
| Sparkle (macOS) | Checks an appcast, an RSS feed with extra fields, then downloads and installs | An appcast and an EdDSA key. Sparkle’s generate_appcast tool builds the feed from a folder of archives |
Electron autoUpdater |
Squirrel-based updates on macOS and Windows. On macOS the app must be signed | A feed URL in the format Squirrel expects, set with setFeedURL |
| Tauri updater | Checks endpoints, verifies a signature and installs | Endpoints that answer 204 when there is no update, or 200 with JSON, and a signature on every bundle |
| Your own check | Asks a releases endpoint and opens a download link | A comparison, a prompt and an installer the user runs |
Sparkle’s documentation recommends signing update archives with EdDSA (Ed25519) and keeping the signing keys off the machine that hosts the files, so that a compromised web server cannot push a bad update. Tauri says its signature check cannot be disabled. Electron’s documentation says an update on macOS requires a signed application. These are good reasons to use the framework’s installer for installation, and to ask your own endpoint only for entitlement and version information when licensing is involved.
Clavem’s releases endpoint is a discovery and download service. It returns its own JSON, not a Sparkle appcast, a Squirrel feed or a Tauri response, so with those frameworks use a small adapter you control, or use it as an entitlement check before you hand over a link.
Ask the endpoint
curl "https://clavem.io/v1/releases/75/latest?platform=macos" \
-H "X-License-Key: YOUR-LICENSE-KEY"
The response, as documented:
{
"version": "3.2.1",
"notes": "Fixes a crash when importing large files.",
"published_at": "2026-11-19T08:30:00.000Z",
"files": [
{ "id": 12, "filename": "Inkwell-3.2.1.dmg", "size": 50540748, "platform": "macos", "url": "https://clavem.io/d/12?exp=1795050000&sig=..." }
]
}
Behaviors worth knowing, each checked against the live service or its documentation:
- No release yet. The demo product has none published, and the endpoint answers HTTP 404 with
{"error":{"code":"not_found","message":"This product has no published release yet."}}. Treat 404 as “no update”, not as an error. - No key. Without a license key, the response carries
versionandpublished_atbut nonotesorfiles. The app can say a version exists without handing it out. - Browser and extension calls. A preflight request from another origin returned HTTP 204, allowing the header
X-License-Keyand the methodsGETandOPTIONS. - Separate rate limit. The endpoint allows 120 requests per 60 seconds per IP address, counted apart from the License API, so update checks do not use up your validation budget.
- Download links expire. The
urlis signed and works for one hour. Request a fresh one when the user clicks, not when the app starts.
Latest means most recently published
“Latest” is the release published most recently, not the highest version number. If you publish 3.3.0 and then a backport 3.2.4, the backport becomes the latest. A customer on 3.2.3 is offered 3.2.4 and never hears of 3.3.0, and a customer on 3.3.0 sees no update at all. If you ship from several branches, publish in version order, or keep branches in separate products. To pull a bad build, unpublish it, and the previously published release becomes the latest again.
Compare versions correctly
The docs’ sample uses localeCompare with numeric sorting. It handles 3.10.0 against 3.9.0, but it has a bug with pre-releases. I ran both approaches on the same pairs:
| Left | Right | Numeric string sort says | Semantic versioning says |
|---|---|---|---|
| 3.10.0 | 3.9.0 | newer | newer |
| 4.0.0-beta.2 | 4.0.0 | newer (wrong) | older |
| 4.0.0-beta.10 | 4.0.0-beta.2 | newer | newer |
| 4.0.0-rc.1 | 4.0.0-beta.9 | newer | newer |
| 2026.11 | 2026.9 | newer | not a semantic version |
The second row is the dangerous one. A customer on the beta would never be offered the final release, and a customer on the final release could be offered the beta. Compare the three core numbers first, then pre-release identifiers, with a release outranking its own pre-releases. Return nothing, not a guess, for strings you cannot parse. The function I used:
function parse(v) {
const m = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/.exec(v.trim());
return m ? { core: [+m[1], +m[2], +m[3]], pre: m[4] ? m[4].split('.') : [] } : null;
}
export function compare(a, b) {
const x = parse(a), y = parse(b);
if (!x || !y) return null;
for (let i = 0; i < 3; i++) if (x.core[i] !== y.core[i]) return x.core[i] - y.core[i];
if (!x.pre.length || !y.pre.length) return y.pre.length - x.pre.length;
for (let i = 0; i < Math.max(x.pre.length, y.pre.length); i++) {
const p = x.pre[i], q = y.pre[i];
if (p === undefined) return -1;
if (q === undefined) return 1;
const pn = /^\d+$/.test(p), qn = /^\d+$/.test(q);
if (pn && qn) { if (+p !== +q) return +p - +q; }
else if (pn !== qn) return pn ? -1 : 1;
else if (p !== q) return p < q ? -1 : 1;
}
return 0;
}
Clavem accepts versions of up to 64 characters made of letters, digits, dots, dashes, plus signs and underscores, so a calendar version such as 2026.11 is possible. If you use one, write a comparison for your own format. Do not mix formats across releases.
Cadence and failure behavior
| Decision | Recommendation |
|---|---|
| When to check | At launch if the last check is over a day old, then about daily |
| Blocking | Never. Run it in the background and let the app start |
| Timeout | A few seconds. An update check is not worth a frozen window |
| Failure | Stay silent, try again at the next interval |
| Jitter | Add a random offset so a million launches do not align on the hour |
| Frequency cap | Remember the version you last told the user about |
The jitter and the cap are cheap and prevent most annoyance. The cap belongs in the update prompts article.
Entitlement: who gets the file
With a valid license key, the response includes files and notes. With no key, or a key that is not valid for the product, it reports the version and the date only. So the app can tell the difference between “up to date” and “an update exists, and this license cannot download it”.
Some products promise “updates for one year” with a license that never expires. Clavem’s expiry model is a single date, so the simplest way to do this is in the app: read the created_at of the license from a validate response and the published_at of the release, and offer the download only if the release was published within your window. I ran this rule with dates, and it correctly allowed a June 2027 release and refused a December 2027 one for a license created in November 2026. The rule lives in your app, so state it in your terms.
Doing this with Clavem
Clavem stores your release files, gives each a signed download link and serves the endpoint described above, with no bandwidth fee. See the releases documentation for the upload limits and the full response. The installation step stays with your framework: Sparkle, Squirrel or the Tauri updater.
Questions
How often should a desktop app check for updates?
At launch if the last check was more than a day ago, and then about once a day while the app stays open. Do not block startup on the answer, set a short timeout of a few seconds, and stay quiet when the check fails.
Why does my app think a beta is newer than the final release?
A numeric string sort treats 4.0.0-beta.2 as greater than 4.0.0. Under semantic versioning a pre-release is older than its release. Parse the version and compare the core numbers first, then the pre-release parts.
Should the license key go in the update URL?
No. Send it in a request header so it stays out of server logs, referrer headers and shared screenshots. Clavem's releases endpoint reads the X-License-Key header.