Pear DocsMigrate from pear run to pear-runtime
Move off the deprecated pear run runtime and the global Pear API onto the pear-runtime library before pear run is removed at the end of June 2026.
pear run will be removed around the end of June 2026, along with the global Pear API. Migrate any app before then — once pear run is gone, an unmigrated app is at its end of life. There is no later recovery path.
Pear is evolving from a runtime baked into the Pear CLI (pear run) into an embeddable runtime library, pear-runtime, that integrates into any JavaScript environment. The CLI keeps the deployment commands (pear stage, pear build, pear provision, pear multisig); the runtime moves into your own process. This exposes peer-to-peer over-the-air updates and Bare workers to any JS project instead of locking them behind the CLI runtime.
This page is the operator how-to for moving an existing v1 app across. For the background on why this changed, see Runtime and languages.
Why this changed
Running every app on a single vendor-signed Electron build made shipping trivial — no OS signing keys, no native compiling — but it turned out to be fragile. The same build served many apps, so it could not be tested against each one before an update; OS updates, virus scanners, and process managers did not expect the non-standard runtime; and Dock/Tray branding was glitchy (a restarted app could show the Pear icon). Splitting the runtime into a library lets the CLI focus on deployment and productionization while your app owns a standard, testable runtime.
What changes
pear run (v1) | pear-runtime (v2) |
|---|---|
The CLI runtime launches the app and provides the ambient Pear global | You import pear-runtime in your own JS entrypoint |
pear stage deploys the app contents | pear build produces a build folder that is the deployment folder |
global.Pear.run() spawns workers | pear-runtime's run() method (backed by bare-sidecar, which bundles the native Bare runtime) |
Steps
Start from the boilerplate
The fastest migration is to scaffold a fresh Electron app that already has pear-runtime integrated, then move your code into it. Use the hello-pear-electron boilerplate:
git clone https://github.com/holepunchto/hello-pear-electron
cd hello-pear-electron
npm install
npm startMove your HTML, JS, CSS, assets, and dependencies into the template's structure. For a guided tour of where each piece goes, see Start from the hello-pear-electron template.
The build directory layout pear-runtime expects is produced by the pear build command (Pear v2.5.0+). Your package.json needs an upgrade field set to the application's pear:// link — see Configuration.
Remove the global Pear API
Any code using the Pear global must be removed and replaced. For Electron:
v1 global Pear API | v2 replacement |
|---|---|
global.Pear.run() | pear-runtime run() |
global.Pear.updates() | pear-runtime updated and updating events |
global.Pear.exit() | process.exit() |
global.Pear.exitCode | process.exitCode |
global.Pear.restart() | app.relaunch() (Electron) |
global.Pear.teardown() | graceful-goodbye or similar |
global.Pear.config.args | process.argv.slice(2) |
global.Pear.config.applink | require('./package.json').upgrade |
The remaining state on global.Pear.config is either self-referential (no longer relevant) or link parsing — replace link parsing with direct deep-link protocol handling.
Deploy with the production flow
pear-runtime pairs with the CLI's deployment commands rather than pear run. Use pear stage for internal previews, staging, and ephemeral variations — not for production. For production rigour, run pear stage, pear provision, and pear multisig in sequence:
pear provision(Pear v2.6.5+) strips interim operations by block-syncing from a source drive, reducing the disk space an app needs. Use it to create a prerelease.pear multisigmanages cryptographic cosigning: define the signers, define the quorum, then sign against the prerelease.
Until you migrate to this deployment flow, you risk losing write access if something happens to the machine holding the key — with no way to recover, because there is no way to push an update that switches to a new application link. Unlike all other Pear application drives, a pear multisig'd drive is not machine-bound, which removes that single point of failure. Use pear multisig for any serious production sign-off.
See Deploy your application for the full step-by-step release flow.
See also
pear-runtimereference — the module that replaces the globalpear runAPI.- Start from the hello-pear-electron template — clone-first tour of the boilerplate to migrate into.
- Deploy your application — the stage → provision → multisig production flow.
- Runtime and languages — why the runtime moved out of the CLI and into a library.
- Configuration — where the
upgradelink and entrypoint are declared.