Skip to main content

Package lifecycle

This guide covers how to develop, test, release, and run package versions in a group. Each device chooses which version to run; the group shares version records and defaults, but dev work does not automatically switch everyone else.

For the underlying design rationale and remaining roadmap items, see Package lifecycle design.

Overview​

Packages move through three promotion levels:

dev ──▶ beta ──▶ stable
PhaseHow it is createdSyncs to the group?Auto-activates on other devices?
devAutomatically when code is loaded from diskYes (version records sync)Never: each device must activate it, then follows its rebuilds until it switches back to a release
betaPromote in the package Versions UI or with peers packages promoteYesOnly on devices following stable,beta or *
stablePromote in the package Versions UI or with peers packages promoteYesOn devices using the default follow policy (stable)

The platform assigns versionTag (dev / beta / stable). Do not set it in definePackage() or contract definitions.

Metadata vs bundle bytes: PackageVersions (and related Files records) sync as group data. As soon as a version record arrives, this device also downloads that version’s package, routes, and UI bundles into the local chunk cache so later activation or UI load does not wait on a peer. A downloaded version is not automatically activated. The device waits until the current sync has applied every page and saved its watermark, then evaluates the final package state once using its pin, follow, and device-override rules. An incompatible bundle can fail to load without blocking metadata sync or preventing a newer version from arriving. If a peer cannot provide a bundle yet, metadata sync still succeeds and the missing chunks retry when another peer becomes available.

Rebuilding old bundles​

Old raw package bundles fail to load, including bundles with no tools. So do isolated packages whose manifest says guestApi: 2 or has no guestApi. Rebuild with definePackage() and peers-package. The package's status shows the rebuild instruction in the UI and in peers packages get <packageId>. If an update fails, the previously running version keeps serving, and other packages can still load.

If a package was built for a newer guest API, Peers instead reports that it “needs a newer version of Peers; update Peers to use it.” Update Peers before installing or loading that package.

Group defaults vs this device​

Two layers work together:

LayerWhere it livesPurpose
Group settingsIPackage record (synced)activePackageVersionId, versionFollowRange, followVersionTags for devices that follow the group
Device preferencesgroupDeviceVar per package (packagePrefs_${packageId})Local active version, pin state, and optional per-device follow overrides

By default, a device follows the group settings. Turning on Override on this device in Package Info makes the auto-update range and release channel local to that device.

Activation scope depends on the version and override state:

  • Activating a non-dev version with device override off updates the group active version.
  • Activating a non-dev version with device override on updates only this device.
  • Activating a dev version updates only this device, even when override is off.
  • Promoting the version this device is already running to a tag the group follows (default stable) advances the group active version under the same admin / override / not-pinned rules as Activate.
  • Automatic non-dev upgrades advance the group active version only when the device is following group settings and the current user is a group Admin or higher. Otherwise the upgrade remains local to the device.

Day-to-day development​

  1. Edit and build your package on disk (local path in Package settings). Before changing a beta or stable release, bump version in package.json. Reload refuses changed builds at a released number; bump, rebuild, and reload. A rebuild against a newer @peers-app/peers-sdk is a changed build even when your source is not, because the SDK's code is bundled into your package.
  2. Reload with Reload Package or peers packages reload <packageId>. A changed build at an unreleased number becomes the dev version on this device. An unchanged release creates no dev version and leaves the selection alone. A single reload still restarts the selected version; reload --all and page refresh leave unchanged packages running.
  3. Dev versions sync to the group as PackageVersions records, and other devices download those version files immediately, but they do not auto-switch to dev. That holds even for a new package whose only version is dev: other devices show it installed but not running ("Only a dev version is selected; activate it on this device to run it"), and leave its app out of their apps list, until someone activates it on that device. That includes your own other devices in your personal context. A device that activates a dev version keeps loading each rebuild of it, until it activates a beta or stable release, follows the group again, or the dev version is promoted.
  4. Open Packages → your package → Versions to see versions, hashes, and tags. Use Activate on a dev version to run it on this device without changing the group active version.

Each changed reload replaces the package's previous dev build in that group. Peers removes the replaced build's bundles 7 days after no version uses them; bundles a beta or stable version uses stay. Rebuilding an earlier commit brings its bundles back. See System Files.

A failed dev reload leaves old code running

A failed reload exits 1 and leaves the previous code running. Refused builds are not installed. An accepted dev build that fails to load stays selected, shows Update failed, and is tried again on restart. Check peers packages get <packageId> after a failure. Page refresh also checks package folders (on by default), but reports failures only in the developer console.

App icons in the apps list come from appNavs on the active PackageVersion (copied from the manifest generated from pkg.appNavs when bundles are installed). Startup sync always persists appNavs onto new versions, including when the group is currently on a stable build.

Routes and UI bundles reload when you change the active version on this device (no full page refresh required). Activating a version (Activate, Use Dev, Use Release, or peers packages activate) also loads it on this device's Runtime right away; you do not need to restart.

Releasing to the group​

  1. In Versions, choose Promote: dev → beta, dev → stable, or beta → stable (Admin). The version number stays the same. The release is signed when this device has the signing key; otherwise you see an unsigned-release warning.
  2. The result says what the group now runs. If it already selected this version, it uses the new channel. Otherwise promotion selects it automatically only when this device selected it, the group is not pinned, and the group follows the new channel (default stable). With a device follow override, that automatic selection applies only here.
  3. To select the release for the group explicitly, choose … and use for group or add --group below. This also makes this device follow that selection and keeps pin and update policies. If activation fails, the promotion is kept; retry activation.
peers packages get <packageId>  # find version ids
peers packages promote <packageVersionId> beta --group
peers packages activate <packageId> <packageVersionId> --group

Omit --group from promote to use automatic selection. When the group stays on another version, the result explains why and gives the activation command. Add -c <groupId> to work in a group.

If the group's selected version isn't on this device, get and Versions warn that it may not have synced yet. Wait for sync, or have an Admin select an available beta or stable version with activate ... --group. Reloading an unchanged release does not repair the group selection. See System: Packages.

Signed publish artifacts (local)​

Use the local-only System Desktop Tools v1 member publish-package to build distributable files on disk after you have a signing key and built bundles:

peers tools run publish-package '{"name":"Groceries","versionTag":"beta"}'

This writes (by default under <packageLocalPath>/dist/publish/):

  • A signed .peers-pkg.tar.gz containing the three bundles plus metadata
  • A latest-<tag>.json pointer with version, hashes, and author signature

Verification expectations before you trust an artifact:

  • Bundle file hashes in the pointer/payload match the files inside the tarball
  • packageAuthorSignature verifies against Packages.publishPublicKey
  • Semver in the pointer is what you intend to publish (remote auto-activation requires a newer semver than the installed follow candidate)

The Electron resolver binds publication to dataContext.userContext, uses the existing Self-level admission, and retains catalog ID 000peers0tool000publishpk. Headless hosts list its catalog row but cannot execute it. Its six string inputs (packageId, name, localPath, versionTag, version, outputDir) are optional in the public shape; the implementation requires either packageId or name.

Upload / hosting is a separate step. publish-package does not push to S3 or your updateUrl. Point Packages.updateUrl at a host only after you have uploaded the tarball and pointer yourself (or via your release tooling).

Permissions​

ActionTypical role
List packages, read versions and runtime stateReader
Create / update dev versions (disk reload)Writer
Import, create, clone, install, or uninstall a packageAdmin
Promote to beta or stableAdmin
Activate beta/stable for the groupAdmin
Activate dev or use device overrideLocal device choice
Pin a deviceLocal device choice

Personal space (no group) bypasses group role checks for your own packages. These are the System Packages access levels; the UI and peers packages both go through them.

Package Info Settings​

On the package Info tab, Auto-update range and Following edit group settings by default. Enable Override on this device to make those controls local to the current device.

  • Update URL — base URL where admin devices check for new signed releases (<updateUrl>/latest-<tag>.json). Edit on the Info tab and save with Save Changes. See Package lifecycle design for publishing and upload details.
  • Auto-update range - pinned (no auto-updates), patch, minor, or latest.
  • Following - stable or stable,beta.
  • Override on this device - when enabled, auto-upgrades and manual beta/stable activations affect only this device.

Pinned devices keep their active version even when new stable or beta versions sync in.

Multi-device testing​

To test with other devices before a stable release:

  1. Promote your build to beta in Versions.
  2. On each tester device, set Follow version tags to stable,beta (or *) if you want automatic beta upgrades, or Activate the beta version manually.
  3. Dev versions remain available for manual activation on any device but never auto-activate elsewhere.

Contracts and stable releases​

Contract maturity follows the package channel. New contract shapes can evolve freely in dev and beta builds. Stable releases freeze their provided contract versions when loaded. Use the source-controlled guard below to catch incompatible changes before releasing them.

If you need to extend a frozen contract after stable, increment the contract version and keep serving the old version's consumers: list it in alsoImplements when the new shape satisfies it (alsoImplements: [1]), or provide both versions explicitly. See Package contracts.

Freeze your contracts before a stable release​

A stable release freezes every contract version it provides. Record them in your package, so a later build can't change one by accident.

A freeze can't be undone. Run it only as part of a stable release. Until then (in development or beta), change your contracts in place: keep each addition optional so existing callers keep working, with no new version and no alsoImplements. Agents working on your package shouldn't run it unless you ask.

Before you promote a version to stable, run this in the package:

npx peers-package contract freeze

It writes frozen-contracts.json at the package root: each contract version the package provides, its shape, and the package version that froze it. Commit it with the release, and leave it as written: the file is generated, so the template's biome.json leaves it out of Biome (add "!frozen-contracts.json" to files.includes in a package made before that). From then on:

  • peers-package build fails when the build would change a frozen version's shape, and names the table, tool, observable, or event that changed. New descriptions are fine, and so is a tool's remoteAccessLevel.
  • npx peers-package contract freeze --check compares against the recorded versions without writing anything, for a test or CI. It passes if no file exists; run freeze to record a release.
  • At the next stable release, freeze adds the contract versions that release introduced and keeps the rest. If a frozen version changed, it writes nothing and fails.

Malformed contract definitions and duplicate contract identities fail the check and cannot be frozen. The check also compares shapes carried by alsoImplements against previously frozen versions.

To change a frozen contract, declare a new version, with alsoImplements naming the frozen one when the change is backwards compatible. A package may stop serving a frozen version, neither providing it nor listing it in alsoImplements; the check notes it, since that version's consumers lose this provider. To check the exact artifact you intend to release, build it with peers-package build, then run npx peers-package contract freeze --check --bundle dist/package.bundle.js. The check reads the generated manifest without running the provider code. Bundle paths are relative to your current directory, even with --root.