Ship your app

Touch and seed

pear touch mints a new pear:// link backed by a fresh Hypercore. pear seed keeps that core online so other peers can fetch updates from you. The output should look like this (your link will be different):

pear touch
# pear://qxenz5wmspmryjc13m9yzsqj1conqotn8fb4ocbufwtz9mtbqq5o

pear seed pear://qxenz5wmspmryjc13m9yzsqj1conqotn8fb4ocbufwtz9mtbqq5o

Leave pear seed running in its own terminal for the rest of the tutorial — without an active seeder, peers cannot download your build. In production, run pear seed on at least one always-online machine (a small VPS works) so updates keep flowing while developer laptops sleep. See hello-pear-electron 0. Touch and Seed.

Set the upgrade link

In a separate terminal, set the upgrade field in package.json to the link you just minted:

npm pkg set upgrade=pear://<your-pear-link>

After this, every distributable you build is opinionated about which pear:// link it pulls updates from.

Bump the version

pear-runtime only swaps the application drive when the new build advertises a higher version. If you forget this step, peers see your stage and do nothing:

npm version patch

This rewrites package.json (1.0.0 → 1.0.1) and creates a git tag. From now on, every release iteration starts with npm version patch.

Make distributables

A "distributable" is the platform-native installer — .app on macOS, .msix on Windows, .AppImage on Linux. Pear uses electron-forge with a single forge.config.js that configures makers for every platform, including Linux AppImage via pear-electron-forge-maker-appimage.

Install electron-forge and the makers you need

npm install --save-dev \
  @electron-forge/cli@^7.11.1 \
  @electron-forge/maker-dmg@^7.11.1 \
  @electron-forge/maker-msix@^7.11.1 \
  pear-electron-forge-maker-appimage@^2.0.0 \
  pear-electron-forge-maker-flatpak@^0.0.4 \
  pear-electron-forge-maker-snap@^0.0.10 \
  electron-forge-plugin-universal-prebuilds@^1.0.0 \
  electron-forge-plugin-prune-prebuilds@^1.0.0

Two electron-forge plugins matter:

• electron-forge-plugin-universal-prebuilds — bundles native prebuilds for every supported architecture.
• electron-forge-plugin-prune-prebuilds — trims the prebuilds you do not need for the current platform, keeping installers small.

Add scripts to package.json

Use one make entry point on every OS — Forge runs only the makers whose platforms match the host:

"scripts": {
  "start": "electron-forge start -- --no-updates",
  "package": "electron-forge package",
  "make": "electron-forge make"
}

Add forge.config.js

Copy or diff against the canonical hello-pear-electron forge.config.js rather than maintaining a separate inline copy in this tutorial. That file configures:

• Packager — build/icon, URL schemes from package.json name, optional macOS signing when MAC_CODESIGN_IDENTITY is set (notarization via KEYCHAIN_PROFILE).
• Makers — @electron-forge/maker-dmg (darwin), @electron-forge/maker-msix (win32), and Pear makers for Linux AppImage, Flatpak, and Snap.
• Hooks — preMake rewrites build/AppxManifest.xml version for MSIX; postMake moves Windows .msix artifacts into out/<AppName>-win32-<arch>/.
• Plugins — universal-prebuilds and prune-prebuilds.

You also need the template build/ assets (AppxManifest.xml, entitlements.mac.plist, icon set under build/icon/, and Linux Flatpak/Snap metadata). See the hello-pear-electron build/ tree.

Run the maker on your OS

npm run make builds distributables for the current host OS only. Run it on macOS, Linux, and Windows (or on CI runners per OS) when you need a multi-arch deployment directory.

npm run make   # .app + .dmg on macOS; .AppImage (+ Flatpak/Snap) on Linux; .msix on Windows

The output lands in out/PearChat-darwin-arm64/PearChat.app (or the matching path for your platform).

Build the deployment directory

You should run pear-build from outside the project folder (pear-build and the project folder must not be parent/child — see stage size increases). Each --<platform-arch>-app flag points at one make's output. For example:

cd ..
pear-build \
  --package=./pear-chat/package.json \
  --darwin-arm64-app ./pear-chat/out/PearChat-darwin-arm64/PearChat.app \
  --target pear-chat-1.0.1

The result is ./pear-chat-1.0.1/by-arch/darwin-arm64/app/... ready for the next step.

If you have makes from more than one platform — for example a Linux AppImage built on a colleague's machine — pass each one:

pear-build \
  --package=./pear-chat/package.json \
  --darwin-arm64-app ./pear-chat/out/PearChat-darwin-arm64/PearChat.app \
  --linux-x64-app ./pear-chat/out/PearChat-linux-x64/PearChat.AppImage \
  --win32-x64-app ./pear-chat/out/PearChat-win32-x64/PearChat.msix \
  --target pear-chat-1.0.1

pear-build assembles a Pear deployment directory from the per-platform makes. The layout must be as follows:

PearChat-1.0.1/
├─ package.json
└─ by-arch/
   └─ <platform-arch>/
      └─ app/

Stage and release the first version

pear stage syncs the deployment directory into the Hypercore behind your pear:// link. Always run --dry-run first and read the file-by-file diff:

pear stage --dry-run pear://<your-pear-link> ./pear-chat-1.0.1

Look for:

• Files you expect to ship — electron/, workers/, renderer/, package.json, node_modules/....
• No surprise additions — stray .DS_Store, editor swap files, secrets, the deployment directory itself.
• Sensible byte counts — if a file is suddenly 100 MB, something is wrong.

If the diff looks right, drop the --dry-run flag and run it for real:

pear stage pear://<your-pear-link> ./pear-chat-1.0.1

pear stage writes the new content into the Hypercore but does not advance the release pointer that peers actually poll. Until you advance it, peers cannot fetch anything new. Run pear release after every stage you want peers to fetch:

pear release pear://<your-pear-link>

Your first version is now published. Peers running an app with the same upgrade link will see it on their next poll.