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
| Phase | How it is created | Syncs to the group? | Auto-activates on other devices? |
|---|---|---|---|
| dev | Automatically when code is loaded from disk | Yes (version records sync) | Never: each device must activate it, then follows its rebuilds until it switches back to a release |
| beta | Promote in the package Versions UI or with peers packages promote | Yes | Only on devices following stable,beta or * |
| stable | Promote in the package Versions UI or with peers packages promote | Yes | On 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:
| Layer | Where it lives | Purpose |
|---|---|---|
| Group settings | IPackage record (synced) | activePackageVersionId, versionFollowRange, followVersionTags for devices that follow the group |
| Device preferences | groupDeviceVar 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
- Edit and build your package on disk (local path in Package settings). Before changing a beta or stable release, bump
versioninpackage.json. Reload refuses changed builds at a released number; bump, rebuild, and reload. A rebuild against a newer@peers-app/peers-sdkis a changed build even when your source is not, because the SDK's code is bundled into your package. - 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 --alland page refresh leave unchanged packages running. - Dev versions sync to the group as
PackageVersionsrecords, 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. - 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 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
- 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.
- 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. - To select the release for the group explicitly, choose … and use for group or add
--groupbelow. 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.gzcontaining the three bundles plus metadata - A
latest-<tag>.jsonpointer 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
packageAuthorSignatureverifies againstPackages.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
| Action | Typical role |
|---|---|
| List packages, read versions and runtime state | Reader |
| Create / update dev versions (disk reload) | Writer |
| Import, create, clone, install, or uninstall a package | Admin |
| Promote to beta or stable | Admin |
| Activate beta/stable for the group | Admin |
| Activate dev or use device override | Local device choice |
| Pin a device | Local 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 -
stableorstable,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:
- Promote your build to beta in Versions.
- On each tester device, set Follow version tags to
stable,beta(or*) if you want automatic beta upgrades, or Activate the beta version manually. - 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 buildfails 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'sremoteAccessLevel.npx peers-package contract freeze --checkcompares against the recorded versions without writing anything, for a test or CI. It passes if no file exists; runfreezeto record a release.- At the next stable release,
freezeadds 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.
Related
- Development and production groups — separate test data, release propagation, and current setup limits
- Getting started — isolated package structure and build basics
- Package contracts — versioned interfaces, validation,
alsoImplements - Package lifecycle design — design doc, shipped vs planned work
- Variables (pvars) —
groupDeviceVarand other persistent variable scopes