elseware-electron-updater

Cloudflare R2 release publishing and secure self-updates for Electron applications. The package supports independent Windows, macOS, and Linux releases, multiple CPU architectures, differential downloads, verified full downloads, native installer launching, and opt-in app.asar patching.

Install

npm install elseware-electron-updater elseware-js

elseware-js supplies the shared Cloudflare R2 storage service used by release publishing. Both elseware-js and Electron are peers supplied by the consuming application.

Version 3 introduced Cloudflare R2 release-time storage. Version 4 switches runtime manifest discovery to a provider-neutral HTTP API.

Runtime

import { app } from "electron";
import {
  createElectronUpdater,
  registerUpdaterIpc,
} from "elseware-electron-updater/electron";

const updater = createElectronUpdater({
  appId: "com.example.desktop",
  manifestUrl:
    "https://api.example.com/api/v1/egl/release/latest/{platform}/manifest",
  enableAsarPatch: false,
});

registerUpdaterIpc(updater, {
  autoInstall: true,
  onInstalled: () => app.quit(),
});

The preload owns the public bridge:

import { contextBridge, ipcRenderer } from "electron";
import { createUpdaterBridge } from "elseware-electron-updater/electron/bridge";

contextBridge.exposeInMainWorld("updater", createUpdaterBridge(ipcRenderer));

The package does not include renderer UI or close the application after an installer is launched. The consuming application controls both behaviors. Downloads are resumable and progress includes transferred bytes, recovered bytes, speed, and estimated time remaining.

manifestUrl must contain {platform}. The endpoint returns the standard API envelope with a complete manifest in data; every installer, blockmap, patch, and patch-blockmap reference must include an absolute download URL. The runtime updater never reads an object-storage manifest or constructs a storage URL.

Release

Create elseware-updater.config.ts:

import { defineElectronBuilderUpdaterConfig } from "elseware-electron-updater";

export default defineElectronBuilderUpdaterConfig({
  appId: "com.example.desktop",
  r2: {
    bucketName: "egl-storage",
    publicBaseUrl: "https://updates.example.com",
    createBucket: false,
  },
});

Package name/version, native platform/architecture, installer path, optional app.asar, and the installed Electron version are inferred. The app.asar is read from the packaged output of the release target (mac-universal, win-unpacked, …), never from electron-builder's single-architecture staging copies. CLI flags override RELEASE_PLATFORM/RELEASE_ARCH, which override the native host.

npx elseware-electron-updater release validate
npx elseware-electron-updater release status --github
npx elseware-electron-updater release publish
npx elseware-electron-updater ci export-github-env

Add --require-absent to both release status and release publish when a workflow must reject every pre-existing <version>/<platform>/ target instead of resuming an incomplete upload. The publish command checks again and uses create-only writes for versioned objects to close the status-to-publish race.

The release command displays real-time aggregate R2 upload percentage and byte progress.

Publishing uploads immutable artifacts and version history before promoting the current platform manifest:

latest-win.yml
latest-mac.yml
latest-linux.yml
<version>/<platform>/release.yml
<version>/<platform>/<artifacts>

See architecture, manifest contract, runtime integration, and release workflow. The desktop rollout checklist covers app-owned CI.

Quality

npm run validate

The validation gate includes TypeScript source and test checks, Oxlint, Prettier, Knip, Vitest coverage, the ESM package build, publint, and tarball inspection.

Automated npm publishing

Pull requests targeting main run the complete validation suite and verify that the package version has not already been published. A successful merge to main repeats those checks and publishes through npm trusted publishing using GitHub OIDC, without storing a long-lived npm token.

Before enabling the workflow, configure npm's trusted publisher for the elseware-electron-updater package with the GitHub organization/repository and workflow filename .github/workflows/publish.yml. Create the npm-production GitHub environment, restrict it to main, and keep the version in package.json and package-lock.json synchronized. For example:

npm version patch --no-git-tag-version

The workflow refuses to publish a version that already exists on npm. Because this source repository is private, npm provenance is disabled while OIDC trusted publishing remains enabled. Remove --provenance=false if the repository becomes public.

test