Configuration

stable

`package.json`

The package.json is used by pear and pear-runtime for application builds, delivery and updates.

`version`

In order for an OTA update to occur from pear-runtime, the package.json version field must be updated before deploying an application update.

`upgrade`

The upgrade field of the package.json should hold a pear:// link to seeded application:

Example:

{
  "name": "my-app",
  "version": "1.2.3",
  "upgrade": "pear://qxenz5wmspmryjc13m9yzsqj1conqotn8fb4ocbufwtz9mtbqq5o",
  ...
}

`package.json` `pear` field

Field source on GitHub

`pear.stage <Object>`

Staging configuration options.

`pear.stage.entrypoints <Array>`

Field source on GitHub

An array of entrypoint paths as staging start-points in addition to (deduped) main entry point.

`pear.stage.ignore <Array>`

Field source on GitHub

An array of file paths to ignore relative to package.json file.

Removed in Pear v3: it fed the pear stage JavaScript static-analysis / warmup phase (used mainly with the removed pear stage --compact flag), and pear stage no longer reads it. To control what is staged in v3, use pear.stage.ignore (or the pear.stage.only filter).

For pear ≤ v2.6.5 (named pear.stage.includes in ≤ v2.2.15): explicitly declared paths to include so files not recognized during pear stage's JavaScript static analysis — non-JavaScript files, or files required/imported via an expression like require(getPkgName()) — were still staged.

`pear.stage.defer <Array>`

REMOVED

Removed in Pear v3 together with the pear stage static-analysis (compact/warmup) phase it applied to; pear stage no longer reads it.

For pear ≤ v2.6.5: an array of dependency specifiers (as used with require/import) to declare as uninstalled optional or peer dependencies, so the static-analysis steps during pear stage (compact and warmup phases) would step over patterns like try { require('a-dep') } catch { fallback() }. pear stage printed skip hints for such dependencies.

Deprecated & removed fields

pear run was removed in Pear v3, along with the pear stage static-analysis / warmup phase. The fields below related to those. Verified against pear-state and the pear repo (v3): some are still deprecated (accepted but discouraged) while others are removed (no longer read by pear). Use Pear OTA (the pear-runtime module) instead.

`pear.name <String>`

Field source on GitHub

DEPRECATED

The name of the application. Overrides package.json name.

`pear.pre <String>`

REMOVED

Removed in Pear v3: the pear CLI no longer reads pear.pre.

A specifier such as ./path/to/pre.js or some-module, or pear-electron/pre.

The specifier must point to a script that executes prior to run-from-disk, prior to stage but not prior to run-from-link:

pear run ./some-dir - pre specifier executes prior
pear stage ./some-dir - pre specifier executes prior
pear run pear://some/link - pre specifier does not execute

When a pre script runs, it has a pipe available, obtained via pear-pipe. The pipe carries values encoded with compact-encoding any encoding (an encoded object, like JSON).

The first encoded object sent on pipe is the application configuration. The first response pear run or pear stage expects back on the script's pipe is another any-encoded configuration object. This lets the pre-script return a mutated configuration to the calling command.

The application then loads with that mutated configuration. With pear run, the mutated configuration is used at runtime. With pear stage, the mutated configuration overrides the application drive's manifest property.

To view any mutated configuration after staging, run pear info --manifest <link>.

`pear.routes <Object|String>`

Field source on GitHub

DEPRECATED

By default, pear run considers link pathnames to be entrypoints. This means pear run can execute any valid file staged to a Pear application. For example pear run pear://<key>/some/path.js would run some/path.js if it's valid. In that case Pear.app.route would contain /some/path.js and Pear.app.entrypoint would also contain /some/path.js.

To opt-out, and only allow top-level running set Pear.routes to . or / (it means the same thing):

{
  "pear": {
    "routes": "."
  }
}

This redirects all paths to the entrypoint.

In this case pear run pear://<key>/some/path.js would run the application entrypoint, Pear.app.route would contain /some/path.js while Pear.app.entrypoint would also be / - because Pear.app.route holds the raw pathname whereas Pear.app.entrypoint holds the mapped pathname.

The pear.routes configuration can also be an object where the keys are pathnames to map from, and the values are pathnames to map to:

{
  "pear": {
    "routes": {
      "/from/path": "/to/path"
    }
  }
}

When routes: "." is used in conjunction with pear-electron and pear-bridge waypoint option this enables in-app single-page-application routing.

`pear.unrouted <Array>`

Field source on GitHub

DEPRECATED

Array of paths to exclude from any routing rules in pear.routes.

`pear.assets <Object>`

Field source on GitHub

DEPRECATED

Asset declarations to fetch and store on disk on behalf of the application.

By convention namespaces (the object keys) should be used to describe the asset type.

In particular, Desktop applications should use the ui namespace to declare UI assets.

Asset objects take the form {link, name?, only?}.

link <String> - Required. The pear://<fork>.<length>.<key> link to fetch the assets from. The link must contain the full version (fork.length.key)
name <String> - Optional. Used in UI integration libraries such as pear-electron to determine bin name.
only <Array<String>> - Optional. An array of drive keys (pathnames) to exclusively fetch from the link with interpolation support for a special %%HOST%% keyword which is mapped to <platform>-<architecture> as in: linux-x64, darwin-arm64 etc. This is useful for asset builds per OS and CPU architecture.

Example:

{
  "pear": {
    "assets": {
      "ui": {
        "link": "pear://0.940.pkzpbccx8ojp4516p7abompuhyj5gcpqfux1s9e7e4zzcdhyhdto",
        "name": "Pear Runtime",
        "only": [
          "/boot.bundle",
          "/by-arch/%%HOST%%",
          "/prebuilds/%%HOST%%"
        ]
      }
    }
  }
}

The pear.assets config isn't only for User Interface runtimes, such as pear-electron. It applies to any assets that need to be placed on disk, such as large language model (LLM) assets, prebuilds, and other runtimes or binaries.

Declared assets are updated onto user machines passively while the application is running. Initial assets are fetched on first run by the embedded Pear OTA runtime; application installers and distributables prefetch them so they are in place before first run.

While assets can be declared directly on the pear.assets as described but when used in combination with pear.pre, installable modules such as pear-electron can also automatically define assets (and other configuration) on behalf of the application.

Assets are automatically stored in the platform folder. Use Pear.app.assets[namespace].path within the application to get the path to the asset. For example, Pear.assets.ui.path.

`pear.links <Object|Array>`

Field source on GitHub

DEPRECATED

Storing and managing Pear application links and domains.

links can be an object or an array. If it's an object, naming the key makes it easy to reference from Pear.config.links

By default in Pear apps, only requests to the sidecar host (127.0.0.1:9342) are allowed. Additional hosts and trusted keys must be added in pear.links to allow access.

Any Pear links that the app trusts to run (for example, as a worker) must be added and any HTTP or HTTPS domains that the app wants to access must also be added, including localhost.

Adding "https://*" or "http://*" will trust all domains based on their respective protocol.

Note that this is only for requests that the Pear app makes itself such as loading assets.

{
  // ...
  "pear": {
    // accessed at runtime using Pear.config.links[index], for example Pear.config.links[0] for pear://somePearKey
    "links": [
      "pear://somePearKey",
      "https://example.com"
    ]
    // OR
    // accessed at runtime using Pear.config.links.name, for example Pear.config.links.myWorker for myWorker
    "links": {
      "myWorker": "pear://somePearKey",
      "host": "https://example.com"
    }
  }
}

`pear.gui <Object>`

DEPRECATED

Graphical User Interface configuration options.

This is a namespace reserved for UI integration libraries to use for configuration options.

Defined per UI Integration library.

pear-electron pear.gui

`pear.stage.prefetch <Array>`

REMOVED

Removed in Pear v3. (In Pear v2 it was superseded by pear.stage.include, which is itself removed in v3.)

`pear.userAgent <string>`

REMOVED

Former default was a template literal that interpolated Pear.#state.id after the Pear prefix.

Removed in Pear v3; not read by pear. Use pear.gui.userAgent per pear-electron pear.gui

Configuration

`package.json`

`version`

`upgrade`

`package.json` `pear` field

`pear.stage <Object>`

`pear.stage.entrypoints <Array>`

`pear.stage.ignore <Array>`

`pear.stage.include <Array>`

`pear.stage.defer <Array>`

Deprecated & removed fields

`pear.name <String>`

`pear.pre <String>`

`pear.routes <Object|String>`

`pear.unrouted <Array>`

`pear.assets <Object>`

`pear.links <Object|Array>`

`pear.gui <Object>`

`pear.stage.prefetch <Array>`

`pear.userAgent <string>`

See also

On this page