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 the same way the main process will, right before handing them to the worker as positional arguments—the worker itself never touches package.json directly, it only reads Bare.argv:

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 config depends on before any PearRuntime instance or network activity exists—just the two fields, read the same way the main process will read them once it exists (next step but one).

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 this same workers/main.js, as a one-line require('hello-pear-worker'). The file below is that worker inlined, so you can see (and, if you vendor it as this guide does, edit) every line:

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') {
    try {
      await pear.ready()
      await pear.updater.applyUpdate()
      pipe.write('pear:updateApplied')
    } catch (err) {
      pipe.write('pear:updateFailed ' + (err.message || 'unknown error'))
    }
  } 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', or 'pear:updateFailed <message>' if the apply throws; 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

Three responsibilities live in the main process: deriving where the worker's config comes from, spawning it and relaying its events to the renderer, and exposing apply/relaunch 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 parses a fuller set of dev flags in its own parseArgs helper, but the updates contract itself is one boolean—default true, flipped by a --no-updates flag:

const { app, BrowserWindow, ipcMain } = require('electron')
const path = require('path')
const PearRuntime = require('pear-runtime')
const FramedStream = require('framed-stream')
const { isLinux, isMac, isWindows } = require('which-runtime')
const { name, productName, version, upgrade } = require('../package.json')

const appName = productName ?? name
const extension = isLinux ? '.AppImage' : isMac ? '.app' : '.msix'

// `--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')

applyUpdate() finds the staged build under by-arch/<host>/app/<name> and swaps it in for the app's own path on disk, so it needs to know that path. pear-chat's getAppPath() derives it per platform—self-contained, so it's worth quoting directly rather than re-deriving:

function getAppPath () {
  if (!app.isPackaged) return null
  if (isLinux && process.env.APPIMAGE) return process.env.APPIMAGE
  if (isWindows) return process.execPath
  return path.join(process.resourcesPath, '..', '..')
}

pear-chat also namespaces its storage directory to support a --storage dev flag for running multiple instances side by side—skip that here and just use Electron's own per-app data directory, which PearRuntime is happy to nest its own pear-runtime/ and app-storage/ subfolders under:

let updaterPipe = null

function sendToAll (name, data) {
  for (const win of BrowserWindow.getAllWindows()) {
    if (!win.isDestroyed()) win.webContents.send(name, data)
  }
}

function getUpdaterPipe () {
  if (updaterPipe) return updaterPipe

  const worker = PearRuntime.run(require.resolve('../workers/main.js'), [
    updates,
    version,
    upgrade,
    appName + extension,
    app.getPath('userData'),
    getAppPath()
  ])
  const pipe = new FramedStream(worker)

  worker.stdout.pipe(process.stdout)
  worker.stderr.pipe(process.stderr)

  function onData (data) {
    const message = data.toString()
    if (message === 'updating') sendToAll('pear:event:updating', 'updating')
    else if (message === 'updated') sendToAll('pear:event:updated', 'updated')
  }

  pipe.on('data', onData)

  // Without this, a crashed worker leaves a dead pipe cached and every later
  // getUpdaterPipe() hands it back.
  worker.once('exit', () => {
    pipe.removeListener('data', onData)
    updaterPipe = null
  })

  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, dir, and app. The returned duplex doubles as the worker's stdout/stderr streams and is wrapped in the same FramedStream framing the worker uses on its side for the IPC pipe; its 'updating'/'updated' strings are relayed to every window as pear:event:updating/pear:event:updated.

Nothing calls getUpdaterPipe() yet—do that once, after the window is up, so the worker actually starts:

app.whenReady().then(() => {
  createWindow()
  getUpdaterPipe()

  app.on('activate', () => {
    if (BrowserWindow.getAllWindows().length === 0) createWindow()
  })
})

With the worker running, two ipcMain.handle calls give the renderer an awaitable bridge into it. The first asks the worker to apply the staged update and waits for its acknowledgement before resolving—or rejecting, if the worker reports pear:updateFailed or the pipe closes because the worker died mid-apply:

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

  return new Promise((resolve, reject) => {
    function done (err) {
      pipe.removeListener('data', onData)
      pipe.removeListener('close', onClose)
      if (err) reject(err)
      else resolve()
    }

    function onData (data) {
      const message = data.toString()
      if (message === 'pear:updateApplied') done(null)
      else if (message.startsWith('pear:updateFailed')) {
        done(new Error(message.slice('pear:updateFailed '.length) || 'Update failed'))
      }
    }

    // A worker that dies mid-apply never replies; without this the promise
    // would stay pending forever.
    function onClose () {
      done(new Error('updater worker exited before replying'))
    }

    pipe.on('data', onData)
    pipe.once('close', onClose)
    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 settles once the worker's reply comes back, so the renderer gets a genuine "the swap finished" (or "it failed, here's why") 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. The highlighted lines above 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 (triggered by the swap applyUpdate() already performed) 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. This app's electron/preload.js only needs three properties: thin wrappers around the previous step's two handlers, plus a subscribe/unsubscribe helper for the relayed events. pear-chat's own electron/preload.js builds the same three properties into a larger contextBridge.exposeInMainWorld('bridge', { ... }) call that also covers its multi-worker and clipboard features; here's the minimal version:

const { contextBridge, ipcRenderer } = require('electron')

contextBridge.exposeInMainWorld('bridge', {
  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—applyUpdate() now rejects if the underlying ipcMain.handle call rejected, so await it inside a try/catch. 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 () => {
    banner.onclick = null // one apply in flight at a time
    try {
      await bridge.applyUpdate()
      await bridge.appAfterUpdate()
    } catch (err) {
      banner.textContent = 'Update failed: ' + err.message
    }
  }
})

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. Clearing banner.onclick before awaiting keeps a second click from firing a second pear:applyUpdate while the first is still in flight.

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. Watch the terminal npm start is running in (worker.stdout.pipe(process.stdout) sends the worker's own output there): this guide's vendored workers/main.js logs Application storage: <path> once pear.ready() resolves. If that line appears and the app window opens with no thrown error, the wiring is in place. Nothing here has talked to a peer yet.