Integrate Pear OTA into an existing Electron app

Install the dependencies

pear-runtime is the embeddable Pear OTA library. The updater worker added two steps from now is a copy of upstream's hello-pear-worker, so its own dependencies have to resolve from your project too—and your main process needs framed-stream (to frame the worker pipe) and which-runtime (to branch the relaunch by platform):

npm install pear-runtime hyperswarm corestore framed-stream graceful-goodbye bare-path bare-storage which-runtime

Nothing else changes yet—your app has no upgrade link and no PearRuntime instance until the later steps wire them up.

First-time package.json setup

Mint a link to develop against. pear touch creates a fresh pear:// link backed by its own Hypercore:

pear touch
# pear://qxenz5wmspmryjc13m9yzsqj1conqotn8fb4ocbufwtz9mtbqq5o

Add version and upgrade to package.json. pear-runtime only swaps in an update when a build's version is higher than the one currently installed, and upgrade is the link it polls:

{
  "version": "1.0.0",
  "upgrade": "pear://qxenz5wmspmryjc13m9yzsqj1conqotn8fb4ocbufwtz9mtbqq5o",
  ...
}

Both fields are required before anything in the following steps can run: the main process reads them straight out of package.json and hands them to the worker as positional arguments, and upgrade is a required PearRuntime option.

Before wiring the runtime up for real, it's worth confirming the two fields resolve the way pear-runtime expects them to. Starting from the example app's own package.json (already at 1.0.0, with no upgrade field yet):

npm pkg set version=1.0.0 upgrade=pear://qxenz5wmspmryjc13m9yzsqj1conqotn8fb4ocbufwtz9mtbqq5o

Then a small script that reads them back exactly the way the updater worker's argv() will—via require('./package.json'):

const { version, upgrade } = require('./package.json')
console.log('version:', version)
console.log('upgrade:', upgrade)

Run it with Node:

node check-config.js

It prints both fields back:

version: 1.0.0
upgrade: pear://qxenz5wmspmryjc13m9yzsqj1conqotn8fb4ocbufwtz9mtbqq5o

That's the entire contract the updater worker depends on—no PearRuntime instance, no network, just the two fields it reads out of package.json.

Add a dedicated updater worker

Run the updater in its own Bare worker, separate from whatever worker (if any) already carries your app's peer-to-peer logic. Reshape into a production app uses the same split for exactly this reason: it "embeds the pear-runtime OTA updater in its own Bare worker, so update traffic never blocks the chat." The update poll, the Corestore replication it drives, and the swarm connection it maintains all happen off to the side—your main worker and your renderer never wait on any of it.

Every hello-pear-* template ships the same workers/main.js. The file below is the canonical body, shared verbatim across all of them:

const PearRuntime = require('pear-runtime') // pear-runtime on desktop; pear-mobile on mobile
const Hyperswarm = require('hyperswarm')
const Corestore = require('corestore')
const goodbye = require('graceful-goodbye')
const FramedStream = require('framed-stream')
const path = require('bare-path')
const dir = require('bare-storage')
const { isBareKit } = require('which-runtime')

// mobile doesn't have the executable path (argv[0])
// and the worker entry path (argv[1]) in the workers argv's
// ... to reuse the same worker in all platforms this logic is needed
const argv = (index) => Bare.argv[index + (isBareKit ? 0 : 2)]

const updaterConfig = {
  updates: argv(0) !== 'false',
  version: argv(1),
  upgrade: argv(2),
  name: argv(3),
  dir: argv(4) || dir.persistent(), // argv[4] is undefined in mobile
  app: argv(5) // argv[5] is undefined in mobile
}

const pipe = new FramedStream(Bare.IPC)
const store = new Corestore(path.join(updaterConfig.dir, 'pear-runtime', 'corestore'))
const swarm = new Hyperswarm()
const pear = new PearRuntime({ ...updaterConfig, swarm, store })

pear.updater.on('error', console.error)
if (updaterConfig.updates !== false) {
  swarm.on('connection', (connection) => store.replicate(connection))
  swarm.join(pear.updater.drive.core.discoveryKey, {
    client: true,
    server: false
  })
}

console.log('Application storage:', pear.storage)

pear.updater.on('updating', () => pipe.write('updating'))
pear.updater.on('updated', () => pipe.write('updated'))
pear.on('minver-required', () => pipe.write('minver-required')) // for mobile store update notification

goodbye(async () => {
  await swarm.destroy()
  await pear.close()
  await store.close()
})

pipe.on('data', async (data) => {
  const message = data.toString()
  if (message === 'pear:applyUpdate') {
    await pear.ready()
    await pear.updater.applyUpdate()
    pipe.write('pear:updateApplied')
  } else console.log(message)
})

pipe.write('Hello from worker')

Reading it top to bottom: argv() reads the positional arguments the host process passes it (with an index offset for Bare Kit / mobile, where argv[0] and argv[1] aren't the executable and worker paths the way they are under plain Bare). Those six arguments become the PearRuntime options—updates, version, upgrade, name, dir, and app. The worker builds its own Corestore and Hyperswarm, hands them to PearRuntime via the store/swarm options, and—unless updates is false—joins the update drive's discovery key so it can replicate. It relays updating, updated, and minver-required over the IPC pipe as plain strings. The one message it acts on coming back is 'pear:applyUpdate'—on receipt it awaits pear.updater.applyUpdate() and replies 'pear:updateApplied'; anything else it just logs.

Copy this file into your project as workers/main.js (or wherever your build already spawns workers from), unchanged. It takes its entire configuration from Bare.argv, so the only thing you customize is what the host process passes it—that's the next step.

Wire the main process

Two responsibilities live in the main process: spawning the updater worker with the right configuration, and relaying the worker's events to the renderer over IPC.

The configuration comes from two places. version, upgrade, name, and productName are read straight out of package.json (the fields set two steps ago); updates is a runtime flag, so the main process parses it off its own argv. pear-chat does it in a parseArgs helper, but the whole contract is one boolean—default true, flipped by a --no-updates flag:

const { name, productName, version, upgrade } = require('../package.json')

// `--no-updates` is what the "Run it locally" step below passes to boot the
// app with the updater constructed but never swarming.
const updates = !process.argv.includes('--no-updates')

With those in hand, pear-chat's electron/main.js spawns the worker and relays its events:

// Updater worker. pear-runtime + the updater swarm/store run in bare, mirroring
// hello-pear-electron. The main process only spawns it and relays messages.
function getUpdaterPipe () {
  if (updaterPipe) return updaterPipe
  const dir = getStorageDir()
  const appPath = getAppPath()
  const extension = isLinux ? '.AppImage' : isMac ? '.app' : '.msix'
  const worker = PearRuntime.run(require.resolve('..' + updaterSpecifier), [
    updates,
    version,
    upgrade,
    productName + extension,
    dir,
    appPath
  ])
  const pipe = new FramedStream(worker)

  function onData (data) {
    const message = data.toString()
    if (message === 'updating') sendToAll('pear:event:updating', 'updating')
    else if (message === 'updated') sendToAll('pear:event:updated', 'updated')
  }
  function onStderr (data) {
    process.stderr.write(data)
  }
  function onBeforeQuit () {
    pipe.destroy()
  }
  pipe.on('data', onData)
  worker.stderr.on('data', onStderr)
  worker.once('exit', () => {
    app.removeListener('before-quit', onBeforeQuit)
    pipe.removeListener('data', onData)
    worker.stderr.removeListener('data', onStderr)
    updaterPipe = null
  })
  app.on('before-quit', onBeforeQuit)
  updaterPipe = pipe
  return pipe
}

PearRuntime.run() is a static method, so the main process calls it directly without needing its own PearRuntime instance—it only needs the worker's entrypoint and the positional arguments the worker's argv() expects, in order: updates, version, upgrade, name (here productName plus a per-platform extension, since applyUpdate() uses it to find the bundled app on disk), dir, and app. The returned duplex is wrapped in the same FramedStream framing the worker uses on its side, and its 'updating'/'updated' strings are relayed to every window as pear:event:updating/pear:event:updated.

Two ipcMain.handle calls give the renderer an awaitable bridge into that worker. The first asks the worker to apply the staged update and waits for its acknowledgement before resolving:

ipcMain.handle('pear:applyUpdate', () => {
  const pipe = getUpdaterPipe()

  return new Promise((resolve) => {
    function onData (data) {
      if (data.toString() === 'pear:updateApplied') {
        pipe.removeListener('data', onData)
        resolve()
      }
    }

    pipe.on('data', onData)
    pipe.write('pear:applyUpdate')
  })
})

The renderer never calls pear.updater.applyUpdate() itself—it can't; the PearRuntime instance lives in the worker, not the renderer or even the main process. Instead, pear:applyUpdate writes 'pear:applyUpdate' down the pipe and only resolves its promise once the worker's 'pear:updateApplied' reply comes back, so the renderer gets a genuine "the swap finished" signal to act on.

The second handler is what actually restarts the app once the swap is done:

ipcMain.handle('app:afterUpdate', () => {
  if (isLinux && process.env.APPIMAGE) {
    app.relaunch({
      execPath: process.env.APPIMAGE,
      args: [
        '--appimage-extract-and-run',
        ...process.argv.slice(1).filter((arg) => arg !== '--appimage-extract-and-run')
      ]
    })
  } else if (!isWindows) {
    app.relaunch()
  }
  app.quit()
})

Relaunching a packaged .AppImage on Linux needs execPath pointed at the APPIMAGE environment variable and the --appimage-extract-and-run flag—plain app.relaunch() on its own restarts the temporary FUSE-mounted copy, not the file that was just updated on disk. Lines 235–242 handle that case. Everywhere else, app.relaunch() is enough, except on Windows: this code quits without an explicit relaunch call there, leaving the MSIX-installed binary's own restart path to bring the app back. Either way, app.quit() runs unconditionally last.

Expose applyUpdate and appAfterUpdate on the preload bridge

The renderer runs with contextIsolation: true, so it never touches ipcRenderer directly—the preload script is the only bridge across. pear-chat's electron/preload.js exposes the two handlers from the previous step, plus a subscribe/unsubscribe helper for the relayed events (the excerpt is the middle of one contextBridge.exposeInMainWorld('bridge', { ... }) call):

  applyUpdate: () => ipcRenderer.invoke('pear:applyUpdate'),
  appAfterUpdate: () => ipcRenderer.invoke('app:afterUpdate'),
  onPearEvent: (name, listener) => {
    const wrap = (evt, eventName) => listener(eventName)
    ipcRenderer.on('pear:event:' + name, wrap)
    return () => ipcRenderer.removeListener('pear:event:' + name, wrap)
  },

bridge.applyUpdate() and bridge.appAfterUpdate() are thin ipcRenderer.invoke() wrappers around the two handlers from the previous step. bridge.onPearEvent(name, listener) subscribes to pear:event:<name>—call it with 'updating' and 'updated'—and returns an unsubscribe function, so a component can clean up its listener when it unmounts.

Wire a UI affordance (optional)

Nothing requires a visible update indicator—updates apply whenever you call bridge.applyUpdate(), on whatever schedule fits your app. Most apps show something anyway. A minimal version, in a renderer script (the example app ships an empty <div id="update-banner" hidden> for it to drive), built on the bridge from the previous step:

const banner = document.getElementById('update-banner')

bridge.onPearEvent('updating', () => {
  banner.textContent = 'Downloading update…'
  banner.hidden = false
})

bridge.onPearEvent('updated', () => {
  banner.textContent = 'Update ready'
  banner.hidden = false
  banner.onclick = async () => {
    await bridge.applyUpdate()
    await bridge.appAfterUpdate()
  }
})

updating fires as soon as a newer version starts downloading; updated fires once it has finished staging and is safe to apply. Waiting for a click—rather than applying the moment updated fires—avoids swapping the app out from under a user mid-task. Apply whenever suits your app, including immediately.

Run it locally

Start the app with updates disabled, to confirm everything constructs cleanly before any network activity happens:

npm start -- --no-updates

That flag is the one the main process parses in the Wire the main process step. The updater worker still runs new PearRuntime({ ...updaterConfig, swarm, store })—it just never joins the swarm, because updates: argv(0) !== 'false' evaluates to false. If the worker logs Application storage: <path> and the app window opens with no unhandled error, the wiring is in place. Nothing here has talked to a peer yet.