Pear Docs

Distribute as a binary

Get a Pear app onto machines that don't have Pear: install it from a pear:// link, or hand out a signed binary that updates itself over the air with Pear OTA.

A Pear v3 app is a normal installed binary. It embeds Pear OTA (pear-runtime) and follows an upgrade link, so one binary can serve every future release. There is no bootstrap binary to compile: pear run was removed in v3, so a pear:// link no longer launches an app through an installed Pear. This guide gets that binary to users who don't have Pear, then covers what to do for each release after that.

The pear-appling template and its cmake-pear build were the v2 way to do this. Both are archived upstream, and the launcher they build bootstraps a pinned v2 platform rather than Pear v3, so don't start new work from them. If you have an appling-era app, see Migrate from pear run to Pear OTA.

Before you begin

Steps

  1. Version and build the release. For every release after the first, raise version in package.json with npm version patch (or the level you intend). An installed copy takes a release only if the release's version is higher than the copy's, so without a bump nobody receives it; see Version. Then make the distributables and assemble the deployment directory with pear build: see Build desktop distributables for an Electron app, or Build a CLI executable with pear make for a Bare command-line app (Pear 3.7.0 or later). Steps 3 and 4 of Deploy your application show the whole sequence.

  2. Publish it to the link your binaries follow. Each binary's upgrade link decides its release line, and pear stage appends only to the link you name, so release along the path that line expects; see Set the upgrade link and Release lines. Keep the link seeded so users can fetch it (Touch and seed). Whichever line it is, the link must carry a build made with pear build.

    • Stage link (developer builds): stage the deployment directory to it.
    • Provision link (internal preview): stage, then provision onto it.
    • Multisig link (production): stage, provision, then have a quorum of signers cosign and commit with Sign with multisig, after the one-time Set up multisig. Only pear multisig writes this drive, so staging and provisioning alone leave production binaries where they were.
  3. Give users the binary. Choose how they first get it:

    • From the link. Use the link your binaries follow. On a machine without Pear, run npx pear-install pear://<key>; it needs Node.js and npm, not Pear. On a machine with Pear, run pear install pear://<key>. pear install lists where each OS puts the result.
    • As a download. Publish the distributable from step 1 on GitHub Releases or a download page, signed first: macOS and Windows builds need vendor signing, pear make output isn't signed, and Windows MSIX updates need the same certificate on every build; see Build desktop distributables.
    • Through a store. Submit the build to the Mac App Store, Flathub, the Snap Store, or a mobile store; see Submit to app stores.
  4. Ship each later release the same way. Repeat steps 1 and 2, raising version each time. Installed copies poll their upgrade link and update themselves over the air, so users don't download a new binary. Confirm stage updates shows how to check that a release is visible. Two cases need more than the link:

    • Mac App Store builds keep the updater off, so each release is a new store submission; see Updates. Flathub and Snap installs still update over the air.
    • Mobile apps take only the Metro bundle over the air. The Bare worker bundle loads from the installed build on every launch, so changing it needs a new store build; see Two bundles, not one.

When this is the wrong tool

  • For users who already have Pear, pear install pear://<key> skips the download page entirely.
  • For a command-line app that never updates itself, pear make alone is enough, from Pear 3.7.0. It writes a standalone executable that needs no Node.js, Bare, or Pear, so you can skip the link, stage, and provision steps. Its output isn't signed for distribution, so sign it yourself. If the app should update itself, follow the steps above with pear make as step 1.
  • For mobile distribution, there is no standalone binary to hand out—mobile apps ship through the App Store and Google Play (or TestFlight / Play Console internal testing for pre-release builds). See Submit to app stores. For the raw Worklet/IPC primitive pear-mobile builds on, see Bare Kit.

Last updated on

Was this helpful?

On this page