# Pear



import { Tabs, Tab } from 'fumadocs-ui/components/tabs'
import { Cards, Card } from 'fumadocs-ui/components/card'

Pear is an installable peer-to-peer runtime, development, and deployment platform. Build, share, and extend unstoppable, zero-infrastructure P2P apps for mobile, desktop, and terminal.

Welcome to the Internet of Peers.

  *– Holepunch, the P2P Company*

Install Pear [#install-pear]

Get the [`pear`](/reference/pear/cli) CLI from **[install.pears.com](https://install.pears.com)**:

<Tabs items={['curl (macOS / Linux)', 'irm (Windows)', 'npx', 'docker']}>
  <Tab value="curl (macOS / Linux)">
    ```sh
    curl https://install.pears.com/pear.sh | sh
    ```
  </Tab>

  <Tab value="irm (Windows)">
    ```powershell
    irm https://install.pears.com/pear.ps1 | iex
    ```
  </Tab>

  <Tab value="npx">
    ```sh
    npx pear
    ```
  </Tab>

  <Tab value="docker">
    ```sh
    docker run -it --rm tetherto/pear
    ```
  </Tab>
</Tabs>

Follow the `PATH` instructions the installer prints, then run `pear` directly. Full details, upgrade instructions, and the npm-global alternative are on [Install & upgrade](/reference/pear/cli#install). The [`tetherto/pear`](https://hub.docker.com/r/tetherto/pear) image runs Pear inside Ubuntu with `pear` and `pear-install` ready to go—a low-risk way to try out Pear apps without installing anything locally.

Boilerplates & key docs [#boilerplates--key-docs]

Starter paths and the most relevant docs for building and shipping a Pear desktop app (macOS / Linux / Windows):

<Cards>
  <Card href="/getting-started" title="Getting started" description="Type-along chat, persistence, then ship and update." />

  <Card href="/getting-started/from-a-template/start-from-hello-pear-electron" title="hello-pear-electron template" description="Clone the boilerplate and learn your way around it, then add a feature end to end." />

  <Card href="/getting-started/from-a-template/start-from-hello-pear-bare" title="hello-pear-bare template" description="Clone the terminal boilerplate and learn your way around it, then ship it as a standalone binary." />

  <Card href="/explanation/pear-desktop-architecture" title="Pear desktop architecture" description="How Electron, Bare workers, storage, and OTA fit together." />

  <Card href="/explanation/deployment-releasing-apps-p2p" title="Deployment - Releasing Apps P2P" description="Stage → provision → multisig and release lines." />

  <Card href="/explanation/use-bare-standalone" title="Using Bare on its own" description="Use Bare—the runtime under Pear—on its own as an embeddable, cross-platform JavaScript runtime, without the peer-to-peer platform." />
</Cards>

The upstream Electron template used by the team is `holepunchto/hello-pear-electron` on GitHub (clone there for a ready-made repo; use the links above for explanations and procedures).

How-to guides by task [#how-to-guides-by-task]

Goal-oriented recipes, grouped by task. **Releasing and distributing your app** lives here too—shipping and updating is a how-to, spanning [manual deployment](/how-to/operate-an-app/manual-deployment), [multisig](/how-to/operate-an-app/multisig), [build & package](/how-to/operate-an-app/build-and-package), and [CI](/how-to/operate-an-app/github-actions); the why is in [Release pipeline](/explanation/deployment-releasing-apps-p2p).

<Cards>
  <Card href="/how-to/connect-to-peers" title="Connect to peers" description="Dial a peer by key with HyperDHT, join topics with Hyperswarm, and host multiple rooms in one app." />

  <Card href="/how-to/store-and-replicate" title="Store and replicate" description="Persist and replicate with Hypercore, manage many cores with Corestore, and share databases with Hyperbee." />

  <Card href="/how-to/blind-peering" title="Blind peering" description="Keep data available when peers go offline, and add blind peering to a chat app." />

  <Card href="/how-to/manage-identity" title="Manage identity" description="Create a portable identity with Keet identity keys and wire it into an app." />

  <Card href="/how-to/stream-and-share-media" title="Stream and share media" description="Build a peer-to-peer filesystem with Hyperdrive; share files, back up photos, and stream stored or live video." />

  <Card href="/how-to/run-on-native" title="Run on mobile & native" description="Embed Bare in React Native, type a native RPC bridge, and bundle a Bare app." />

  <Card href="/how-to/operate-an-app" title="Release & distribute your app" description="Stage, provision, and multisig releases; build desktop distributables; automate with CI; submit to app stores." />

  <Card href="/how-to/manage-installed-applications" title="Manage installed apps" description="List installed Pear apps and reset their storage." />

  <Card href="/how-to/troubleshooting" title="Troubleshoot common issues" description="Fixes for common Pear and Bare development issues." />
</Cards>

Module catalog [#module-catalog]

The full list of `pear-*` and `bare-*` modules—application libraries, UI libraries, common libraries, developer libraries, integration libraries—lives at **[Reference → Modules](/reference/modules/pear-modules)** and **[Reference → Bare modules](/reference/modules/bare-modules)**. Building-block libraries ([Hypercore](/reference/building-blocks/hypercore), [Hyperbee](/reference/building-blocks/hyperbee), [Hyperdrive](/reference/building-blocks/hyperdrive), …), helpers ([Corestore](/reference/helpers/corestore), [Localdrive](/reference/helpers/localdrive), …), and CLI tools have full reference pages under **[Reference](/reference)**. The runtime underneath has its own reference—the [Bare runtime API](/reference/bare/runtime), the [`bare` CLI](/reference/bare/cli), and [Bare Kit](/reference/bare/bare-kit) for native embedding.


# Availability and blind peering



Peer-to-peer availability is not automatic. A new user can only download data that at least one online peer already holds. Pear applications therefore need an explicit strategy for [data availability](#data-availability) and [application availability](#application-availability).

<Callout type="info">
  This page covers seeding, when it falls short, and **blind peering**—a service that replicates cores on your behalf without reading their contents. For the general distribution model, see [Storage and distribution](/explanation/storage-and-distribution).
</Callout>

Two availability problems [#two-availability-problems]

Data availability [#data-availability]

Data availability means the [Hypercores](/reference/building-blocks/hypercore), [Autobases](/reference/building-blocks/autobase), or drives your application reads and writes remain reachable on the swarm. Chat history, shared documents, and room state all depend on someone seeding the relevant cores.

Application availability [#application-availability]

Application availability means the Pear app itself—its metadata core and content [Hyperdrive](/reference/building-blocks/hyperdrive)—can be discovered and installed. A `pear://` link is stable, but the bytes behind it still have to exist on at least one peer.

Both problems share the same underlying constraint: replication requires a live source.

Seeding with pear seed [#seeding-with-pear-seed]

The simplest way to keep an application bundle online is [seeding](#seeding-with-pear-seed), analogous to seeding a torrent. Running `pear seed pear://<app>` keeps the underlying cores announced and available for download.

```bash
pear seed pear://<app>
```

The process must stay running while you want to act as a guaranteed source. Anyone can open the link, but a first-time user needs at least one seeder with a complete copy.

<Callout type="info">
  See [Storage and distribution](/explanation/storage-and-distribution#how-distribution-works) for how staging, seeding, and lazy replication fit together—this page does not repeat that model.
</Callout>

Seeding works well when you control an always-on machine and the cores you care about are ones you already possess. It has two practical limits:

1. **Operational overhead**—You need a running `pear` (or equivalent replicator) per application you seed.
2. **Scope**—You can only seed cores you have locally. A private room or direct-message thread you are not a member of cannot be seeded from your node.

When authors go offline and no participant keeps seeding, data can become temporarily unreachable even though the cryptographic keys still exist.

Blind peering [#blind-peering]

A **blind peer** is a dedicated replicator that stores and serves Hypercores **without decrypting or interpreting** their contents. Blind peering is one way of **putting the server in serverless**: always-on reachability like a hosted service, but the operator never holds the plaintext. It joins swarms on request and caches blocks so other peers can find a source. Blind peering separates "make this core findable" from "I personally hold the plaintext."

The stack has three parts:

1. **[blind-peer](https://github.com/holepunchto/blind-peer)**—server library that accepts peering requests and replicates cores.
2. **[blind-peering](https://github.com/holepunchto/blind-peering)**—client library used inside applications to register cores or Autobases with a blind peer.
3. **[blind-peer-cli](https://github.com/holepunchto/blind-peer-cli)**—CLI that runs a blind peer as a standalone server (provides the `blind-peer` command).

Running a blind peer server [#running-a-blind-peer-server]

Install the CLI and start the server:

```bash
npm i -g blind-peer-cli
blind-peer
```

On startup the process logs (as ndjson) a `Listening at <key>` line—that public key is the blind peer's identity, and clients use it as one of their configured `keys`. The default disk budget is 100 GB; cap it with `-m <size>` (megabytes).

For production, run `blind-peer` under a service manager. Example systemd unit:

```toml
[Unit]
Description=Blind Peer
After=network.target

[Service]
ExecStart=/usr/local/bin/blind-peer -m 10000 --trusted-peer <your-public-key>
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
```

Pass `--trusted-peer <public-key>` to authorize a specific peer to announce on the blind peer (set `announce: true` on its requests). The public key here is the identity of the peer that will make those requests—the `Listening at <key>` value logged by that peer's own swarm node.

Registering cores from an application [#registering-cores-from-an-application]

Inside a Pear worker, wire the client to your existing [Hyperswarm](/reference/building-blocks/hyperswarm) and [Corestore](/reference/helpers/corestore):

```js
import BlindPeering from 'blind-peering'
import Hyperswarm from 'hyperswarm'
import Corestore from 'corestore'

const store = new Corestore(Pear.config.storage)
const swarm = new Hyperswarm()
swarm.on('connection', (conn) => store.replicate(conn))

const BLIND_PEER_KEYS = ['<blind-peer-public-key-hex>']
const blinds = new BlindPeering(swarm.dht, store.namespace('blind-peering'), {
  keys: BLIND_PEER_KEYS
})

// Ask the blind peers to keep a single Hypercore available…
await blinds.addCore(core)

// …or a whole Autobase (all of its writer and view cores).
await blinds.addAutobase(base)
```

<Callout type="tip">
  `addCore` / `addAutobase` connect to the closest configured blind peers and request that they replicate and seed the given cores—without the blind peer ever being able to read them.
</Callout>

Consider letting users configure which blind peers they trust—default infrastructure may not match privacy or jurisdiction requirements (for example location-sensitive data).

Finding the keys to keep available [#finding-the-keys-to-keep-available]

`pear info pear://<app>` prints the keys behind an application bundle:

```bash
pear info pear://<app>
```

The `project` and `content` rows identify the metadata core and content drive. To keep them available, open the corresponding cores in a replicator process and register them with the client library shown above—`blinds.addCore(core)` for a single [Hypercore](/reference/building-blocks/hypercore), `blinds.addAutobase(base)` for an [Autobase](/reference/building-blocks/autobase) and all of its writer and view cores.

Trusted peers and discovery keys [#trusted-peers-and-discovery-keys]

When a blind peer runs with `--trusted-peer`, it recognizes seed requests signed by that key and joins the swarm for the requested core. That is more targeted than broadcasting blindly: peers looking for a specific core use its **discovery key** as a [Hyperswarm](/reference/building-blocks/hyperswarm) topic, so participants in that topic are likely to hold or want the same data.

Blind peering does not replace end-to-end encryption or capability checks on the cores themselves; it only improves **reachability** by keeping an always-on replica on the network.

See also [#see-also]

* [Storage and distribution](/explanation/storage-and-distribution)—on-disk layout and the `pear seed` distribution model.
* [Deploy your application](/how-to/operate-an-app/manual-deployment/deployment)—staging and announcing releases.
* [Peer-to-peer, demystified](/explanation/peer-to-peer-demystified)—how peers find one another on the swarm.
* [Autobase reference](/reference/building-blocks/autobase)—multi-writer cores often registered with blind peering.
* [Hyperswarm reference](/reference/building-blocks/hyperswarm)—topic-based discovery blind peers participate in.


# One core, many platforms



A peer-to-peer app has two very different halves.

1. One is the **core**: swarm identity, storage, replication, and the protocol logic—code that should be identical on every device.
2. The other is the **UI**: windows, views, and gestures—code that is necessarily different on a desktop, a phone, and a terminal.

Bare's answer is to keep the core in one place and let only the UI change. This page explains that pattern and the machinery that connects the two halves. For the runtime itself, see [Inside Bare](/explanation/bare-runtime); for where this sits in the wider picture, see [How Pear and Bare fit together](/explanation/pear-and-bare).

The shape: shell, seam, core [#the-shape-shell-seam-core]

A cross-platform Bare app has three parts:

<Mermaid
  chart="flowchart LR
  shell[&#x22;Native UI shell<br/>(SwiftUI / Kotlin / Electron)&#x22;]
  seam[&#x22;Typed RPC seam&#x22;]
  core[&#x22;JavaScript core<br/>(Bare worklet)&#x22;]
  shell <-->|&#x22;typed methods&#x22;| seam
  seam <-->|&#x22;IPC&#x22;| core
  core -.->|&#x22;runs&#x22;| net[&#x22;Hyperswarm · HyperDHT · Noise · storage&#x22;]"
/>

* The **native shell** is written in the platform's own language and owns nothing but presentation.
* The **core** runs as a Bare *worklet*—an isolated Bare thread—and owns everything peer-to-peer:
  * it holds the swarm identity
  * opens the [Corestore](/reference/helpers/corestore)
  * runs [Hyperswarm](/reference/building-blocks/hyperswarm) and [HyperDHT](/reference/building-blocks/hyperdht)
  * handles the Noise-encrypted connections to other peers.
* The shell never imports a networking library
* The core never imports a UI framework
* Between them is a [**typed RPC seam**](#the-typed-rpc-seam)

Worklets carry the core [#worklets-carry-the-core]

[`bare-kit`](/reference/bare/bare-kit) is the toolkit that runs a Bare core inside a native app. It exposes a web-worker-like API for starting and managing isolated Bare threads—called *worklets*—each with an IPC channel to the host.

* On iOS you drive a worklet from Objective-C (Swift interop is available through the standard language bridge);
* on Android, from Java (Kotlin interop is available through the standard language bridge);
* from React Native or Expo, [`react-native-bare-kit`](/reference/bare/bare-kit) gives you the same `Worklet` and `IPC` objects in JavaScript;
* The worklet honours the Bare [lifecycle](/explanation/bare-runtime#the-lifecycle), so the host can suspend and resume the core in step with the OS's app-lifecycle rules.

Because the worklet is just Bare, the core you ship to mobile is the *same JavaScript* you'd run in a desktop [worker](/explanation/workers) or a standalone terminal binary. Write it once; embed it everywhere.

The typed RPC seam [#the-typed-rpc-seam]

The shell and the core could exchange raw bytes over the IPC pipe, but that pushes framing and parsing into hand-written code on both sides. The Bare RPC ecosystem replaces those raw bytes with **typed methods generated from a shared schema**:

* [`hyperschema`](https://github.com/holepunchto/hyperschema) defines versioned, append-only data structures and generates [`compact-encoding`](/reference/helpers/compact-encoding) codecs for them.
* [`bare-rpc`](/reference/modules/bare-modules) frames requests and replies over a duplex stream, with a unique command number per method.
* Code generators turn the schema into typed bindings for each language. JavaScript bindings are generated today, and a Swift toolchain (`hyperschema-swift`, `bare-rpc-swift`, `compact-encoding-swift`, `hrpc-swift`) produces wire-compatible Swift structs and a typed RPC class, with C and Kotlin generators following.

The seam supports the RPC patterns a real app needs:

* **unary** request/response,
* **send-only** events,
* **response-stream** (the handler writes a sequence of chunks),
* **request-stream** (the caller streams input), and
* **duplex** (both at once).
  Update the schema, regenerate, and both sides get the new types—no hand-maintained parsing, and a compiler error if the shell and core drift apart.

One core, many platforms [#one-core-many-platforms]

Put the pieces together and the payoff is structural.

* The JavaScript core is portable and unchanged across devices.
* Each platform adds two cheap, generated or layout-only pieces: a native shell and the bindings for the seam.
* Swapping from iOS to Android to desktop changes the shell and the generated bindings—never the protocol logic.

This is the architecture behind [Keet's](https://keet.io) identical behaviour on phones, laptops, and terminals: one core, several UIs. The desktop ([Electron](/explanation/pear-desktop-architecture)) and terminal ([standalone Bare binary](/getting-started/from-a-template/start-from-hello-pear-bare)) hosts ship today. On mobile, [`pear-runtime`](/reference/pear/runtime) itself targets desktop; its mobile counterpart is [`pear-mobile`](https://www.npmjs.com/package/pear-mobile), the embeddable Pear runtime for mobile applications—or wire the worklet and updates yourself with `bare-kit`.

Common questions [#common-questions]

Does Bare run on iOS and Android? [#does-bare-run-on-ios-and-android]

Yes. `bare-kit` embeds a Bare worklet in native iOS and Android apps today, and `react-native-bare-kit` does the same for React Native and Expo. The [`pear-runtime`](/reference/pear/runtime) equivalent for mobile is [`pear-mobile`](https://www.npmjs.com/package/pear-mobile) (noted earlier on this page).

How does native code talk to the JavaScript core? [#how-does-native-code-talk-to-the-javascript-core]

Through an IPC channel between the host and the worklet. You can write bytes directly, or—recommended—put a [typed RPC seam](#the-typed-rpc-seam) on top so both sides call generated, type-checked methods instead.

How is this different from React Native's own JavaScript engine? [#how-is-this-different-from-react-natives-own-javascript-engine]

React Native runs your UI's JavaScript on the main JS thread. A Bare worklet is a *separate*, isolated runtime for your peer-to-peer core, running off the UI thread with its own module system and native addons. The two communicate over IPC; the worklet keeps networking and storage out of the UI's way.

Do I have to write the protocol twice—once in JS, once in Swift? [#do-i-have-to-write-the-protocol-twiceonce-in-js-once-in-swift]

No. You define the schema once with `hyperschema` and generate bindings for each language. The Swift, JavaScript (and forthcoming C/Kotlin) sides are all generated from—and wire-compatible with—that single source.

See also [#see-also]

* [`bare-kit` reference](/reference/bare/bare-kit)—the Worklet and IPC API for iOS, Android, and React Native.
* [Embed Bare in a React Native app](/how-to/run-on-native/embed-bare-in-react-native)—start a worklet and exchange messages.
* [Type a native RPC bridge](/how-to/run-on-native/type-a-native-rpc-bridge)—generate a typed seam with `hyperschema` and `bare-rpc`.
* [Bundle a Bare app](/how-to/run-on-native/bundle-a-bare-app)—produce an embeddable bundle or a standalone binary.
* [Workers](/explanation/workers)—the same host-and-core split on the desktop.
* [Inside Bare](/explanation/bare-runtime)—the runtime the worklet is an instance of.


# Inside Bare



[Bare](https://github.com/holepunchto/bare) is the JavaScript runtime every Pear app runs on. Like Node.js, it gives you an asynchronous, event-driven environment for writing applications in JavaScript. Unlike Node.js, it treats **embedding** and **cross-device support** as core use cases—it aims to run just as well inside a phone app as on a laptop or a server. This page explains what that buys you and why the runtime is shaped the way it is.

<Callout type="info">
  * For the exact API, see the [`Bare` runtime reference](/reference/bare/runtime).
  * For where Bare sits relative to Pear, see [How Pear and Bare fit together](/explanation/pear-and-bare).
</Callout>

What Bare adds, and what it leaves out [#what-bare-adds-and-what-it-leaves-out]

Bare is built on two C libraries: [`libjs`](https://github.com/holepunchto/libjs), which provides low-level bindings to V8 (or QuickJS, via [`libqjs`](https://github.com/holepunchto/libqjs)) in an engine-independent way, and [`libuv`](https://github.com/libuv/libuv), which provides the asynchronous I/O event loop. On top of those primitives Bare adds only a few missing pieces:

1. A **module system** supporting both CommonJS and ESM, with bidirectional interoperability between the two.
2. A **native-addon system** supporting both statically and dynamically linked addons.
3. **Lightweight threads** with synchronous joins and `SharedArrayBuffer` support.

Everything else is left to userland. There is no built-in `fs`, no built-in `http`, no bundled standard library—those live in installable [`bare-*` modules](/reference/modules/bare-modules) you add only when you need them. The runtime itself stays succinct and, well, *bare*.

That minimalism is a deliberate "less is more" stance, and it pays off in two ways. Bundles only carry the modules an app actually declares, so they stay small enough to embed on a phone. And because the standard library isn't baked into the runtime, you can upgrade Bare without being forced to refactor dependencies in lockstep.

Engine independence [#engine-independence]

By abstracting the JavaScript engine behind the `libjs` ABI and platform I/O behind `libuv`, Bare lets a native addon run on *any* engine that implements the `libjs` ABI and *any* system `libuv` supports. In practice that means Bare can be compiled against V8, through [`libqjs`](https://github.com/holepunchto/libqjs), QuickJS, or through [`libjsc`](https://github.com/holepunchto/libjsc), JavaScriptCore — useful on platforms like iOS where JSC is the sanctioned engine. The addon you wrote against Bare doesn't change.

The lifecycle [#the-lifecycle]

A server runtime can assume it owns the process and runs until it's killed. A runtime embedded in a mobile app can't: the operating system suspends apps that move to the background and may reclaim them entirely. Bare models this explicitly with a process lifecycle that an embedder — or your JavaScript — can drive.

Calling `Bare.suspend()` emits a `suspend` event, signalling that outstanding work (network activity, file access) should be deferred or paused. When the loop runs out of work it emits `idle` and blocks rather than exiting, keeping the process alive but quiet. `Bare.resume()` emits `resume` and lets the loop continue; `Bare.wakeup()` allows a bounded burst of work (**awake** state) during suspension before the process settles back to idle.

<Mermaid
  chart="stateDiagram-v2
  direction LR
  [*] --> Active
  Active --> Suspending: Bare.suspend()
  Suspending --> Active: Bare.resume()
  Suspending --> Awake: Bare.wakeup()
  Suspending --> Idle
  Awake --> Active: Bare.resume()
  Awake --> Idle
  Idle --> Active: Bare.resume()
  Active --> Terminated: Bare.exit()
  Terminated --> [*]"
/>

This is what lets a peer-to-peer core behave correctly when a phone locks the screen: it parks its sockets on `suspend`, sits quietly at `idle`, and picks back up on `resume`—instead of being killed mid-replication. The [full state machine and event list](/reference/bare/runtime#lifecycle) is in the reference.

Common questions [#common-questions]

Is Bare a fork of Node.js? [#is-bare-a-fork-of-nodejs]

No. Bare is a separate runtime built on `libjs` and `libuv`. The surface looks familiar—asynchronous, event-driven, module-based—but Bare drops Node's server-oriented assumptions and its bundled standard library. The [`bare-node`](https://github.com/holepunchto/bare-node) shim maps many Node.js builtins onto their `bare-*` equivalents to ease porting.

Can I use npm modules with Bare? [#can-i-use-npm-modules-with-bare]

Pure-JavaScript packages from npm generally work, and Bare uses the npm dependency model. Packages that depend on Node's built-in modules need the corresponding [`bare-*` module](/reference/modules/bare-modules) (or the `bare-node` shim), and packages with native addons need to be built against Bare's addon API rather than Node's N-API (the [`bare-compat-napi`](https://github.com/holepunchto/bare-compat-napi) headers ease that transition).

<Callout type="info">
  For the full builtin-to-`bare-*` mapping, see [Node.js compatibility](/reference/modules/bare-modules#nodejs-compatibility).
</Callout>

Do users need Node.js installed to run a Bare app? [#do-users-need-nodejs-installed-to-run-a-bare-app]

No. A Bare program can be compiled into a single standalone executable with `bare-build`—this is how the [`hello-pear-bare`](/getting-started/from-a-template/start-from-hello-pear-bare) template ships—so no Node.js, Bare, or [Pear CLI](/reference/pear/cli) is required on the user's machine.

Which JavaScript engine does Bare use? [#which-javascript-engine-does-bare-use]

It depends on the build. Bare talks to the engine through the `libjs` ABI, so it can be compiled against V8 (the default), QuickJS via `libqjs`, or JavaScriptCore via `libjsc`. Your application and addons don't change between engines.

See also [#see-also]

* [Using Bare on its own](/explanation/use-bare-standalone)—the runtime-only path, for adopting Bare without Pear.
* [`Bare` runtime reference](/reference/bare/runtime)—the `Bare` global API, lifecycle events, addons, and threads.
* [`bare` CLI reference](/reference/bare/cli)—running scripts and the REPL from the command line.
* [Bare modules](/reference/modules/bare-modules)—the `bare-*` standard library you opt into.
* [One core, many platforms](/explanation/bare-on-native)—embedding the runtime in native and mobile apps.
* [Handle app suspension](/how-to/run-on-native/handle-app-suspension)—stop all I/O on `suspend` or the OS will force-terminate the app.
* [Runtime and languages](/explanation/runtime-and-languages)—why Pear is JavaScript and how other languages plug in.
* [How Pear and Bare fit together](/explanation/pear-and-bare)—where the runtime sits relative to Pear.


# Dependencies and network



Two questions come up enough during onboarding:

* [Why Pear uses npm at all when applications run on Bare, not Node?](#why-npm-for-dependencies)
* [What peers can learn about you when you join a swarm?](#what-peers-learn-from-your-ip)

Both answers have the same shape—a deliberate trade-off between developer ergonomics and the platform's clean-room ideals.

Why npm for dependencies [#why-npm-for-dependencies]

npm is a great package manager for JavaScript, and most JavaScript developers already know how to use it. All of Holepunch's modules—[Hypercore](/reference/building-blocks/hypercore), [Hyperdrive](/reference/building-blocks/hyperdrive), [Hyperbee](/reference/building-blocks/hyperbee), the lot—are published there. Reinventing a peer-to-peer package manager would have meant reinventing every developer's habits at the same time, for very little upside.

The bootstrap relationship is what's interesting: npm and Node.js are required to **install** Pear initially (`npm install -g pear`), but once the platform is set up neither is needed at runtime. The `pear` command after install is using Bare, not Node, to run your application; npm was just the delivery mechanism.

What dependencies your application declares stays meaningful, though. When you `pear stage`, every dependency in your `package.json` is bundled into the application's hyperdrive and replicated to peers along with your code. A few practical implications follow:

* **Audit before you ship.** Run `pear stage --dry-run` to review the file list before announcing a release; this is where you'd catch a dependency that ballooned in size or pulled in something unexpected.
* **Updates ship fully replicated.** If you update a dependency, you're not merely changing a `package-lock.json`—you're shipping the actual new code to every running peer. Ordinary semver discipline applies, but the consequence is more direct than on a server-rendered web app.

Dependency layout for Pear apps [#dependency-layout-for-pear-apps]

Bare loads modules from `node_modules` the same way Node does during development, and Pear replicates those trees into the application hyperdrive at stage time. A few layout rules keep staging predictable:

1. **Use `node_modules` for dependencies**—Pear picks them up during development and includes them when you stage.
2. **Use `package.json`**—Pear reads it for application metadata and dependency lists.
3. **Do not bundle dependencies into a single file**—bundlers that inline `node_modules` fight Pear's model of replicating discrete packages. Ship source and dependencies as separate files instead.

TypeScript is supported. Not every Holepunch module ships its own typings yet; the community [holepunch-types](https://github.com/Drache93/holepunch-types) project aggregates coverage. An IDE with TypeScript language service helps even for plain JavaScript projects.

If you compile TypeScript locally, keep dependencies external. With Bun:

```bash
bun build index.ts --packages=external --outdir=.
```

The `--packages=external` flag compiles your application code without inlining `node_modules`. Avoid bundling dependencies into the output artifact you stage.

<Callout type="warn">
  **Never load JavaScript over HTTP(S).** Loading code from an external source is dangerous—if that source is compromised or malicious, your app can be exploited, and the risk is worse for apps with native API access. Pear blocks HTTP and HTTPS code loading by default to prevent this supply-chain risk. Ship dependencies with the app (as above) instead of fetching them at runtime.
</Callout>

What peers learn from your IP [#what-peers-learn-from-your-ip]

When you connect to a swarm—directly via `hyperswarm`, or transitively because you're running a Pear application that swarms—your IP address is exposed to the peers you connect to. This is unavoidable for the same reason it's unavoidable for any peer-to-peer network: peers need a routable address to reach you, and IP is what TCP/UDP transport provides.

This means a peer you connect to can, in principle:

* Geolocate you to the level of granularity their IP database supports (typically city, sometimes ISP).
* Correlate your presence on multiple swarms if they participate on more than one.
* Log timing of your connections and disconnections.

What they can't do without further ado:

* Read your traffic (Pear connections are end-to-end encrypted via [Secretstream](/reference/helpers/secretstream))
* Impersonate you (your peer key is a public key you control)
* Identify you across IP changes (the IP changes; your peer key is what's stable)

If your IP is sensitive—you're a journalist, an activist, or just privacy-conscious—route Pear's traffic through a VPN or Tor. The peer-to-peer protocol doesn't care what's underneath the transport, and using a privacy network shifts the IP-disclosure surface from your real address to the exit node's.

See also [#see-also]

* [Connect to many peers by topic with Hyperswarm](/how-to/connect-to-peers/connect-to-many-peers-by-topic-with-hyperswarm)—joining a swarm in practice.
* [Peer-to-peer, demystified](/explanation/peer-to-peer-demystified)—conceptual overview of HyperDHT and Hyperswarm.
* [Secretstream](/reference/helpers/secretstream)—the encryption layer on every Pear peer connection.
* [Storage and distribution](/explanation/storage-and-distribution)—what actually crosses the wire when peers replicate.
* [Hyperswarm reference](/reference/building-blocks/hyperswarm)—topic-based peer discovery and connection management.
* [HyperDHT reference](/reference/building-blocks/hyperdht)—the lower-level DHT layer handling hole punching and IP routing.


# Deployment - Releasing Apps P2P



This page explains **why** many Pear **desktop** release flows use three operations: **stage**, **provision**, and **multisig**, and how **release lines** and the **deployment directory** fit around them.

Read it before you run commands so the mental model matches the CLI (concrete steps live under [Deploy your application](/how-to/operate-an-app/manual-deployment/deployment) and [Build desktop distributables](/how-to/operate-an-app/build-and-package/build-desktop-distributables)).

{/*
  Shared snippet (content/_snippets/) included via Fumadocs <include> by the full-control
  release pages, pointing readers at the CI shortcut for the simple publish/update path.
  See: https://www.fumadocs.dev/docs/markdown#include
  */}

<Callout type="info">
  For the simplest publish/update workflow, let CI stage for you. [Publish with GitHub Actions](/how-to/operate-an-app/github-actions/publish-with-github-actions) turns shipping a new version into a `git push`. This page is the full-control path when you need release lines, provision, and multisig.
</Callout>

<Callout type="info">
  **Operator detail:** [Deploy your application](/how-to/operate-an-app/manual-deployment/deployment), [Build desktop distributables](/how-to/operate-an-app/build-and-package/build-desktop-distributables), and [Troubleshoot desktop releases](/how-to/operate-an-app/manual-deployment/troubleshoot-desktop-releases) carry the same pipeline as these diagrams. The [Glossary](#glossary) below defines the terms.
</Callout>

The short version [#the-short-version]

Centralized deploy pipelines often separate *staging servers*, *preview*, and *production*. Pear can fold similar **trust boundaries** into **different Hyperdrives addressed by different `pear://` links**:

1. You **stage** a folder of builds into a drive used for iteration,
2. You **provision** from a versioned stage into a leaner prerelease drive, and
3. You **multisig-commit** into production so a **quorum of signers** must agree. **Each hop can shrink history or raise assurance.**

OTA update event lifecycle [#ota-update-event-lifecycle]

A running Pear desktop app polls the [Hyperdrive](/reference/building-blocks/hyperdrive) behind its `upgrade` link, downloads new application data when the [Hypercore](/reference/building-blocks/hypercore) length advances, and emits two events from [`pear.updater`](/reference/pear/runtime). The host process forwards them to renderers so the UI can react:

<Mermaid
  chart="sequenceDiagram
    participant Peer as Seeder peer
    participant Updater as pear.updater
    participant Main as Electron main
    participant UI as Renderer
    Peer-->>Updater: new core length
    Updater-->>Main: 'updating' (download in progress)
    Main-->>UI: webContents.send('pear:event:updating')
    Updater-->>Main: 'updated' (download ready)
    Main-->>UI: webContents.send('pear:event:updated')
    UI->>Main: applyUpdate()
    Main->>Updater: updater.applyUpdate()
    Note over Updater,Main: swap app path on disk, remove old build
    UI->>Main: appAfterUpdate()
    Main->>Main: app.relaunch(); app.quit()"
/>

* [`updating`](/reference/pear/runtime#updates) fires when the updater begins streaming new blocks; treat it as "background work in progress."
* [`updated`](/reference/pear/runtime#updates) fires when the new build is fully on disk; it is safe to swap.
* [`bridge.applyUpdate()`](https://github.com/holepunchto/pear-docs/blob/preview/examples/getting-started/pear-chat/electron/preload.js#L9) (renderer side) calls [`pear.updater.applyUpdate()`](https://github.com/holepunchto/pear-runtime-updater#await-updaterapplyupdate) (updater worker side). [`applyUpdate()`](https://github.com/holepunchto/pear-runtime-updater#await-updaterapplyupdate) renames the application directory to the new build and deletes the old one—until the process restarts, the running code is still the old build.
* [`bridge.appAfterUpdate()`](https://github.com/holepunchto/pear-docs/blob/preview/examples/getting-started/pear-chat/electron/preload.js#L10) triggers [`app.relaunch()`](https://www.electronjs.org/docs/latest/api/app#apprelaunchoptions) and [`app.quit()`](https://www.electronjs.org/docs/latest/api/app#appquit). On Linux AppImage you usually relaunch with `process.env.APPIMAGE` instead of `process.execPath` so the host wrapper script gets re-executed—see [`app:afterUpdate` in pear-chat](https://github.com/holepunchto/pear-docs/blob/preview/examples/getting-started/pear-chat/electron/main.js#L234).

<Callout type="idea">
  You can disable updates per run with `--no-updates` (handy in development) or globally by setting `"updates": false` in `package.json` and spreading the package config into the `PearRuntime` options.
</Callout>

The two-event split is what lets you build UI like the "Update ready" banner in [Reshape into a production app](/getting-started/build-a-peer-to-peer-chat/reshape-into-a-production-app): show a spinner on `updating`, swap to a restart button on `updated`, restart the app on click.

Stage, provision, multisig [#stage-provision-multisig]

<Mermaid
  chart="graph LR
  S[Stage] --> P[Provision] --> M[Multisig]"
/>

* **Stage**—Local and team checks: feature branches, unsigned or lightly signed builds, ephemeral links. Appends to the application drive; good for iteration.
* **Provision**—Prerelease / QA / dogfood: synchronizes from a **versioned** stage source onto a target link while **compacting** additions and deletions so the drive is closer to what stakeholders mirror.
* **Multisig**—Production: writes require **co-signing** up to a configured quorum so one compromised machine cannot redefine the release line.

Each stage link can feed the next operation; a **provisioned** link becomes the source for **multisig** commits once signers agree.

Deployment directory and release lines [#deployment-directory-and-release-lines]

A **deployment directory** is the multi-architecture output you assemble after per-OS **make** steps (often with `pear build` merging `darwin`, `linux`, and `win32` artifacts). That directory is what **`pear stage`** reads from disk and writes into [Hypercore](/reference/building-blocks/hypercore)-backed storage for a given **release line** link.

**Release lines** are parallel stability tracks: common names are **development**, **staging**, **rc** (each a **staged** link), then **prerelease** (provisioned from `rc`), then **production** (multisig’d from prerelease). The **`upgrade`** field in `package.json` decides **which link** a shipped binary follows for OTA—so different builds can track different lines intentionally.

<Mermaid
  chart="graph TB
  DF[(Deployment directory)] -->|&#x22;pear://‹dev-key›&#x22;| Dev[development]
  DF -->|&#x22;pear://‹staging-key›&#x22;| Stg[staging]
  DF ==>|&#x22;pear://‹PROD-KEY›&#x22;| RC[rc]

  subgraph STAGE[Stage]
    Dev
    Stg
    RC
  end

  subgraph PROVISION[Provision]
    Pre[prerelease]
  end

  subgraph MULTISIG[Multisig]
    Prod[production]
  end

  RC ==>|source| Pre
  Pre ==>|source| Prod"
/>

A common pattern is that **`rc`’s `upgrade` pins the production multisig key**, so `rc` builds **do not** receive casual OTA bumps—you ship new installers when that line moves.

Release cycle (steady state) [#release-cycle-steady-state]

Once bootstrapping finishes, the steady **release cycle** is repetitive: bump **`version`**, **make** per platform, **build** the deployment directory, **stage**, iterate; when stable, **provision**; when assessed, run **multisig** prepare → sign → verify → commit; production goes live; the next cycle starts again at **version**.

<Mermaid
  chart="graph LR
  V(2. Version) --> Make(3. Make distributables) --> Build(4. Build deployment directory) --> Stage(5. Stage)
  Stage -->|stable| Prov(6. Provision)
  Prov -->|assessed| Req(7d. Prepare request) --> Sign(7e. Sign) --> Verify(7f. Verify) --> Commit(7g. Commit) --> Live[Production live]
  Stage -.->|iterate| V
  Live -.->|next release| V"
/>

Numbered labels align with common documentation ordering (touch/seed and upgrade-link setup happen **before** this loop is warm).

Foundational steps (bootstrap + loop) [#foundational-steps-bootstrap--loop]

The **foundational** diagram adds multisig **key creation** and config **beside** the main loop: signing keys, the multisig config in `pear.json`, pointing `upgrade` at the multisig link, then joining the same release flow.

<Mermaid
  chart="graph LR
  subgraph Link_setup[Link setup]
    T(0. Touch and seed) --> U(1. Set upgrade link)
  end

  U -.-> V

  V(2. Version) --> Make(3. Make distributables) --> Build(4. Build deployment directory) --> Stage(5. Stage)
  Stage -->|stable| Prov(6. Provision)
  Prov -->|assessed| Req(7d. Prepare request) --> Sign(7e. Sign) --> Verify(7f. Verify) --> Commit(7g. Commit) --> Live[Production live]
  Stage -.->|iterate| V
  Live -.->|next release| V

  K(7a. Create signing keys) --> C(7b. Create multisig config)
  Prov -->|setup| C
  C --> L(7c. Set upgrade to multisig link)
  L --> Req"
/>

**Stage-only** is enough for proofs of concept; **production** benefits from quorum signing and machine-independent drives.

From per-OS builds to one directory [#from-per-os-builds-to-one-directory]

<Mermaid
  chart="graph TB
  V(Version) -->|make| MakeWin[/Windows/]
  V -->|make| MakeMac[/macOS/]
  V -->|make| MakeLinux[/Linux/]

  MakeWin --> Build(pear build)
  MakeMac --> Build
  MakeLinux --> Build

  Build --> DF[(Deployment directory)]"
/>

That directory must at least contain `package.json` and `by-arch/.../app` trees before `pear stage` is meaningful.

Multisig setup and signing [#multisig-setup-and-signing]

The diagrams below follow [`hello-pear-electron`'s Foundational Steps](https://github.com/holepunchto/hello-pear-electron#foundational-steps)—the same Electron + Bare worker template [Keet](https://keet.io) and [PearPass](https://pass.pears.com) ship. **One-time** multisig wiring is in [Set up multisig](/how-to/operate-an-app/multisig/set-up-multisig); every production shipment after that uses [Sign with multisig](/how-to/operate-an-app/multisig/sign-with-multisig). If a commit fails mid-flight, see [Troubleshoot multisig](/how-to/operate-an-app/multisig/troubleshoot-multisig).

How setup connects to the release cycle [#how-setup-connects-to-the-release-cycle]

The [multisig config](/how-to/operate-an-app/multisig/set-up-multisig#create-the-multisig-config) in `pear.json` derives the **multisig link** from its `namespace`, `publicKeys`, and `quorum` alone—it does **not** reference the provision drive. The provision link from the most recent [`hello-pear-electron`](https://github.com/holepunchto/hello-pear-electron) `pear stage` / [`pear provision`](/how-to/operate-an-app/manual-deployment/deployment#6-provision) is instead supplied as the **source** when you prepare and commit each signing request. Shipped binaries read the **multisig link** from [`package.json` `upgrade`](/how-to/operate-an-app/multisig/set-up-multisig#set-upgrade-to-the-multisig-link).

<Mermaid
  chart="graph TB
  subgraph Setup[Multisig setup]
    K(7a. Create signing keys) --> C(7b. Create multisig config)
    C --> L(7c. Set upgrade to multisig link)
  end

  subgraph HPE[hello-pear-electron release cycle]
    V(2. Version) --> Make(3. Make distributables) --> Build(4. pear build) --> Stage(5. pear stage)
    Stage --> Prov(6. Provision drive)
  end

  L -.->|package.json upgrade| Stage
  Prov -->|assessed, source at commit| MS(7d–7g. Multisig)
  MS --> Live[Production live]"
/>

Quorum signing [#quorum-signing]

Each production commit runs the four steps in [Sign with multisig](/how-to/operate-an-app/multisig/sign-with-multisig): [`pear multisig request`](/how-to/operate-an-app/multisig/sign-with-multisig#prepare-the-request), [`pear multisig sign`](/how-to/operate-an-app/multisig/sign-with-multisig#sign) from each signer until [quorum](/how-to/operate-an-app/multisig/set-up-multisig#create-the-multisig-config) is met, [`pear multisig verify`](/how-to/operate-an-app/multisig/sign-with-multisig#verify), then [`pear multisig commit`](/how-to/operate-an-app/multisig/sign-with-multisig#commit).

<Mermaid
  chart="graph TB
  Prov[hello-pear-electron provision drive] --> Req(7d. Prepare request)
  Req --> G((Gather signatures))
  G -->|signing request| S1[Signer 1]
  G -->|signing request| S2[Other signers]
  S1 -->|response| Q{Quorum met?}
  S2 -->|response| Q
  Q -->|no| G
  Q -->|yes| Ver(7f. Verify)
  Ver --> Com(7g. Commit)
  Com --> Live[Production live]"
/>

Release lines [#release-lines]

For [`hello-pear-electron`](https://github.com/holepunchto/hello-pear-electron), one [`pear build`](https://github.com/holepunchto/hello-pear-electron#deploying) output can feed parallel **stage** links; **prerelease** and **production** are the provision and multisig gates on the trust ladder.

<Mermaid
  chart="graph TB
  HPE[[hello-pear-electron deployment directory]] --> STAGED

  subgraph STAGED[Staged pear:// links]
    Dev[development]
    Stg[staging]
    RC[rc]
    subgraph CUSTOM[Custom]
      Cst[custom…]
    end
  end

  subgraph PROVISIONED[Provisioned]
    Pre[prerelease]
  end

  subgraph MULTISIGD[Multisig production]
    Prod[production]
  end

  RC --> Pre
  Pre --> Prod"
/>

**Custom** lines are optional forks for spikes, hotfixes, or instrumented builds—same mechanics, different seeded link.

Relationship to Pear’s global storage story [#relationship-to-pears-global-storage-story]

Platform installs still use Pear’s OS-wide tree described in [Storage and distribution](/explanation/storage-and-distribution). The diagrams here are about **application release artifacts** moving between links—not replacing that global layout.

Glossary [#glossary]

Terms you will see across the **Pear desktop release** and **OTA update** docs:

| Term                     | Meaning                                                                                                                                                                                                                  |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **OTA**                  | Over-the-air: delivering a new app build without a traditional reinstall flow from a store.                                                                                                                              |
| **OTA updates**          | Syncing the running app’s bundle from a peer-to-peer source when the [application drive](#deployment-directory-and-release-lines) changes.                                                                               |
| **P2P**                  | Peer-to-peer: machines replicate directly; distribution does not require a single central server if seeders exist.                                                                                                       |
| **Application drive**    | The [Hyperdrive](/reference/building-blocks/hyperdrive) that holds the published app files and version history for a given `pear://` link.                                                                               |
| **Deployment directory** | The multi-architecture folder produced after per-OS builds are assembled (for example with `pear build`) and before `pear stage`. See [Deployment directory and release lines](#deployment-directory-and-release-lines). |
| **Multisig**             | Co-signing: a quorum of signers must approve before writes land on the production drive.                                                                                                                                 |
| **Pear link**            | Stable `pear://…` identifier the swarm routes on; see the **Links** row in [Command Line Interface](/reference/pear/cli) and [Storage and distribution](/explanation/storage-and-distribution).                          |
| **Quorum**               | Minimum number of multisig signers required to commit a release.                                                                                                                                                         |
| **Release line**         | A parallel deployment stream (for example development, staging, rc) at its own stability level, each with its own staged link.                                                                                           |
| **Seeding**              | Keeping a drive announced and available so peers can discover and replicate it (`pear seed`).                                                                                                                            |
| **Vendor signing**       | OS-level code signing (Apple notarization, Windows Authenticode, etc.) so distributables run on other machines without quarantine.                                                                                       |
| **Versioned link**       | A `pear://` link that pins `fork`, `length`, and `key` of the [Hypercore](/reference/building-blocks/hypercore) behind the application Hyperdrive—used when provisioning between known versions.                         |

Where to go next [#where-to-go-next]

* [Pear desktop application architecture](/explanation/pear-desktop-architecture)—workers, storage, and update events in the running app.
* [Deploy your application](/how-to/operate-an-app/manual-deployment/deployment)—operator checklist for `pear stage` / `pear provision` / multisig tooling.
* [Build desktop distributables](/how-to/operate-an-app/build-and-package/build-desktop-distributables)—per-OS makes and signing pointers.
* [Desktop release npm scripts](/reference/ci-and-release/desktop-release-npm-scripts)—common `package.json` scripts.
* [Troubleshoot desktop releases](/how-to/operate-an-app/manual-deployment/troubleshoot-desktop-releases)—OTA, staging, and `pear build` pitfalls.


# From append-only logs to files



Pear storage is built from a small set of composable primitives stacked on top of one another:

<Mermaid
  chart="flowchart LR
  HC[Hypercore] --> HB[Hyperblobs] --> HD[Hyperdrive]"
/>

At the bottom is **[Hypercore](#hypercore-append-only-blocks)**, an append-only log of verified blocks. Everything else in Pear storage ultimately replicates through one or more cores.

**[Hyperblobs](#hyperblobs-large-opaque-objects)** sits on a core when you need opaque objects larger than a single block—it handles chunking and returns stable ids you can store elsewhere.

**[Hyperdrive](#hyperdrive-paths-metadata-and-directories)** is the top layer: path-addressed files and directories, with metadata in a [Hyperbee](/reference/building-blocks/hyperbee) tree and file contents in **[Hyperblobs](#hyperblobs-large-opaque-objects)**.

Understanding that ladder helps you pick the right building block before you reach for a full filesystem API.

<Callout type="info">
  This page is conceptual. For API details, see [Hypercore](/reference/building-blocks/hypercore), [Hyperdrive](/reference/building-blocks/hyperdrive), and [Hyperbee](/reference/building-blocks/hyperbee).
</Callout>

Hypercore: append-only blocks [#hypercore-append-only-blocks]

[Hypercore](/reference/building-blocks/hypercore) is a secure, sparse-replicated append-only log. Each `append` adds one block; readers verify integrity and optionally decrypt per-block. Hypercore is the foundation for nearly every other Pear data structure.

You can store arbitrary bytes directly in a core:

```js
import Hypercore from 'hypercore'

const core = new Hypercore('./my-core')
await core.ready()

await core.append(Buffer.from('I am a block of data'))
```

That works for small payloads, but Hypercore blocks have a practical size limit. Storing a large file as one block is inefficient; splitting it manually means tracking chunk order, offsets, and retrieval yourself.

Hyperblobs: large opaque objects [#hyperblobs-large-opaque-objects]

[Hyperblobs](https://github.com/holepunchto/hyperblobs) chunks large data across [Hypercore](/reference/building-blocks/hypercore) blocks and exposes a simple put/get API. A `put` returns an **id** (block and byte offsets and lengths) that you store elsewhere—for example in a [Hyperbee](/reference/building-blocks/hyperbee) key.

```js
import Hypercore from 'hypercore'
import Hyperblobs from 'hyperblobs'

const core = new Hypercore('./blob-core')
const blobs = new Hyperblobs(core)
await blobs.ready()

const id = await blobs.put(Buffer.from('hello world', 'utf-8'))
const data = await blobs.get(id)
```

Hyperblobs is the right choice when you need **object storage**—attachments, media, serialized blobs—without file paths or directory semantics. Replication still flows through the underlying Hypercore; peers fetch missing blob blocks like any other core data.

[Hyperdrive](/reference/building-blocks/hyperdrive) uses Hyperblobs internally for file contents. You do not need Hyperdrive if all you want is keyed blob storage.

Hyperdrive: paths, metadata, and directories [#hyperdrive-paths-metadata-and-directories]

[Hyperdrive](/reference/building-blocks/hyperdrive) combines a [Hyperbee](/reference/building-blocks/hyperbee) metadata tree with a Hyperblobs content store. You get path-based operations—`get`, `put`, `del`, `list`, existence checks—similar to a filesystem, with the same replication properties as [Hypercore](/reference/building-blocks/hypercore).

```js
import Hyperdrive from 'hyperdrive'
import Corestore from 'corestore'

const store = new Corestore('./drive-storage')
const drive = new Hyperdrive(store)
await drive.ready()

await drive.put('/notes/readme.txt', Buffer.from('hello'))
const buffer = await drive.get('/notes/readme.txt')
```

Pear application bundles are Hyperdrives: code, assets, and dependencies staged with `pear stage` live in a drive that peers replicate. User-facing apps often keep **application state** in separate cores or drives under [Corestore](/reference/helpers/corestore).

Helpers extend the model without changing the stack:

* [Localdrive](/reference/helpers/localdrive)—mirror between a Hyperdrive and a local folder.
* [Mirrordrive](/reference/helpers/mirrordrive)—copy or sync between two drives.

Choosing a layer [#choosing-a-layer]

| Need                              | Use                                                                                     |
| --------------------------------- | --------------------------------------------------------------------------------------- |
| Ordered event log, small messages | [Hypercore](/reference/building-blocks/hypercore) directly                              |
| Large binary object, no path      | Hyperblobs on a dedicated core                                                          |
| Files, directories, bundle layout | [Hyperdrive](/reference/building-blocks/hyperdrive)                                     |
| Sorted key/value over one log     | [Hyperbee](/reference/building-blocks/hyperbee) (often inside Hyperdrive or standalone) |

If you do not need path-addressed files shared between peers, prefer Hyperblobs over Hyperdrive. Hyperdrive pays for directory semantics and metadata indexing you may not use.

See also [#see-also]

* [Storage and distribution](/explanation/storage-and-distribution)—where cores and drives live on disk in a Pear installation.
* [Share append-only databases with Hyperbee](/how-to/store-and-replicate/share-append-only-databases-with-hyperbee)—key/value patterns on Hypercore.
* [Work with many Hypercores using Corestore](/how-to/store-and-replicate/work-with-many-hypercores-using-corestore)—managing multiple cores from one storage root.
* [Hypercore reference](/reference/building-blocks/hypercore)—append-only log API.
* [Hyperdrive reference](/reference/building-blocks/hyperdrive)—filesystem API.
* [Hyperbee reference](/reference/building-blocks/hyperbee)—sorted key/value tree.


# About Pear



The pages here are for understanding, not doing. They answer "why" rather than "how": why does Pear use append-only logs, what does "peer-to-peer" mean in practice, what's the difference between Bare and Node, and why is there no central server.

If you want to build something, head to **[How To](/how-to)**. If you need to look up a specific API, that's **[Reference](/reference)**.

In this section [#in-this-section]

Pages are grouped by topic and ordered roughly from foundational concepts to app-specific ones.

Platform foundations [#platform-foundations]

* [How Pear and Bare fit together](/explanation/pear-and-bare)—how Pear and Bare layer together, from the native C foundations up to the apps you run.
* [Peer-to-peer, demystified](/explanation/peer-to-peer-demystified)—hole punching, public-key identity, and the roles of [HyperDHT](/reference/building-blocks/hyperdht) and [Hyperswarm](/reference/building-blocks/hyperswarm).
* [Runtime and languages](/explanation/runtime-and-languages)—JavaScript on Bare, native addons for other languages, and the Pear-end pattern for cross-platform apps.
* [Using Bare on its own](/explanation/use-bare-standalone)—the entry point for adopting Bare as a standalone runtime, without Pear's peer-to-peer platform.
* [Inside Bare](/explanation/bare-runtime)—what the Bare runtime adds, its lifecycle, and why its standard library is opt-in.
* [One core, many platforms](/explanation/bare-on-native)—running the peer-to-peer core in a Bare worklet behind a typed RPC seam.
* [Dependencies and network](/explanation/dependencies-and-network)—why NPM is the install path, the runtime relationship to Node, and what your IP discloses on a swarm.

Storing & replicating data [#storing--replicating-data]

* [From append-only logs to files](/explanation/from-logs-to-files)—Hypercore, Hyperblobs, and [Hyperdrive](/reference/building-blocks/hyperdrive)—which storage layer to use and why.
* [Storage and distribution](/explanation/storage-and-distribution)—where Pear keeps your data, what the swarm replicates, and how new releases reach users.
* [Availability and blind peering](/explanation/availability-and-blind-peering)—seeding, its limits, and always-on replication without reading user data.

Building & shipping apps [#building--shipping-apps]

* [Pear desktop application architecture](/explanation/pear-desktop-architecture)—how a typical Pear Electron app splits updates, storage, and Bare workers (with a link to a full sample repo).
* [Workers](/explanation/workers)—why peer-to-peer logic lives in a Bare worker behind one IPC stream, and where the host/worker boundary should sit.
* [Release pipeline](/explanation/deployment-releasing-apps-p2p)—stage, provision, multisig, release lines, and deployment-directory diagrams (agnostic; sample implementation on GitHub).

{/* Planned explanation pages. Uncomment each bullet as the page lands.

  More conceptual overviews are in flight; topics planned to land here include:

  - **What is Pear?**—the runtime, the toolchain, and the philosophy in plain language.
  - **Append-only logs are a database**—why [Hypercore](/reference/building-blocks/hypercore) looks weird if you're coming from SQL.
  - **The runtime model**—how Pear apps start, update, and shut down.

  */}

Coming from the old FAQ? [#coming-from-the-old-faq]

The single FAQ page was retired. Each question now lives in the section it actually belongs to:

| Old FAQ question                                                            | New home                                                                                                              |
| --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| *How do I get a list of installed applications?*                            | [Manage installed applications](/how-to/manage-installed-applications)                                                |
| *How do I uninstall a Pear application?*                                    | [Manage installed applications](/how-to/manage-installed-applications)                                                |
| *Where is the Pear application stored?*                                     | [Storage and distribution](/explanation/storage-and-distribution)                                                     |
| *Can Pear be used with X language?*                                         | [Runtime and languages](/explanation/runtime-and-languages)                                                           |
| *How do I write an application once that runs on desktop, mobile, etc.?*    | [Runtime and languages](/explanation/runtime-and-languages) · [One core, many platforms](/explanation/bare-on-native) |
| *Is Bare a fork of Node? Can I use npm modules?*                            | [Inside Bare](/explanation/bare-runtime)                                                                              |
| *Can Bare run on iOS or Android?*                                           | [One core, many platforms](/explanation/bare-on-native)                                                               |
| *How is my application distributed? Do I have to keep `pear seed` running?* | [Storage and distribution](/explanation/storage-and-distribution)                                                     |
| *Why is NPM used for dependencies?*                                         | [Dependencies and network](/explanation/dependencies-and-network)                                                     |
| *How do I distribute a binary version of my application?*                   | [Distribute as a binary](/how-to/operate-an-app/build-and-package/distribute-as-binary)                               |
| *Can peers know my IP address when using `hyperswarm`?*                     | [Dependencies and network](/explanation/dependencies-and-network)                                                     |

{/* Writing a new explanation? See [Diátaxis on explanation](https://diataxis.fr/explanation/)—discursive, comparative, opinionated where it helps. Don't list APIs; that's reference. Don't tell readers to do anything; that's how-to. */}


# How Pear and Bare fit together



Pear is the platform people see: a runtime, a CLI, and over-the-air updates for peer-to-peer apps. [Bare](/explanation/bare-runtime) is the engine underneath it. They sit at different layers, and knowing which layer you're working at makes the rest of these docs easier to navigate.

This page lays out the layers, bottom to top, and shows where each library you'll meet elsewhere belongs.

The layers at a glance [#the-layers-at-a-glance]

<Mermaid
  chart="flowchart TB
  subgraph APPS[&#x22;Apps—one core, many UI hosts&#x22;]
    direction LR
    desktop[&#x22;Desktop<br/>Electron + pear-electron&#x22;]
    terminal[&#x22;Terminal<br/>standalone Bare binary&#x22;]
    mobile[&#x22;Mobile<br/>native shell + worklet&#x22;]
  end
  subgraph PEAR[&#x22;Pear platform&#x22;]
    pear[&#x22;pear-runtime · pear-* modules · Pear CLI · OTA updates&#x22;]
  end
  subgraph BLOCKS[&#x22;P2P building blocks—JavaScript, run on Bare&#x22;]
    blocks[&#x22;Hypercore · Hyperbee · Hyperdrive · Autobase · Hyperswarm · HyperDHT · Corestore&#x22;]
  end
  subgraph USERLAND[&#x22;Bare userland—bare-* modules&#x22;]
    direction LR
    std[&#x22;Standard library<br/>bare-fs · bare-tcp · bare-crypto · bare-http1 …&#x22;]
    embed[&#x22;Embedding & native<br/>bare-kit · react-native-bare-kit<br/>RPC seam: bare-rpc · hyperschema&#x22;]
    build[&#x22;Build & bundle<br/>bare-pack · bare-bundle · bare-make&#x22;]
  end
  subgraph RUNTIME[&#x22;Bare runtime&#x22;]
    rt[&#x22;module system (CJS/ESM) · native addons · threads · Bare global + lifecycle&#x22;]
  end
  subgraph NATIVE[&#x22;Native foundations (C)&#x22;]
    nat[&#x22;libjs / libjsc (V8 / JSC ABI) · libuv (event loop) · libudx (UDP)&#x22;]
  end
  APPS --> PEAR --> BLOCKS --> USERLAND --> RUNTIME --> NATIVE
  mobile -. embeds .-> embed
  terminal -. compiled by .-> build"
/>

Each layer runs on the one beneath it. Read from the bottom up, it's a story about how raw C bindings become a peer-to-peer app you can install.

The engine room: native foundations and the Bare runtime [#the-engine-room-native-foundations-and-the-bare-runtime]

At the very bottom are C libraries: [`libjs`](https://github.com/holepunchto/libjs) (and its JavaScriptCore-backed sibling [`libjsc`](https://github.com/holepunchto/libjsc)) give an engine-independent, ABI-stable way to talk to a JavaScript engine; [`libuv`](https://github.com/libuv/libuv) provides the asynchronous I/O event loop; [`libudx`](https://github.com/holepunchto/libudx) carries the reliable UDP streams the networking stack rides on.

[Bare](/explanation/bare-runtime) sits directly on top. It's a small, embeddable JavaScript runtime that adds only what those C primitives can't supply on their own: a module system (with CommonJS/ESM interop), a native-addon loader, and lightweight threads. Everything else is left to userland—which is the next layer up.

Bare userland: the bare-* modules [#bare-userland-the-bare--modules]

Bare ships almost no standard library. The familiar runtime surface—file system, sockets, crypto, HTTP—lives in installable [`bare-*` modules](/reference/modules/bare-modules) you opt into. The same layer holds two other families that matter for cross-platform apps:

* **Embedding & native** ([`bare-kit`](/reference/bare/bare-kit), [`react-native-bare-kit`](/reference/bare/bare-kit), and the typed RPC seam of [`bare-rpc`](/reference/modules/bare-modules) + [`hyperschema`](https://github.com/holepunchto/hyperschema)) let a native app run a Bare core on a background thread. See [One core, many platforms](/explanation/bare-on-native).
* **Build & bundle** (`bare-pack`, `bare-bundle`, `bare-make`, `bare-build`) turn a Bare program and its dependencies into an embeddable bundle or a standalone executable.

The peer-to-peer building blocks [#the-peer-to-peer-building-blocks]

The libraries Pear is famous for—[Hypercore](/reference/building-blocks/hypercore), [Hyperbee](/reference/building-blocks/hyperbee), [Hyperdrive](/reference/building-blocks/hyperdrive), [Autobase](/reference/building-blocks/autobase), [Hyperswarm](/reference/building-blocks/hyperswarm), [HyperDHT](/reference/building-blocks/hyperdht), and [Corestore](/reference/helpers/corestore)—are ordinary JavaScript modules. They have no special status in the runtime; they run *on* Bare like any other dependency. That's why the same storage and networking code works unchanged whether it's hosted by Electron on the desktop or a worklet on a phone.

The Pear platform [#the-pear-platform]

[Pear](/) is the layer that turns those building blocks into a product: [`pear-runtime`](/reference/pear/runtime) spawns and updates your app, the [`pear-*` modules](/reference/modules/pear-modules) supply application services, and the [Pear CLI](/reference/pear/cli) stages, seeds, and releases it. Pear is built *on* Bare and the building blocks—it doesn't replace them.

Apps: one core, many UI hosts [#apps-one-core-many-ui-hosts]

At the top are the apps—[Keet](https://keet.io), [PearPass](https://pass.pears.com), and whatever you build. The recommended shape splits an app into a portable JavaScript **core** (peer-to-peer logic and storage) and a thin **UI host** that changes per platform: Electron on desktop, a native shell on mobile, a standalone binary in the terminal. The core is the same code everywhere; only the host swaps. That split is the subject of [Runtime and languages](/explanation/runtime-and-languages) and [One core, many platforms](/explanation/bare-on-native).

See also [#see-also]

* [Inside Bare](/explanation/bare-runtime)—what the runtime layer actually adds.
* [One core, many platforms](/explanation/bare-on-native)—how the portable core reaches mobile and native apps.
* [Runtime and languages](/explanation/runtime-and-languages)—why the stack is JavaScript and how other languages join in.
* [Bare modules](/reference/modules/bare-modules)—the catalog of `bare-*` userland modules.
* [Pear modules](/reference/modules/pear-modules)—the `pear-*` libraries at the platform layer.


# Pear desktop application architecture



This page explains **why** a production-style Pear **Electron** app usually separates three concerns:

1. **over-the-air (OTA) updates**,
2. **persistent peer-to-peer storage**, and
3. **Bare workers** behind a single IPC stream.

Read it if you are sketching your own main/renderer/worker split or comparing a full runtime setup to the minimal [getting started chat](/getting-started/build-a-peer-to-peer-chat/build-a-peer-to-peer-chat).

The short version [#the-short-version]

The pattern optimizes to:

* **ship new builds without a central server**
* **keep replication-capable storage beside the app**
* **keep native P2P modules out of the renderer**

A [**Bare worker**](/explanation/workers) owns the [`pear-runtime`](/reference/pear/runtime) instance together with [Hyperswarm](/reference/building-blocks/hyperswarm), [Hypercore](/reference/building-blocks/hypercore), and the [OTA updater](/reference/pear/runtime#updates); Electron's [main process](#process-model) is a thin shell that spawns the worker and forwards [IPC](/explanation/workers#the-ipc-contract); the [renderer](#process-model) stays a normal web view. Updates flow when the [**application Hyperdrive**](/reference/building-blocks/hyperdrive) changes; the runtime signals the UI, then swaps paths on disk so the [**next process start**](#updates) runs the new code.

<Callout type="info">
  The official [`hello-pear-electron`](https://github.com/holepunchto/hello-pear-electron) template uses this worker-hosted shape, and the [getting started production-shape part](/getting-started/build-a-peer-to-peer-chat/reshape-into-a-production-app) follows it—running the `pear-runtime` updater in its own dedicated Bare worker so update traffic never blocks the chat worker.
</Callout>

Process model [#process-model]

<Mermaid
  chart="flowchart LR
  subgraph Electron
    R[Renderer]
    M[Main process]
  end
  W[Bare worker]

  R <-->|preload / IPC| M
  M <-->|PearRuntime.run duplex| W"
/>

The renderer does not load `hyperswarm`, `hypercore`, or other Bare-oriented modules directly. The main process starts the worker with [`PearRuntime.run`](/reference/pear/runtime#running-workers) (or the instance method [`pear.run`](/reference/pear/runtime#running-workers)) and forwards bytes between the worker’s [`Bare.IPC`](/reference/pear/runtime#running-workers) stream and whatever bridge you expose to the renderer.

Updates [#updates]

An **update** is triggered when a **seeded application drive** gains new writes: the replicated [Hyperdrive](/reference/building-blocks/hyperdrive) behind your `pear://` link reflects a new staged or provisioned build. The runtime emits **`updating`** while it syncs, then **`updated`** when the new bundle is ready. These events are emitted on the runtime's [`pear.updater`](/reference/pear/runtime#updates) sub-object—handlers attach with `pear.updater.on('updating')` / `pear.updater.on('updated')`, and the staged update is applied with `pear.updater.applyUpdate()`.

After `updated`, a common shell **repoints the active application path** to the freshly synced build and removes the old tree from disk so the **next start** runs the new code. That matches OTA expectations: sync in the background, switch on restart (or after your UI explicitly restarts).

<Callout type="info">
  Disable updates per run (`--no-updates`) or with [`package.json` `updates: false`](/reference/pear/runtime#disabling-updates) during local development so a seeded link does not replace your working tree mid-session.
</Callout>

Storage [#storage]

The runtime’s **`dir`** option is the root for **peer-to-peer and local application data**. In production that usually maps to per-OS application support directories; in development many teams use a **separate dev default** or a flag. [`pear.storage`](/reference/pear/runtime#storage) is the string you pass into [`Corestore`](/reference/helpers/corestore) so every core shares one coherent on-disk layout.

<Callout type="info">
  Passing **`--storage /path`** (or equivalent) spins up an **isolated Corestore**—the same idea as running two app instances on two machines: different storage roots, no key collisions.
</Callout>

Workers [#workers]

**Application P2P logic**—swarms, cores, drives—belongs in the worker entrypoint. Arguments you pass from `pear.run('./workers/main.js', [pear.storage, …])` show up as [`Bare.argv`](/reference/pear/api#bare-argv) inside the worker (`argv[0]`/`argv[1]` are reserved; **`argv[2]`** is the first user argument, which is why sample apps often pass storage at index `2`).

Rule of thumb: **main = shell + IPC**, **worker = data plane**, **renderer = view**.

Where this differs from the minimal tutorial [#where-this-differs-from-the-minimal-tutorial]

The [getting started chat](/getting-started/build-a-peer-to-peer-chat/build-a-peer-to-peer-chat) walkthrough uses [`PearRuntime.run()`](/reference/pear/runtime#running-workers) so you can paste a tiny worker without configuring `upgrade` or `dir`. A shipped desktop app switches on the **full `new PearRuntime({ ... })` constructor** so OTA, storage, and the updater share one runtime object—the shape in the [`pear-runtime` reference](/reference/pear/runtime). In the official [`hello-pear-electron`](https://github.com/holepunchto/hello-pear-electron) template, that constructor runs inside the Bare worker, keeping the main process a thin proxy; the [getting started production-shape part](/getting-started/build-a-peer-to-peer-chat/reshape-into-a-production-app) does the same, running the updater in its own dedicated Bare worker.

Where to go next [#where-to-go-next]

* [Start from the hello-pear-electron template](/getting-started/from-a-template/start-from-hello-pear-electron)—a hands-on tour of this architecture in the official boilerplate.
* [Release pipeline](/explanation/deployment-releasing-apps-p2p)—stage, provision, multisig, and diagrams for moving builds between links.
* [Release pipeline glossary](/explanation/deployment-releasing-apps-p2p#glossary)—terminology in one table.
* [Storage and distribution](/explanation/storage-and-distribution)—Pear-wide layout versus per-app `dir`.
* [Deploy your application](/how-to/operate-an-app/manual-deployment/deployment)—when you are ready to run commands.

<Callout type="info">
  **Related documentation**

  **Getting Started:** [Part 1: Chat](/getting-started/build-a-peer-to-peer-chat/build-a-peer-to-peer-chat) · [Part 2: Production-shaped](/getting-started/build-a-peer-to-peer-chat/reshape-into-a-production-app) · [Part 3: Ship](/getting-started/build-a-peer-to-peer-chat/ship) · [Part 4: Update](/getting-started/build-a-peer-to-peer-chat/update)

  **Operating an app**

  * [Build desktop distributables](/how-to/operate-an-app/build-and-package/build-desktop-distributables)
  * [Desktop release npm scripts](/reference/ci-and-release/desktop-release-npm-scripts)
  * [Distribute as a binary](/how-to/operate-an-app/build-and-package/distribute-as-binary)
  * [Manage installed applications](/how-to/manage-installed-applications)
  * [Troubleshoot desktop releases](/how-to/operate-an-app/manual-deployment/troubleshoot-desktop-releases)
  * [Troubleshoot common issues](/how-to/troubleshooting)
</Callout>


# Peer-to-peer, demystified



import { Cards, Card } from 'fumadocs-ui/components/card'

Pear applications replicate data and connect to one another without a central server. Peers exchange bytes directly over encrypted streams; there is no single host that routes every message or stores every copy. That model changes how discovery, connectivity, and privacy work compared with a traditional client–server application—but it does not remove the need for careful application design.

<Callout type="info">
  This page explains networking concepts. For step-by-step connection guides, see [Connect two peers by key with HyperDHT](/how-to/connect-to-peers/connect-two-peers-by-key-with-hyperdht) and [Connect to many peers by topic with Hyperswarm](/how-to/connect-to-peers/connect-to-many-peers-by-topic-with-hyperswarm).
</Callout>

<Cards>
  <Card title="Peer-to-peer networking with Holepunch (video)" href="https://www.youtube.com/watch?v=QWWHKLyCFTU" external />
</Cards>

What changes without a server [#what-changes-without-a-server]

In a client–server design, clients know where to connect: a hostname or IP address, often fronted by a load balancer. In Pear, **peers are identified by cryptographic public keys**, not by fixed network locations. A peer can move between Wi‑Fi networks, cellular connections, or countries and still be reachable at the same key.

Replication and chat still need **at least one peer online** with a copy of the data you want—Pear does not magically materialize files from nowhere. What changes is *who* can serve that copy: any participant in the swarm, not only the original author.

What does **not** change: you still need to think about availability, authorization, and what metadata leaks at the transport layer.

<Callout type="info">
  * [Storage and distribution](/explanation/storage-and-distribution)—how application bundles and user data reach peers over the same primitives.
  * [Dependencies and network](/explanation/dependencies-and-network)—what peers can infer from your IP when you join a swarm.
</Callout>

Hole punching and NAT traversal [#hole-punching-and-nat-traversal]

Most devices sit behind home routers or carrier-grade network address translation (NAT). Two peers cannot open a Transmission Control Protocol (TCP) connection to each other simply by knowing each other's keys—neither side has a stable, publicly routable address that the other can dial first.

**User Datagram Protocol (UDP) hole punching** coordinates both peers through a rendezvous point so that each opens a path through its local firewall. Once the "hole" exists, Pear's transport can carry encrypted traffic over it. Hole punching works on most consumer networks; it is not guaranteed on every corporate or symmetric-NAT setup, which is why Pear also supports relay paths when direct connectivity fails.

[HyperDHT](#hyperdht-discovery-and-encrypted-connections) implements this discovery and connection machinery. You rarely call hole punching directly; you create a DHT node or join a [Hyperswarm](/reference/building-blocks/hyperswarm) topic and the stack handles traversal.

HyperDHT: discovery and encrypted connections [#hyperdht-discovery-and-encrypted-connections]

[HyperDHT](/reference/building-blocks/hyperdht) is a distributed hash table. It is the layer that finds peers and establishes **end-to-end encrypted** connections using Noise streams (via [Secretstream](/reference/helpers/secretstream)).

Core mechanisms:

1. **Peer identification**—Connections are addressed by public key, not IP address. Location and network changes do not invalidate identity.
2. **Hole punching**—UDP techniques to connect through NATs and firewalls on typical networks.
3. **Encrypted streams**—Every connection is encrypted; intermediaries see traffic volume and endpoints, not payload.
4. **Bootstrapping**—Default bootstrap nodes help a new node join the public DHT; isolated networks can use custom bootstrap lists.
5. **Announcement and discovery**—Peers announce themselves under 32-byte topics; others look up who is listening on a topic. Peers with a known public key can also connect directly without topic lookup.

<Callout type="info">
  See [Connect two peers by key with HyperDHT](/how-to/connect-to-peers/connect-two-peers-by-key-with-hyperdht) for a walkthrough of how to use HyperDHT.
</Callout>

HyperDHT also supports limited mutable and immutable storage in the DHT itself. Most Pear applications instead replicate structured data over [Hypercore](/reference/building-blocks/hypercore) once a connection exists; the DHT's primary job is **finding and connecting**, not long-term storage.

Hyperswarm: topic-based connection management [#hyperswarm-topic-based-connection-management]

[Hyperswarm](/reference/building-blocks/hyperswarm) wraps [HyperDHT](/reference/building-blocks/hyperdht) with a higher-level API oriented around **topics**—arbitrary 32-byte identifiers, often a [Hypercore](/reference/building-blocks/hypercore)'s `discoveryKey`. Where HyperDHT exposes servers, clients, announce streams, and lookup streams, Hyperswarm exposes `join`, `leave`, and a single `connection` event.

<Callout type="info">
  [Connect to many peers by topic with Hyperswarm](/how-to/connect-to-peers/connect-to-many-peers-by-topic-with-hyperswarm) for a walkthrough of how to use Hyperswarm.
</Callout>

Hyperswarm adds:

* **Automatic reconnection** when peers drop off the network.
* **Connection limits and firewall hooks** to cap fan-out or reject unwanted keys.
* **Client/server roles per topic**—a peer can announce only, discover only, or both.
* **Direct peer joins** via `joinPeer(publicKey)` when you already know whom to reach.

For replication workflows—chat rooms, file sync, application updates—Hyperswarm is usually the right default: you join the discovery key of the core or drive you care about and let the swarm maintain connections. HyperDHT remains the right choice when you need fine-grained control over server lifecycle, custom DHT storage, or minimal dependencies.

Choosing between HyperDHT and Hyperswarm [#choosing-between-hyperdht-and-hyperswarm]

| Concern              | [HyperDHT](/reference/building-blocks/hyperdht) | [Hyperswarm](/reference/building-blocks/hyperswarm)                            |
| -------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------ |
| API surface          | Low-level: nodes, servers, sockets              | High-level: topics, connections                                                |
| Reconnection         | Your responsibility                             | Built in                                                                       |
| Typical use          | Custom protocols, direct key connections        | [Hypercore](/reference/building-blocks/hypercore) replication, multi-peer apps |
| Underlying transport | UDX + hole punching                             | Same (uses HyperDHT internally)                                                |

If you are replicating a Hypercore or [Hyperdrive](/reference/building-blocks/hyperdrive), start with Hyperswarm unless you have a specific reason to manage DHT nodes yourself.

See also [#see-also]

* [Connect two peers by key with HyperDHT](/how-to/connect-to-peers/connect-two-peers-by-key-with-hyperdht)—minimal two-peer connection walkthrough.
* [Connect to many peers by topic with Hyperswarm](/how-to/connect-to-peers/connect-to-many-peers-by-topic-with-hyperswarm)—topic-based discovery and chat.
* [Replicate and persist with Hypercore](/how-to/store-and-replicate/replicate-and-persist-with-hypercore)—persistence once peers are connected.
* [Dependencies and network](/explanation/dependencies-and-network)—IP disclosure and NPM's role at install time.
* [From append-only logs to files](/explanation/from-logs-to-files)—how replicated data is structured above the transport layer.
* [HyperDHT reference](/reference/building-blocks/hyperdht)—full API.
* [Hyperswarm reference](/reference/building-blocks/hyperswarm)—full API.


# Runtime and languages



Pear applications are JavaScript programs. The runtime under them is **[Bare](/explanation/bare-runtime)**, a small embeddable JavaScript runtime that strips the assumptions Node.js carries about being a server. This page explains why the language story looks the way it does, how non-JavaScript code joins in, and what the recommended app shape is when you want one codebase to run on desktop, mobile, and terminal.

<Callout type="info">
  For where Bare sits relative to Pear, see [How Pear and Bare fit together](/explanation/pear-and-bare).
</Callout>

Why JavaScript [#why-javascript]

Two pragmatic reasons:

1. **Web heritage.** The peer-to-peer libraries Pear is built on ([Hypercore](/reference/building-blocks/hypercore), [Hyperdrive](/reference/building-blocks/hyperdrive), [Hyperswarm](/reference/building-blocks/hyperswarm)) are mature JavaScript modules with millions of downloads. Reusing them on the desktop and on mobile through a single language eliminates a translation layer.

2. **Bare keeps it small.** Bare ships without Node's standard library opinions—no `fs.read` on a URL, no built-in `http` module, no Worker baggage. That makes it cheap to embed in mobile apps, desktop shells, and constrained terminal environments alike. The Pear runtime adds the bits applications actually need on top.

If you're coming from Node.js, the surface looks similar but isn't identical—see [Bare modules](/reference/modules/bare-modules) for the exact set of standard libraries available, and the [Node.js compatibility](/reference/modules/bare-modules#nodejs-compatibility) section for a builtin-by-builtin mapping to the corresponding `bare-*` modules. The [`bare-node`](https://github.com/holepunchto/bare-node) shim maps many Node.js builtins onto their Bare equivalents, easing the port.

Other languages: native addons [#other-languages-native-addons]

For code that JavaScript can't naturally express—tight cryptography loops, codec work, hardware access—Bare loads native addons. The [`bare-addon`](https://github.com/holepunchto/bare-addon) template is the starting point: write the addon in C, C++, Rust, or any language with a C-compatible ABI, expose it through Bare's addon API, and call it from JavaScript like any module.

For languages that compile to JavaScript (TypeScript being the obvious one) the path is unchanged: compile to JS, then point the application's [`main` field or HTML `<script>` entrypoint](/reference/pear/configuration#packagejson) at the compiled output.

To build native addons for every platform you ship to, the [Bare native-addon prebuild actions](/reference/ci-and-release/github-actions#bare-native-addon-prebuilds) (`compile-prebuilds`, `merge-prebuilds`, and friends) run `bare-make` across a CI matrix and collect the prebuilt binaries.

One codebase, many platforms: the Pear-end pattern [#one-codebase-many-platforms-the-pear-end-pattern]

The recommendation for cross-platform Pear apps is to split the code into two halves:

* **Pear-end**—the peer-to-peer logic, business rules, and storage. Runs in a Bare worker.
* **UI**—the platform-specific presentation. Talks to the Pear-end over an inter-process communication (IPC) stream.

Because the Pear-end never imports DOM APIs and never assumes a particular UI framework, it's portable across desktop (Electron), mobile (React Native via Bare iOS / Bare Android), and terminal. Only the UI half changes per platform—it gets a fresh implementation each time, but it's also the cheap half: layout, not logic. On mobile the worklet and the typed seam between the two halves are what carry this split—see [One core, many platforms](/explanation/bare-on-native).

This split is what powers Keet's identical experience across phones, laptops, and terminals: one Pear-end, three UIs.

**[Pear OTA](/reference/pear/runtime)** (the `pear-runtime` library) is what wires the two halves together: the UI host embeds it to spawn the Pear-end as a Bare worker, manage peer-to-peer storage, and apply over-the-air updates. It targets desktop; on mobile the same role is filled by [`pear-mobile`](https://www.npmjs.com/package/pear-mobile), the embeddable Pear runtime for mobile applications. If you have an app on the removed global `pear run` API, see [Migrate from pear run to Pear OTA](/how-to/operate-an-app/migration).

Workers carry the Pear-end [#workers-carry-the-pear-end]

In a desktop Pear app the Pear-end runs as a [Bare](/reference/modules/bare-modules) worker spawned by the Electron main process. The worker owns the swarm identity, the [Corestore](/reference/helpers/corestore), and every peer-to-peer protocol the app implements; the renderer reaches it through a single IPC duplex stream. The same shape applies on mobile and terminal—only the host that spawns the worker changes.

See [Workers](/explanation/workers) for the pattern in full—what crosses the IPC boundary, why native addons live on the worker side, and how `Bare.argv` lines up with `process.argv`.

See also [#see-also]

* [How Pear and Bare fit together](/explanation/pear-and-bare)—the full layering, from native C foundations up to apps.
* [Inside Bare](/explanation/bare-runtime)—what the runtime adds, its lifecycle, and why it's minimal.
* [One core, many platforms](/explanation/bare-on-native)—running the Pear-end in a worklet behind a typed RPC seam.
* [Workers](/explanation/workers)—the host-and-worker split this page calls the "Pear-end."
* [`pear-runtime` reference](/reference/pear/runtime)—the JavaScript API exposed inside a running Pear app.
* [Bare modules](/reference/modules/bare-modules)—the standard library available to both halves of a Pear app.
* [Storage and distribution](/explanation/storage-and-distribution)—what's running underneath both halves.


# Storage and distribution



Pear stores everything—the runtime itself, every installed application, and each application's persistent data—under a single per-OS directory. New versions of an application reach users through the same peer-to-peer swarm that distributes data inside the application; there is no central server. This page explains the on-disk layout and the distribution model, and the trade-offs that motivate both.

On-disk layout [#on-disk-layout]

The top-level directory depends on the operating system:

| OS      | Pear directory                       |
| ------- | ------------------------------------ |
| macOS   | `~/Library/Application Support/pear` |
| Linux   | `~/.config/pear`                     |
| Windows | `%USERPROFILE%\AppData\Roaming\pear` |

Inside that directory:

* **`current`**—a symlink to the Pear platform binary that's currently active. The platform itself is delivered the same way an application is: by the swarm. Updating Pear means re-pointing this symlink.
* **`corestores/`**—every installed application, stored as a [Corestore](/reference/helpers/corestore) of [Hyperdrives](/reference/building-blocks/hyperdrive). One corestore per application; one Hyperdrive per logical bundle (binaries plus assets).
* **`app-storage/`**—application-private persistent data, keyed by the application's `dkey` (derived from its `pear://` link). This is where chat history, drafts, settings, and user content live. Each subdirectory is its own corestore again, scoped to one application.

In a running application, the path you'd write to is exposed as [`Pear.config.storage`](/reference/pear/api#pearconfig-object); the platform root is [`Pear.config.pearDir`](/reference/pear/api#pearconfig-object).

A practical consequence of this layout: you can't browse the on-disk files with Finder or a file manager and expect to see the application's actual content. Everything is encoded inside hyperdrives. To read what an installed application actually distributed, use [`pear dump`](/reference/pear/cli#pear-dump-flags-link-dir)—it materializes the hyperdrive's contents back into ordinary files.

Application storage in development vs production [#application-storage-in-development-vs-production]

The directories above are the **platform**'s storage. An **application** embedded in [Electron](/getting-started/build-a-peer-to-peer-chat/reshape-into-a-production-app)—the `dir` field passed to `new PearRuntime({ dir, ... })`—lives in a different per-OS location, and it differs between development and packaged builds:

| OS      | Packaged                                      | Development (no packaged app) |
| ------- | --------------------------------------------- | ----------------------------- |
| macOS   | `~/Library/Application Support/<productName>` | `<tmpdir>/pear/<productName>` |
| Linux   | `~/.config/<productName>`                     | `<tmpdir>/pear/<productName>` |
| Windows | `%USERPROFILE%\AppData\Local\<productName>`   | `<tmpdir>/pear/<productName>` |

The convention comes from the getting-started [pear-chat `getStorageDir()` helper](/getting-started/build-a-peer-to-peer-chat/reshape-into-a-production-app): when `app.isPackaged` is `false`, the dir falls back to `os.tmpdir()`; otherwise it picks the OS-appropriate user-data folder. (In the [`hello-pear-electron`](https://github.com/holepunchto/hello-pear-electron/blob/main/electron/main.js) template the same logic lives in `getWorker()`, which passes `dir` to the Bare worker that constructs the runtime.) The Pear runtime exposes that dir as `pear.storage`, which the worker passes to [Corestore](/reference/helpers/corestore) as `storage`.

On Windows the docs and examples deliberately use `AppData\Local` (machine-local), not the `AppData\Roaming` the upstream template defaults to: a [Corestore](/reference/helpers/corestore) holds a per-device peer keypair and can grow large, so it should stay machine-bound rather than sync across roaming profiles.

Running multiple application instances [#running-multiple-application-instances]

Because [Corestore](/reference/helpers/corestore) takes an exclusive file-system lock on its directory, two copies of the same packaged app cannot share `dir`. To run a second local instance you point it at a separate folder with the `--storage` flag (recognised by every Pear-shaped Electron app that wires `paparam` like the template):

```bash
# development
npm start -- --storage /tmp/custom/storage

# packaged macOS
open -n PearChat.app --args --storage /tmp/custom/storage

# packaged Linux
./PearChat.AppImage --storage /tmp/custom/storage

# packaged Windows
.\PearChat.exe --storage C:\tmp\custom\storage
```

A second `--storage` instance behaves exactly like an instance running on another machine: a separate [Corestore](/reference/helpers/corestore), a separate [Hyperswarm](/reference/building-blocks/hyperswarm) presence, the same `pear://` link. This is the simplest way to test peer-to-peer flows locally without involving a second device.

How distribution works [#how-distribution-works]

A Pear application's `pear://<key>` link is a stable identifier the swarm can route on. When you publish a new version with `pear stage` and announce it with `pear seed`, you're appending to the application's [Hyperdrive](/reference/building-blocks/hyperdrive)—peers tracking that drive pick up the new version while they're connected to the swarm, replicating only the blocks they actually need rather than the whole drive.

The swarm replicates lazily: a peer that runs your app becomes a source for it. Once you have a few users running an application, distribution scales without any central infrastructure on your end. The original author can go offline and the application keeps spreading, as long as at least one peer with a copy is reachable.

The `pear seed <link>` command keeps a peer online and announcing as a source for a given link. It's not strictly required—any peer running the app contributes—but it's the recommended way to guarantee availability for a release. A handful of seeders is usually enough; very popular apps reach the long-tail-availability sweet spot quickly.

The same model applies to the Pear platform itself: there's no Pear download server, only a swarm.

Installing applications [#installing-applications]

For a long time the way to launch a Pear application was `pear run pear://<key>`—the runtime fetched the bundle from the swarm and ran it in place.

That runtime capability has been unbundled from the CLI: `pear run` was **removed in Pear v3** in favour of the embeddable **[Pear OTA](/reference/pear/runtime)** (`pear-runtime`) library, so any JavaScript project can carry peer-to-peer over-the-air updates without depending on the CLI. The CLI's remaining focus is deployment and, now, installation. The full rationale is in [Pear Evolution](https://pears.com/news/pear-evolution/).

Installing replaces "run from a link" with a first-class on-disk install. [`pear install pear://<key>`](/reference/pear/cli#pear-install) pulls an application built with [`pear build`](https://github.com/holepunchto/hello-pear-electron#deploying) from the swarm and sets it up locally, the same way the platform binary arrives—there is still no download server, only peers. The command works for both applications and standalone binaries.

```bash
# install an application peer-to-peer
pear install pear://<key>
```

<Callout type="info">
  `pear install` ships with the Pear v3 CLI, provided by the standalone [`pear-install`](https://www.npmjs.com/package/pear-install) module—which also works directly via `npx pear-install pear://<key>` on machines without Pear.
</Callout>

The same mechanism bootstraps Pear itself. As of v3 the CLI is a standalone binary that updates over the swarm through **[Pear OTA](/reference/pear/runtime)** (`pear-runtime`), so `npx pear-install` installs `pear`—collapsing the install path for the platform and for the apps it distributes into one model. A mobile counterpart, [`pear-mobile`](https://www.npmjs.com/package/pear-mobile), carries the same over-the-air update story to iOS and Android.

Because installed applications already live as [Corestores](/reference/helpers/corestore) of [Hyperdrives](/reference/building-blocks/hyperdrive) under the platform directory (see [On-disk layout](#on-disk-layout)), an install is just another entry in that tree, and updates flow through the same lazy swarm replication described above.

When seeding is not enough [#when-seeding-is-not-enough]

Self-seeding with `pear seed` only covers cores you hold locally and requires an always-on process per application. Private rooms, direct-message threads, and offline authors create gaps where no participant seeds the data a new peer needs.

<Callout type="info">
  [Availability and blind peering](/explanation/availability-and-blind-peering) describes blind peers—dedicated replicators that cache cores without reading them—as one way to close that gap.
</Callout>

Why this shape [#why-this-shape]

* **No infrastructure.** The author of an application doesn't run servers, doesn't pay for bandwidth, doesn't have a single point of failure. The cost of serving the app is amortized across users.
* **Versioning is built in.** Each [Hyperdrive](/reference/building-blocks/hyperdrive) is backed by an append-only [Hypercore](/reference/building-blocks/hypercore) log, so an application's history is preserved automatically and rollbacks are routine—even though the drive itself still supports deletes and updates on top of that log.
* **Same primitives for code and data.** Application storage and the application itself are both corestores, which means the same replication, encryption, and update mechanics apply to both.

See also [#see-also]

* [Pear desktop application architecture](/explanation/pear-desktop-architecture)—how a typical Electron app maps `dir`, workers, and OTA into that layout.
* [Release pipeline](/explanation/deployment-releasing-apps-p2p)—stage, provision, multisig, and release lines for shipping desktop builds.
* [Manage installed applications](/how-to/manage-installed-applications)—listing and dropping local application storage.
* [Deploy your application](/how-to/operate-an-app/manual-deployment/deployment)—staging and seeding new releases.
* [Hypercore](/reference/building-blocks/hypercore)—the append-only log every other primitive composes.
* [Hyperdrive](/reference/building-blocks/hyperdrive)—file-system layer used for application bundles and assets.
* [Corestore](/reference/helpers/corestore)—the storage manager whose on-disk format backs every installed application and app-storage directory.


# Using Bare on its own



Most of these docs assume you're building on [Pear](/), the peer-to-peer platform. But [Bare](/explanation/bare-runtime)—the runtime underneath Pear—is a general-purpose JavaScript runtime in its own right, and you can adopt it on its own, with no peer-to-peer or Pear machinery at all. This page is the entry point for that runtime-only path.

When to reach for Bare alone [#when-to-reach-for-bare-alone]

Use standalone Bare when you want:

* **A runtime to embed in a native app.** Run JavaScript logic inside an iOS, Android, or React Native app on a background thread—the "run JavaScript everywhere" case—via [Bare Kit](/reference/bare/bare-kit) worklets.
* **A modular Node.js alternative.** Bare is mobile-first and ships almost no standard library; you opt into only the [`bare-*` modules](/reference/modules/bare-modules) you actually use, keeping bundles small.
* **A single standalone executable.** Compile a CLI, service, or daemon into one binary with no Node.js, Bare, or Pear install required on the user's machine.

If instead you're building a peer-to-peer app—storage, replication, swarms, over-the-air updates—start with Pear rather than Bare directly: [Getting started](/getting-started) and [How Pear and Bare fit together](/explanation/pear-and-bare) show how Bare fits underneath it.

The runtime-only path [#the-runtime-only-path]

**Understand it**

* [Inside Bare](/explanation/bare-runtime)—what the runtime is, its lifecycle, and why its standard library is opt-in.
* [One core, many platforms](/explanation/bare-on-native)—embedding a Bare core in native apps via worklets and a typed RPC seam.

**Look it up**

* [Bare runtime API](/reference/bare/runtime)—the `Bare` global: process properties, lifecycle, addons, threads.
* [Bare CLI](/reference/bare/cli)—run a script or start a REPL with the `bare` command.
* [Bare Kit](/reference/bare/bare-kit)—the Worklet and IPC API for iOS, Android, and React Native.
* [Bare modules](/reference/modules/bare-modules)—the `bare-*` standard library.

**Do it**

* [Embed Bare in a React Native app](/how-to/run-on-native/embed-bare-in-react-native)
* [Type a native RPC bridge](/how-to/run-on-native/type-a-native-rpc-bridge)
* [Bundle a Bare app](/how-to/run-on-native/bundle-a-bare-app)

Where Bare and Pear meet [#where-bare-and-pear-meet]

Even used on its own, Bare shares an ecosystem with Pear. The peer-to-peer [building blocks](/reference/building-blocks/hypercore) are ordinary JavaScript modules that run on Bare, and tools like [`compact-encoding`](/reference/helpers/compact-encoding) and `hyperschema` are used on both sides. So if a standalone Bare app later grows peer-to-peer features, the same core moves onto Pear unchanged—see [How Pear and Bare fit together](/explanation/pear-and-bare).


# Workers



A Pear application splits into two halves:

1. a UI (the renderer, terminal, or mobile shell) and
2. a **worker** that owns everything peer-to-peer.

The worker is a [Bare](/reference/modules/bare-modules) process the host spawns at startup, and it's where [Hyperswarm](/reference/building-blocks/hyperswarm), [Corestore](/reference/helpers/corestore), [Hypercore](/reference/building-blocks/hypercore), and any native addons run.

The two halves only ever see each other through a single [Inter-Process Communication (IPC)](/explanation/workers#the-ipc-contract) duplex stream.

<Callout type="info">
  This page is about the pattern, not the API. For the call signatures and IPC stream type, see [Running workers in the runtime reference](/reference/pear/runtime#running-workers).
</Callout>

Workers as a local backend [#workers-as-a-local-backend]

The mental model is **the worker is your application's local backend**. The renderer is a client to that backend in the same way a web app is a client to a remote API—it makes requests, it gets streaming events back, it doesn't own state. The difference is the "server" is a sibling process on the same machine, started and stopped by the host.

In a desktop Pear app the host is the Electron main process; in a mobile Pear app it's the [Bare iOS / Bare Android](https://github.com/holepunchto) shell; in a terminal app it's the [`pear`](/reference/pear/cli) CLI itself. The worker code is identical across all of them—only the UI half and the bridge that forwards [IPC](/explanation/workers#the-ipc-contract) change.

Why the split [#why-the-split]

Three concrete reasons to put peer-to-peer code in a worker rather than inline in the UI:

Native addons stay out of the renderer [#native-addons-stay-out-of-the-renderer]

[Hypercore](/reference/building-blocks/hypercore), [Hyperswarm](/reference/building-blocks/hyperswarm), [sodium-native](https://www.npmjs.com/package/sodium-native), and many other Pear building blocks load native modules. Electron's renderer cannot load native code under `sandbox: true`, and a `sandbox: false` renderer is a large attack surface. **Keeping native code in the worker keeps the renderer untrusted.**

The renderer becomes portable [#the-renderer-becomes-portable]

Because the worker never imports DOM APIs and the UI never imports [Corestore](/reference/helpers/corestore) or Hyperswarm, you can swap the UI for a different framework (or a different platform's UI entirely) without rewriting the peer-to-peer logic. **This is what makes Keet's identical experience across desktop, mobile, and terminal possible.**

One IPC channel, one place to audit [#one-ipc-channel-one-place-to-audit]

Every byte that crosses from peers into your application crosses the IPC boundary first. Validation, framing decisions, rate limits, and observability all sit at that one chokepoint instead of being scattered across the UI.

<Callout type="info">
  See [Runtime and languages](/explanation/runtime-and-languages#one-codebase-many-platforms-the-pear-end-pattern) for the wider "Pear-end / UI" framing and why it's the recommended app shape.
</Callout>

The IPC contract [#the-ipc-contract]

The host spawns a worker by calling [`PearRuntime.run`](/reference/pear/runtime#running-workers)—the static method an Electron main process uses—or its instance alias [`pear.run`](/reference/pear/runtime#running-workers), passing the worker's entrypoint and a list of arguments:

```js
const IPC = pear.run('./workers/main.js', [pear.storage])
IPC.on('data', (data) => {
  console.log('data from worker', data)
})
IPC.write('hello')
```

`IPC` is a [duplex stream](https://nodejs.org/api/stream.html#class-streamduplex): bytes the host writes show up on the worker side, and bytes the worker writes show up here. Inside the worker the other side of that same stream is `Bare.IPC`:

```js
const Corestore = require('corestore')
const storage = Bare.argv[2]

Bare.IPC.on('data', (data) => console.log(data.toString()))
Bare.IPC.write('Hello from worker')

const corestore = new Corestore(storage)
// ... open Hypercores, replicate over Hyperswarm, etc.
```

A few things about that snippet aren't obvious if you're new to Bare:

Bare.argv indexing matches Node's process.argv [#bareargv-indexing-matches-nodes-processargv]

* `Bare.argv[0]` is the Bare binary,
* `Bare.argv[1]` is the worker script path, and
* `Bare.argv[2]` is the first argument *you* passed.
  Anything beyond that lands at `Bare.argv[3]`, `[4]`, and so on.

The IPC stream carries bytes, not objects [#the-ipc-stream-carries-bytes-not-objects]

There's no built-in JSON or length-framing. Either send one message per `write()` (Bare's IPC preserves write boundaries on the receiving side when the message is small enough not to be split), or pick a framing format like newline-delimited JSON or [compact-encoding](/reference/helpers/compact-encoding) and stick to it on both ends.

pear.storage is the recommended first argument [#pearstorage-is-the-recommended-first-argument]

It points at a per-app directory the host has already prepared (see [Storage and distribution](/explanation/storage-and-distribution)). **Worker code stays portable as long as it treats `Bare.argv[2]` as "wherever the host says my storage is" rather than hard-coding a path.**

Structured RPC over IPC [#structured-rpc-over-ipc]

Raw Inter-Process Communication (IPC) carries **bytes**, not typed messages. For a handful of one-off signals, length-preserving writes or newline-delimited JSON may be enough (see [Compact encoding](/reference/helpers/compact-encoding) for binary framing). As the host–worker protocol grows, manually pairing requests and responses becomes error-prone.

**[bare-rpc](/reference/modules/bare-modules)** adds a thin Remote Procedure Call (RPC) layer on top of a duplex stream. Each message has a numeric command id and a payload; handlers dispatch on `req.command`:

```js
import RPC from 'bare-rpc'

export const RPC_MESSAGE = 1

const rpc = new RPC(Bare.IPC, (req) => {
  if (req.command === RPC_MESSAGE) {
    console.log(req.data.toString())
  }
})

const req = rpc.request(RPC_MESSAGE)
req.send(Buffer.from('Hello from worker'))
```

Share command constants between host and worker (a shared `commands.mjs` module works well). `bare-rpc` scales to moderate protocols but still leaves schema, versioning, and method naming to you.

**[hrpc](https://www.npmjs.com/package/hrpc)** generates typed client and server stubs from a schema. Define request and response types (often via [hyperschema](https://www.npmjs.com/package/hyperschema)), register methods, run the code generator, and import the result:

```js
import HRPC from './spec/hrpc/index.js'

const rpc = new HRPC(Bare.IPC)

rpc.onHello(({ world }) => ({
  message: `Hello ${world}, from worker`
}))

await rpc.hello({ world: 'host' })
```

The host side constructs `new HRPC(IPC)` with the same generated module. Method names and encodings stay in sync because both sides compile from one definition.

| Approach | Best for                                     |
| -------- | -------------------------------------------- |
| Raw IPC  | Prototypes, single-channel streaming         |
| bare-rpc | Small fixed command sets, mobile worklets    |
| HRPC     | Many methods, evolving schemas, shared types |

Stay on raw IPC until message pairing hurts; adopt HRPC when the protocol is large enough that hand-maintained command ids become a maintenance burden.

Schema-first design [#schema-first-design]

Larger apps push this further: instead of hand-writing encoders, they **declare every data shape once** and generate the byte-level machinery from that single definition. In a peer-to-peer app this is not just ergonomics—it's a correctness requirement, for two reasons a client–server app doesn't face:

No server normalizes the wire format [#no-server-normalizes-the-wire-format]

Peers replicate raw bytes directly to each other, and any two peers may be running different builds. If one peer encodes a message differently than another decodes it, replication produces garbage—there's no central authority to reconcile them. **Every peer has to agree on the format ahead of time.**

Append-only logs are immutable and permanent [#append-only-logs-are-immutable-and-permanent]

Blocks written to a [Hypercore](/reference/building-blocks/hypercore) or [Autobase](/reference/building-blocks/autobase) are signed and replicated forever; you can't migrate them later. **Today's encoding must still decode in next year's build, so the format has to evolve in a backward-compatible way (add optional fields, never renumber existing ones).**

The schema-first toolchain solves both by deriving everything from one declaration. A single schema file (run via a build step like `npm run build:db`) typically generates:

* **[hyperschema](https://www.npmjs.com/package/hyperschema)**—the canonical field definitions every other generator consumes, using stable field numbering so additions stay compatible.
* **[hyperdb](https://www.npmjs.com/package/hyperdb)**—typed, compactly-encoded collections for what's stored on disk.
* **[hyperdispatch](https://www.npmjs.com/package/hyperdispatch)**—typed encoders for the payloads appended to an Autobase.
* **[hrpc](https://www.npmjs.com/package/hrpc)**—the typed worker↔UI stubs from the section above.

Because storage, replication, and the IPC contract are all generated from the same source, they can't drift out of sync, and the generated code is the part you don't edit by hand. **This is the role a database schema and API contract play in a client–server stack—but pushed down to the wire and disk format so every peer and every version shares it.** [Reshape into a production app](/getting-started/build-a-peer-to-peer-chat/reshape-into-a-production-app#understand-spec) walks a concrete `schema.js` and its generated `spec/` directory.

Where the boundary should sit [#where-the-boundary-should-sit]

A pragmatic rule of thumb:

* Anything that touches peers, storage, or cryptography belongs on the worker side;
* Anything that touches a screen, a keyboard, or a window belongs on the UI side.

<Callout type="info">
  When in doubt, ask "could this code run unchanged if I swapped Electron for a terminal UI?"—if yes, it's worker code; if not, it's UI code.
</Callout>

The renderer in a typical Pear Electron app, then, owns very little: layout, event listeners, and a thin transport that posts user actions to the worker and renders whatever streams back. The worker is where the application actually lives.

Lifecycle and multiple workers [#lifecycle-and-multiple-workers]

A host can run more than one worker. Common patterns:

* One **main worker** that owns the application's primary append-only logs and swarm membership. This is the usual shape and what [Reshape into a production app](/getting-started/build-a-peer-to-peer-chat/reshape-into-a-production-app) (part 2 of the getting started path) builds.
* Additional **ephemeral workers** for one-off jobs—a heavy import, a video transcode, a synchronous CPU task—that exit when their work is done. These keep the main worker's event loop free.

Each worker is its own [Bare](/reference/modules/bare-modules) process, has its own [`IPC`](/reference/pear/runtime#running-workers) stream on the host side—the duplex returned by [`PearRuntime.run`](/reference/pear/runtime#running-workers)—and can be torn down independently. The host is responsible for cleaning up on Electron's [`before-quit`](https://www.electronjs.org/docs/latest/api/app#event-before-quit) event; see how [`getWorker()`](/getting-started/build-a-peer-to-peer-chat/reshape-into-a-production-app#read-the-electron-main-process) registers an `app.on('before-quit', …)` listener in the pear-chat tutorial for one way to wire that up.

See also [#see-also]

* [Running workers in the runtime reference](/reference/pear/runtime#running-workers)—covers `pear.run`, the `IPC` duplex stream, and `Bare.IPC` on the worker side.
* [Runtime and languages](/explanation/runtime-and-languages)—the broader "Pear-end / UI" pattern, Bare's role, and how non-JavaScript code joins in via native addons.
* [Pear desktop application architecture](/explanation/pear-desktop-architecture)—how workers, the preload bridge, and the OTA updater fit together in a real Electron app.
* [Storage and distribution](/explanation/storage-and-distribution)—where `pear.storage` actually points on each operating system.
* [Reshape into a production app](/getting-started/build-a-peer-to-peer-chat/reshape-into-a-production-app)—a tutorial that wires the hello-pear-electron-shaped `pear-chat` worker behind a `window.bridge` API.
* [Corestore reference](/reference/helpers/corestore)—the storage factory typically opened on `Bare.argv[2]` inside a worker.
* [Compact encoding reference](/reference/helpers/compact-encoding)—binary framing for IPC messages crossing the host/worker boundary.
* The upstream source: [`hello-pear-electron`'s Workers](https://github.com/holepunchto/hello-pear-electron#workers).


# Getting started



import { Cards, Card } from 'fumadocs-ui/components/card'
import { Tabs, Tab } from 'fumadocs-ui/components/tabs'

Build a peer-to-peer desktop chat app with [Pear](https://docs.pears.com), then evolve it into the same shape as the official [`hello-pear-electron`](https://github.com/holepunchto/hello-pear-electron) template, and finally release it over the air.

There are two ways in. Start from the finished template and learn your way around it, or build the same app up from scratch across a four-part path.

{/*
  Shared snippet (content/_snippets/) included via Fumadocs <include> by getting-started
  pages that introduce peer-to-peer, pointing newcomers at the two core explanations.
  See: https://www.fumadocs.dev/docs/markdown#include
  */}

<Callout type="info">
  New to peer-to-peer? [Peer-to-peer, demystified](/explanation/peer-to-peer-demystified) explains how peers find each other and connect directly—no servers—and [How Pear and Bare fit together](/explanation/pear-and-bare) maps the pieces you'll wire together.
</Callout>

Install Pear [#install-pear]

Get the [`pear`](/reference/pear/cli) CLI from **[install.pears.com](https://install.pears.com)**:

<Tabs items={['curl (macOS / Linux)', 'irm (Windows)', 'npx', 'docker']}>
  <Tab value="curl (macOS / Linux)">
    ```sh
    curl https://install.pears.com/pear.sh | sh
    ```
  </Tab>

  <Tab value="irm (Windows)">
    ```powershell
    irm https://install.pears.com/pear.ps1 | iex
    ```
  </Tab>

  <Tab value="npx">
    ```sh
    npx pear
    ```
  </Tab>

  <Tab value="docker">
    ```sh
    docker run -it --rm tetherto/pear
    ```
  </Tab>
</Tabs>

Follow the `PATH` instructions the installer prints, then run `pear` directly. See [Install & upgrade](/reference/pear/cli#install) for the npm-global alternative and upgrade details. The [`tetherto/pear`](https://hub.docker.com/r/tetherto/pear) image runs Pear inside Ubuntu with `pear` and `pear-install` ready to go—handy for trying this walkthrough without installing anything locally.

Start from a template [#start-from-a-template]

The fastest way to a production-shaped app: clone an official boilerplate and learn where each piece lives. Pick the one that matches what you're shipping—a desktop GUI app or a standalone terminal binary.

<Cards>
  <Card href="/getting-started/from-a-template/start-from-hello-pear-electron" title="hello-pear-electron (desktop)" description="Clone the Electron boilerplate, map renderer ↔ main ↔ worker, and add a feature end to end." />

  <Card href="/getting-started/from-a-template/start-from-hello-pear-bare" title="hello-pear-bare (terminal)" description="Clone the standalone Bare boilerplate: pear-runtime OTA updates and cross-platform binaries, no GUI." />
</Cards>

Build it up from scratch [#build-it-up-from-scratch]

Prefer to learn the moving parts by building them? Take the four-part path. Each part is a single sitting. Read them in order—every part starts from the previous part's code.

<Cards>
  <Card href="/getting-started/build-a-peer-to-peer-chat/build-a-peer-to-peer-chat" title="Build a peer-to-peer chat" description="Five files, ~15 minutes. Static PearRuntime.run, [Hyperswarm](/reference/building-blocks/hyperswarm), no persistence." />

  <Card href="/getting-started/build-a-peer-to-peer-chat/reshape-into-a-production-app" title="Reshape into a production app" description="Reshape part 1 into the hello-pear-electron scaffold: a Bare chat worker, an [Autobase](/reference/building-blocks/autobase) room with blind-pairing invites, on-disk persistence, a separate OTA updater worker, and a polished Tailwind UI with a copy-invite button." />

  <Card href="/getting-started/build-a-peer-to-peer-chat/ship" title="Ship your app" description="pear touch + upgrade link, electron-forge make, pear build, and pear stage to publish your first version." />

  <Card href="/getting-started/build-a-peer-to-peer-chat/update" title="Deploy over-the-air updates" description="Run the installed app, ship a second version, watch the OTA cycle, and preview multisig." />
</Cards>

What you'll build [#what-youll-build]

A small Electron window with a message list, an input, and a peer counter. Two instances on the same machine—or on different machines anywhere on the public internet—discover each other through the [DHT](/reference/building-blocks/hyperdht) and stream messages directly.

<Mermaid
  chart="flowchart LR
  Renderer[&#x22;renderer/app.js (HTML + JS)&#x22;] <-->|&#x22;window.chat / window.bridge&#x22;| Preload[electron/preload.js]
  Preload <-->|IPC| Main[&#x22;electron/main.js (Electron main process)&#x22;]
  Main <-->|&#x22;PearRuntime.run / new PearRuntime&#x22;| Worker[&#x22;workers/main.mjs (Bare)&#x22;]
  Worker <-->|Hyperswarm| Peers((remote peers))"
/>

Each part adds one layer to that picture:

* Part 1 wires the renderer ↔ main ↔ worker ↔ peers path with the smallest amount of code.
* Part 2 reshapes that into the full [`hello-pear-electron`](https://github.com/holepunchto/hello-pear-electron) production scaffold: a dedicated Bare chat worker, an [Autobase](/reference/building-blocks/autobase)-backed room with [blind-pairing](https://www.npmjs.com/package/blind-pairing) invites, a HyperDB schema, on-disk persistence, a separate OTA updater worker, and a polished Tailwind UI—the vanilla renderer that every peer-to-peer how-to extends.
* Part 3 turns the project into a release pipeline: signed distributables, a `pear://` upgrade link, and the first published version on a [Hypercore](/reference/building-blocks/hypercore).
* Part 4 puts that release pipeline in motion: run the installed app, ship a second version, watch OTA fire end-to-end, and preview the production `stage → provision → multisig` flow from the [release pipeline](/explanation/deployment-releasing-apps-p2p).

Before you start [#before-you-start]

* [Node.js](https://nodejs.org/) v22.17 or newer and npm v10.9 or newer
* A POSIX-style terminal (macOS, Linux, or Windows with WSL)
* An IDE or text editor
* The [`pear`](/reference/pear/cli) CLI—[install it above](#install-pear); only required for parts 3 and 4 (shipping and updating)

Each part lists any extra npm packages it adds.

Where to go next [#where-to-go-next]

* [Pear desktop application architecture](/explanation/pear-desktop-architecture)—why Bare workers, the preload bridge, and the OTA updater look the way they do.
* [Storage and distribution](/explanation/storage-and-distribution)—where `pear.storage` lives in development versus production.
* [Release pipeline](/explanation/deployment-releasing-apps-p2p)—the `stage → provision → multisig` flow parts 3 and 4 walk through.
* [Release pipeline glossary](/explanation/deployment-releasing-apps-p2p#glossary)—terms used across the desktop release docs.
* The upstream template: [`holepunchto/hello-pear-electron`](https://github.com/holepunchto/hello-pear-electron).


# How To



How-tos are goal-oriented recipes. Each one assumes you already know roughly what you're doing and just need the steps for a particular task—[replicating a Hypercore](/how-to/store-and-replicate/replicate-and-persist-with-hypercore), [deploying an app](/how-to/operate-an-app/manual-deployment/deployment), or [troubleshooting common issues](/how-to/troubleshooting).

If you want to look up a CLI flag, an API, or a config field, that's **[Reference](/reference)**. For the conceptual "why," see **[About Pear](/explanation)**.

Start here [#start-here]

Many recipes below build on one of two starting points. Chat-focused guides extend the **`pear-chat` scaffold** (Electron shell, Bare worker, [Autobase](/reference/building-blocks/autobase)-backed chat room) built step by step in the **[Getting Started](/getting-started)** path—see [Reshape into a production app](/getting-started/build-a-peer-to-peer-chat/reshape-into-a-production-app). Guides that don't need chat start from one of the boilerplates in **[Start from a template](/getting-started/from-a-template)**—desktop ([`hello-pear-electron`](/getting-started/from-a-template/start-from-hello-pear-electron)) or terminal ([`hello-pear-bare`](/getting-started/from-a-template/start-from-hello-pear-bare)). Each guide states its base up front. If you're new, work through Getting Started first so you understand each piece before adapting it.

In this section [#in-this-section]

* [Manage installed applications](/how-to/manage-installed-applications)—list installed Pear apps and reset their storage.
* [Troubleshoot common issues](/how-to/troubleshooting)—fixes for common Pear and Bare development issues.

Several guides below extend a base scaffold—either the `pear-chat` app from the [Getting Started path](/getting-started/build-a-peer-to-peer-chat/reshape-into-a-production-app) or a boilerplate from [Start from a template](/getting-started/from-a-template)—with one capability at a time. They teach **Pear-end logic**—the code in the Bare [worker](/explanation/workers), not the UI—so the same worker is portable across desktop, mobile, and terminal; only the UI half changes per platform (see [Runtime and languages](/explanation/runtime-and-languages)).

**Jump to a section overview:** [Connect to peers](/how-to/connect-to-peers) · [Store and replicate](/how-to/store-and-replicate) · [Blind peering](/how-to/blind-peering) · [Manage identity](/how-to/manage-identity) · [Stream and share media](/how-to/stream-and-share-media) · [Run on mobile & native](/how-to/run-on-native) · [Release & distribute](/how-to/operate-an-app)

Connecting peers [#connecting-peers]

* [Connect two peers by key with HyperDHT](/how-to/connect-to-peers/connect-two-peers-by-key-with-hyperdht)
* [Connect to many peers by topic with Hyperswarm](/how-to/connect-to-peers/connect-to-many-peers-by-topic-with-hyperswarm)
* [Host multiple rooms in one chat app](/how-to/connect-to-peers/host-multiple-rooms-in-one-chat-app)

Storage and replication [#storage-and-replication]

* [Replicate and persist with Hypercore](/how-to/store-and-replicate/replicate-and-persist-with-hypercore)
* [Work with many Hypercores using Corestore](/how-to/store-and-replicate/work-with-many-hypercores-using-corestore)
* [Share append-only databases with Hyperbee](/how-to/store-and-replicate/share-append-only-databases-with-hyperbee)
* [Create a full peer-to-peer filesystem with Hyperdrive](/how-to/stream-and-share-media/create-a-full-peer-to-peer-filesystem-with-hyperdrive)
* [Store and serve large media with Hyperblobs](/how-to/stream-and-share-media/store-and-serve-large-media-with-hyperblobs)
* [Keep data available with blind peering](/how-to/blind-peering/keep-data-available-with-blind-peering)
* [Add blind peering to a chat app](/how-to/blind-peering/add-blind-peering-to-a-chat-app)

Managing identity [#managing-identity]

* [Create a portable identity with Keet identity keys](/how-to/manage-identity/create-a-portable-identity-with-keet-identity-key)
* [Add Keet identity to a chat app](/how-to/manage-identity/add-keet-identity-to-a-chat-app)

Stream and share media [#stream-and-share-media]

* [Share files in a peer-to-peer app](/how-to/stream-and-share-media/share-files-in-a-peer-to-peer-app)
* [Back up photos in a peer-to-peer app](/how-to/stream-and-share-media/back-up-photos-in-a-peer-to-peer-app)
* [Stream stored video in a peer-to-peer app](/how-to/stream-and-share-media/stream-stored-video-in-a-peer-to-peer-app)
* [Stream a live camera in a peer-to-peer app](/how-to/stream-and-share-media/stream-a-live-camera-in-a-peer-to-peer-app)

Run on mobile & native [#run-on-mobile--native]

* [Embed Bare in a React Native app](/how-to/run-on-native/embed-bare-in-react-native)
* [Type a native RPC bridge](/how-to/run-on-native/type-a-native-rpc-bridge)
* [Bundle a Bare app](/how-to/run-on-native/bundle-a-bare-app)

Releasing & distributing your app [#releasing--distributing-your-app]

**CI / GitHub Actions**

* [Publish with GitHub Actions](/how-to/operate-an-app/github-actions/publish-with-github-actions)
* [Build and sign desktop apps in CI](/how-to/operate-an-app/github-actions/build-and-sign-in-ci)

**Build & package**

* [Build desktop distributables](/how-to/operate-an-app/build-and-package/build-desktop-distributables)
* [Distribute as a binary](/how-to/operate-an-app/build-and-package/distribute-as-binary)
* [Submit to app stores](/how-to/operate-an-app/build-and-package/submit-to-app-stores)

**Manual deployment**

* [Deploy your application](/how-to/operate-an-app/manual-deployment/deployment)
* [Troubleshoot desktop releases](/how-to/operate-an-app/manual-deployment/troubleshoot-desktop-releases)

**Multisig**

* [Set up multisig](/how-to/operate-an-app/multisig/set-up-multisig)
* [Sign with multisig](/how-to/operate-an-app/multisig/sign-with-multisig)
* [Troubleshoot multisig](/how-to/operate-an-app/multisig/troubleshoot-multisig)

**Maintenance**

* [Migrate from pear run to Pear OTA](/how-to/operate-an-app/migration)

{/* Writing a new how-to? See [Diátaxis on how-to guides](https://diataxis.fr/how-to-guides/)—they assume competence and serve a goal, unlike tutorials which serve learning. */}


# Manage installed applications



Since Pear v3, applications are installed with [`pear install`](/reference/pear/cli#pear-install) directly into your operating system's application folder, and each app keeps its peer-to-peer data in a local corestore (described in [Storage and distribution](/explanation/storage-and-distribution)). This guide covers finding what's installed and resetting an app's storage.

<Callout type="info">
  `pear data apps` and `pear drop` were removed in Pear v3. Applications now live in the OS application folder, and local corestore data is cleared with [`pear gc cores`](/reference/pear/cli#pear-gc).
</Callout>

{/*
  Shared snippet (content/_snippets/) included via Fumadocs <include> by guides that
  run `pear` CLI commands, so readers can install the CLI before following the steps.
  See: https://www.fumadocs.dev/docs/markdown#include
  */}

<Callout type="info">
  **Need the `pear` CLI?** Install it from **[install.pears.com](https://install.pears.com)**, or prefix any command below with `npx`. See [Install & upgrade](/reference/pear/cli#install) for details.
</Callout>

Find installed applications [#find-installed-applications]

`pear install pear://<key>` places apps in the standard OS location:

* **macOS** — apps in `/Applications`, binaries in `/usr/local/bin`
* **Linux** — apps in `~/Applications`, `~/AppImages`, or `~/.local/bin`; binaries in `~/.local/bin`

Browse that folder to see what's installed, the same as any native application. To inspect a specific application, pass its link to [`pear info`](/reference/pear/cli#pear-info):

```console skip="machine-state"
pear info pear://<application-link>
```

Run `pear info` with no argument to view Pear platform information instead.

Reset an application's storage [#reset-an-applications-storage]

There is no `pear uninstall`—remove the app from your OS application folder to uninstall it. To wipe an application's **local peer-to-peer storage** (its corestore) without touching the copy on the swarm, use [`pear gc cores`](/reference/pear/cli#pear-gc) with the app link:

```console skip="destructive"
pear gc cores pear://<application-link>
```

This clears the corestore cores tied to your local copy. Anything stored only locally (chat history, drafts, user-generated content) is gone afterwards. Use it when you want a clean slate for testing or to recover from a corrupt drive.

The application binary itself stays available on the swarm; only the local storage is cleared. Re-running the application against the same link rebuilds an empty storage.


# Troubleshoot common issues



* [Pear](#pear)
* [Bare](#bare)

Pear [#pear]

<a name="pear" />

Troubleshooting confusing scenarios while developing Pear applications.

Joining a Hyperswarm topic takes a long time [#joining-a-hyperswarm-topic-takes-a-long-time]

[Hyperswarm](/reference/building-blocks/hyperswarm) topic discovery can stall for several common reasons:

* Random NAT networks can take longer as another node may be needed to facilitate the connection. See [Dependencies and network](/explanation/dependencies-and-network) for what's actually happening at the IP level.
* Not destroying the hyperswarm instance during application teardown so Hyperswarm can unannounce and clean up the [HyperDHT](/reference/building-blocks/hyperdht).
  It's recommended to clean up the hyperswarm instance with [`swarm.destroy()`](/reference/building-blocks/hyperswarm#await-swarmdestroy-force---) before exiting the application. This prevents conflicting records in the DHT for the application's peer which cause it take longer to join a topic. See [Connect to many peers by topic with Hyperswarm](/how-to/connect-to-peers/connect-to-many-peers-by-topic-with-hyperswarm) for the full one-instance-per-app pattern.
* A firewall is blocking the traffic.
  Please let Holepunch know if this is the case.

Bare [#bare]

<a name="bare" />

Troubleshooting confusing scenarios while developing with Bare. For background on why Bare is the runtime under Pear, see [Runtime and languages](/explanation/runtime-and-languages).

Missing builtin Modules when Running with Bare [#missing-builtin-modules-when-running-with-bare]

Bare is minimal by design, so does not include all of the modules provided with Node.js. Instead modules such as `process` can be imported as a Bare specific module, for example `bare-process`. For a list of Node.js builtins and their Bare replacements, check out `bare-node`'s [`Modules table`](https://github.com/holepunchto/bare-node#modules), or browse the [Bare modules reference](/reference/modules/bare-modules).

Writing a module with Support for Bare & Node.js [#writing-a-module-with-support-for-bare--nodejs]

If writing a library that can be run in both the Bare and Node.js runtimes, import maps should be used to support both the Bare version and the Node.js version of builtin modules. Import maps only apply to the `package.json`'s package so does not modify dependencies of the module.

See `bare-node`'s [`Import maps`](https://github.com/holepunchto/bare-node#import-maps) for more details.

Running Third-Party Modules Written for Node.js [#running-third-party-modules-written-for-nodejs]

To support dependencies that rely on Node.js builtins (eg. `fs`, `os`, etc), an alias can be used to point to a wrapper module to use the Bare version. For example to use `bare-net` where ever `net` is used in dependencies, install it as an alias:

```sh skip="install-instruction"
npm i bare-net net@npm:bare-node-net
```

For compatibility and to support builtin globals, such as `process`, the corresponding `bare-*` module will include a `/global.js` submodule that sets the global variable to `global`. This is useful when importing modules that assume the global variable exists. It is not recommended to use global variables when writing new code as it is less flexible and harder to upgrade piecemeal.

Usage of a globals submodule looks like:

```js skip="snippet-illustration"
require('bare-process/global')
console.log('platform', process.platform) // now prints
```

AddonError: ADDON_NOT_FOUND: Cannot find addon when running Bare [#addonerror-addon_not_found-cannot-find-addon-when-running-bare]

As the error suggests, this is because the native addon cannot be found. This could either be because the addon is missing or Bare is looking in a different place than expected.

A few reasons why an addon may be missing:

* The addon is not available for the current platform and/or architecture.
  To see what platform and architecture Bare is running on, log `Bare.platform` and `Bare.arch`.
* The addon wasn't linked ahead of time.
  Mobile applications require native code to be linked as part of compiling the application.

  If developing with `react-native-bare-kit` (including using `bare-expo` as a template), check that the addon was loaded in `node_modules/react-native-bare-kit/ios/addons` for iOS and `node_modules/react-native-bare-kit/android/src/main/addons` for Android. This is where the libraries are linked from.

  If other solutions are not working, it may be an issue with the build cache. Try clearing the cache and recompiling.

bare-pack with conditional module loading [#bare-pack-with-conditional-module-loading]

[`bare-pack`](https://github.com/holepunchto/bare-pack) does not evaluate your code but scans for imports. This means it cannot infer dynamic imports but assumes all imports will be loaded for the target platform. For example:

```js skip="snippet-illustration"
const { runtime } = require('which-runtime')

let crypto
if (runtime === 'bare') {
  crypto = require('bare-crypto')
} else {
  crypto = require('node:crypto')
}
```

Will throw:

```text skip="sample-error"
./node_modules/paparam/index.js:514
    throw new Bail(bail.reason)
          ^

Bail: ModuleTraverseError: MODULE_NOT_FOUND: Cannot find module 'node:crypto' imported from 'file://./index.js'
    at exports.imports (./node_modules/bare-module-traverse/index.js:331:24)
    at exports.imports.next (<anonymous>)
    at exports.module (./node_modules/bare-module-traverse/index.js:152:18)
    at exports.module.next (<anonymous>)
    at process (./node_modules/bare-pack/index.js:50:26)
    at async pack (./node_modules/bare-pack/index.js:24:3)
    at async Command._runner (./node_modules/bare-pack/bin.js:46:18)
    at async runAsync (./node_modules/paparam/index.js:793:5)
    at Command._bail (./node_modules/paparam/index.js:514:11)
    at Command.bail (./node_modules/paparam/index.js:127:36)
    at runAsync (./node_modules/paparam/index.js:795:7)
```

This is because it is trying to pack `node:crypto` for Bare which isn't possible.

Instead of dynamic conditions based on runtime environment, modules should have an import map defined to use the correct module for the given runtime.

See `bare-node`'s [`Import maps`](https://github.com/holepunchto/bare-node#import-maps) for more details.

See also [#see-also]

* [Bare modules reference](/reference/modules/bare-modules)—the `bare-*` builtins listed here.
* [Runtime and languages](/explanation/runtime-and-languages)—why Bare diverges from Node and what that means for libraries.
* [Dependencies and network](/explanation/dependencies-and-network)—what's actually happening when peer discovery stalls at the IP layer.
* [Hyperswarm reference](/reference/building-blocks/hyperswarm)—full API including `swarm.destroy()` for clean teardown.
* [HyperDHT reference](/reference/building-blocks/hyperdht)—the DHT layer whose records accumulate when Hyperswarm instances aren't destroyed.


# Reference



Reference is the technical description of how Pear works. It's information-oriented: comprehensive, accurate, and dry. Use it to look up a flag, an API signature, or a configuration field.

{/* Tutorials quadrant is hidden until we have actual tutorials. Re-add this leading clause when content lands: "If you're learning, see **[Tutorials](/tutorials)**. " */}

If you're trying to accomplish a specific task, see **[How To](/how-to)**. For the design rationale, see **[About Pear](/explanation)**.

In this section [#in-this-section]

Pear [#pear]

* [Pear CLI](/reference/pear/cli)—covers `pear stage`, `pear seed`, `pear build`, `pear install`, and every flag.
* [Pear OTA](/reference/pear/runtime)—the `pear-runtime` library and JavaScript API for over-the-air updates inside a running Pear app.
* [Configuration](/reference/pear/configuration)—every key in `package.json`'s `pear` block.
* [Pear API (removed)](/reference/pear/api)—the older direct-access `global.Pear` API, removed in v3. Use the Pear OTA (`pear-runtime`) module instead.

For a curated record of breaking changes and removals across these modules, see the [Release Overview](/release-overview).

Bare [#bare]

The runtime Pear is built on, and the kit for embedding it in native apps:

* [Bare runtime API](/reference/bare/runtime)—the `Bare` global: process properties, lifecycle, addons, threads, IPC.
* [Bare CLI](/reference/bare/cli)—run a script or REPL with the `bare` command.
* [Bare Kit](/reference/bare/bare-kit)—the Worklet and IPC API for iOS, Android, and React Native.

Per-module API references (also linked from the [Bare modules catalog](/reference/modules/bare-modules)): [bare-fs](/reference/bare/modules/bare-fs), [bare-os](/reference/bare/modules/bare-os), [bare-stream](/reference/bare/modules/bare-stream), [bare-tcp](/reference/bare/modules/bare-tcp), [bare-fetch](/reference/bare/modules/bare-fetch), [bare-crypto](/reference/bare/modules/bare-crypto), [bare-subprocess](/reference/bare/modules/bare-subprocess), [bare-rpc](/reference/bare/modules/bare-rpc), [bare-sqlite](/reference/bare/modules/bare-sqlite), [bare-broadcast-channel](/reference/bare/modules/bare-broadcast-channel), [bare-sdl](/reference/bare/modules/bare-sdl), [bare-module-resolve](/reference/bare/modules/bare-module-resolve), [bare-module-traverse](/reference/bare/modules/bare-module-traverse), [bare-addon-resolve](/reference/bare/modules/bare-addon-resolve), [bare-bluetooth-android](/reference/bare/modules/bare-bluetooth-android), [bare-bluetooth-apple](/reference/bare/modules/bare-bluetooth-apple), [bare-module](/reference/bare/modules/bare-module), [bare-url](/reference/bare/modules/bare-url), [bare-atomics](/reference/bare/modules/bare-atomics), [bare-timers](/reference/bare/modules/bare-timers), [bare-pipe](/reference/bare/modules/bare-pipe), [bare-semver](/reference/bare/modules/bare-semver), [bare-form-data](/reference/bare/modules/bare-form-data), [bare-channel](/reference/bare/modules/bare-channel), [bare-tls](/reference/bare/modules/bare-tls), [bare-console](/reference/bare/modules/bare-console), [bare-structured-clone](/reference/bare/modules/bare-structured-clone), [bare-ipc](/reference/bare/modules/bare-ipc), [bare-inspector](/reference/bare/modules/bare-inspector), [bare-make](/reference/bare/modules/bare-make), [bare-prom-client](/reference/bare/modules/bare-prom-client), [bare-posix](/reference/bare/modules/bare-posix), [bare-mdns-discovery](/reference/bare/modules/bare-mdns-discovery), [bare-sidecar](/reference/bare/modules/bare-sidecar), [bare-union-bundle](/reference/bare/modules/bare-union-bundle), [bare-mime](/reference/bare/modules/bare-mime), [bare-apk](/reference/bare/modules/bare-apk).

CI & release [#ci--release]

* [Desktop release npm scripts](/reference/ci-and-release/desktop-release-npm-scripts)—the common `package.json` scripts in Pear Electron desktop repos.
* [Holepunch GitHub Actions](/reference/ci-and-release/github-actions)—the reusable composite actions in `holepunchto/actions` for building, signing, publishing, and recovering Pear apps and modules.
* [pear-ci GitHub Action](/reference/ci-and-release/pear-ci-action)—staging a Pear app from CI into a `pear://` link with the `pear-ci` action.

Module catalog [#module-catalog]

* [Modules](/reference/modules/pear-modules)—the `pear-*` libraries: application, UI, common, developer, integration.
* [Bare modules](/reference/modules/bare-modules)—the `bare-*` runtime modules underpinning Pear.

Building blocks [#building-blocks]

The core peer-to-peer primitives Pear is built on:

* [Hypercore](/reference/building-blocks/hypercore), [Hyperbee](/reference/building-blocks/hyperbee), [Hyperdrive](/reference/building-blocks/hyperdrive), [Autobase](/reference/building-blocks/autobase), [HyperDHT](/reference/building-blocks/hyperdht), [Hyperswarm](/reference/building-blocks/hyperswarm).

Helpers [#helpers]

Higher-level utilities that combine the building blocks:

* [Corestore](/reference/helpers/corestore), [Localdrive](/reference/helpers/localdrive), [Mirrordrive](/reference/helpers/mirrordrive), [Secretstream](/reference/helpers/secretstream), [Compact-encoding](/reference/helpers/compact-encoding), [Protomux](/reference/helpers/protomux).

Tools [#tools]

CLI utilities built on Pear:

* [Hypershell](/reference/tools/hypershell), [Hypertele](/reference/tools/hypertele), [Hyperbeam](/reference/tools/hyperbeam), [Hyperssh](/reference/tools/hyperssh), [Drives](/reference/tools/drives).

Stability legend [#stability-legend]

Module pages call out a stability indicator. The four levels:

| Stability                       | Description                                                 |
| ------------------------------- | ----------------------------------------------------------- |
| <Status level="stable" />       | Unlikely to change or be removed in the foreseeable future. |
| <Status level="experimental" /> | New, untested, or has known issues.                         |
| <Status level="deprecated" />   | Being removed or replaced in the future.                    |
| <Status level="unstable" />     | May change or be removed without warning.                   |

{/* Writing a new reference page? See [Diátaxis on reference](https://diataxis.fr/reference/)—neutral, accurate, exhaustive. No tutorials, no anecdotes, no "you might want to." */}


# Release Overview



A curated record of changes across Pear and its modules, newest first. Entries are grouped by module, and every **Breaking** item links to migration guidance. For the raw upstream record, see each module's GitHub releases; this page is the docs-team view of what the changes mean for your application. To publish release notes for *your own* app instead, ship a `CHANGELOG.md`—see [Publish a changelog for your app](/how-to/operate-an-app/publish-a-changelog).

{/* changelog:insert — automation inserts draft entries below this marker; keep it directly above the newest entry. */}

2026-07-30 — Pear 3.1.0 and module updates [#2026-07-30--pear-310-and-module-updates]

Pear 3.1.0 is the first feature release on top of Pear v3 (below). Nothing in it is breaking: it adds core inspection, speeds up vanity key generation, and fills in reporting gaps left by the v3 restructure.

pear (CLI) — v3.1.0 [#pear-cli--v310]

* Added: [`pear cores`](/reference/pear/cli#pear-cores) lists an application's cores—one `pear://` link per core, suffixed `(writable)` when this device holds the key pair—followed by a totals summary.
* Added: [`pear touch --vanity`](/reference/pear/cli#pear-touch) generates vanity keys across multiple threads instead of one.
* Changed: [`pear info`](/reference/pear/cli#pear-info) now reports `productName`, `version`, `upgrade`, and `verlink`.
* Changed: [`pear multisig`](/reference/pear/cli#pear-multisig) asks you to confirm the password before it is used.
* Fixed: [`pear info`](/reference/pear/cli#pear-info) and [`pear changelog`](/reference/pear/cli#pear-changelog) output corrections, and password prompts no longer ignore backspace.
* Sidecar errors are now persisted rather than lost with the process—see [Sidecar logs](/reference/pear/cli#sidecar-logs).

pear (CLI) — v3.0.1 [#pear-cli--v301]

* Fixed: [`pear build`](/reference/pear/cli#pear-build) resolves package-relative paths correctly.
* Fixed: Linux runs check for `libatomic` up front instead of failing later.
* Fixed: [`pear install`](/reference/pear/cli#pear-install) guards against an unset `SHELL`.

pear-runtime-updater — v3.3.0 [#pear-runtime-updater--v330]

* Added: a network monitor, so the updater reacts to connectivity changes.
* Fixed: errors raised when closing during an update, or immediately before one started.

pear-build — v1.1.1 [#pear-build--v111]

* Fixed: `package.json` is read and parsed directly instead of via `require`, which fixes package-relative resolution during [`pear build`](/reference/pear/cli#pear-build).
* Added: test coverage for `win32-arm64`.

pear-install — v1.2.2, v1.2.1 [#pear-install--v122-v121]

* Fixed (v1.2.2): [`pear install`](/reference/pear/cli#pear-install) guards against an unset `SHELL` when detecting your shell config.
* Added (v1.2.1): Node 20 and 21 support, and `--timeout <seconds>` now works as documented.

Hypercore — v11.34.0–v11.35.1 [#hypercore--v11340v11351]

* Changed (v11.34.0): the tree-node proof cache is enabled, cutting repeated proof work for peers that serve many connections.
* Added (v11.35.0): a manifest can be supplied as a raw buffer.
* Fixed (v11.35.1): the idle range-completion scan.
* Fixed (v11.34.1): the latest batch is always selected.

Hyperdrive — v13.3.3 [#hyperdrive--v1333]

* Fixed: [`drive.download()`](/reference/building-blocks/hyperdrive#drivedownloadfolder-options) and [`drive.has()`](/reference/building-blocks/hyperdrive) silently stalled or fetched the wrong data for entries written with `dedup: true`. Those entries store blobs as a non-contiguous block map rather than a contiguous range, and the contiguous form was being used for every entry. `downloadDiff()` had the same bug.

HyperDHT — v6.33.0 [#hyperdht--v6330]

* Fixed: relayed server connections now inherit `connectionKeepAlive` the way direct sockets already did, and a relay-to-direct upgrade sends an explicit handoff packet so the peer observes the direct path before the relay is torn down.
* Fixed: a LAN shortcut no longer blocks hole-punch fallback, and relay sockets close once a direct connection is established.
* Removed: the internal `global.Pear` reference, following the v3 removal of the ambient Pear API.

Corestore — v7.12.0, v7.11.1 [#corestore--v7120-v7111]

* Changed (v7.12.0): `suspend()` no longer performs an implicit flush. Write-ahead-log filtering makes reopening cheap, so the flush is no longer needed on every suspend.
* Added (v7.11.1): a `treeCache` option for tuning Hypercore's tree-node cache—raise `maxSize` on peers that serve more connections than usual.

2026-07 — Pear v3 [#2026-07--pear-v3]

Pear v3 completes the split announced in [Pear Evolution](https://pears.com/news/pear-evolution/): the runtime moves out of the CLI and into the embeddable **[Pear OTA](/reference/pear/runtime)** (`pear-runtime`) library, and the CLI focuses on deployment and installation.

pear (CLI) — v3 [#pear-cli--v3]

* **Breaking:** `pear run` removed. Launch applications by embedding [Pear OTA](/reference/pear/runtime) instead—see [Migrate from pear run to Pear OTA](/how-to/operate-an-app/migration). Running it now exits with `pear run has been removed`.
* **Breaking:** `pear release` removed. The single-key release pointer is replaced by quorum cosigning—use [`pear provision`](/reference/pear/cli#pear-provision) + [`pear multisig`](/reference/pear/cli#pear-multisig).
* **Breaking:** `pear presets`, `pear shift`, and `pear drop` removed. For resetting an app's storage, see [Manage installed applications](/how-to/manage-installed-applications).
* **Breaking:** the ambient `global.Pear` API is gone with `pear run`. The [Pear API page](/reference/pear/api) is retained for reference only.
* **Breaking:** `--no-ask` (all commands), `pear stage --compact`, and `pear sidecar --mem`/`--key` flags removed; `pear data` slims down to `dht` and `multisig` subcommands.
* **Breaking:** `pear://<alias>` shorthand links removed. Refer to applications by their full `pear://<key>` link.
* Added: [`pear install <link>`](/reference/pear/cli#pear-install) installs applications from peers directly into the OS application folder (provided by [`pear-install`](https://github.com/holepunchto/pear-install)).
* Added: `pear multisig keys paths`, `pear info --multisig`, `pear sidecar shutdown|inspect`, and `pear gc cores [link]`.
* Changed: `pear build` is now provided by the standalone [`pear-build`](https://github.com/holepunchto/pear-build) module.
* Changed: [`pear seed`](/reference/pear/cli#pear-seed) reports `whoami` and drive length, encodes all keys as z32, and cleans up its colored output.
* Fixed: `pear stage --truncate`, first-run [`pear dump`](/reference/pear/cli#pear-dump) failures, and several `pear seed` edge cases.

pear-runtime (Pear OTA) — v1.3.1 [#pear-runtime-pear-ota--v131]

* The embeddable OTA-update library is now branded **Pear OTA** in these docs; the package name stays `pear-runtime`.
* Constructor accepts `store` + `swarm` (supply your own [Corestore](/reference/helpers/corestore)/Hyperswarm, together), `storage`, `delay`, and `bundled` options—see the [Options reference](/reference/pear/runtime#options).
* `PearRuntime.run()` workers started from a Bare process run as Bare threads; thread workers do not expose `IPC.stdin`/`stdout`/`stderr`.

See also [#see-also]

* [Pear CLI reference](/reference/pear/cli)—current command set with removed commands badged.
* [Migrate from pear run to Pear OTA](/how-to/operate-an-app/migration)—the v3 migration path.


# Build a peer-to-peer chat



import { Steps, Step } from 'fumadocs-ui/components/steps'

This is **part 1 of 4** in the [getting started path](/getting-started). You build a peer-to-peer desktop chat with Pear. By the end you have an Electron app that finds peers on the public distributed hash table (DHT) and streams messages directly between them.

The example mirrors [`hello-pear-electron`](https://github.com/holepunchto/hello-pear-electron)—Pear's official Electron template—but uses the simplest form of the runtime ([`PearRuntime.run`](/reference/pear/runtime#running-workers)) and skips persistence, over-the-air updates, and packaging. [Part 2](/getting-started/build-a-peer-to-peer-chat/reshape-into-a-production-app) reshapes it into the full production scaffold with all of those layered on top.

{/*
  Shared snippet (content/_snippets/) included via Fumadocs <include> by every getting-started step.
  Reminds readers that a production-ready reference implementation already exists
  upstream, so they can clone it any time without abandoning the type-along.
  See: https://www.fumadocs.dev/docs/markdown#include
  */}

<Callout type="info">
  **Full production-ready reference: `hello-pear-electron`.** The complete version of this chat lives at [`holepunchto/hello-pear-electron`](https://github.com/holepunchto/hello-pear-electron)—Holepunch's official Electron template, the same shape [Keet](https://keet.io) and [PearPass](https://pass.pears.com) ship. Clone it any time to see the finished structure or to crib code. For a guided tour of the template, see [Start from the hello-pear-electron template](/getting-started/from-a-template/start-from-hello-pear-electron).
</Callout>

What you'll build [#what-youll-build]

A small desktop window with a message list, a text input, and a peer counter. Two windows on the same machine—or on a friend's machine on the other side of the world—discover each other through the DHT and stream messages directly.

Each peer shows up under a six-character hex id derived from its public key (**line 10** of `workers/main.mjs`). That's what your worker emits when a new peer connects.

The four moving parts:

* **[`pear-runtime`](/reference/pear/runtime)**—the library that lets a JavaScript host (Electron here) embed [Bare](/explanation/runtime-and-languages) workers.
* **The [Bare worker](/explanation/runtime-and-languages)**—a separate process that owns the peer-to-peer code. It is your local backend for the renderer.
* **[Hyperswarm](/reference/building-blocks/hyperswarm)**—finds peers on a topic and gives you an end-to-end-encrypted connection.
* **[The Electron preload bridge](#add-the-preload-bridge)**—the only door between the browser-style renderer and the worker.

{/*
  Shared snippet (content/_snippets/) included via Fumadocs <include> by getting-started
  pages that introduce peer-to-peer, pointing newcomers at the two core explanations.
  See: https://www.fumadocs.dev/docs/markdown#include
  */}

<Callout type="info">
  New to peer-to-peer? [Peer-to-peer, demystified](/explanation/peer-to-peer-demystified) explains how peers find each other and connect directly—no servers—and [How Pear and Bare fit together](/explanation/pear-and-bare) maps the pieces you'll wire together.
</Callout>

Before you start [#before-you-start]

You need:

* [Node.js](https://nodejs.org/) v22.17 or newer and npm v10.9 or newer
* A POSIX-style terminal (macOS, Linux, or Windows with WSL)
* An IDE or text editor

Project layout [#project-layout]

You create five files in a fresh folder:

```text
pear-chat/
├─ package.json        # app metadata, scripts, npm dependencies
├─ electron/
│  ├─ main.js          # CommonJS — window + worker + IPC
│  └─ preload.js       # CommonJS — exposes window.chat to the renderer
├─ renderer/
│  ├─ index.html       # layout + Tailwind CDN script
│  └─ app.js           # DOM + window.chat send/receive
└─ workers/
   └─ main.mjs         # ESM — Hyperswarm (Bare argv/IPC)
```

<Steps>
  <Step>
    Set up the project [#set-up-the-project]

    1. Create the folder and initialise it with npm init -y [#1-create-the-folder-and-initialise-it-with-npm-init--y]

    ```bash
    mkdir pear-chat && cd pear-chat && npm init -y
    ```

    2. Replace the generated package.json with the following [#2-replace-the-generated-packagejson-with-the-following]

    ```json file=<rootDir>/examples/getting-started/chat/package.json title="package.json" lineNumbers {4-8,9-16}
    {
      "name": "pear-chat",
      "version": "1.0.0",
      "main": "electron/main.js",
      "type": "commonjs",
      "scripts": {
        "start": "electron ."
      },
      "dependencies": {
        "b4a": "^1.6.7",
        "hyperswarm": "^4.17.0",
        "pear-runtime": "^1.1.4"
      },
      "devDependencies": {
        "electron": "^40.2.1"
      }
    }
    ```

    `type: "commonjs"` on **line 5** keeps `.js` files using `require`; the Bare worker uses `.mjs` later in this part so it stays an ES module. **Line 4** points Electron at `electron/main.js`; **lines 6–7** wire `npm start`.

    What each dependency does (**lines 9–16**):

    * **Line 12:** [`pear-runtime`](/reference/pear/runtime) lets Electron run a [Bare](/explanation/runtime-and-languages) worker. ([npm](https://www.npmjs.com/package/pear-runtime))
    * **Line 11:** [`hyperswarm`](https://www.npmjs.com/package/hyperswarm) discovers peers on a topic.
    * **Line 10:** [`b4a`](https://www.npmjs.com/package/b4a) is a small Buffer / Uint8Array helper.
    * **Line 15:** [`electron`](https://www.npmjs.com/package/electron) is the desktop shell.

    3. Install the dependencies with npm install [#3-install-the-dependencies-with-npm-install]

    ```bash
    npm install
    ```

    The renderer loads [Tailwind CSS v4](https://tailwindcss.com/) from a CDN inside `index.html` (line 7 of `renderer/index.html` loads [`@tailwindcss/browser`](https://www.npmjs.com/package/@tailwindcss/browser) from jsDelivr), so Tailwind does not appear as an npm dependency.

    The Bare runtime ships as a prebuilt binary inside [`bare-sidecar`](https://www.npmjs.com/package/bare-sidecar), a transitive dependency of `pear-runtime`. There is nothing to compile.
  </Step>

  <Step>
    Write the worker [#write-the-worker]

    The worker is where the peer-to-peer code lives. It runs in a separate [Bare](/explanation/runtime-and-languages) process, not in Electron. That keeps the renderer free of native modules and the Electron main process free of swarm logic.

    1. Create the worker file [#1-create-the-worker-file]

    Create `workers/main.mjs`. The `.mjs` extension matters: it forces ES module loading regardless of `package.json`'s `"type"` field.

    ```js file=<rootDir>/examples/getting-started/chat/workers/main.mjs title="workers/main.mjs" lineNumbers {1-2,5-6,12,15-16,28,34}
    import Hyperswarm from 'hyperswarm' // topic swarms / DHT discovery
    import b4a from 'b4a' // encode/decode binary topic and payloads

    // Topic hex string comes from Electron via Bare.argv (see main process step)
    const topic = b4a.from(Bare.argv[2], 'hex')
    const swarm = new Hyperswarm()
    const conns = [] // active peer sockets

    swarm.on('connection', (conn) => {
      const id = b4a.toString(conn.remotePublicKey, 'hex').slice(0, 6) // short display id
      conns.push(conn)
      Bare.IPC.write(JSON.stringify({ type: 'peers', count: conns.length }))

      conn.on('data', (data) => {
        Bare.IPC.write(
          JSON.stringify({ type: 'message', from: id, text: b4a.toString(data) })
        )
      })

      conn.on('error', () => {}) // ignore transient socket errors
      conn.once('close', () => {
        conns.splice(conns.indexOf(conn), 1)
        Bare.IPC.write(JSON.stringify({ type: 'peers', count: conns.length }))
      })
    })

    // Text from Electron main → broadcast to every peer
    Bare.IPC.on('data', (data) => {
      const text = b4a.toString(data)
      for (const conn of conns) conn.write(text)
    })

    await swarm.join(topic, { client: true, server: true }).flushed()
    Bare.IPC.write(JSON.stringify({ type: 'ready' }))
    ```

    Three things to notice:

    * **Lines 1–2, 6:** The worker depends on nothing Bare-specific beyond `Bare.IPC` and `Bare.argv`. `hyperswarm` and `b4a` are normal npm packages that work in both Bare and Node.
    * **Lines 12, 15–16, 28, 34:** [`Bare.IPC`](/reference/pear/runtime#running-workers) is the worker's pipe back to the Electron main process. Anything you write to `Bare.IPC` shows up as a `'data'` event on the worker handle in Electron (**lines 31–33** of `electron/main.js`).
    * **Line 5:** [`Bare.argv`](/reference/pear/api#bare-argv) holds the arguments the main process passes when it spawns the worker. `Bare.argv[2]` is the first user-supplied arg—the topic hex passed from **line 29** of `electron/main.js`.

    <Callout type="info">
      The worker uses ESM (`import` on **lines 1–2**) because that is Bare's recommended convention for new code. The Electron files in the next steps use CommonJS (`require`) because that is what most Electron projects ship with. The two coexist cleanly thanks to the file-extension split: anything ending in `.mjs` is ESM; anything ending in `.js` follows the `package.json` `"type"` field (**line 5**). See [Runtime and languages](/explanation/runtime-and-languages).
    </Callout>
  </Step>

  <Step>
    <span id="wire-up-electrons-main-process" />

    Wire up Electron's main process [#wire-up-electrons-main-process]

    1. Create the main process file [#1-create-the-main-process-file]

    The main process creates the window and starts the worker. [`PearRuntime.run()`](/reference/pear/runtime#running-workers) does most of the work; everything else is plumbing.

    Create `electron/main.js`:

    ```js file=<rootDir>/examples/getting-started/chat/electron/main.js title="electron/main.js" lineNumbers {5,9-12,28-29,31-33,39-41}
    const { app, BrowserWindow, ipcMain } = require('electron')
    const path = require('path')
    const os = require('os')
    const crypto = require('crypto')
    const PearRuntime = require('pear-runtime') // spawn Bare workers from Node

    // Deterministic per-username topic so two local windows meet,
    // while other readers running the same example stay separate by default
    const topic = crypto
      .createHash('sha256')
      .update('pear-getting-started-chat:' + os.userInfo().username)
      .digest('hex')

    let worker = null // Bare worker handle (duplex stream)

    function createWindow() {
      const win = new BrowserWindow({
        width: 480,
        height: 600,
        webPreferences: {
          preload: path.join(__dirname, 'preload.js'),
          contextIsolation: true,
          sandbox: true,
          nodeIntegration: false
        }
      })

      const workerPath = path.join(__dirname, '..', 'workers', 'main.mjs')
      worker = PearRuntime.run(workerPath, [topic]) // argv[2] in the worker is the topic hex

      worker.on('data', (data) => {
        if (!win.isDestroyed()) win.webContents.send('chat:from-worker', data.toString())
      })

      worker.stderr.on('data', (data) => {
        console.error('[worker]', data.toString())
      })

      ipcMain.handle('chat:send', (_evt, text) => {
        worker.write(Buffer.from(text)) // forwarded to Bare.IPC in the worker
      })

      win.loadFile(path.join(__dirname, '..', 'renderer', 'index.html'))
    }

    app.whenReady().then(createWindow)

    app.on('window-all-closed', () => {
      if (worker) worker.destroy()
      app.quit()
    })
    ```

    Three things happen here:

    * **Lines 9–12:** The topic is derived from the OS username with a fixed prefix. Two **running instances** of this app on your machine automatically find each other. Other readers following this tutorial are isolated by default because their usernames produce a different topic hash. Note that two people on different machines who happen to share the same OS username will also land on the same topic and connect unexpectedly. To share a room intentionally with a specific friend, or to guarantee you stay private, change `'pear-getting-started-chat:'` on **line 11** to any string only the two of you know.
    * **Lines 28–29, 31–33:** [`PearRuntime.run(workerPath, [topic])`](/reference/pear/runtime#running-workers) is the static helper on [`pear-runtime`](/reference/pear/runtime) (**line 5**) that spawns a Bare worker. The second argument becomes the worker's `Bare.argv`—that is how the topic reaches **line 5** of `workers/main.mjs`. The call returns a duplex stream whose other end is `Bare.IPC` inside the worker; **lines 31–33** forward worker output to the renderer.
    * **Lines 28–29:** This is the **simplest** form of [`pear-runtime`](/reference/pear/runtime). [Part 2](/getting-started/build-a-peer-to-peer-chat/reshape-into-a-production-app) reshapes this into the production scaffold, where a dedicated Bare worker owns the OTA updater and a shared [Corestore](/reference/helpers/corestore).
  </Step>

  <Step>
    Add the preload bridge [#add-the-preload-bridge]

    1. Create the preload script [#1-create-the-preload-script]

    The renderer runs in a sandboxed browser context with `contextIsolation: true` (**line 22** of `electron/main.js`). It cannot talk to the worker directly. The preload script is a tiny adapter that exposes a `window.chat` object the renderer uses.

    Create `electron/preload.js`:

    ```js file=<rootDir>/examples/getting-started/chat/electron/preload.js title="electron/preload.js" lineNumbers {4,5-7,8-11}
    const { contextBridge, ipcRenderer } = require('electron')

    // Expose a minimal API to the sandboxed renderer (no direct Node or worker access)
    contextBridge.exposeInMainWorld('chat', {
      send(text) {
        return ipcRenderer.invoke('chat:send', text) // → ipcMain.handle in main
      },
      onMessage(listener) {
        const wrap = (_evt, payload) => listener(JSON.parse(payload))
        ipcRenderer.on('chat:from-worker', wrap) // ← webContents.send from main
        return () => ipcRenderer.removeListener('chat:from-worker', wrap)
      }
    })
    ```

    **Line 4:** [`contextBridge.exposeInMainWorld`](https://www.electronjs.org/docs/latest/api/context-bridge#contextbridgeexposeinmainworldapikey-api) puts a single `chat` object on the renderer's `window` with two methods:

    * **Lines 5–7:** `send(text)` ships a message to the worker through the main process ([lines 39–41 of `electron/main.js`](#wire-up-electrons-main-process)).
    * **Lines 8–11:** `onMessage(listener)` subscribes to anything the worker pushes back ([lines 31–33 of `electron/main.js`](#wire-up-electrons-main-process)).
  </Step>

  <Step>
    Build the renderer [#build-the-renderer]

    The renderer is a normal HTML page. Nothing here is Pear-specific—it calls `window.chat.send` and `window.chat.onMessage` to send and receive.

    <Callout type="info">
      Styling uses [Tailwind CSS](https://tailwindcss.com/) loaded in the page with the v4 browser build from jsDelivr ([`@tailwindcss/browser`](https://www.npmjs.com/package/@tailwindcss/browser)). That script compiles utility classes in the browser, which keeps this tutorial to five files with no CSS build step. For a shipped app you switch to the [Tailwind CLI or a bundler](https://tailwindcss.com/docs/installation).
    </Callout>

    1. Create the index.html file [#1-create-the-indexhtml-file]

    Create `renderer/index.html`:

    ```html file=<rootDir>/examples/getting-started/chat/renderer/index.html title="renderer/index.html" lineNumbers {7,29-31,34,36-41,43}
    <!doctype html>
    <html class="h-full">
      <head>
        <meta charset="utf-8" />
        <title>Pear chat</title>
        <!-- Tailwind v4 in the browser (no npm tailwind in this tutorial) -->
        <script src="https://cdn.jsdelivr.net/npm/@tailwindcss/browser@4"></script>
      </head>
      <body class="flex h-full flex-col bg-zinc-950 font-sans text-zinc-100 antialiased">
        <header class="flex items-center justify-between border-b border-zinc-800 bg-zinc-900/60 px-4 py-3">
          <div class="flex items-center gap-2">
            <svg class="h-5 w-auto" viewBox="0 0 265 358" fill="none" xmlns="http://www.w3.org/2000/svg" aria-label="Pear">
              <path d="M123.036 0H141.964V35.3525H123.036V0Z" fill="#B0D944"/>
              <path d="M113.572 46.5399V53.6999H94.643V62.6499H170.357V53.6999H151.429V39.8274H132.5V46.5399H113.572Z" fill="#B0D944"/>
              <path d="M189.286 67.1249H132.5V73.8374H75.7144V89.9474H189.286V67.1249Z" fill="#B0D944"/>
              <path d="M208.214 94.4224H132.5V101.135H56.7858V117.245H208.214V94.4224Z" fill="#B0D944"/>
              <path d="M208.214 121.72H132.5V128.433H56.7858V144.543H208.214V121.72Z" fill="#B0D944"/>
              <path d="M227.143 149.018H132.5V155.73H37.8573V171.84H227.143V149.018Z" fill="#B0D944"/>
              <path d="M227.143 176.315H132.5V183.028H37.8573V199.138H227.143V176.315Z" fill="#B0D944"/>
              <path d="M246.071 203.613H132.5V210.325H18.9286V226.435H246.071V203.613Z" fill="#B0D944"/>
              <path d="M265 230.91H132.5V237.623H0V253.733H265V230.91Z" fill="#B0D944"/>
              <path d="M265 258.208H132.5V264.92H0V281.03H265V258.208Z" fill="#B0D944"/>
              <path d="M265 285.505H132.5V292.218H0V308.328H265V285.505Z" fill="#B0D944"/>
              <path d="M227.143 312.803H132.5V319.515H37.8573V335.625H227.143V312.803Z" fill="#B0D944"/>
              <path d="M189.286 340.1H132.5V346.812H75.7144V358H189.286V340.1Z" fill="#B0D944"/>
            </svg>
            <h1 class="text-sm font-semibold">Pear chat</h1>
          </div>
          <div class="flex items-center gap-2 text-xs text-zinc-400">
            <span class="size-2 rounded-full bg-emerald-500"></span>
            <span>peers: <span id="peers" class="font-medium text-zinc-100">0</span></span>
          </div>
        </header>
        <main id="log" class="flex-1 space-y-1 overflow-y-auto px-4 py-3 text-sm"></main>
        <footer class="border-t border-zinc-800 bg-zinc-900/60 px-4 py-3">
          <input
            id="input"
            placeholder="type and press enter"
            autofocus
            class="w-full rounded-md border border-zinc-800 bg-zinc-900 px-3 py-2 text-zinc-100 placeholder:text-zinc-500 focus:border-amber-500/50 focus:outline-none focus:ring-2 focus:ring-amber-500/30"
          />
        </footer>
        <script src="app.js"></script>
      </body>
    </html>
    ```

    * **Line 7:** Tailwind v4 browser build from jsDelivr.
    * **Lines 29–31:** peer counter in the header (`#peers`).
    * **Line 34:** scrollable message log (`#log`).
    * **Lines 36–41:** text input (`#input`).
    * **Line 43:** loads `app.js`.

    2. Create the app.js file [#2-create-the-appjs-file]

    Create `renderer/app.js`. It sets up the DOM and listens for events from the worker:

    * **Lines 29–31:** if the event type is `peers`, update the counter; if `message` or `ready`, append a row.
    * **Lines 34–39:** when you press Enter, append locally and call `window.chat.send(text)`—which flows through **lines 5–7** of `preload.js` and **lines 39–41** of `electron/main.js` to **line 28** of `workers/main.mjs`.

    ```js file=<rootDir>/examples/getting-started/chat/renderer/app.js title="renderer/app.js" lineNumbers {28-32,34-39}
    const log = document.getElementById('log')
    const peers = document.getElementById('peers')
    const input = document.getElementById('input')

    const fromColor = {
      system: 'text-zinc-500 italic',
      you: 'text-emerald-400 font-medium',
      peer: 'text-sky-400 font-medium'
    }

    function append(from, text) {
      const row = document.createElement('div')
      row.className = 'flex gap-2 items-baseline'

      const fromEl = document.createElement('span')
      fromEl.className = fromColor[from] ?? fromColor.peer
      fromEl.textContent = from + ':'

      const textEl = document.createElement('span')
      textEl.textContent = text

      row.append(fromEl, textEl)
      log.appendChild(row)
      log.scrollTop = log.scrollHeight // keep latest line visible
    }

    // JSON lines from the worker, forwarded by preload → main → here
    window.chat.onMessage((event) => {
      if (event.type === 'peers') peers.textContent = event.count
      else if (event.type === 'message') append(event.from, event.text)
      else if (event.type === 'ready') append('system', 'connected to swarm')
    })

    input.addEventListener('keydown', (e) => {
      if (e.key !== 'Enter' || !input.value) return
      const text = input.value
      input.value = ''
      append('you', text)
      window.chat.send(text) // preload → main → worker Bare.IPC
    })
    ```
  </Step>

  <Step>
    Run it [#run-it]

    From the `pear-chat` folder run:

    ```bash
    npm start
    ```

    A small dark window opens. The header shows `peers: 0` (**line 31** of `index.html`) and the message log is empty. After about 5 seconds your worker finishes joining the DHT and the log shows `system: connected to swarm` (**line 31** of `app.js`, triggered by **line 34** of `workers/main.mjs`).

    Open a second terminal in the same folder and run `npm start` again. Within a few seconds the two peers find each other and the header on **both** windows ticks to `peers: 1`.

    Type `hey` in one window and press Enter. The other window shows it prefixed with the sender's short peer id—a six-character hex slice of the remote public key.

    What is running:

    * two Electron processes
    * two [Bare workers](/explanation/runtime-and-languages)
    * one DHT topic
    * a direct, end-to-end encrypted peer-to-peer connection between them

    <Callout type="info">
      First connection typically takes 5–15 seconds while [Hyperswarm](/reference/building-blocks/hyperswarm) announces the topic to the DHT. If both peers are on the same machine they connect over the local network; on different networks they hole-punch through the DHT. If two readers happen to share an OS username they find each other on the public DHT—change the prefix string on **line 11** of `electron/main.js` if that bothers you.
    </Callout>
  </Step>
</Steps>

What you built [#what-you-built]

A peer-to-peer desktop chat that runs without a server. Each piece maps to one concept:

| File                   | What it does                                                                                       | Pear concept                                                                   |
| ---------------------- | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| `package.json`         | Declares Electron, [Hyperswarm](/reference/building-blocks/hyperswarm), and `pear-runtime` as deps | What you embed into a JS host                                                  |
| `workers/main.mjs`     | Hyperswarm + topic + connection handlers                                                           | Peer-to-peer code lives in a [Bare worker](/explanation/runtime-and-languages) |
| `electron/main.js`     | `PearRuntime.run()` spawns the worker                                                              | The worker is your local backend                                               |
| `electron/preload.js`  | `contextBridge.exposeInMainWorld('chat', { ... })`                                                 | The single door from renderer to worker                                        |
| `renderer/*.{html,js}` | Plain DOM, no Pear imports                                                                         | The view layer is a plain web page                                             |

Three things are deliberately missing—[part 2](/getting-started/build-a-peer-to-peer-chat/reshape-into-a-production-app) adds them:

* **No persistence.** Messages disappear when you close the window. [Part 2](/getting-started/build-a-peer-to-peer-chat/reshape-into-a-production-app) adds an [Autobase](/reference/building-blocks/autobase)-backed room persisted to disk with [Corestore](/reference/helpers/corestore).
* **No over-the-air updates.** [Part 2](/getting-started/build-a-peer-to-peer-chat/reshape-into-a-production-app) wires a dedicated OTA updater worker with [`pear.updater`](/reference/pear/runtime) events.
* **No packaging.** `npm start` runs Electron in development mode. [Ship your app](/getting-started/build-a-peer-to-peer-chat/ship) covers `electron-forge`, `pear build`, and the first stage; [Deploy over-the-air updates](/getting-started/build-a-peer-to-peer-chat/update) walks the live OTA loop and the `stage → provision → multisig` production flow.

Where to go next [#where-to-go-next]

* **Continue the path:** [Reshape into a production app](/getting-started/build-a-peer-to-peer-chat/reshape-into-a-production-app).
* For the production-grade Electron starter you would actually clone for a real project, see [`hello-pear-electron`](https://github.com/holepunchto/hello-pear-electron).
* To swap [Hyperswarm](/reference/building-blocks/hyperswarm) for a direct one-to-one connection by public key, see [Connect two peers by key with HyperDHT](/how-to/connect-to-peers/connect-two-peers-by-key-with-hyperdht).
* To understand why Pear ships with two runtimes (Node-style for Electron, Bare for workers), read [Runtime and languages](/explanation/runtime-and-languages).


# Reshape into a production app



import { Steps, Step } from 'fumadocs-ui/components/steps'

This is **part 2 of 4** in the [getting started path](/getting-started). [Part 1](/getting-started/build-a-peer-to-peer-chat/build-a-peer-to-peer-chat) built a working chat from scratch with the simplest form of the runtime ([`PearRuntime.run`](/reference/pear/runtime#running-workers)). This part reshapes it into a **production-shaped scaffold** built on the same patterns as Pear's official [`hello-pear-electron`](https://github.com/holepunchto/hello-pear-electron) template—a Bare worker behind a preload bridge, an OTA updater worker, and Electron Forge packaging—the same patterns [Keet](https://keet.io) and [PearPass](https://pass.pears.com) use under the hood.

By the end you have the shared **`pear-chat` scaffold** every chat-family and media how-to in [the How To guides](/how-to) extends. There is no separate intermediate app—part 2 is the finished template shape:

* A separate [Bare worker](/explanation/runtime-and-languages) that owns all the P2P code.
* An [Autobase](/reference/building-blocks/autobase)-backed shared room with [blind-pairing](https://www.npmjs.com/package/blind-pairing) invite codes, so two peers join from a short string without exposing keys.
* On-disk persistence via [Corestore](/reference/helpers/corestore) + a [HyperDB](https://www.npmjs.com/package/hyperdb) view—the conversation survives restarts.
* A separate [OTA updater worker](/explanation/deployment-releasing-apps-p2p#ota-update-event-lifecycle), wired but inert, ready for [part 3](/getting-started/build-a-peer-to-peer-chat/ship) and [part 4](/getting-started/build-a-peer-to-peer-chat/update) to flip on.
* A polished [Tailwind CSS](https://tailwindcss.com/) UI (compiled by the CLI, not the CDN) with a peer counter and a **copy-invite** button.

{/*
  Shared snippet (content/_snippets/) included via Fumadocs <include> by every getting-started step.
  Reminds readers that a production-ready reference implementation already exists
  upstream, so they can clone it any time without abandoning the type-along.
  See: https://www.fumadocs.dev/docs/markdown#include
  */}

<Callout type="info">
  **Full production-ready reference: `hello-pear-electron`.** The complete version of this chat lives at [`holepunchto/hello-pear-electron`](https://github.com/holepunchto/hello-pear-electron)—Holepunch's official Electron template, the same shape [Keet](https://keet.io) and [PearPass](https://pass.pears.com) ship. Clone it any time to see the finished structure or to crib code. For a guided tour of the template, see [Start from the hello-pear-electron template](/getting-started/from-a-template/start-from-hello-pear-electron).
</Callout>

What you'll build [#what-youll-build]

A standalone Electron app that:

* Runs the actual peer-to-peer code inside a [Bare worker](/explanation/runtime-and-languages), keeping native modules out of the renderer and Electron's main thread:
  * [Hyperswarm](/reference/building-blocks/hyperswarm) finds and connects peers over the DHT.
  * [Corestore](/reference/helpers/corestore) is the on-disk store that holds the app's Hypercores.
  * [Autobase](/reference/building-blocks/autobase) is the multi-writer log that merges every peer's messages into one shared room view.
  * [blind-pairing](https://www.npmjs.com/package/blind-pairing) lets a new peer join from a short invite code without either side exposing its keys.
* Pairs two peers via an **invite code** generated from the room owner's Autobase key—the UI exposes it behind a copy button.
* Persists every message to disk in an [Autobase-backed HyperDB view](/reference/building-blocks/autobase), so reopening the app replays the conversation.
* Embeds the [`pear-runtime`](/reference/pear/runtime) OTA updater in its **own** Bare worker, so update traffic never blocks the chat.
* Renders a vanilla HTML + [Tailwind CSS](https://tailwindcss.com/) UI that talks to the worker by exchanging JSON over a framed pipe—no bundler, no framework.

<Mermaid
  chart="flowchart LR
  subgraph Electron
    R[HTML renderer]
    M[Main process<br/>worker bridge]
  end
  W[Bare chat worker<br/>WorkerTask + ChatRoom]
  U[Bare updater worker<br/>PearRuntime OTA]
  P[(Corestore +<br/>Autobase + HyperDB)]
  S{{Hyperswarm}}

  R <-->|preload IPC| M
  M <-->|FramedStream| W
  M <-->|FramedStream| U
  W <--> P
  W <--> S"
/>

<Callout type="info">
  For the conceptual picture behind this split—why a production app separates OTA updates, storage, and workers—read [Pear desktop application architecture](/explanation/pear-desktop-architecture).
</Callout>

Before you start [#before-you-start]

You need:

* [Node.js](https://nodejs.org/) v22.17 or newer and npm v10.9 or newer.
* A POSIX-style terminal (macOS, Linux, or Windows with WSL).
* An IDE or text editor.
* The working chat from [part 1—build the peer-to-peer chat](/getting-started/build-a-peer-to-peer-chat/build-a-peer-to-peer-chat), so you are comfortable with [`PearRuntime.run()`](/reference/pear/runtime#running-workers), [Bare workers](/explanation/workers), and [Hyperswarm](/reference/building-blocks/hyperswarm) topics.

<Callout type="info">
  Part 1 was type-along in five files. The production scaffold is \~14 files and a generated `spec/` directory—too much to retype. **Clone the repo** and walk the working code as this part explains it. Every snippet points to a real file so you can read the surrounding context.
</Callout>

<Steps>
  <Step>
    Clone the example [#clone-the-example]

    ```bash skip="desktop-gui"
    git clone https://github.com/holepunchto/pear-docs
    cd pear-docs
    git switch published
    cd examples/getting-started/pear-chat
    npm install
    npm run build
    ```

    `npm run build` does two things you must run before the first `npm start`:

    * `build:db` runs `node schema.js` to generate the `spec/` directory (HyperSchema records, the HyperDB view, and the HyperDispatch encoders).
    * `build:tailwind` compiles `input.css` into `renderer/build/output.css` with the [Tailwind CLI](https://tailwindcss.com/docs/installation)—replacing part 1's in-browser CDN script.

    You should now have a `pear-chat/` directory laid out like this:

    ```text
    pear-chat/
    ├─ build/                # icons + per-OS packaging assets
    ├─ electron/
    │  ├─ main.js            # spawns the chat worker + the updater worker
    │  └─ preload.js         # contextBridge exposing window.bridge
    ├─ renderer/
    │  ├─ app.js             # vanilla DOM + worker bridge
    │  └─ index.html         # chat shell (Tailwind classes)
    ├─ spec/                 # generated HyperDispatch + HyperDB schemas
    ├─ workers/
    │  ├─ chat-room.js       # Autobase + blind-pairing room
    │  ├─ index.js           # Bare chat worker entrypoint
    │  ├─ main.js            # Bare updater worker (PearRuntime OTA)
    │  └─ worker-task.js     # WorkerTask: Corestore + Hyperswarm + ChatRoom
    ├─ forge.config.js       # Electron Forge makers + signing hooks
    ├─ input.css             # Tailwind v4 entrypoint
    ├─ package.json          # app metadata, scripts, deps
    ├─ pear.json             # multisig namespace for OTA releases
    └─ schema.js             # regenerates spec/ from schema definitions
    ```

    The four "moving parts" are `electron/`, `workers/`, `spec/`, and `renderer/`. Everything else is plumbing or build config.
  </Step>

  <Step>
    Read the Bare chat worker [#read-the-bare-chat-worker]

    The worker is the **only** place P2P code lives. The renderer never imports [Hyperswarm](/reference/building-blocks/hyperswarm) or [Corestore](/reference/helpers/corestore); the main process barely touches them. That isolation keeps native modules out of the browser-style sandbox and off Electron's main thread.

    Open `workers/index.js`. It is the Bare-side entrypoint and is intentionally tiny:

    ```js file=<rootDir>/examples/getting-started/pear-chat/workers/index.js title="workers/index.js" lineNumbers {9-13,15-16,23-24,26-27,29-30,32-34,37-40}
    const FramedStream = require('framed-stream')
    const fs = require('bare-fs')
    const goodbye = require('graceful-goodbye')
    const { command, flag } = require('paparam')
    const path = require('bare-path')

    const WorkerTask = require('./worker-task.js')

    const cmd = command('pear-chat',
      flag('--invite|-i <invite>', 'Room invite'),
      flag('--name|-n <name>', 'Your name'),
      flag('--reset', 'Reset')
    )

    const storage = path.join(Bare.argv[2], 'corestore')
    cmd.parse(Bare.argv.slice(3))

    async function main () {
      if (cmd.flags.reset) {
        await fs.promises.rm(storage, { recursive: true, force: true })
      }

      const pipe = new FramedStream(Bare.IPC)
      pipe.pause()

      const workerTask = new WorkerTask(pipe, storage, cmd.flags)
      goodbye(() => workerTask.close())

      await workerTask.ready()
      pipe.resume()

      console.log(`Storage: ${storage}`)
      console.log(`Name: ${workerTask.name}`)
      console.log(`Invite: ${await workerTask.room.getInvite()}`)
    }

    main().catch((err) => {
      console.error(err)
      Bare.exit(1)
    })
    ```

    Things to notice:

    * **Lines 9–13:** the worker declares its flags with [`paparam`](https://www.npmjs.com/package/paparam): `--invite`/`-i` (the room code a joining peer pastes), `--name`/`-n`, and `--reset`.
    * **Lines 15–16:** `Bare.argv[2]` is the storage directory the main process passes when it spawns the worker; the remaining flags are parsed on line 16.
    * **Lines 23–24:** the worker wraps [`Bare.IPC`](/reference/pear/runtime#running-workers) in a [`framed-stream`](https://www.npmjs.com/package/framed-stream), then pauses it until the task is ready. From here on, worker and renderer talk by exchanging JSON over this framed pipe—no typed RPC layer.
    * **Lines 26–27 and 29–30:** `WorkerTask` extends [`ready-resource`](https://www.npmjs.com/package/ready-resource) so open/close are explicit lifecycle steps. [`graceful-goodbye`](https://www.npmjs.com/package/graceful-goodbye) registers its `close()` for shutdown. Once ready, line 30 resumes the stream so buffered frames flow.
    * **Lines 32–34:** the `console.log` lines print the storage path, the chosen name, and the room invite—handy when running two peers from the terminal.
  </Step>

  <Step>
    Trace WorkerTask [#trace-workertask]

    Open `workers/worker-task.js`. This is the worker's "main object"—it owns a Corestore, a Hyperswarm, and a `ChatRoom`, and it speaks JSON to the renderer over the pipe:

    ```js file=<rootDir>/examples/getting-started/pear-chat/workers/worker-task.js title="workers/worker-task.js" lineNumbers {18-28,42-49,58-61,63-67}
    const Corestore = require('corestore')
    const debounce = require('debounceify')
    const Hyperswarm = require('hyperswarm')
    const ReadyResource = require('ready-resource')

    const ChatRoom = require('./chat-room')

    class WorkerTask extends ReadyResource {
      constructor (pipe, storage, opts = {}) {
        super()

        this.pipe = pipe
        this.storage = storage
        this.invite = opts.invite
        this.name = opts.name || `User ${Date.now()}`
        this.peers = 0

        this.store = new Corestore(storage)
        this.swarm = new Hyperswarm()
        this.swarm.on('connection', (conn) => {
          this.store.replicate(conn)
          this._peers(1)
          conn.once('close', () => this._peers(-1))
        })

        this.room = new ChatRoom(this.store, this.swarm, this.invite)
        this.debounceMessages = debounce(() => this._messages())
        this.room.on('update', () => this.debounceMessages())
      }

      async _open () {
        await this.store.ready()
        await this.room.ready()

        this.pipe.on('data', async (data) => {
          let message
          try {
            message = JSON.parse(data)
          } catch {
            return
          }
          if (message.type === 'add-message') {
            await this.room.addMessage(message.text, { name: this.name, at: Date.now() })
          }
        })

        // Push the room invite so the renderer can show its "copy invite" button.
        this.pipe.write(JSON.stringify({ type: 'invite', invite: await this.room.getInvite() }))
        await this.debounceMessages()
      }

      async _close () {
        await this.room.close()
        await this.swarm.destroy()
        await this.store.close()
      }

      _peers (delta) {
        this.peers += delta
        this.pipe.write(JSON.stringify({ type: 'peers', count: this.peers }))
      }

      async _messages () {
        const messages = await this.room.getMessages()
        messages.sort((a, b) => a.info.at - b.info.at)
        this.pipe.write(JSON.stringify({ type: 'messages', messages }))
      }
    }

    module.exports = WorkerTask
    ```

    The lifecycle is canonical Pear shape:

    * **Construct (L9–L29)**—wire dependencies, do not perform I/O. The [Corestore](/reference/helpers/corestore), [Hyperswarm](/reference/building-blocks/hyperswarm), and `ChatRoom` are created. On every swarm `connection` the store replicates and the peer count ticks (L20–L24); the room's `update` event is wired to a debounced `_messages()` push (L27–L28).
    * **`_open()` (L31–L50)**—open the store and room, subscribe to incoming renderer IPC (JSON parsed off the pipe, L35–L45), then push the room's invite (L48) and the first batch of messages (L49) to the renderer.
    * **`_peers()` (L58–L61)**—every connect/disconnect writes a `{ type: 'peers', count }` frame, which lights the renderer's status dot.
    * **`_messages()` (L63–L67)**—read every message from the room, sort by timestamp, and write a `{ type: 'messages', messages }` frame. Runs once on open and again, debounced, on every room `update`.

    The two additions over the bare scaffold are the **peer counter** and the **invite push** (L48)—the worker hands the renderer the room code so the UI can show a working "Copy invite" button.

    <Callout type="info">
      For why P2P state is owned by the worker rather than the renderer, read [Workers](/explanation/workers).
    </Callout>
  </Step>

  <Step>
    Read ChatRoom [#read-chatroom]

    `workers/chat-room.js` is the actual peer-to-peer data structure. It combines four building blocks:

    * An [Autobase](/reference/building-blocks/autobase) so multiple writers (each peer's local core) merge into one deterministic materialised view.
    * A [HyperDB](https://www.npmjs.com/package/hyperdb) view (a [Hyperbee](/reference/building-blocks/hyperbee)-derived database) for the `messages` and `invites` tables.
    * [HyperDispatch](https://www.npmjs.com/package/hyperdispatch) for typed Autobase `append` payloads (`@pear-chat/add-message`, `@pear-chat/add-writer`, `@pear-chat/add-invite`).
    * [`blind-pairing`](https://www.npmjs.com/package/blind-pairing) so a new peer joins with only a short invite code—the inviter never sees the joiner's key in plaintext.

    These come together when peer **B** joins peer **A**'s room.

    **1. A creates an invite.** `getInvite()` appends a `@pear-chat/add-invite` record to the Autobase and returns a [z32](https://www.npmjs.com/package/z32)-encoded invite code (this is the string the worker pushes to the renderer's copy button):

    ```js file=<rootDir>/examples/getting-started/pear-chat/workers/chat-room.js#L127-L137 title="workers/chat-room.js"
      async getInvite () {
        const existing = await this.view.findOne('@pear-chat/invites', {})
        if (existing) {
          return z32.encode(existing.invite)
        }
        const { id, invite, publicKey, expires } = BlindPairing.createInvite(this.base.key)
        await this.base.append(
          ChatDispatch.encode('@pear-chat/add-invite', { id, invite, publicKey, expires })
        )
        return z32.encode(invite)
      }
    ```

    **2. B pairs as a candidate.** In `_open`, an empty local core *and* an `--invite` means the room uses [`blind-pairing`](https://www.npmjs.com/package/blind-pairing) as a candidate to reach **A** over the swarm and receive the Autobase keys:

    ```js file=<rootDir>/examples/getting-started/pear-chat/workers/chat-room.js#L37-L47 title="workers/chat-room.js"
        if (isEmpty && this.invite) {
          const res = await new Promise((resolve) => {
            this.pairing.addCandidate({
              invite: z32.decode(this.invite),
              userData: localKey,
              onadd: resolve
            })
          })
          key = res.key
          encryptionKey = res.encryptionKey
        }
    ```

    **3. A confirms and adds B as a writer.** A's `pairing.addMember` `onadd` handler resolves the invite, calls `addWriter(B.key)`, and hands back the Autobase root and encryption keys:

    ```js file=<rootDir>/examples/getting-started/pear-chat/workers/chat-room.js#L72-L85 title="workers/chat-room.js"
        this.pairMember = this.pairing.addMember({
          discoveryKey: this.base.discoveryKey,
          /** @type {function(import('blind-pairing-core').MemberRequest)} */
          onadd: async (request) => {
            const inv = await this.view.findOne('@pear-chat/invites', { id: request.inviteId })
            if (!inv) return
            request.open(inv.publicKey)
            await this.addWriter(request.userData)
            request.confirm({
              key: this.base.key,
              encryptionKey: this.base.encryptionKey
            })
          }
        })
    ```

    **4. B opens the shared Autobase.** With those keys, **B** opens the base, joins the discovery topic on the swarm, and waits for the writable signal before replicating:

    ```js file=<rootDir>/examples/getting-started/pear-chat/workers/chat-room.js#L52-L68 title="workers/chat-room.js"
        this.base = new Autobase(this.store, key, {
          encrypt: true,
          encryptionKey,
          open: this._openBase.bind(this),
          close: this._closeBase.bind(this),
          apply: this._applyBase.bind(this)
        })

        const writablePromise = new Promise((resolve) => {
          this.base.on('update', () => {
            if (this.base.writable) resolve()
            if (!this.base._interrupting) this.emit('update')
          })
        })
        await this.base.ready()
        this.swarm.join(this.base.discoveryKey)
        if (!this.base.writable) await writablePromise
    ```

    Any message either peer adds is appended to its local Autobase core, replicated through the swarm, and applied to the shared HyperDB view. The room emits `update` on every Autobase update; `WorkerTask` debounces those into a single `{ type: 'messages', messages }` write back to the renderer.

    <Callout type="info">
      For the deeper picture of Autobase merging, read [From append-only logs to files](/explanation/from-logs-to-files).
    </Callout>
  </Step>

  <Step>
    Understand spec/ [#understand-spec]

    The `spec/` directory holds **generated** code—that's why `npm run build` had to run before the first start. `schema.js` at the repo root regenerates everything in `spec/` from declarative definitions, in three blocks.

    `spec/schema/`—the canonical record shapes (`writer`, `invite`, `message`) registered with HyperSchema:

    ```js file=<rootDir>/examples/getting-started/pear-chat/schema.js#L9-L34 title="schema.js — records"
    const hyperSchema = Hyperschema.from(SCHEMA_DIR)
    const schema = hyperSchema.namespace('pear-chat')
    schema.register({
      name: 'writer',
      fields: [
        { name: 'key', type: 'buffer', required: true }
      ]
    })
    schema.register({
      name: 'invite',
      fields: [
        { name: 'id', type: 'buffer', required: true },
        { name: 'invite', type: 'buffer', required: true },
        { name: 'publicKey', type: 'buffer', required: true },
        { name: 'expires', type: 'int', required: true }
      ]
    })
    schema.register({
      name: 'message',
      fields: [
        { name: 'id', type: 'string', required: true },
        { name: 'text', type: 'string', required: true },
        { name: 'info', type: 'json' }
      ]
    })
    Hyperschema.toDisk(hyperSchema)
    ```

    `spec/db/`—typed HyperDB collections (`@pear-chat/messages`, `@pear-chat/invites`), each keyed by `id`:

    ```js file=<rootDir>/examples/getting-started/pear-chat/schema.js#L36-L48 title="schema.js — collections"
    const hyperdb = HyperdbBuilder.from(SCHEMA_DIR, DB_DIR)
    const db = hyperdb.namespace('pear-chat')
    db.collections.register({
      name: 'invites',
      schema: '@pear-chat/invite',
      key: ['id']
    })
    db.collections.register({
      name: 'messages',
      schema: '@pear-chat/message',
      key: ['id']
    })
    HyperdbBuilder.toDisk(hyperdb)
    ```

    `spec/dispatch/`—typed [Autobase](/reference/building-blocks/autobase) append-payload encoders, one per record type:

    ```js file=<rootDir>/examples/getting-started/pear-chat/schema.js#L50-L55 title="schema.js — dispatch"
    const hyperdispatch = Hyperdispatch.from(SCHEMA_DIR, DISPATCH_DIR, { offset: 0 })
    const dispatch = hyperdispatch.namespace('pear-chat')
    dispatch.register({ name: 'add-writer', requestType: '@pear-chat/writer' })
    dispatch.register({ name: 'add-invite', requestType: '@pear-chat/invite' })
    dispatch.register({ name: 'add-message', requestType: '@pear-chat/message' })
    Hyperdispatch.toDisk(hyperdispatch)
    ```

    You do not normally edit files under `spec/`. To change a message shape or add a record type, edit `schema.js` and re-run `npm run build:db`. For why P2P apps benefit from schema-first design, see [Schema-first design](/explanation/workers#schema-first-design).
  </Step>

  <Step>
    Read the Electron main process [#read-the-electron-main-process]

    Open `electron/main.js`. The whole app is CommonJS—mirroring [`hello-pear-electron`](https://github.com/holepunchto/hello-pear-electron). The main process keeps Electron's UI thread free of P2P work by spawning two [workers](/explanation/workers)—separate Bare processes—and brokering messages between them and the renderer.

    Chat worker [#chat-worker]

    The chat worker (`workers/index.js`) owns the Corestore, swarm, and `ChatRoom`. The main process spawns it and relays its byte streams to every window. Because `Bare.IPC` is a raw byte stream, the main process wraps the worker in a [`FramedStream`](https://www.npmjs.com/package/framed-stream) and forwards deframed frames:

    ```js file=<rootDir>/examples/getting-started/pear-chat/electron/main.js#L101-L138 title="electron/main.js — chat worker"
    function getWorker (specifier) {
      if (workers.has(specifier)) return workers.get(specifier)
      const storage = path.join(getStorageDir(), 'app-storage')
      const worker = PearRuntime.run(require.resolve('..' + specifier), [storage, ...passthroughArgs])
      const pipe = new FramedStream(worker)
      function sendWorkerStdout (data) {
        process.stdout.write(data)
        sendToAll('pear:worker:stdout:' + specifier, data)
      }
      function sendWorkerStderr (data) {
        process.stderr.write(data)
        sendToAll('pear:worker:stderr:' + specifier, data)
      }
      function sendWorkerIPC (data) {
        sendToAll('pear:worker:ipc:' + specifier, data)
      }
      function onBeforeQuit () {
        pipe.destroy()
      }
      ipcMain.handle('pear:worker:writeIPC:' + specifier, (evt, data) => {
        return pipe.write(data)
      })
      workers.set(specifier, pipe)
      pipe.on('data', sendWorkerIPC)
      worker.stdout.on('data', sendWorkerStdout)
      worker.stderr.on('data', sendWorkerStderr)
      worker.once('exit', (code) => {
        app.removeListener('before-quit', onBeforeQuit)
        ipcMain.removeHandler('pear:worker:writeIPC:' + specifier)
        pipe.removeListener('data', sendWorkerIPC)
        worker.stdout.removeListener('data', sendWorkerStdout)
        worker.stderr.removeListener('data', sendWorkerStderr)
        sendToAll('pear:worker:exit:' + specifier, code)
        workers.delete(specifier)
      })
      app.on('before-quit', onBeforeQuit)
      return pipe
    }
    ```

    `getWorker` spawns the worker with the `PearRuntime.run` shortcut and fans four named IPC channels out to every window (`pear:worker:ipc`, `:stdout`, `:stderr`, `:exit`), plus a `pear:worker:writeIPC` handler the renderer calls to send bytes back.

    Updater worker [#updater-worker]

    The updater worker (`workers/main.js`) runs the [`pear-runtime`](/reference/pear/runtime) OTA updater with its **own** swarm and Corestore, downloads new application drives from peers, and emits `updating`/`updated`. When the main process asks it to apply a downloaded release, it calls `pear.updater.applyUpdate()` and replies `pear:updateApplied`. Upstream ships this **exact** worker as the [`hello-pear-worker`](https://github.com/holepunchto/hello-pear-worker) package—here it's inlined so you can read what it does:

    ```js file=<rootDir>/examples/getting-started/pear-chat/workers/main.js title="workers/main.js — updater worker" lineNumbers {10-13,15-22,24-27,30-36,40-41,49-56}
    const PearRuntime = require('pear-runtime') // pear-runtime on desktop; pear-mobile on mobile
    const Hyperswarm = require('hyperswarm')
    const Corestore = require('corestore')
    const goodbye = require('graceful-goodbye')
    const FramedStream = require('framed-stream')
    const path = require('bare-path')
    const dir = require('bare-storage')
    const { isBareKit } = require('which-runtime')

    // mobile doesn't have the executable path (argv[0])
    // and the worker entry path (argv[1]) in the workers argv's
    // ... to reuse the same worker in all platforms this logic is needed
    const argv = (index) => Bare.argv[index + (isBareKit ? 0 : 2)]

    const updaterConfig = {
      updates: argv(0) !== 'false',
      version: argv(1),
      upgrade: argv(2),
      name: argv(3),
      dir: argv(4) || dir.persistent(), // argv[4] is undefined in mobile
      app: argv(5) // argv[5] is undefined in mobile
    }

    const pipe = new FramedStream(Bare.IPC)
    const store = new Corestore(path.join(updaterConfig.dir, 'pear-runtime', 'corestore'))
    const swarm = new Hyperswarm()
    const pear = new PearRuntime({ ...updaterConfig, swarm, store })

    pear.updater.on('error', console.error)
    if (updaterConfig.updates !== false) {
      swarm.on('connection', (connection) => store.replicate(connection))
      swarm.join(pear.updater.drive.core.discoveryKey, {
        client: true,
        server: false
      })
    }

    console.log('Application storage:', pear.storage)

    pear.updater.on('updating', () => pipe.write('updating'))
    pear.updater.on('updated', () => pipe.write('updated'))

    goodbye(async () => {
      await swarm.destroy()
      await pear.close()
      await store.close()
    })

    pipe.on('data', async (data) => {
      const message = data.toString()
      if (message === 'pear:applyUpdate') {
        await pear.ready()
        await pear.updater.applyUpdate()
        pipe.write('pear:updateApplied')
      } else console.log(message)
    })

    pipe.write('Hello from worker')
    ```

    Things to notice:

    * **Lines 10–13:** an `argv()` helper offsets `Bare.argv` so the same worker reads its arguments identically on desktop and on mobile (`bare-kit`), where the executable and entry paths aren't present.
    * **Lines 15–22:** the runtime config the host passed positionally—`updates`, `version`, `upgrade`, `name`, storage `dir`, and the running `app` path—reassembled into one object, with `dir` falling back to the persistent per-app directory.
    * **Lines 24–27:** the worker opens its **own** `FramedStream` pipe, [Corestore](/reference/helpers/corestore), and [Hyperswarm](/reference/building-blocks/hyperswarm), then constructs the `pear-runtime` updater over them—independent of the chat worker's swarm and store.
    * **Lines 30–36:** with updates enabled, it replicates the store on every connection and joins the update drive's discovery key as a client to pull new releases from seeding peers.
    * **Lines 40–41:** the updater's `updating` and `updated` events are forwarded to the main process as pipe messages.
    * **Lines 49–56:** on `pear:applyUpdate` from the main process, it awaits `pear.ready()`, applies the release, and replies `pear:updateApplied`.

    The main process does **not** embed `new PearRuntime({ ... })`; like the template, it keeps the updater in its own Bare worker so update traffic never blocks the chat. It only spawns the worker, wraps it in a `FramedStream`, and relays `pear:event:updating` / `pear:event:updated`:

    ```js file=<rootDir>/examples/getting-started/pear-chat/electron/main.js#L142-L179 title="electron/main.js — updater worker"
    function getUpdaterPipe () {
      if (updaterPipe) return updaterPipe
      const dir = getStorageDir()
      const appPath = getAppPath()
      const extension = isLinux ? '.AppImage' : isMac ? '.app' : '.msix'
      const worker = PearRuntime.run(require.resolve('..' + updaterSpecifier), [
        updates,
        version,
        upgrade,
        productName + extension,
        dir,
        appPath
      ])
      const pipe = new FramedStream(worker)

      function onData (data) {
        const message = data.toString()
        if (message === 'updating') sendToAll('pear:event:updating', 'updating')
        else if (message === 'updated') sendToAll('pear:event:updated', 'updated')
      }
      function onStderr (data) {
        process.stderr.write(data)
      }
      function onBeforeQuit () {
        pipe.destroy()
      }
      pipe.on('data', onData)
      worker.stderr.on('data', onStderr)
      worker.once('exit', () => {
        app.removeListener('before-quit', onBeforeQuit)
        pipe.removeListener('data', onData)
        worker.stderr.removeListener('data', onStderr)
        updaterPipe = null
      })
      app.on('before-quit', onBeforeQuit)
      updaterPipe = pipe
      return pipe
    }
    ```

    `applyUpdate` swaps the app on disk; `app:afterUpdate` relaunches the process. The renderer wires both into a button:

    ```js file=<rootDir>/examples/getting-started/pear-chat/electron/main.js#L215-L247 title="electron/main.js — apply + relaunch"
    ipcMain.handle('pear:applyUpdate', () => {
      const pipe = getUpdaterPipe()

      return new Promise((resolve) => {
        function onData (data) {
          if (data.toString() === 'pear:updateApplied') {
            pipe.removeListener('data', onData)
            resolve()
          }
        }

        pipe.on('data', onData)
        pipe.write('pear:applyUpdate')
      })
    })
    ipcMain.handle('pear:startWorker', (evt, filename) => {
      getWorker(filename)
      return true
    })
    ipcMain.handle('app:afterUpdate', () => {
      if (isLinux && process.env.APPIMAGE) {
        app.relaunch({
          execPath: process.env.APPIMAGE,
          args: [
            '--appimage-extract-and-run',
            ...process.argv.slice(1).filter((arg) => arg !== '--appimage-extract-and-run')
          ]
        })
      } else if (!isWindows) {
        app.relaunch()
      }
      app.quit()
    })
    ```

    Single-instance lock + deep links [#single-instance-lock--deep-links]

    `requestSingleInstanceLock` makes a `pear-chat://` deep link from the OS go to the running instance instead of spawning a second one. `setAsDefaultProtocolClient(protocol)` registers the scheme:

    ```js file=<rootDir>/examples/getting-started/pear-chat/electron/main.js#L253-L292 title="electron/main.js — single instance"
    app.setAsDefaultProtocolClient(protocol)

    app.on('open-url', (evt, url) => {
      evt.preventDefault()
      handleDeepLink(url)
    })

    const lock = app.requestSingleInstanceLock()

    if (!lock) {
      app.quit()
    } else {
      app.on('second-instance', (evt, args) => {
        const url = args.find((arg) => arg.startsWith(protocol + '://'))
        if (url) handleDeepLink(url)
      })

      app.whenReady().then(() => {
        createWindow()
          .then(() => getUpdaterPipe())
          .catch((err) => {
            console.error('Failed to create window:', err)
            app.quit()
          })

        app.on('activate', () => {
          if (BrowserWindow.getAllWindows().length === 0) {
            createWindow().catch((err) => {
              console.error('Failed to create window:', err)
            })
          }
        })
      })

      app.on('window-all-closed', () => {
        if (process.platform !== 'darwin') {
          app.quit()
        }
      })
    }
    ```
  </Step>

  <Step>
    Expose the bridge in electron/preload.js [#expose-the-bridge-in-electronpreloadjs]

    The renderer never sees the worker handle directly. It only sees `window.bridge`:

    ```js file=<rootDir>/examples/getting-started/pear-chat/electron/preload.js title="electron/preload.js" {8,16,27-39}
    const { contextBridge, ipcRenderer, webUtils } = require('electron')

    contextBridge.exposeInMainWorld('bridge', {
      pkg () {
        return ipcRenderer.sendSync('pkg')
      },
      getPathForFile: (file) => webUtils.getPathForFile(file),
      writeClipboard: (text) => ipcRenderer.invoke('clipboard:write', text),
      applyUpdate: () => ipcRenderer.invoke('pear:applyUpdate'),
      appAfterUpdate: () => ipcRenderer.invoke('app:afterUpdate'),
      onPearEvent: (name, listener) => {
        const wrap = (evt, eventName) => listener(eventName)
        ipcRenderer.on('pear:event:' + name, wrap)
        return () => ipcRenderer.removeListener('pear:event:' + name, wrap)
      },
      startWorker: (specifier) => ipcRenderer.invoke('pear:startWorker', specifier),
      onWorkerStdout: (specifier, listener) => {
        const wrap = (evt, data) => listener(new Uint8Array(data))
        ipcRenderer.on('pear:worker:stdout:' + specifier, wrap)
        return () => ipcRenderer.removeListener('pear:worker:stdout:' + specifier, wrap)
      },
      onWorkerStderr: (specifier, listener) => {
        const wrap = (evt, data) => listener(new Uint8Array(data))
        ipcRenderer.on('pear:worker:stderr:' + specifier, wrap)
        return () => ipcRenderer.removeListener('pear:worker:stderr:' + specifier, wrap)
      },
      onWorkerIPC: (specifier, listener) => {
        const wrap = (evt, data) => listener(new Uint8Array(data))
        ipcRenderer.on('pear:worker:ipc:' + specifier, wrap)
        return () => ipcRenderer.removeListener('pear:worker:ipc:' + specifier, wrap)
      },
      onWorkerExit: (specifier, listener) => {
        const wrap = (evt, code) => listener(code)
        ipcRenderer.on('pear:worker:exit:' + specifier, wrap)
        return () => ipcRenderer.removeListener('pear:worker:exit:' + specifier, wrap)
      },
      writeWorkerIPC: (specifier, data) => {
        return ipcRenderer.invoke('pear:worker:writeIPC:' + specifier, data)
      }
    })
    ```

    This is the **single door** between the HTML renderer and the Bare workers. It is intentionally narrow—`startWorker`, `writeWorkerIPC`, `onWorkerIPC`, `onWorkerExit` for the worker, `onPearEvent` / `applyUpdate` / `appAfterUpdate` for OTA, and one extra this part adds:

    * `writeClipboard` (line 8), which the copy-invite button calls.
    * The renderer sends `{ type: 'add-message', text }` and receives `{ type: 'messages' }`, `{ type: 'peers' }`, and `{ type: 'invite' }`—all plain JSON over the bridge.

    <Callout type="info">
      For *why* this split exists, read [the process model](/explanation/pear-desktop-architecture#process-model).
    </Callout>
  </Step>

  <Step>
    Read the renderer [#read-the-renderer]

    The renderer is **vanilla HTML + JavaScript**—no framework, no bundler—styled with [Tailwind CSS v4](https://tailwindcss.com/) compiled by the CLI (the `build:tailwind` script), not the part-1 CDN script. Two files matter.

    renderer/index.html [#rendererindexhtml]

    The static chat shell:

    * a header with the Pear logo, a peer-status dot,
    * a **Copy invite** button,
    * an "Update ready" button (hidden until OTA fires),
    * a scrollable message list,
    * a composer form, and
    * every class is a Tailwind utility scanned out of the markup at build time:

    ```html file=<rootDir>/examples/getting-started/pear-chat/renderer/index.html#L12-L47 title="renderer/index.html — header"
      <header class="px-6 py-4 border-b border-neutral-900 flex items-center justify-between gap-4">
        <div class="flex items-center gap-2.5">
          <svg class="h-5 w-auto" viewBox="0 0 265 358" fill="none" xmlns="http://www.w3.org/2000/svg" aria-hidden="true">
            <path d="M123.036 0H141.964V35.3525H123.036V0Z" fill="#B0D944"/>
            <path d="M113.572 46.5399V53.6999H94.643V62.6499H170.357V53.6999H151.429V39.8274H132.5V46.5399H113.572Z" fill="#B0D944"/>
            <path d="M189.286 67.1249H132.5V73.8374H75.7144V89.9474H189.286V67.1249Z" fill="#B0D944"/>
            <path d="M208.214 94.4224H132.5V101.135H56.7858V117.245H208.214V94.4224Z" fill="#B0D944"/>
            <path d="M208.214 121.72H132.5V128.433H56.7858V144.543H208.214V121.72Z" fill="#B0D944"/>
            <path d="M227.143 149.018H132.5V155.73H37.8573V171.84H227.143V149.018Z" fill="#B0D944"/>
            <path d="M227.143 176.315H132.5V183.028H37.8573V199.138H227.143V176.315Z" fill="#B0D944"/>
            <path d="M246.071 203.613H132.5V210.325H18.9286V226.435H246.071V203.613Z" fill="#B0D944"/>
            <path d="M265 230.91H132.5V237.623H0V253.733H265V230.91Z" fill="#B0D944"/>
            <path d="M265 258.208H132.5V264.92H0V281.03H265V258.208Z" fill="#B0D944"/>
            <path d="M265 285.505H132.5V292.218H0V308.328H265V285.505Z" fill="#B0D944"/>
            <path d="M227.143 312.803H132.5V319.515H37.8573V335.625H227.143V312.803Z" fill="#B0D944"/>
            <path d="M189.286 340.1H132.5V346.812H75.7144V358H189.286V340.1Z" fill="#B0D944"/>
          </svg>
          <h1 class="text-base font-medium tracking-tight">Pear Chat</h1>
          <span id="version" class="text-xs text-neutral-600"></span>
          <button id="update" type="button"
            class="hidden rounded-full bg-lime-400/15 px-3 py-1 text-xs font-medium text-lime-300 hover:bg-lime-400/25 transition">
            Update ready — restart
          </button>
        </div>

        <div class="flex items-center gap-3">
          <span class="flex items-center gap-1.5 text-xs text-neutral-500">
            <span id="dot" class="size-2 rounded-full bg-neutral-600"></span>
            <span id="peers">0 peers</span>
          </span>
          <button id="copy-invite" type="button" disabled
            class="rounded-full border border-neutral-800 bg-neutral-900 px-3.5 py-1.5 text-xs font-medium text-neutral-200 hover:bg-neutral-800 disabled:cursor-not-allowed disabled:opacity-40 transition">
            Copy invite
          </button>
        </div>
      </header>
    ```

    renderer/app.js [#rendererappjs]

    The entrypoint. It talks to the worker entirely through `window.bridge`. The composer sends `{ type: 'add-message', text }`; the worker pushes back `messages`, `peers`, and `invite` frames:

    ```js file=<rootDir>/examples/getting-started/pear-chat/renderer/app.js#L90-L105 title="renderer/app.js — worker IPC"
    bridge.startWorker(SPECIFIER)

    const offWorkerIPC = bridge.onWorkerIPC(SPECIFIER, (data) => {
      let message
      try {
        message = JSON.parse(decoder.decode(data))
      } catch {
        return
      }
      if (message.type === 'messages') renderMessages(message.messages)
      else if (message.type === 'peers') renderPeers(message.count)
      else if (message.type === 'invite') {
        invite = message.invite
        copyEl.disabled = false
      }
    })
    ```

    The copy button writes the cached invite to the clipboard through the bridge:

    ```js file=<rootDir>/examples/getting-started/pear-chat/renderer/app.js#L73-L78 title="renderer/app.js — copy invite"
    copyEl.addEventListener('click', () => {
      if (!invite) return
      bridge.writeClipboard(invite)
      copyEl.textContent = 'Copied!'
      setTimeout(() => { copyEl.textContent = 'Copy invite' }, 1500)
    })
    ```

    And the OTA banner is driven entirely by `bridge.onPearEvent`—inert in development, live once [part 4](/getting-started/build-a-peer-to-peer-chat/update) ships a second version:

    ```js file=<rootDir>/examples/getting-started/pear-chat/renderer/app.js#L80-L88 title="renderer/app.js — OTA banner"
    // OTA update banner, driven by the updater worker via pear:event:* (see electron/main.js).
    updateEl.addEventListener('click', async () => {
      updateEl.disabled = true
      updateEl.textContent = 'restarting…'
      await bridge.applyUpdate()
      await bridge.appAfterUpdate()
    })
    bridge.onPearEvent('updating', () => { versionEl.textContent = 'updating…' })
    bridge.onPearEvent('updated', () => { updateEl.classList.remove('hidden') })
    ```

    Peer-supplied text is always written with `textContent`, never `innerHTML`, so a message can't inject markup.

    **The split is deliberate.** The renderer treats the worker like a remote API—and that's exactly what it is. Swap the worker specifier and the same plumbing works.
  </Step>

  <Step>
    Run two peers locally [#run-two-peers-locally]

    [Corestore](/reference/helpers/corestore) takes an exclusive lock on its directory, so each peer needs its own `--storage`. From the project root:

    ```bash skip="desktop-gui"
    npm run build

    # user1: create the room + print an invite
    npm start -- --storage /tmp/pear-chat-user1 --name user1
    ```

    Watch the terminal for an `Invite: …` line—or click **Copy invite** in the window. Copy that z32-encoded string.

    In a second terminal, still in `pear-chat/`:

    ```bash skip="desktop-gui"
    npm start -- --storage /tmp/pear-chat-user2 --name user2 --invite <paste-invite>
    ```

    A second window opens. Within a few seconds the two peers pair via [`blind-pairing`](https://www.npmjs.com/package/blind-pairing), the second becomes a writer on the shared [Autobase](/reference/building-blocks/autobase), and both windows show the message history and tick the peer dot to green. Type in one window, hit Enter, and watch it appear in the other.

    Both peers persist messages under `--storage`. Close the apps, reopen them with the same paths, and the conversation is still there. To wipe a peer's local state:

    ```bash skip="desktop-gui"
    npm start -- --storage /tmp/pear-chat-user1 --name user1 --reset
    ```

    `npm start` already forwards `--no-updates`, so the OTA updater stays inert in development—[part 4](/getting-started/build-a-peer-to-peer-chat/update) flips it on.
  </Step>
</Steps>

What you built [#what-you-built]

A complete P2P desktop chat with persistence, pairing, OTA-update wiring, and three-platform packaging config—all on the canonical Pear + Electron template.

| Layer        | File                                         | Concept                                                                                                        |
| ------------ | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| Distribution | `forge.config.js`, `build/`, `pear.json`     | [Build desktop distributables](/how-to/operate-an-app/build-and-package/build-desktop-distributables)          |
| Shell        | `electron/main.js`, `electron/preload.js`    | [Pear desktop application architecture](/explanation/pear-desktop-architecture)                                |
| Updater      | `workers/main.js` (PearRuntime OTA in Bare)  | [Pear OTA](/reference/pear/runtime)                                                                            |
| Worker       | `workers/index.js`, `workers/worker-task.js` | [Workers](/explanation/workers)                                                                                |
| Room         | `workers/chat-room.js`                       | [Autobase](/reference/building-blocks/autobase) + [blind-pairing](https://www.npmjs.com/package/blind-pairing) |
| Storage      | `Corestore`, `HyperDB` view                  | [Corestore](/reference/helpers/corestore), [Hyperbee](/reference/building-blocks/hyperbee)                     |
| Transport    | `electron/preload.js`, framed worker pipe    | JSON messages over `window.bridge` IPC                                                                         |
| UI           | `renderer/index.html`, `renderer/app.js`     | Vanilla DOM + [Tailwind CSS](https://tailwindcss.com/); copy-invite + peer dot                                 |

Where to go next [#where-to-go-next]

* **Continue the path:** [Ship your app](/getting-started/build-a-peer-to-peer-chat/ship) (part 3 of 4)—mint a `pear://` link, build per-OS distributables, and stage your first release. Then [Deploy over-the-air updates](/getting-started/build-a-peer-to-peer-chat/update) (part 4 of 4) ships a second version live and the OTA banner you wired here goes hot.

Or pick a capability to add on top of this scaffold—each how-to under [the How To guides](/how-to) documents only the **delta** over this exact code:

* [Add blind peering to a chat app](/how-to/blind-peering/add-blind-peering-to-a-chat-app)—keep the room online when its writers are offline.
* [Add Keet identity to a chat app](/how-to/manage-identity/add-keet-identity-to-a-chat-app)—anchor messages to a portable identity key.
* [Host multiple rooms in one chat app](/how-to/connect-to-peers/host-multiple-rooms-in-one-chat-app)—extend from one room to an account with many.
* [Share files in a peer-to-peer app](/how-to/stream-and-share-media/share-files-in-a-peer-to-peer-app)—swap the room's HyperDB view for a [Hyperdrive](/reference/building-blocks/hyperdrive).

Or zoom out to the conceptual picture:

* [Pear desktop application architecture](/explanation/pear-desktop-architecture)—why a production app splits OTA updates, storage, and workers.
* [Workers](/explanation/workers)—what a Bare worker is and why P2P state lives there.
* [Release pipeline](/explanation/deployment-releasing-apps-p2p)—staging links, multisig, and the OTA loop.


# Ship your app



import { Steps, Step } from 'fumadocs-ui/components/steps'

This is **part 3 of 4** in the [getting started path](/getting-started). You take the production-shaped app from [part 2](/getting-started/build-a-peer-to-peer-chat/reshape-into-a-production-app) and walk it through the first half of Pear's release pipeline:

1. [Minting a `pear://` link](#touch-set-the-upgrade-link-and-seed)
2. [Building per-OS distributables](#make-distributables)
3. [Staging and provisioning the first version onto those links](#stage-and-provision-the-first-version)

<Callout type="info">
  [Deploy over-the-air updates](/getting-started/build-a-peer-to-peer-chat/update) (part 4 of 4) continues from here and demonstrates the live OTA cycle on the provision link, plus a tour of multisig.
</Callout>

The full pipeline looks like this:

<Mermaid
  chart="flowchart LR
  T[&#x22;0. Touch & seed&#x22;] --> U[&#x22;1. Upgrade link&#x22;]
  U --> V[&#x22;2. Version&#x22;]
  V --> M[&#x22;3. Make distributables&#x22;]
  M --> B[&#x22;4. Deployment Directory&#x22;]
  B --> S[&#x22;5. Stage&#x22;]
  S --> P[&#x22;6. Provision&#x22;]
  P --> MS[&#x22;7. Multisig&#x22;]"
/>

This part stops after step 6—the first `pear stage` plus `pear provision`. You do not need cosigners, a Windows machine, or Apple signing credentials. The deeper guides cover the production-only material:

* [Deploy a Pear desktop app](/how-to/operate-an-app/manual-deployment/deployment)—every command, every release line.
* [Build desktop distributables](/how-to/operate-an-app/build-and-package/build-desktop-distributables)—code-signing, notarization, MSIX publisher details.
* [Release pipeline](/explanation/deployment-releasing-apps-p2p)—the conceptual picture.

{/*
  Shared snippet (content/_snippets/) included via Fumadocs <include> by every getting-started step.
  Reminds readers that a production-ready reference implementation already exists
  upstream, so they can clone it any time without abandoning the type-along.
  See: https://www.fumadocs.dev/docs/markdown#include
  */}

<Callout type="info">
  **Full production-ready reference: `hello-pear-electron`.** The complete version of this chat lives at [`holepunchto/hello-pear-electron`](https://github.com/holepunchto/hello-pear-electron)—Holepunch's official Electron template, the same shape [Keet](https://keet.io) and [PearPass](https://pass.pears.com) ship. Clone it any time to see the finished structure or to crib code. For a guided tour of the template, see [Start from the hello-pear-electron template](/getting-started/from-a-template/start-from-hello-pear-electron).
</Callout>

Before you start [#before-you-start]

You need:

1. The working production-shaped app from [part 2](/getting-started/build-a-peer-to-peer-chat/reshape-into-a-production-app).
2. [`pear`](/reference/pear/cli):
   * Install it with `npm i -g pear` or run via `npx pear`.
   * Every `pear` command in this part also works as `npx pear ...`. This is useful if you want to run the commands from a different directory than the one you installed `pear` in.
3. `pear build`—assembles per-OS makes into a deployment directory. It ships with the `pear` CLI above, so there is nothing extra to install: run it as `pear build` (or `npx pear build`).

<Steps>
  <Step>
    Touch, set the upgrade link, and seed [#touch-set-the-upgrade-link-and-seed]

    [`pear touch`](/reference/pear/cli) mints a **new `pear://` link you own**—one backed by a fresh [Hypercore](/reference/building-blocks/hypercore) whose write key is stored locally on this machine. This becomes your **stage link**: the append-only core you sync builds into before each provision. (The link you set in part 2 was a public placeholder so the app would boot; you replace it now with your own.)

    ```bash
    pear touch
    # pear://<stage-link>
    ```

    <Callout type="warning">
      Stage and provision only work against links you **own**—ones you minted on this machine with `pear touch`. If you stage to someone else's link (for example the public placeholder from part 2), `pear stage` prints the header and then fails with `✖ Destination must be writable`. Always use the link `pear touch` just printed.
    </Callout>

    Point `package.json#upgrade` at the stage link for now—you will switch it to the **provision link** after the first provision:

    ```bash
    npm pkg set upgrade=pear://<stage-link>
    ```

    [`pear seed`](/reference/pear/cli#pear-seed) keeps that core online so other peers can fetch updates from you.
    Your output will be different.

    ```bash
    pear seed pear://<stage-link>

    Seeding:        pear://<stage-link>
    Drive Key:      <stage-key>
    Drive Length:   0
    Discovery Key:  qx138e5wnc3bmnjcbks68xpp17m6bj6h5165hud9ps4tr8zad4fo
    Content Key:    pending
    Firewalled:     true
    NAT Type:       consistent
    Whoami:         t8kgj1p3a4e9x8p1etsgks1rc4j58yu9xjh11bbjkgys7zkfmabo
    Network:        [ Peers 0 ]  [ ⬆ 0B - 0B/s ]  [ ⬇ 0B - 0B/s ]
    ────────────────────────────────────────────────────────
    ^_^ announced
    ```

    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.
  </Step>

  <Step>
    Bump the version [#bump-the-version]

    [`pear-runtime`](/reference/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:

    ```bash
    npm version [<newversion> | major | minor | patch | premajor | preminor | prepatch | prerelease]
    ```

    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` (or `major`, `minor`, `patch`, etc.).
  </Step>

  <Step>
    Make distributables [#make-distributables]

    A "distributable" is the platform-native installer—`.app` on macOS, `.msix` on Windows, `.AppImage` on Linux. Pear uses [`electron-forge`](https://www.electronforge.io/) with a single [`forge.config.js`](https://github.com/holepunchto/hello-pear-electron/blob/main/forge.config.js) that configures makers for every platform, including Linux AppImage via [`pear-electron-forge-maker-appimage`](https://www.npmjs.com/package/pear-electron-forge-maker-appimage).

    Install electron-forge and the makers you need [#install-electron-forge-and-the-makers-you-need]

    ```bash
    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.6 \
      pear-electron-forge-maker-snap@^1.0.0 \
      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`](https://www.npmjs.com/package/electron-forge-plugin-universal-prebuilds)—bundles native prebuilds for every supported architecture.
    * [`electron-forge-plugin-prune-prebuilds`](https://www.npmjs.com/package/electron-forge-plugin-prune-prebuilds)—trims the prebuilds you do not need for the current platform, keeping installers small.

    Add scripts to package.json [#add-scripts-to-packagejson]

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

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

    Add forge.config.js [#add-forgeconfigjs]

    In your project's root, copy or diff against the canonical [`hello-pear-electron` `forge.config.js`](https://github.com/holepunchto/hello-pear-electron/blob/main/forge.config.js). 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.

    ```js file=<rootDir>/examples/getting-started/pear-chat/forge.config.js title="forge.config.js"
    const fs = require('fs')
    const path = require('path')
    const plink = require('pear-link')
    const pkg = require('./package.json')
    const appName = pkg.productName ?? pkg.name

    function getWindowsKitVersion () {
      const programFiles = process.env['PROGRAMFILES(X86)'] || process.env.PROGRAMFILES
      if (!programFiles) return undefined
      const kitsDir = path.join(programFiles, 'Windows Kits')
      try {
        for (const kit of fs.readdirSync(kitsDir).sort().reverse()) {
          const binDir = path.join(kitsDir, kit, 'bin')
          if (!fs.existsSync(binDir)) continue
          const version = fs
            .readdirSync(binDir)
            .filter((d) => /^\d+\.\d+\.\d+\.\d+$/.test(d))
            .sort()
            .pop()
          if (version) return version
        }
      } catch {
        return undefined
      }
    }

    let packagerConfig = {
      icon: 'build/icon',
      protocols: [{ name: appName, schemes: [pkg.name] }],
      derefSymlinks: true
    }

    if (process.env.MAC_CODESIGN_IDENTITY) {
      packagerConfig = {
        ...packagerConfig,
        osxSign: {
          identity: process.env.MAC_CODESIGN_IDENTITY,
          optionsForFile: () => ({
            entitlements: path.join(__dirname, 'build', 'entitlements.mac.plist')
          })
        },
        osxNotarize: {
          tool: 'notarytool',
          keychainProfile: process.env.KEYCHAIN_PROFILE
        }
      }
    }

    module.exports = {
      packagerConfig,

      makers: [
        {
          name: '@electron-forge/maker-dmg',
          platforms: ['darwin'],
          config: {}
        },
        {
          name: '@electron-forge/maker-msix',
          platforms: ['win32'],
          config: {
            appManifest: path.join(__dirname, 'build', 'AppxManifest.xml'),
            windowsKitVersion: getWindowsKitVersion(),
            ...(process.env.WINDOWS_SIGN_HOOK
              ? {
                  windowsSignOptions: {
                    hookModulePath: process.env.WINDOWS_SIGN_HOOK
                  }
                }
              : {})
          }
        },
        {
          name: 'pear-electron-forge-maker-appimage',
          platforms: ['linux'],
          config: {
            icons: [
              { file: 'build/icon/icon-16x16.png', size: 16 },
              { file: 'build/icon/icon-32x32.png', size: 32 },
              { file: 'build/icon/icon-64x64.png', size: 64 },
              { file: 'build/icon/icon-128x128.png', size: 128 },
              { file: 'build/icon/icon-256x256.png', size: 256 }
            ]
          }
        },
        {
          name: 'pear-electron-forge-maker-flatpak',
          platforms: ['linux'],
          config: {
            appId: 'com.pears.BasicChat',
            icon: `${packagerConfig.icon}.png`,
            metainfo: 'build/metainfo.xml',
            entrypoint: 'build/entrypoint.sh',
            comment: 'A peer-to-peer chat example built with Pear and Electron',
            categories: ['Network', 'InstantMessaging']
          }
        },
        {
          name: 'pear-electron-forge-maker-snap',
          platforms: ['linux'],
          config: {
            snapcraftYamlPath: 'build/snapcraft.yaml',
            summary: 'A peer-to-peer chat example built with Pear and Electron',
            description:
              'A peer-to-peer chat example demonstrating how to embed pear-runtime into an Electron desktop app.',
            contact: 'hello@holepunchto.to',
            license: 'Apache-2.0',
            issues: 'https://github.com/holepunchto/examples-p2p-desktop/issues',
            website: 'https://github.com/holepunchto/examples-p2p-desktop',
            icon: `${packagerConfig.icon}.png`
          }
        }
      ],

      hooks: {
        readPackageJson: async (forgeConfig, packageJson) => {
          if (process.env.UPGRADE_KEY) {
            packageJson.upgrade = process.env.UPGRADE_KEY
          }

          try {
            plink.parse(packageJson.upgrade)
          } catch {
            throw new Error('Use `pear touch` to get a valid upgrade key for package.json#upgrade')
          }

          return packageJson
        },
        preMake: async () => {
          fs.rmSync(path.join(__dirname, 'out', 'make'), { recursive: true, force: true })

          const manifest = path.join(__dirname, 'build', 'AppxManifest.xml')
          const msixVersion = pkg.version.replace(/^(\d+\.\d+\.\d+)$/, '$1.0')
          const xml = fs.readFileSync(manifest, 'utf-8')
          fs.writeFileSync(manifest, xml.replace(/Version="[^"]*"/, `Version="${msixVersion}"`))
        },
        postMake: async (forgeConfig, results) => {
          for (const result of results) {
            if (result.platform !== 'win32') continue
            for (const artifact of result.artifacts) {
              if (!artifact.endsWith('.msix')) continue
              const standardDir = path.join(__dirname, 'out', `${appName}-win32-${result.arch}`)
              fs.mkdirSync(standardDir, { recursive: true })
              const dest = path.join(standardDir, path.basename(artifact))
              fs.renameSync(artifact, dest)
              fs.mkdirSync(path.dirname(artifact), { recursive: true })
              fs.copyFileSync(dest, artifact)
              result.artifacts[result.artifacts.indexOf(artifact)] = dest
            }
          }
        }
      },

      plugins: [
        {
          name: 'electron-forge-plugin-universal-prebuilds',
          config: {}
        },
        {
          name: 'electron-forge-plugin-prune-prebuilds',
          config: {}
        }
      ]
    }
    ```

    Add the template build/ assets to your project [#add-the-template-build-assets-to-your-project]

    Createa a `build/` folder in your project's root and copy the template's `build/` assets (`AppxManifest.xml`, `entitlements.mac.plist`, icon set under `build/icon/`, and Linux Flatpak/Snap metadata).

    Run the maker on your OS [#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.

    <Callout type="warning">
      Brand icons before you make:

      * `build/icon.icns` (macOS),
      * `build/icon.ico` (Windows),
      * `build/icon.png` plus sized PNGs under `build/icon/` (Linux makers).

      You can copy the set from [`hello-pear-electron`'s `build/` tree](https://github.com/holepunchto/hello-pear-electron/tree/main/build).
    </Callout>

    ```bash
    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).

    <Callout type="info">
      If the make fails with a `NODE_MODULE_VERSION` mismatch (for example after `nvm use` or upgrading Node between `npm install` and `npm run make`), run `npm rebuild` and try again. See [Node ABI mismatch during make](/how-to/operate-an-app/manual-deployment/troubleshoot-desktop-releases#node-abi-mismatch-during-make).
    </Callout>

    <Callout type="info">
      Code-signing, notarization, and MSIX publisher requirements are full topics on their own—production builds need them, but you can skip them for this dry run.

      The full coverage is in [Build desktop distributables](/how-to/operate-an-app/build-and-package/build-desktop-distributables). See [Desktop release npm scripts](/reference/ci-and-release/desktop-release-npm-scripts) for common `npm` entry points in sample repos.
    </Callout>
  </Step>

  <Step>
    Build the deployment directory [#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](https://github.com/holepunchto/hello-pear-electron#stage-size-increases)). Each `--<platform-arch>-app` flag points at one make's output. For example:

    ```bash
    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:

    ```bash
    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:

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

  <Step>
    Stage and provision the first version [#stage-and-provision-the-first-version]

    Run these from the **parent directory** of your app (same place you ran `pear build`) unless noted. [`pear stage`](/reference/pear/cli) syncs the deployment directory into the [Hypercore](/reference/building-blocks/hypercore) behind your **stage link**.

    1. Dry-run the stage [#1-dry-run-the-stage]

    Always run `--dry-run` first and read the file-by-file diff:

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

    Your keys and byte counts will differ; the shape looks like this:

    ```text
    🍐 Staging pear-chat

    [  pear://<stage-link>  ]
    pear://0.0.<stage-key>

    Current: 1

    NOTE: This is a dry run, no changes will be persisted.

    + /package.json (+2.1kB)
    + /by-arch/darwin-arm64/app/PearChat.app/Contents/Info.plist (+1.4kB)
    + /by-arch/darwin-arm64/app/PearChat.app/Contents/MacOS/PearChat (+55kB)
    + /by-arch/darwin-arm64/app/PearChat.app/Contents/Frameworks/Electron Framework.framework/Versions/A/Electron Framework (+165MB)
    + /by-arch/darwin-arm64/app/PearChat.app/Contents/Resources/app/electron/main.js (+12.4kB)
    + /by-arch/darwin-arm64/app/PearChat.app/Contents/Resources/app/workers/chat-room.js (+8.7kB)
    + /by-arch/darwin-arm64/app/PearChat.app/Contents/Resources/app/renderer/index.html (+3.2kB)
      ... more files under /by-arch/ ...
    ✔ Skipping (dry-run)

    Staging dry run complete!
    ```

    How to read it:

    * **`+` lines**—files that would be written or updated, as `/`-prefixed drive paths with byte counts in parentheses. Scan for surprises before you run without `--dry-run`.
    * **Versioned link in the header**—the line under the bracketed stage link shows the drive at its **current** length. On a first stage nothing is staged yet, so it reads `pear://0.0.<stage-key>`. The versioned link you need for `pear provision` is printed by the real stage in the next step, after the sync actually happens.

    Look for:

    * Only two entries at the drive root—`/package.json` and `/by-arch/...`. That is everything `pear build` writes into the deployment directory. Your app source (`electron/`, `workers/`, `renderer/`, `node_modules/`) ships **inside** the packaged app—for example under `/by-arch/darwin-arm64/app/PearChat.app/Contents/Resources/app/`—never as loose files at the root.
    * No surprise additions—stray `.DS_Store`, editor swap files, secrets, the deployment directory itself.
    * Sensible byte counts—the Electron framework binary dominates (a hundred-plus MB per platform-arch); if an unrelated file is suddenly 100 MB, something is wrong.

    2. Stage for real [#2-stage-for-real]

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

    ```bash
    pear stage pear://<stage-link> ./pear-chat-1.0.1
    ```

    The live output repeats the dry-run diff, then ends with the post-stage **versioned link** after the `^Latest:` line:

    ```text
    🍐 Staging pear-chat

    [  pear://<stage-link>  ]
    pear://0.0.<stage-key>

    Current: 1

    + /package.json (+2.1kB)
      ... same diff as the dry run ...

    Staging complete!

    ^Latest: 1426

    pear://0.1426.<stage-key>
    [  pear://<stage-link>  ]
    ```

    Copy the versioned link printed under `^Latest:`—`pear://0.<length>.<stage-key>`, where `<length>` is the Hypercore length **after** this stage (a few hundred to a few thousand on a first stage). Don't copy the versioned link at the top of the output—that one shows the drive **before** staging (`pear://0.0.<stage-key>` on a first stage).

    Use the full versioned string as the first argument to `pear provision` below (not the unversioned `<stage-link>` you passed to `pear stage`).

    3. Mint the provision link [#3-mint-the-provision-link]

    Peers should not poll the stage link directly—it keeps the full append-only history. [`pear provision`](/reference/pear/cli#pear-provision) block-syncs the staged snapshot onto a lean **provision link** that packaged apps poll instead. That target is a **second** link—mint it now with another `pear touch` (the first touch in step 1 was only for staging). Cwd does not matter; `pear touch` does not read your project:

    ```bash
    pear touch
    # pear://<provision-link>   ← different key from <stage-link>
    ```

    `pear touch` prints the link on its own line—copy the whole `pear://…` string.

    4. Provision onto the provision link [#4-provision-onto-the-provision-link]

    Dry-run first, then run for real. Fill the three arguments like this:

    | Argument               | What to paste                                                                                                           |
    | ---------------------- | ----------------------------------------------------------------------------------------------------------------------- |
    | `<source-verlink>`     | The versioned link from `pear stage`: `pear://0.<length>.<stage-key>`                                                   |
    | `<target-link>`        | The unversioned provision link from `pear touch`: `pear://<provision-link>`                                             |
    | `<production-verlink>` | On first ship: `pear://0.0.<provision-key>` where `<provision-key>` is everything after `pear://` in `<provision-link>` |

    Paste all three links on **one line**—backslash continuations are easy to break if a line has trailing spaces:

    ```bash
    pear provision --dry-run pear://0.<length>.<stage-key> pear://<provision-link> pear://0.0.<provision-key>

    pear provision pear://0.<length>.<stage-key> pear://<provision-link> pear://0.0.<provision-key>
    ```

    Example with concrete keys (yours will differ):

    ```bash
    pear provision --dry-run pear://0.1426.9mdt6h676phg7nuwp1urs7457nsz3juyeuqcbw4h7r1tqz8e84ay pear://o11z79iogfzx1ckthrhwoeyk7pyxxhy7par4edq5sy1dmwieutso pear://0.0.o11z79iogfzx1ckthrhwoeyk7pyxxhy7par4edq5sy1dmwieutso
    ```

    Provision syncs the target, prints the same file diff you just staged plus a summary, and—on the real run—ends with the provisioned links. The dry run stops after `Dry Run Complete`; the real run pauses for a 10-second cooldown before writing:

    ```text
    Syncing existing metadata, please wait...

    Completed metadata sync
    Checking diff

    + /package.json (+2.1kB)
      ... same diff as the stage ...
    Diffing complete
    Total changes: 1425
    Package version: 1.0.1

    Core:
      Key: o11z79iogfzx1ckthrhwoeyk7pyxxhy7par4edq5sy1dmwieutso
      ...

    NOT A DRY RUN! Waiting 10s for certainty. Use ctrl+c to bail
    Staging to target...
      ... same diff again ...

    Provisioned:
      Verlink: pear://0.1426.o11z79iogfzx1ckthrhwoeyk7pyxxhy7par4edq5sy1dmwieutso

      Hashlink: pear://0.1426.o11z79iogfzx1ckthrhwoeyk7pyxxhy7par4edq5sy1dmwieutso.<hash>

    Seed with:

       pear seed pear://o11z79iogfzx1ckthrhwoeyk7pyxxhy7par4edq5sy1dmwieutso
    ```

    The diff should mirror what you just staged. The `Seed with` line at the end names the unversioned provision link peers will poll—set `upgrade` to that link in the next step, not the versioned stage link.

    5. Switch upgrade to the provision link [#5-switch-upgrade-to-the-provision-link]

    From the **app root** (`pear-chat/`), point `package.json#upgrade` at the provision link and seed it—this is what shipped binaries poll:

    ```bash
    npm pkg set upgrade=pear://<provision-link>
    pear seed pear://<provision-link>
    ```

    6. Rebuild once [#6-rebuild-once]

    Rebuild so the packaged app embeds the new `upgrade` field (the provision link already holds v1.0.1—no restage needed):

    ```bash
    npm run make
    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
    ```

    Your first version is now published on the provision link. Peers running a build with that `upgrade` field will see it on their next poll.

    <Callout type="info">
      Keep both links: **stage** for `pear stage` on every iteration; **provision** for what apps install and poll. Part 4 repeats `pear stage` → `pear provision` for v1.0.2. The full operator reference is [Deploy your application—provision](/how-to/operate-an-app/manual-deployment/deployment#6-provision).
    </Callout>
  </Step>
</Steps>

What you've learned [#what-youve-learned]

You now have a stage link and a provision link with your first build published:

| Stage               | What it is                                                                        | Reversible?                                   |
| ------------------- | --------------------------------------------------------------------------------- | --------------------------------------------- |
| `pear touch`        | Mints a new `pear://` link                                                        | Yes—just abandon it                           |
| Make + `pear build` | Per-OS distributable folded into a Deployment Directory                           | Yes—rebuild                                   |
| `pear stage`        | Append-only sync into the stage [Hypercore](/reference/building-blocks/hypercore) | History is permanent; updates are not         |
| `pear provision`    | Block-sync onto the provision link peers poll                                     | Yes—reprovision from a different stage length |

Every release iteration after this is the same pattern: `npm version patch`, `npm run make` (on each OS you ship), `pear build`, `pear stage --dry-run`, `pear stage`, `pear provision`. Part 4 puts that loop on a running app and shows the OTA cycle from both sides.

Where to go next [#where-to-go-next]

* **Continue the path:** [Deploy over-the-air updates](/getting-started/build-a-peer-to-peer-chat/update) (part 4 of 4)—run the installed build, ship a second version, watch OTA fire end-to-end, and preview multisig.
* **Automate it:** [Publish with GitHub Actions](/how-to/operate-an-app/github-actions/publish-with-github-actions)—skip the manual staging and let CI stage a stable `pear://` link on every push.
* [Deploy a Pear desktop app](/how-to/operate-an-app/manual-deployment/deployment)—the canonical how-to with every command, every flag, and every recovery procedure.
* [Build desktop distributables](/how-to/operate-an-app/build-and-package/build-desktop-distributables)—code-signing, notarization, MSIX publisher details.
* [Publish a changelog for your app](/how-to/operate-an-app/publish-a-changelog)—ship a `CHANGELOG.md` so users read your release notes with `pear changelog`.
* [Troubleshoot desktop releases](/how-to/operate-an-app/manual-deployment/troubleshoot-desktop-releases)—"the app did not update," lost write-access, stage size blowups.
* [Release pipeline](/explanation/deployment-releasing-apps-p2p)—the conceptual picture, deployment layers, and release lines.
* [Release pipeline glossary](/explanation/deployment-releasing-apps-p2p#glossary)—terminology.
* [`hello-pear-electron`](https://github.com/holepunchto/hello-pear-electron)—the upstream template every snippet in this getting started path is based on.


# Deploy over-the-air updates



import { Steps, Step } from 'fumadocs-ui/components/steps'

This is **part 4 of 4** in the [getting started path](/getting-started). You start from the v1.0.1 you shipped in [part 3](/getting-started/build-a-peer-to-peer-chat/ship):

* a [**provision link**](/getting-started/build-a-peer-to-peer-chat/ship#5-switch-upgrade-to-the-provision-link) in `package.json#upgrade`
* an active [`pear seed`](/getting-started/build-a-peer-to-peer-chat/ship#5-switch-upgrade-to-the-provision-link) on that link
* a [packaged build](/getting-started/build-a-peer-to-peer-chat/ship#6-rebuild-once) that embeds the same field.

From here you put the live OTA cycle to work:

1. [Run the installed app](#open-the-installed-build)
2. [Change something visible in the renderer](#make-a-visible-change)
3. [Stage v1.0.2 onto your **stage link**](#stage-and-provision-the-deployment-directory)
4. [Provision it onto the provision link](#stage-and-provision-the-deployment-directory)
5. [Watch the OTA cycle fire](#watch-the-ota-cycle-fire)—see the [OTA update event lifecycle](/explanation/deployment-releasing-apps-p2p#ota-update-event-lifecycle)
6. [Preview multisig](#multisig-production-releases), the production gate on top of provision.

{/*
  Shared snippet (content/_snippets/) included via Fumadocs <include> by every getting-started step.
  Reminds readers that a production-ready reference implementation already exists
  upstream, so they can clone it any time without abandoning the type-along.
  See: https://www.fumadocs.dev/docs/markdown#include
  */}

<Callout type="info">
  **Full production-ready reference: `hello-pear-electron`.** The complete version of this chat lives at [`holepunchto/hello-pear-electron`](https://github.com/holepunchto/hello-pear-electron)—Holepunch's official Electron template, the same shape [Keet](https://keet.io) and [PearPass](https://pass.pears.com) ship. Clone it any time to see the finished structure or to crib code. For a guided tour of the template, see [Start from the hello-pear-electron template](/getting-started/from-a-template/start-from-hello-pear-electron).
</Callout>

<Mermaid
  chart="flowchart LR
  R[&#x22;Run the installed app&#x22;] --> C[&#x22;Change the renderer&#x22;]
  C --> I[&#x22;Iterate: bump → make → build → stage → provision&#x22;]
  I --> O[&#x22;Watch the OTA cycle&#x22;]
  O --> MS[&#x22;7. Multisig (production releases)&#x22;]"
/>

You do not need cosigners, a Windows machine, or Apple signing credentials to follow along. The deeper guides cover the production-only material:

* [Deploy a Pear desktop app](/how-to/operate-an-app/manual-deployment/deployment)—every command, every release line.
* [Build desktop distributables](/how-to/operate-an-app/build-and-package/build-desktop-distributables)—code-signing, notarization, MSIX publisher details.
* [Release pipeline](/explanation/deployment-releasing-apps-p2p)—the conceptual picture.

Before you start [#before-you-start]

You need:

1. The shipped v1.0.1 from [part 3—ship](/getting-started/build-a-peer-to-peer-chat/ship). That part covered `pear touch`, the stage and provision links, `npm version patch`, `electron-forge make`, `pear build`, `pear stage`, and `pear provision`.
2. The `pear seed` on your **provision link** from part 3 still running. Without an active seeder, peers cannot fetch the new version.
3. The same `pear` CLI from part 3—`pear build` ships with it (`npm i -g pear` or `npx pear ...`).

<Steps>
  <Step>
    Open the installed build [#open-the-installed-build]

    ```bash
    open ./pear-chat/out/PearChat-darwin-arm64/PearChat.app
    # Linux:   ./pear-chat/out/PearChat-linux-x64/PearChat.AppImage
    # Windows: install PearChat-1.0.1.msix and launch from Start menu
    ```

    The header shows `v1.0.1`. Send a few chat messages so you can confirm the transcript survives the restart. Leave the app open.

    <Callout type="info">
      This must be the **installed `.app`**, not `npm start`. The dev script forwards `--no-updates`, which intentionally disables OTA. Only the packaged build polls for updates.
    </Callout>

    <Callout type="warning">
      On macOS, the first launch may prompt Gatekeeper because this build is unsigned. Right-click the `.app` → **Open** → **Open** to bypass it once. Production signing and notarization is covered in [Build desktop distributables](/how-to/operate-an-app/build-and-package/build-desktop-distributables).
    </Callout>
  </Step>

  <Step>
    Make a visible change [#make-a-visible-change]

    Edit `renderer/index.html` and change the header so the new version is obviously different:

    ```diff
    -    <h1 class="text-sm font-semibold">Pear chat</h1>
    +    <h1 class="text-sm font-semibold">Pear chat — v2</h1>
    ```

    Any visible tweak works (text, color, emoji). The point is to confirm the renderer asset on disk swaps after the update.
  </Step>

  <Step>
    Bump, make, build, stage, provision [#bump-make-build-stage-provision]

    Same release cycle as part 3, with a patch bump. Run from your terminal in the project root—your packaged app keeps running in the GUI:

    Bump the version [#bump-the-version]

    ```bash
    npm version [<newversion> | major | minor | patch | premajor | preminor | prepatch | prerelease]
    ```

    Note the change in the changelog [#note-the-change-in-the-changelog]

    Add an entry for the new version to `CHANGELOG.md` at your project root—create the file if this is your first release note, and start it with a title line before the first `##` heading:

    ```md title="CHANGELOG.md"
    # Pear chat changelog

    ## v1.0.2

    ### Changes
    - Renamed the header to "Pear chat — v2".
    ```

    Keep releases newest-first with a SemVer version as the first word of each `##` heading. `pear build` copies only `package.json` and `by-arch/` into the deployment directory, so you copy this file in before staging (below); peers then read it with `pear changelog pear://<provision-link>`. See [Publish a changelog for your app](/how-to/operate-an-app/publish-a-changelog) for the format details.

    Make the distributables [#make-the-distributables]

    ```bash
    npm run make
    ```

    Build the deployment directory [#build-the-deployment-directory]

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

    Stage and provision the deployment directory [#stage-and-provision-the-deployment-directory]

    ```bash
    cp ./pear-chat/CHANGELOG.md ./pear-chat-1.0.2/   # release notes ride along with the build
    pear stage pear://<stage-link> ./pear-chat-1.0.2
    pear provision \
      pear://0.<length>.<stage-key> \
      pear://<provision-link> \
      pear://0.0.<provision-key>
    ```

    Use the versioned link from the `pear stage` output for the first argument. `<provision-key>` is the key segment from `<provision-link>` (everything after `pear://`), same as in [part 3](/getting-started/build-a-peer-to-peer-chat/ship#stage-and-provision-the-first-version).

    <Callout type="warning">
      On every cycle, the `--target` value and the deployment dir you pass to `pear stage` must match the version you just bumped to. The example above assumes you went from `1.0.1` to `1.0.2`; if you've already iterated past that, use `pear-chat-<current-version>` everywhere. Otherwise `pear build` writes v`X` into a directory named after v`Y`, which makes the next bump confusing to debug. You can also omit `--target` and `pear build` will auto-name the dir as `<name>-<version>` from `package.json`.
    </Callout>
  </Step>

  <Step>
    Watch the OTA cycle fire [#watch-the-ota-cycle-fire]

    Within seconds the running app reacts. The events come from part 2's wiring (`pear.updater.on('updating'|'updated')` → preload bridge → renderer):

    1. The version label in the header flips from `v1.0.1` to `updating…`.
    2. The yellow **Update ready** button appears.
    3. Click it. `applyUpdate()` swaps the application drive, `appAfterUpdate()` restarts the process.
    4. The header now reads **"Pear chat—v2"** and the version label shows `v1.0.2`. The [Corestore](/reference/helpers/corestore)-backed chat transcript replays from disk.

    If nothing happens for more than a minute, check that `pear seed` is still running on your **provision link** and that `upgrade` in `package.json` matches `<provision-link>`—see [App did not update](/how-to/operate-an-app/manual-deployment/troubleshoot-desktop-releases#app-did-not-update).

    <Callout type="info">
      Part 2 wires the runtime with `delay: 0`, so updates fire as soon as the new content reaches the local drive. The default `pear-runtime-updater` delay is a random value up to **one hour** after the 60s boot grace period—great for production (seeders avoid a thundering herd) but invisible in a tutorial. If you keep that default and the **Update ready** button never appears, restart the app to reset the grace period—see [Tune `PearRuntime` `delay` for live OTA visibility](/how-to/operate-an-app/manual-deployment/troubleshoot-desktop-releases#tune-pearruntime-delay-for-live-ota-visibility).
    </Callout>

    <Callout type="info">
      The walkthrough stops here. Multisig changes real production links and requires coordinating with at least one other signer, so a tutorial walkthrough is the wrong format. The next section summarizes what it does and links to the production guides.
    </Callout>
  </Step>

  <Step>
    <span id="provision-production-preview" />

    Why stage and provision are separate links [#why-stage-and-provision-are-separate-links]

    A **stage link** keeps the full append-only history—every file you ever staged, even ones you later deleted. A **provision link** is the lean snapshot peers poll: [`pear provision`](/reference/pear/cli#pear-provision) block-syncs from a versioned stage link onto the provision target, compacting deletions along the way. Part 3 and the iterate loop above already use that split; [Deploy your application](/how-to/operate-an-app/manual-deployment/deployment#6-provision) covers recovery if a stage or provision link is lost.
  </Step>

  <Step>
    Multisig (production releases) [#multisig-production-releases]

    A multisig drive is a [Hypercore](/reference/building-blocks/hypercore) where write access is gated by a quorum of signing keys instead of a single owner machine. This is what production Pear apps use so no single laptop can push a malicious update.

    The setup, in 30 seconds:

    1. Every signer generates a signing key: `pear multisig keys get`. Each signer's public key goes in a shared list.
    2. One person sets the `multisig` object in `pear.json` with the signers' `publicKeys`, a `quorum` (for example, 2 of 3), and a `namespace`. The provision link is not stored here—it is supplied as the source when you prepare and commit each request.
    3. `pear multisig link` outputs the new `pear://` link, derived from the namespace, public keys, and quorum. Set this as your `upgrade` field.

    The release flow becomes:

    ```bash
    pear multisig request <versioned-provision-link>             # prepare a signing request
    pear multisig sign <signing request>                         # each signer runs this; shares response
    pear multisig verify <source-link> <signing request> [...responses]
    pear multisig commit <source-link> <signing request> [...responses]   # commits when quorum is reached
    ```

    [Release pipeline](/explanation/deployment-releasing-apps-p2p) and [Deploy a Pear desktop app](/how-to/operate-an-app/manual-deployment/deployment) cover the full quorum lifecycle, key rotation, recovering from lost write-access, and the [release lines](/explanation/deployment-releasing-apps-p2p#release-lines) pattern (development → staging → rc → prerelease → production) that real teams use.
  </Step>
</Steps>

What you've learned [#what-youve-learned]

You now have an end-to-end mental model for iterating a Pear Electron app:

| Stage              | What it is                                                                                        | Reversible?                                               |
| ------------------ | ------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
| Iterate loop       | `npm version patch` → make → `pear build` → `pear stage` → `pear provision`                       | Yes—reprovision from a different stage length             |
| OTA cycle          | `pear.updater` emits `updating`/`updated`; renderer button calls `applyUpdate` + `appAfterUpdate` | Yes—restart loads the previous bundle until the next swap |
| Stage vs provision | Stage link for append-only sync; provision link for what peers poll                               | History is permanent on the stage core                    |
| Multisig commit    | Quorum signs and publishes                                                                        | Cryptographically committed                               |

Every release iteration after part 3 is the same pattern: `npm version patch`, `npm run make` (on each OS you ship), `pear build`, `pear stage --dry-run`, `pear stage`, `pear provision`. Once multisig is wired, the four-step multisig flow replaces publishing directly to the provision link for production.

Where to go next [#where-to-go-next]

* [Deploy a Pear desktop app](/how-to/operate-an-app/manual-deployment/deployment)—the canonical how-to with every command, every flag, and every recovery procedure.
* [Build desktop distributables](/how-to/operate-an-app/build-and-package/build-desktop-distributables)—code-signing, notarization, MSIX publisher details.
* [Troubleshoot desktop releases](/how-to/operate-an-app/manual-deployment/troubleshoot-desktop-releases)—"the app did not update," lost write-access, stage size blowups, OTA polling cadence.
* [Release pipeline](/explanation/deployment-releasing-apps-p2p)—the conceptual picture, deployment layers, and release lines.
* [Release pipeline glossary](/explanation/deployment-releasing-apps-p2p#glossary)—terminology.
* [`hello-pear-electron`](https://github.com/holepunchto/hello-pear-electron)—the upstream template every snippet in this getting started path is based on.


# Start from a template



import { Cards, Card } from 'fumadocs-ui/components/card'

The fastest way to a production-shaped app is to clone an official boilerplate and learn where each piece lives. Both embed [`pear-runtime`](/reference/pear/runtime) for peer-to-peer over-the-air updates—pick the one that matches what you're shipping.

<Cards>
  <Card href="/getting-started/from-a-template/start-from-hello-pear-electron" title="hello-pear-electron (desktop)" description="An Electron GUI app: renderer ↔ main ↔ Bare worker behind a preload bridge. The shape Keet and PearPass ship." />

  <Card href="/getting-started/from-a-template/start-from-hello-pear-bare" title="hello-pear-bare (terminal)" description="A standalone Bare executable: CLIs, daemons, and tools with no GUI and no peer dependencies." />
</Cards>

Which one? [#which-one]

* **Building a desktop GUI?** Start from [hello-pear-electron](/getting-started/from-a-template/start-from-hello-pear-electron)—it ships a renderer and the preload bridge that connects your UI to peer-to-peer logic in a Bare worker.
* **Building a CLI, daemon, or other headless tool?** Start from [hello-pear-bare](/getting-started/from-a-template/start-from-hello-pear-bare)—it compiles to a single standalone binary per OS and architecture.

Both share the same peer-to-peer core: the [Bare](/reference/modules/bare-modules) runtime, [`pear-runtime`](/reference/pear/runtime) for updates, and the [Hyperswarm](/reference/building-blocks/hyperswarm) + [Corestore](/reference/helpers/corestore) stack. Your peer-to-peer logic is portable between them—only the shell (GUI versus terminal) changes. See [Runtime and languages](/explanation/runtime-and-languages).

<Callout type="info">
  Once you've cloned a template and made it yours, ship it over the air: [Deploy your application](/how-to/operate-an-app/manual-deployment/deployment) is the step-by-step release flow, and [Release pipeline](/explanation/deployment-releasing-apps-p2p) explains the stage → provision → multisig model behind it.
</Callout>

Where to go next [#where-to-go-next]

* [Build a peer-to-peer chat](/getting-started/build-a-peer-to-peer-chat/build-a-peer-to-peer-chat)—build the desktop app up from scratch instead of cloning.
* [Pear desktop application architecture](/explanation/pear-desktop-architecture)—the renderer/main/worker model behind the Electron template.
* [Runtime and languages](/explanation/runtime-and-languages)—where Bare and the runtimes fit across desktop, terminal, and mobile.


# Start from the hello-pear-bare template



This is the terminal counterpart to [Start from the hello-pear-electron template](/getting-started/from-a-template/start-from-hello-pear-electron). Instead of a desktop window, you start from a finished command-line boilerplate and learn how a Bare app wires peer-to-peer updates and replication through a worker—then ship it as a standalone binary.

[`holepunchto/hello-pear-bare`](https://github.com/holepunchto/hello-pear-bare) is Holepunch's official boilerplate for peer-to-peer terminal applications. Where the Electron template embeds [`pear-runtime`](/reference/pear/runtime) into Electron, this template embeds it into [Bare](/reference/modules/bare-modules), the zero-core embeddable JavaScript runtime. The application and runtime compile into a single standalone executable per OS and architecture with no peer dependencies—no Node.js, and no Bare or [Pear CLI](/reference/pear/cli) required on the user's machine.

With this shape you can build CLIs, REPLs, TUIs, services and daemons, or transport hooks—anything headless—and ship it with peer-to-peer over-the-air (OTA) updates. The Pear CLI v3 is built on this same architecture: a Bare standalone executable that updates itself peer-to-peer through `pear-runtime`.

{/*
  Shared snippet (content/_snippets/) included via Fumadocs <include> by getting-started
  pages that introduce peer-to-peer, pointing newcomers at the two core explanations.
  See: https://www.fumadocs.dev/docs/markdown#include
  */}

<Callout type="info">
  New to peer-to-peer? [Peer-to-peer, demystified](/explanation/peer-to-peer-demystified) explains how peers find each other and connect directly—no servers—and [How Pear and Bare fit together](/explanation/pear-and-bare) maps the pieces you'll wire together.
</Callout>

Take this path when you want to distribute a terminal app as a single executable and update it over the air.
If you want to build a desktop app instead, follow the [hello-pear-electron template](/getting-started/from-a-template/start-from-hello-pear-electron).

{/*
  Shared snippet (content/_snippets/) included via Fumadocs <include> by guides that
  run `pear` CLI commands, so readers can install the CLI before following the steps.
  See: https://www.fumadocs.dev/docs/markdown#include
  */}

<Callout type="info">
  **Need the `pear` CLI?** Install it from **[install.pears.com](https://install.pears.com)**, or prefix any command below with `npx`. See [Install & upgrade](/reference/pear/cli#install) for details.
</Callout>

Clone and run [#clone-and-run]

1. Clone the repository [#1-clone-the-repository]

Clone the repository and install dependencies with the following commands:

```bash
git clone https://github.com/holepunchto/hello-pear-bare
cd hello-pear-bare
npm install
```

2. Create a valid upgrade link [#2-create-a-valid-upgrade-link]

The template ships with a placeholder `upgrade` link in `package.json`. Until you replace it, startup fails with `INVALID_URL`. Create a real link with [`pear touch`](/reference/pear/cli#pear-touch-flags):

```bash
pear touch
```

This prints a link, for example: `pear://qxenz5wmspmryjc13m9yzsqj1conqotn8fb4ocbufwtz9mtbqq5o`.

3. Set the upgrade link in package.json [#3-set-the-upgrade-link-in-packagejson]

Set the `upgrade` field in `package.json` to the link you just created:

```json
"upgrade": "pear://qxenz5wmspmryjc13m9yzsqj1conqotn8fb4ocbufwtz9mtbqq5o"
```

4. Run the app [#4-run-the-app]

`npm start` runs `bare bin.mjs --no-updates`: the process starts in development mode with over-the-air updates disabled, so a live release never swaps the binary while you work.

```bash
npm start
```

To exercise the updater locally, opt back in:

```bash
npm start -- --updates
```

Map the template [#map-the-template]

| Path                                                                                          | What it is                                                                                                                                                                                                                                                                                                 | Do you edit it?                |
| --------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ |
| [`bin.mjs`](https://github.com/holepunchto/hello-pear-bare/blob/main/bin.mjs)                 | The entrypoint—parses CLI flags, resolves the storage path, constructs the `App`, and logs its updater events.                                                                                                                                                                                             | Yes—your startup and CLI.      |
| [`app.js`](https://github.com/holepunchto/hello-pear-bare/blob/main/app.js)                   | The `App` class (a [`ready-resource`](https://github.com/holepunchto/ready-resource)). Spawns the Bare worker with [`PearRuntime.run`](/reference/pear/runtime#running-workers), wraps its IPC in a [`FramedStream`](https://www.npmjs.com/package/framed-stream), and turns updater messages into events. | Sometimes—app lifecycle.       |
| [`workers/main.js`](https://github.com/holepunchto/hello-pear-bare/blob/main/workers/main.js) | The Bare [worker](/explanation/workers) that owns the peer-to-peer code and the [`pear-runtime`](/reference/pear/runtime) updater.                                                                                                                                                                         | Yes—this is your backend.      |
| [`package.json`](https://github.com/holepunchto/hello-pear-bare/blob/main/package.json)       | App metadata, scripts, the `upgrade` link, and the per-platform `make:*` build targets.                                                                                                                                                                                                                    | Yes—branding and release link. |
| [`scripts/make.js`](https://github.com/holepunchto/hello-pear-bare/blob/main/scripts/make.js) | Detects the host OS and architecture and runs the matching `make:` target.                                                                                                                                                                                                                                 | Rarely.                        |
| [`test/index.js`](https://github.com/holepunchto/hello-pear-bare/blob/main/test/index.js)     | The [`brittle`](https://github.com/holepunchto/brittle) test entry, run by `npm test`.                                                                                                                                                                                                                     | Yes—your tests.                |

Like the Electron template, the peer-to-peer logic lives in a Bare [worker](/explanation/workers); `bin.mjs` and `app.js` are the host that spawns it and drives updates. There's no renderer or preload bridge—your "frontend" is the terminal.

<Callout type="info">
  Upstream ships the worker as the [`hello-pear-worker`](https://github.com/holepunchto/hello-pear-worker) package, so the template's `workers/main.js` is just `require('hello-pear-worker')`. That is where your peer-to-peer code goes—open [Corestore](/reference/helpers/corestore) cores, join [Hyperswarm](/reference/building-blocks/hyperswarm) topics, and run your protocol.
</Callout>

How it's wired [#how-its-wired]

The template is three layers: `bin.mjs` (entry + CLI), `app.js` (the host that runs the worker and updater), and the Bare [worker](/explanation/workers) that holds your peer-to-peer code.

`bin.mjs` is the Bare entry process. It parses three flags with [`paparam`](https://github.com/holepunchto/paparam)—`--version`, `--storage`, and `--no-updates`—then constructs the `App`:

```js file=<rootDir>/examples/getting-started/hello-pear-bare/bin.mjs#L13-L19 title="bin.mjs"
const cmd = command(
  appName,
  summary(pkg.description),
  flag('--version|-v', 'Print the current version'),
  flag('--storage <dir>', 'custom storage directory'),
  flag('--no-updates', 'disable OTA updates for this run')
)
```

It resolves a storage directory, then hands the runtime configuration to a `new App(...)`. In development (launched with `bare`) storage is a temporary directory; a packaged binary uses the persistent per-app directory from [`bare-storage`](/reference/modules/bare-modules), and `--storage` overrides both—see [Storage and distribution](/explanation/storage-and-distribution):

```js file=<rootDir>/examples/getting-started/hello-pear-bare/bin.mjs#L28-L41 title="bin.mjs"
const updates = cmd.flags.updates
const storage = cmd.flags.storage || (isDev ? null : path.join(persistent(), appName))
const dir = storage || path.join(os.tmpdir(), 'pear', appName)

console.log(`Updates: ${updates === false ? 'disabled' : 'enabled'}`)

const app = new App({
  dir,
  app: isDev ? null : os.execPath(),
  updates,
  version: pkg.version,
  upgrade: pkg.upgrade,
  name: isWindows ? appName + '.exe' : appName
})
```

`App` (in `app.js`) is a [`ready-resource`](https://github.com/holepunchto/ready-resource). When it opens, it spawns the Bare worker with [`PearRuntime.run`](/reference/pear/runtime#running-workers)—passing the runtime config as arguments—and wraps the worker's IPC pipe in a [`FramedStream`](https://www.npmjs.com/package/framed-stream):

```js file=<rootDir>/examples/getting-started/hello-pear-bare/app.js#L20-L31 title="app.js"
  _open() {
    this.IPC = PearRuntime.run(require.resolve('./workers/main.js'), [
      String(this.updates),
      this.version,
      this.upgrade,
      this.name,
      this.dir,
      this.app || ''
    ])
    this.pipe = new FramedStream(this.IPC)

    this.pipe.on('data', (data) => this._onmessage(data))
```

The worker owns the peer-to-peer code and the [`pear-runtime`](/reference/pear/runtime) updater. It messages the host, and `App` turns those into `updating`, `updated`, and `update-applied` events—which `bin.mjs` logs—applying each downloaded release automatically. `SIGHUP`, `SIGINT`, `SIGQUIT`, and `SIGTERM` handlers call `app.exit()` to close cleanly. For the model behind these updates, see [Pear OTA](/reference/pear/runtime#updates):

```js file=<rootDir>/examples/getting-started/hello-pear-bare/bin.mjs#L43-L55 title="bin.mjs"
app.on('message', (message) => console.log(message))
app.on('updating', () => console.log('[updater] getting new update'))
app.on('updating-delta', (delta) => console.log('[updater]', delta))
app.on('updated', () => console.log('[updater] update complete... applying'))
app.on('update-applied', () =>
  console.log('[updater] applied update, restart to run latest version')
)
app.on('error', (err) => console.error('[app:error]', err))

process.on('SIGHUP', () => app.exit(129))
process.on('SIGINT', () => app.exit(130))
process.on('SIGQUIT', () => app.exit(131))
process.on('SIGTERM', () => app.exit(143))
```

<Mermaid
  chart="flowchart LR
  cli[&#x22;bin.mjs (entry)&#x22;] --> app[&#x22;app.js (App)&#x22;]
  app -->|&#x22;PearRuntime.run&#x22;| worker[&#x22;workers/main.js (Bare worker)&#x22;]
  worker --> updater[&#x22;pear-runtime updater&#x22;]
  worker --> store[&#x22;Corestore&#x22;]
  worker --> swarm[&#x22;Hyperswarm&#x22;]
  swarm <-->|&#x22;replicate update drive&#x22;| peers((seeding peers))"
/>

Variants [#variants]

The `main` branch above (a Bare worker thread) is one of three process shapes `holepunchto/hello-pear-bare` ships. All three share the same `upgrade` link, the same per-platform build targets, and the same [`pear install`](/reference/pear/cli#pear-install)/[`pear seed`](/explanation/availability-and-blind-peering#seeding-with-pear-seed) release flow. What differs is `app.js`, `bin.mjs`, and their dependencies—and **neither variant has a `workers/` directory at all**, so the `workers/main.js` row in [Map the template](#map-the-template) applies to `main` only; on both variants the peer-to-peer code and the updater live in the same process tree as the CLI. Pick the branch that matches how your CLI runs:

| Branch                                                                                               | Shape                                                                                                                                                                     | Use it for                                                                                                                                     |
| ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| [`main`](https://github.com/holepunchto/hello-pear-bare) (this page)                                 | `pear-runtime` inside a Bare [worker](/explanation/workers) thread                                                                                                        | Long-lived programs (services, REPLs, TUIs) that keep peer-to-peer logic off the main thread.                                                  |
| [`variant/single-thread`](https://github.com/holepunchto/hello-pear-bare/tree/variant/single-thread) | `pear-runtime` constructed directly in the main Bare process—no worker, no IPC framing                                                                                    | Long-lived programs whose peer-to-peer logic doesn't need a separate thread.                                                                   |
| [`variant/daemon`](https://github.com/holepunchto/hello-pear-bare/tree/variant/daemon)               | `pear-runtime` runs inside a detached [`bare-daemon`](https://github.com/holepunchto/bare-daemon) process that the foreground command spawns and returns from immediately | Short-lived CLI invocations (like `git`) that shouldn't block on an update check—the command exits while the daemon updates in the background. |

Clone whichever branch fits, swapping it into step 1 of [Clone and run](#clone-and-run):

```bash
git clone -b variant/single-thread https://github.com/holepunchto/hello-pear-bare
```

single-thread [#single-thread]

Same `App` [`ready-resource`](https://github.com/holepunchto/ready-resource) shape as `main`, emitting the `updating`, `updated`, `update-applied`, and `error` events `bin.mjs` logs—plus `updating-delta`, which carries download progress and which `main`'s worker never actually forwards. (`main` also emits a generic `message` event for anything else the worker writes over the pipe; with no worker, single-thread has no equivalent.) The difference is in `_open()`, which constructs `PearRuntime` directly instead of spawning a worker and wrapping its IPC in a `FramedStream`:

```js file=<rootDir>/examples/getting-started/hello-pear-bare-single-thread/app.js#L23-L41 title="app.js"
  _open() {
    const store = new Corestore(path.join(this.dir, 'pear-runtime', 'corestore'))
    const swarm = new Hyperswarm()

    this.store = store
    this.swarm = swarm

    const pear = new PearRuntime({
      dir: this.dir,
      app: this.app,
      updates: this.updates,
      version: this.version,
      upgrade: this.upgrade,
      name: this.name,
      store,
      swarm
    })

    this.pear = pear
```

See [`app.js`](https://github.com/holepunchto/hello-pear-bare/blob/variant/single-thread/app.js) on the `variant/single-thread` branch for the full file.

daemon [#daemon]

`bin.mjs` spawns a **detached** updater and returns immediately—the foreground command never blocks on the network:

```js file=<rootDir>/examples/getting-started/hello-pear-bare-daemon/bin.mjs#L50-L57 title="bin.mjs"
if (updates !== false) {
  try {
    App.spawnUpdater(dir, os.execPath(), isDev ? Bare.argv[1] : null, wait)
  } catch (err) {
    console.error('[app:error]', err)
    Bare.exit(1)
  }
}
```

`App.spawnUpdater` re-invokes the same executable with a hidden `--updater` flag through [`bare-daemon`](https://github.com/holepunchto/bare-daemon):

```js file=<rootDir>/examples/getting-started/hello-pear-bare-daemon/app.js#L11-L18 title="app.js"
  static spawnUpdater(dir, app, entrypoint, updateWindow) {
    const args = entrypoint === null ? [] : [entrypoint]
    args.push('--updater', '--storage', dir)
    if (updateWindow !== undefined) {
      args.push('--update-window', String(updateWindow))
    }
    return daemon.spawn(app, args)
  }
```

The daemon acquires an `updater.lock` file in the storage directory—via [`fs-native-extensions`](https://github.com/holepunchto/fs-native-extensions)—so only one updater runs per storage directory at a time, and logs to `<storage>/updates.log` instead of stdout, since nothing is attached to read it.

`--update-window` (default `30000`, in milliseconds) bounds only how long the daemon waits for a download to **start**. Once one starts, it stays alive until the update is applied or errors out, however long that takes. See [`app.js`](https://github.com/holepunchto/hello-pear-bare/blob/variant/daemon/app.js) and [`bin.mjs`](https://github.com/holepunchto/hello-pear-bare/blob/variant/daemon/bin.mjs) on the `variant/daemon` branch for the full files.

Give a run longer to pick up a download before the daemon gives up:

```bash
npm start -- --updates --update-window 60000
```

<Callout type="warn">
  Two steps from [Clone and run](#clone-and-run) behave differently on this branch. `npm start` **returns immediately** rather than staying up, so there is no `Ctrl+C` to press. And because the foreground process never constructs [`pear-runtime`](/reference/pear/runtime), an unreplaced placeholder `upgrade` link does **not** fail with `INVALID_URL` in your terminal—the detached updater writes that error to `<storage>/updates.log`. Check that file first whenever updates appear not to run.
</Callout>

Build a standalone binary [#build-a-standalone-binary]

[`bare-build`](https://github.com/holepunchto/bare-build) compiles `bin.mjs` and its dependencies into a single standalone executable with no peer dependencies—users don't need Node.js, Bare, or the [Pear CLI](/reference/pear/cli) installed. Build for your current host with:

```bash
npm run make
```

`scripts/make.js` detects your OS and architecture and runs the matching target, writing the binary to `out/<platform>-<arch>`. To build for a specific target—for example, in CI—call that target directly:

```bash
npm run make:darwin-arm64
```

The template ships a target for every supported platform:

* **macOS**: `darwin-arm64`, `darwin-x64`
* **Linux**: `linux-arm64`, `linux-x64`
* **Windows**: `win32-arm64`, `win32-x64`

Build each platform's binary on a matching host.

Install over the air [#install-over-the-air]

Distribute the executable through the usual channels—a download on your website, `apt`, or Homebrew.
You can also install it peer-to-peer: once your `upgrade` link is [seeding](/explanation/availability-and-blind-peering#seeding-with-pear-seed) a release, pull it directly with the [`pear install`](/reference/pear/cli#pear-install) command:

```bash
pear install pear://<key>
```

After the first install, new releases reach users through the swarm—no reinstall needed. For how staging and seeding work, see [Deploy your application](/how-to/operate-an-app/manual-deployment/deployment) and [Installing applications](/explanation/storage-and-distribution#installing-applications).

Example: add a flag [#example-add-a-flag]

The boilerplate is a minimal CLI plus updater; `bin.mjs` holds the CLI and startup logic (your peer-to-peer code lives in the [worker](/explanation/workers)). Flags are parsed with `paparam`, so adding one is a two-line change. Add a `--name` flag to the command definition:

```diff
 const cmd = command(
   appName,
   summary(pkg.description),
   flag('--version|-v', 'Print the current version'),
   flag('--storage <dir>', 'custom storage directory'),
-  flag('--no-updates', 'disable OTA updates for this run')
+  flag('--no-updates', 'disable OTA updates for this run'),
+  flag('--name <name>', 'who to greet on startup')
 )
```

Then log the greeting after the other startup logs:

```diff
 console.log(`Updates: ${updates === false ? 'disabled' : 'enabled'}`)
+
+if (cmd.flags.name) console.log(`Hello, ${cmd.flags.name}!`)
```

Run `npm start -- --name YourName`, and the process greets you on boot. That is the CLI layer in `bin.mjs`; your real peer-to-peer features go in the [worker](/explanation/workers) (`workers/main.js`):

* open a [Corestore](/reference/helpers/corestore) core,
* join a [Hyperswarm](/reference/building-blocks/hyperswarm) topic, and
* run your protocol.

Reuse the storage directory the host passes to the worker so your data lands alongside the updater's—see [Storage and distribution](/explanation/storage-and-distribution).

Customize for your brand [#customize-for-your-brand]

Before you ship, set your identity in `package.json`:

* `name`, `productName`, `description`, `author`, and `license`.
* the `upgrade` `pear://` link (see [Create a valid upgrade link](#2-create-a-valid-upgrade-link)).

`bin.mjs` reads `productName || name` for both the binary name and the persistent storage directory, so set these before your first release. Then build with `npm run make` and release with [Deploy your application](/how-to/operate-an-app/manual-deployment/deployment).

Where to go next [#where-to-go-next]

* [Start from a template](/getting-started/from-a-template)—both boilerplates, side by side.
* [Start from the hello-pear-electron template](/getting-started/from-a-template/start-from-hello-pear-electron)—the desktop counterpart, with a renderer, preload bridge, and Bare worker.
* [Inside Bare](/explanation/bare-runtime)—what the runtime this template builds on actually is, and its lifecycle.
* [How Pear and Bare fit together](/explanation/pear-and-bare)—where Bare and Pear sit relative to each other.
* [Runtime and languages](/explanation/runtime-and-languages)—where Bare fits among Pear's runtimes.
* [Bundle a Bare app](/how-to/run-on-native/bundle-a-bare-app)—the `bare-pack` and `bare-build` paths behind `npm run make`.
* [Bare modules](/reference/modules/bare-modules)—the Bare standard library this template builds on.
* [Pear OTA](/reference/pear/runtime)—the `pear-runtime` API behind the updater.
* [Migrate from pear run to Pear OTA](/how-to/operate-an-app/migration)—if you're moving an existing app onto `pear-runtime`.
* [Publish with GitHub Actions](/how-to/operate-an-app/github-actions/publish-with-github-actions)—stage a stable `pear://` link on every push with the `pear-ci` action.
* [Deploy your application](/how-to/operate-an-app/manual-deployment/deployment)—the full-control manual path for staging, provisioning, and release lines.
* [Seeding with `pear seed`](/explanation/availability-and-blind-peering#seeding-with-pear-seed)—keep your `pear://` link online so peers can fetch releases.


# Start from the hello-pear-electron template



This is an alternative to the [four-part getting started path](/getting-started). Instead of building a chat from five files and reshaping it into the production template, you start from the finished template and learn your way around it.

[`holepunchto/hello-pear-electron`](https://github.com/holepunchto/hello-pear-electron) is Holepunch's official Electron template—the same shape [Keet](https://keet.io) and [PearPass](https://pass.pears.com) ship. This is a clone-first tour: where to put your UI, where to put your peer-to-peer logic, and how the two halves talk. For the conceptual "why" behind the split, read [Pear desktop application architecture](/explanation/pear-desktop-architecture).

{/*
  Shared snippet (content/_snippets/) included via Fumadocs <include> by getting-started
  pages that introduce peer-to-peer, pointing newcomers at the two core explanations.
  See: https://www.fumadocs.dev/docs/markdown#include
  */}

<Callout type="info">
  New to peer-to-peer? [Peer-to-peer, demystified](/explanation/peer-to-peer-demystified) explains how peers find each other and connect directly—no servers—and [How Pear and Bare fit together](/explanation/pear-and-bare) maps the pieces you'll wire together.
</Callout>

Take this path when you want a production-shaped Electron app from the first commit. If you would rather learn the moving parts by building up from scratch, follow the [four-part path](/getting-started) instead.

{/*
  Shared snippet (content/_snippets/) included via Fumadocs <include> by guides that
  run `pear` CLI commands, so readers can install the CLI before following the steps.
  See: https://www.fumadocs.dev/docs/markdown#include
  */}

<Callout type="info">
  **Need the `pear` CLI?** Install it from **[install.pears.com](https://install.pears.com)**, or prefix any command below with `npx`. See [Install & upgrade](/reference/pear/cli#install) for details.
</Callout>

Clone and run [#clone-and-run]

1. Clone the repository [#1-clone-the-repository]

Clone the repository and install dependencies with the following commands:

```bash
git clone https://github.com/holepunchto/hello-pear-electron
cd hello-pear-electron
npm install
```

2. Create a valid upgrade link [#2-create-a-valid-upgrade-link]

Before the app will boot, set a valid `upgrade` link. To do this, run the following command:

```bash
pear touch
```

This will output a link, for example: `pear://qxenz5wmspmryjc13m9yzsqj1conqotn8fb4ocbufwtz9mtbqq5o`.

3. Set the upgrade link in package.json [#3-set-the-upgrade-link-in-packagejson]

Set the `upgrade` link in `package.json` to the link you just created:

```json
"upgrade": "pear://qxenz5wmspmryjc13m9yzsqj1conqotn8fb4ocbufwtz9mtbqq5o"
```

4. Run the app [#4-run-the-app]

`npm start` runs `electron-forge start -- --no-updates`: the app launches in development mode with over-the-air updates disabled, so a live release never replaces your working tree while you hack.

```bash
npm start
```

Map the template [#map-the-template]

| Path                                                                                                      | What it is                                                                                                | Do you edit it?                |
| --------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------ |
| [`renderer/`](https://github.com/holepunchto/hello-pear-electron/tree/main/renderer)                      | The frontend—`index.html` plus `app.js`, plain DOM with no bundler.                                       | Yes—this is your UI.           |
| [`workers/main.js`](https://github.com/holepunchto/hello-pear-electron/blob/main/workers/main.js)         | The app logic—a [Bare](/reference/modules/bare-modules) worker that owns the swarm, storage, and updater. | Yes—this is your backend.      |
| [`electron/main.js`](https://github.com/holepunchto/hello-pear-electron/blob/main/electron/main.js)       | The Electron main process. Spawns the worker and proxies messages; you rarely change it.                  | Occasionally.                  |
| [`electron/preload.js`](https://github.com/holepunchto/hello-pear-electron/blob/main/electron/preload.js) | Exposes the safe `window.bridge` API to the renderer.                                                     | Only to add typed methods.     |
| [`package.json`](https://github.com/holepunchto/hello-pear-electron/blob/main/package.json)               | App metadata, scripts, and the `upgrade` link.                                                            | Yes—branding and release link. |
| [`forge.config.js`](https://github.com/holepunchto/hello-pear-electron/blob/main/forge.config.js)         | Electron Forge packagers, makers, and signing hooks.                                                      | For packaging and signing.     |
| [`build/`](https://github.com/holepunchto/hello-pear-electron/tree/main/build)                            | Icons and per-OS manifests (`AppxManifest.xml`, entitlements, Flatpak/Snap metadata).                     | Yes—brand assets.              |
| [`pear.json`](https://github.com/holepunchto/hello-pear-electron/blob/main/pear.json)                     | Multisig config placeholder for production releases.                                                      | At production time.            |

The three pieces you care about day to day are:

* `renderer/` (view)
* `workers/main.js` (logic)
* the bridge that connects them

How the three processes connect [#how-the-three-processes-connect]

<Mermaid
  chart="flowchart LR
  app[&#x22;renderer/app.js&#x22;] <-->|&#x22;window.bridge&#x22;| preload[&#x22;electron/preload.js&#x22;]
  preload <-->|&#x22;pear:worker:* IPC&#x22;| main[&#x22;electron/main.js&#x22;]
  main <-->|&#x22;FramedStream pipe&#x22;| worker[&#x22;workers/main.js (Bare)&#x22;]
  worker --> stack[&#x22;Hyperswarm + Corestore + updater&#x22;]"
/>

The renderer never touches `ipcRenderer` directly—it only calls `window.bridge`. The main process is a thin proxy: it relays bridge calls to a [FramedStream](https://www.npmjs.com/package/framed-stream) byte stream connected to the Bare worker, and fans the worker's output back out to the renderer on per-worker channels named after the worker specifier (`/workers/main.js`).

The boilerplate ships a "hello" round-trip you can trace on boot:

1. The renderer calls `bridge.startWorker('/workers/main.js')` (`renderer/app.js`).
2. The main process handles `pear:startWorker` and launches the worker with `PearRuntime.run()` ([see below](#where-the-app-logic-goes) for more details).
3. The worker runs `pipe.write('Hello from worker')` ([see below](#where-the-app-logic-goes) for more details).
4. The main process forwards it on `pear:worker:ipc:/workers/main.js`.
5. The renderer's `bridge.onWorkerIPC` callback receives it and replies `bridge.writeWorkerIPC('/workers/main.js', 'Hello from renderer')` ([see below](#how-to-connect-them) for more details).

Where the frontend goes [#where-the-frontend-goes]

Your UI lives in `renderer/`. `index.html` is a static shell loaded by the main process; `renderer/app.js` is loaded as an ES module and drives the DOM:

```js file=<rootDir>/examples/getting-started/hello-pear-electron/renderer/app.js#L1-L4 title="renderer/app.js"
const bridge = window.bridge
const decoder = new TextDecoder('utf-8')

document.getElementById('v').innerText += bridge.pkg().version
```

There is no framework or build step—bring your own (React, Vue, plain DOM) by editing these files. The only rule is: the renderer talks to the rest of the app **only** through `window.bridge`. It has no Node or Bare access of its own, which is what keeps the renderer sandboxed.

If you prefer to develop the UI against a dev server (hot reload, a framework toolchain), set `PEAR_DEV_SERVER_URL` and the main process loads that URL instead of `renderer/index.html`.

The full production bridge—including how `window.bridge` is assembled—is walked through in [Reshape your app for production](/getting-started/build-a-peer-to-peer-chat/reshape-into-a-production-app).

Where the app logic goes [#where-the-app-logic-goes]

Everything peer-to-peer lives in `workers/main.js`, which runs in Bare (not Node). The host passes the runtime configuration as positional arguments; the worker reads them (with an `argv` helper for cross-platform compatibility) and constructs the [`pear-runtime`](/reference/pear/runtime) instance:

```js file=<rootDir>/examples/getting-started/hello-pear-electron/workers/main.js#L15-L27 title="workers/main.js"
const updaterConfig = {
  updates: argv(0) !== 'false',
  version: argv(1),
  upgrade: argv(2),
  name: argv(3),
  dir: argv(4) || dir.persistent(), // argv[4] is undefined in mobile
  app: argv(5) // argv[5] is undefined in mobile
}

const pipe = new FramedStream(Bare.IPC)
const store = new Corestore(path.join(updaterConfig.dir, 'pear-runtime', 'corestore'))
const swarm = new Hyperswarm()
const pear = new PearRuntime({ ...updaterConfig, swarm, store })
```

This is where you add your [Corestore](/reference/helpers/corestore) cores, join [Hyperswarm](/reference/building-blocks/hyperswarm) topics, and run your protocols. Use `pear.storage` as the storage root so your data lands in the same per-app directory Pear manages—see [Storage and distribution](/explanation/storage-and-distribution). For why the logic belongs here rather than in the renderer, see [Workers](/explanation/workers).

<Callout type="info">
  Upstream now ships this worker as the [`hello-pear-worker`](https://github.com/holepunchto/hello-pear-worker) package—the template's `workers/main.js` is just `require('hello-pear-worker')`. The code above is that worker inlined so you can see what it does; write your own peer-to-peer logic in `workers/main.js` the same way.
</Callout>

How to connect them [#how-to-connect-them]

The bridge is the contract between the two halves. `electron/preload.js` exposes these methods on `window.bridge`:

| `window.bridge` method                                                                                                                                                                                                                                                                                                                   | Purpose                                                             |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| [`pkg()`](https://github.com/holepunchto/hello-pear-electron/blob/main/electron/preload.js#L9-L11)                                                                                                                                                                                                                                       | Read `package.json` synchronously (used for the version label).     |
| [`startWorker(specifier)`](https://github.com/holepunchto/hello-pear-electron/blob/main/electron/preload.js#L14)                                                                                                                                                                                                                         | Spawn a worker by path, for example `/workers/main.js`.             |
| [`writeWorkerIPC(specifier, data)`](https://github.com/holepunchto/hello-pear-electron/blob/main/electron/preload.js#L35-L37)                                                                                                                                                                                                            | Send a message to that worker.                                      |
| [`onWorkerIPC(specifier, listener)`](https://github.com/holepunchto/hello-pear-electron/blob/main/electron/preload.js#L25-L29)                                                                                                                                                                                                           | Receive messages from that worker. Returns an unsubscribe function. |
| [`onWorkerStdout`](https://github.com/holepunchto/hello-pear-electron/blob/main/electron/preload.js#L15-L19) / [`onWorkerStderr`](https://github.com/holepunchto/hello-pear-electron/blob/main/electron/preload.js#L20-L24) / [`onWorkerExit`](https://github.com/holepunchto/hello-pear-electron/blob/main/electron/preload.js#L30-L34) | Observe worker output and lifecycle.                                |
| [`applyUpdate()`](https://github.com/holepunchto/hello-pear-electron/blob/main/electron/preload.js#L12) / [`appAfterUpdate()`](https://github.com/holepunchto/hello-pear-electron/blob/main/electron/preload.js#L13)                                                                                                                     | Apply a downloaded OTA update and relaunch.                         |

Messages over the worker pipe are raw bytes—the boilerplate sends plain UTF-8 strings (`'Hello from worker'`, `'updating'`, `'pear:applyUpdate'`). You have two ways to add functionality:

1. Stay on the generic channel. Send and receive your own messages with `writeWorkerIPC` / `onWorkerIPC`. Define a small message protocol (a `type` field is enough). This is the lightest option and is shown below.
2. Add a typed bridge method. For something first-class (not tied to a worker), add a method to `electron/preload.js` and a matching `ipcMain.handle(...)` in `electron/main.js`, the way `applyUpdate` is wired.

Example: add a "ping" feature [#example-add-a-ping-feature]

You can add a button that asks the worker for the current time and shows the reply. It exercises the full round-trip: renderer to worker and back. You can switch the pipe from bare strings to small JSON messages so several message types can coexist. This example uses the generic channel.

1. Add a button to the renderer UI [#1-add-a-button-to-the-renderer-ui]

In `renderer/index.html`, add a button and an output line inside `.container`:

```diff
     <div class="container">
       <h1 id="v">v</h1>
       <button id="update-btn">Apply update</button>
+      <button id="ping-btn">Ping worker</button>
+      <p id="pong"></p>
     </div>
```

2. Send and receive in the renderer [#2-send-and-receive-in-the-renderer]

In `renderer/app.js`, wire the button to `writeWorkerIPC` and handle the reply in the existing `onWorkerIPC` callback. The boilerplate currently treats every worker message as an updater event string; route messages through `JSON.parse` and fall back to the old strings so the updater keeps working:

```diff
 const offWorkerIpc = bridge.onWorkerIPC(workers.main, (data) => {
   const message = decoder.decode(data)
   console.log('worker ipc', '[', workers.main, ']:', message)
-  onWorkerUpdaterEvent(message)
+
+  let parsed
+  try {
+    parsed = JSON.parse(message)
+  } catch {
+    onWorkerUpdaterEvent(message) // 'updating' / 'updated'
+    parsed = null
+  }
+
+  if (parsed?.type === 'pong') {
+    document.getElementById('pong').innerText = 'Worker time: ' + parsed.time
+  }

   if (!sentHello) {
     sentHello = true
     bridge.writeWorkerIPC(workers.main, 'Hello from renderer')
   }
 })
+
+document.getElementById('ping-btn').onclick = () => {
+  bridge.writeWorkerIPC(workers.main, JSON.stringify({ type: 'ping' }))
+}
```

3. Handle it in the worker [#3-handle-it-in-the-worker]

In `workers/main.js`, parse incoming messages and reply to `ping`. Keep the existing `pear:applyUpdate` handling:

```diff
 pipe.on('data', async (data) => {
   const message = data.toString()
   if (message === 'pear:applyUpdate') {
     await pear.ready()
     await pear.updater.applyUpdate()
     pipe.write('pear:updateApplied')
-  } else console.log(message)
+    return
+  }
+
+  try {
+    const msg = JSON.parse(message)
+    if (msg.type === 'ping') {
+      pipe.write(JSON.stringify({ type: 'pong', time: new Date().toISOString() }))
+    }
+  } catch {
+    console.log(message)
+  }
 })
```

Run `npm start`, click **Ping worker**, and the worker's timestamp appears in the renderer. You now have a request/response path you can grow into real features—swap the `pong` handler for a [Corestore](/reference/helpers/corestore) read, a [Hyperswarm](/reference/building-blocks/hyperswarm) lookup, or any protocol your app needs.

Customize for your brand [#customize-for-your-brand]

Before you ship, [deploy your application](/how-to/operate-an-app/manual-deployment/deployment):

* `package.json`—set `name`, `productName`, `description`, `author`, `license`, and the `upgrade` `pear://` link (see [Set the upgrade link](/how-to/operate-an-app/manual-deployment/deployment#1-set-the-upgrade-link)).
* `build/`—replace `icon.icns` / `icon.ico` / `icon.png` and the sized icons, and edit `build/AppxManifest.xml` (`DisplayName`, `Publisher`) for Windows.
* `pear.json`—fill the multisig public-key placeholders when you set up production signing.

Then build and release with [Build desktop distributables](/how-to/operate-an-app/build-and-package/build-desktop-distributables), or automate it with [Build and sign desktop apps in CI](/how-to/operate-an-app/github-actions/build-and-sign-in-ci).

Where to go next [#where-to-go-next]

* [Pear desktop application architecture](/explanation/pear-desktop-architecture)—the conceptual model behind the renderer/main/worker split.
* [Workers](/explanation/workers)—why peer-to-peer logic lives in a Bare worker and where the boundary should sit.
* [Reshape into a production app](/getting-started/build-a-peer-to-peer-chat/reshape-into-a-production-app)—the hello-pear-electron-shaped scaffold with an [Autobase](/reference/building-blocks/autobase)-backed room, blind-pairing invites, and a vanilla HTML renderer.
* [Start from a template](/getting-started/from-a-template)—both boilerplates, side by side.
* [Start from the hello-pear-bare template](/getting-started/from-a-template/start-from-hello-pear-bare)—the terminal counterpart: a standalone Bare CLI with OTA updates and no GUI.
* [Publish with GitHub Actions](/how-to/operate-an-app/github-actions/publish-with-github-actions)—stage a stable `pear://` link on every push with the `pear-ci` action.
* [Build and sign desktop apps in CI](/how-to/operate-an-app/github-actions/build-and-sign-in-ci)—build, sign, and notarize macOS, Windows, and Linux distributables on hosted runners.
* [Seeding with `pear seed`](/explanation/availability-and-blind-peering#seeding-with-pear-seed)—keep your `pear://` link online so peers can fetch releases.
* [Deploy your application](/how-to/operate-an-app/manual-deployment/deployment)—stage, seed, and release your build.


# Add blind peering to a chat app



import { Steps, Step } from 'fumadocs-ui/components/steps'

This guide shows you how to **layer [blind peering](/explanation/availability-and-blind-peering) on top of [`pear-chat`](https://github.com/holepunchto/pear-docs/tree/preview/examples/getting-started/pear-chat)** so the room stays reachable even when none of its writers are connected. The reference implementation is [`pear-chat-blind-peering`](https://github.com/holepunchto/pear-docs/tree/preview/examples/how-to/blind-peering/add-blind-peering-to-a-chat-app).

{/*
  Shared snippet (content/_snippets/) included via Fumadocs <include> by the chat-app delta how-tos.
  Reminds readers these guides teach portable Pear-end (worker) logic, not desktop-specific code.
  See: https://www.fumadocs.dev/docs/markdown#include
  */}

<Callout type="info">
  **This guide is about the Pear-end, not the shell.** The code below lives in the Bare [worker](/explanation/workers)—the peer-to-peer logic, not the user interface. Because the Pear-end never imports DOM APIs and never assumes a UI framework, the same worker is portable across **desktop (Electron)**, **mobile (React Native via Bare iOS / Bare Android)**, and **terminal**. The example apps ship an Electron shell, but only the UI half changes per platform—the logic here stays the same. See [Runtime and languages](/explanation/runtime-and-languages) for the cross-platform model and current support.
</Callout>

{/*
  Shared snippet (content/_snippets/) included via Fumadocs <include> by the chat-app delta how-tos.
  Flags the guide as delta-only on top of the pear-chat scaffold built in the getting-started path.
  See: https://www.fumadocs.dev/docs/markdown#include
  */}

This is a **delta-only** how-to. The shared Electron + PearRuntime + Bare worker scaffold—with plain-JSON messages over a [`framed-stream`](https://www.npmjs.com/package/framed-stream) pipe and a vanilla HTML renderer—is built step by step in [Reshape into a production app](/getting-started/build-a-peer-to-peer-chat/reshape-into-a-production-app)—read that first.

* [Keep data available with blind peering](/how-to/blind-peering/keep-data-available-with-blind-peering)—the standalone `blind-peering` client this guide layers onto the chat scaffold.

Before you begin [#before-you-begin]

* A working clone of `pear-chat` (or your own app built from [Reshape into a production app](/getting-started/build-a-peer-to-peer-chat/reshape-into-a-production-app)).
* Comfort with [Autobase](/reference/building-blocks/autobase) and [Hyperswarm](/reference/building-blocks/hyperswarm).

What changes [#what-changes]

| Layer             | Change                                                                                                                                                                                                        |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Dependencies      | Add [`blind-peering`](https://www.npmjs.com/package/blind-peering).                                                                                                                                           |
| Worker entrypoint | Declare a `--blind-peer-key` flag in `workers/index.js` so the keys reach the worker.                                                                                                                         |
| Worker            | Instantiate a `BlindPeering` client against the swarm, point it at one or more blind-peer public keys, register the room's [Autobase](/reference/building-blocks/autobase), and tear it down before the room. |
| Renderer          | Optional: surface the configured blind-peer keys, or let users supply their own.                                                                                                                              |

Everything else—`electron/`, `spec/`, the vanilla `renderer/`, the forge config, the build assets—stays as in the getting-started chat app.

Steps [#steps]

<Steps>
  <Step>
    Add the dependency [#add-the-dependency]

    ```bash skip="desktop-gui"
    npm install blind-peering
    ```
  </Step>

  <Step>
    Declare the --blind-peer-key flag [#declare-the---blind-peer-key-flag]

    The worker only sees the flags `workers/index.js` declares with [`paparam`](https://www.npmjs.com/package/paparam). Add `--blind-peer-key` to the `command(...)` block so the keys you pass on the command line reach `WorkerTask`—without this, the runtime bails with `UNKNOWN_FLAG: blind-peer-key`:

    ```diff title="workers/index.js" skip="snippet-illustration"
     const cmd = command('pear-chat-blind-peering',
    +  flag('--blind-peer-key|-b <blindPeerKey>', 'Blind peer key').multiple(),
       flag('--invite|-i <invite>', 'Room invite'),
       flag('--name|-n <name>', 'Your name'),
       flag('--reset', 'Reset')
     )
    ```

    `.multiple()` lets the flag repeat, so `cmd.flags.blindPeerKey` is an **array** of keys. `cmd.flags` is already passed to `WorkerTask`, which reads it as `opts.blindPeerKey` in the next step.
  </Step>

  <Step>
    Wire a BlindPeering into WorkerTask [#wire-a-blindpeering-into-workertask]

    In `workers/worker-task.js`, instantiate [`BlindPeering`](https://www.npmjs.com/package/blind-peering) against the swarm and a [Corestore](/reference/helpers/corestore) namespace, pointing it at the public keys of the blind peers you want to mirror to (L23–L25, reading the keys collected from `opts.blindPeerKey` at L15). Register the room's Autobase once it is open (L36). Close it **before** the room so its connections release cleanly (L55):

    ```js file=<rootDir>/examples/how-to/blind-peering/add-blind-peering-to-a-chat-app/workers/worker-task.js title="workers/worker-task.js" lineNumbers {1,15,23-25,36,55} skip="example-import"
    const BlindPeering = require('blind-peering')
    const Corestore = require('corestore')
    const debounce = require('debounceify')
    const Hyperswarm = require('hyperswarm')
    const ReadyResource = require('ready-resource')

    const ChatRoom = require('./chat-room')

    class WorkerTask extends ReadyResource {
      constructor (pipe, storage, opts = {}) {
        super()

        this.pipe = pipe
        this.storage = storage
        this.blindPeerKeys = opts.blindPeerKey || []
        this.invite = opts.invite
        this.name = opts.name || `User ${Date.now()}`

        this.store = new Corestore(storage)
        this.swarm = new Hyperswarm()
        this.swarm.on('connection', (conn) => this.store.replicate(conn))

        this.blindPeering = new BlindPeering(this.swarm.dht, this.store.namespace('blind-peering'), {
          keys: this.blindPeerKeys
        })

        this.room = new ChatRoom(this.store, this.swarm, this.invite)
        this.debounceMessages = debounce(() => this._messages())
        this.room.on('update', () => this.debounceMessages())
      }

      async _open () {
        await this.store.ready()
        await this.room.ready()

        await this.blindPeering.addAutobase(this.room.base)

        this.pipe.on('data', async (data) => {
          let message
          try {
            message = JSON.parse(data)
          } catch {
            return
          }
          if (message.type === 'add-message') {
            await this.room.addMessage(message.text, { name: this.name, at: Date.now() })
          }
        })
        await this.debounceMessages()

        this.pipe.write(JSON.stringify({ type: 'invite', invite: await this.room.getInvite() }))
      }

      async _close () {
        await this.blindPeering.close()
        await this.room.close()
        await this.swarm.destroy()
        await this.store.close()
      }

      async _messages () {
        const messages = await this.room.getMessages()
        messages.sort((a, b) => a.info.at - b.info.at)
        this.pipe.write(JSON.stringify({ type: 'messages', messages }))
      }
    }

    module.exports = WorkerTask
    ```

    The blind peers replicate and seed the room's encrypted [Autobase](/reference/building-blocks/autobase) without holding its read key. Point the client at blind-peer keys you run yourself (the [`blind-peer-cli`](https://github.com/holepunchto/blind-peer-cli) server prints `Listening at <key>` on startup) or shared ones.

    <Callout type="info">
      See [Availability and blind peering](/explanation/availability-and-blind-peering) for the threat model (a blind peer replicates encrypted data but never holds the room encryption key).
    </Callout>
  </Step>

  <Step>
    Confirm the teardown order [#confirm-the-teardown-order]

    The order in `_close` matters (L54–L58): the room holds [`blind-pairing`](https://www.npmjs.com/package/blind-pairing) handles that depend on the swarm, and the blind-peering client holds its own connections to the blind peers. Always close the client first (L55), then the room, then the swarm, then the store (L56–L58).
  </Step>
</Steps>

Run it [#run-it]

You need three processes:

1. A **blind peer** that stays online to keep the room available, and
2. **two chat peers** (`user1` and `user2`) that can come and go. Open a terminal for each.

1. Start a blind peer [#1-start-a-blind-peer]

Run one with [`blind-peer-cli`](https://github.com/holepunchto/blind-peer-cli) (or point at a shared one you trust). On startup it logs a `Listening at <key>` line—copy that key, you pass it to both users as `--blind-peer-key`.

```bash skip="blind-peer"
npm install -g blind-peer-cli
blind-peer
# {"level":30, ... ,"msg":"Listening at es4n7ty45odd1udfqyi9xz58mrbheuhdnxgdufsn9gz6e5uhsqco"}
```

2. Start user1 (creates the room) [#2-start-user1-creates-the-room]

Pass the blind-peer key so the room's [Autobase](/reference/building-blocks/autobase) is mirrored. The app prints an `Invite:` line on stdout—copy it for `user2`:

```bash skip="desktop-gui"
npm run build
npm start -- --storage /tmp/bp-user1 --name user1 --blind-peer-key <BLIND_PEER_KEY>
```

3. Start user2 (joins the room) [#3-start-user2-joins-the-room]

Pass the invite from `user1` and the same blind-peer key:

```bash skip="desktop-gui"
npm start -- --storage /tmp/bp-user2 --name user2 --invite <INVITE> --blind-peer-key <BLIND_PEER_KEY>
```

Both peers register the room's Autobase with the blind peer (you can repeat `--blind-peer-key` to use several). Now quit `user1`: `user2` still receives the existing history and stays in sync, because the blind peer keeps replicating the encrypted room even though neither writer is online. Restart `user1` and it catches up from the blind peer too—without ever handing it the room's read key.

Where to go next [#where-to-go-next]

* [Keep data available with blind peering](/how-to/blind-peering/keep-data-available-with-blind-peering)—the same `blind-peering` client on its own, without the Electron shell.
* [Availability and blind peering](/explanation/availability-and-blind-peering)—why a third-party replicator does not need to be trusted.
* [Add Keet identity to a chat app](/how-to/manage-identity/add-keet-identity-to-a-chat-app)—keep your relay's identity portable.
* [Build desktop distributables](/how-to/operate-an-app/build-and-package/build-desktop-distributables)—package the relay app for macOS, Windows, and Linux.


# Blind peering



import { Cards, Card } from 'fumadocs-ui/components/card'

Recipes for keeping peer-to-peer data reachable when the writers that created it are offline.

<Cards>
  <Card href="/how-to/blind-peering/keep-data-available-with-blind-peering" title="Keep data available with blind peering" description="Ask blind peers to keep your Hypercores and Autobases available even when no writer is online." />

  <Card href="/how-to/blind-peering/add-blind-peering-to-a-chat-app" title="Add blind peering to a chat app" description="Keep a chat room reachable when none of its writers are online by attaching a blind-peering client." />
</Cards>


# Keep data available with blind peering



<Callout type="info">
  **This guide focuses on the Pear/Bare logic.** It shows the [`blind-peering`](https://www.npmjs.com/package/blind-peering) client on its own—no Electron, no UI. For the same capability wired into a full desktop app with a chat front end, see the worked example [`pear-chat-blind-peering`](https://github.com/holepunchto/pear-docs/tree/preview/examples/how-to/blind-peering/add-blind-peering-to-a-chat-app) and its walkthrough, [Add blind peering to a chat app](/how-to/blind-peering/add-blind-peering-to-a-chat-app).
</Callout>

A peer-to-peer core is only available while a peer that has it is online. [Blind peering](/explanation/availability-and-blind-peering) closes that gap: a **blind peer** is an always-on server that replicates and seeds your [Hypercore](/reference/building-blocks/hypercore) or [Autobase](/reference/building-blocks/autobase) **without holding the read capability**—it stores and forwards encrypted blocks it cannot decrypt. Your data stays reachable even when none of its writers are connected.

This is purely Pear-end logic: it lives in a [Bare](/reference/modules/bare-modules) worker (or any Bare/Node process) and never touches a UI.

{/*
  Shared snippet (content/_snippets/) included via Fumadocs <include> by how-tos
  whose Pear-end (worker) logic works with EITHER boilerplate (desktop or
  terminal). Carries the cross-platform portability point too, so it REPLACES
  _pear-end-portability-callout on these guides—one orientation callout, not two.
  For frontend-specific how-tos, use _frontend-template-callout.mdx instead.
  See: https://www.fumadocs.dev/docs/markdown#include
  */}

<Callout type="info">
  **Pear-end logic—start from a boilerplate.** The code in this guide lives in the Bare [worker](/explanation/workers): peer-to-peer logic, no UI. The same worker runs unchanged on desktop, terminal, and mobile—only the shell differs (see [Runtime and languages](/explanation/runtime-and-languages)). Start from a boilerplate in [Start from a template](/getting-started/from-a-template)—desktop ([`hello-pear-electron`](/getting-started/from-a-template/start-from-hello-pear-electron)) or terminal ([`hello-pear-bare`](/getting-started/from-a-template/start-from-hello-pear-bare))—and add this capability on top.
</Callout>

Two roles [#two-roles]

| Role           | What it runs                                                                                                                                                                                                                                                                  | Holds read key? |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- |
| **Blind peer** | An always-on server with its own key pair, run with [`blind-peer-cli`](https://github.com/holepunchto/blind-peer-cli)—which provides the `blind-peer` command on top of the [`blind-peer`](https://github.com/holepunchto/blind-peer) library. Seeds whatever it is asked to. | No              |
| **Client**     | Your app, using the `blind-peering` module to ask one or more blind peers (by public key) to keep specific cores available.                                                                                                                                                   | Yes             |

You point the client at the **public keys** of the blind peers you want to mirror to. Those can be blind peers you run yourself, or shared ones.

Add the dependency [#add-the-dependency]

```sh skip="install-instruction"
npm install blind-peering
```

Wire the client [#wire-the-client]

Create the `BlindPeering` client against your swarm's [HyperDHT](/reference/building-blocks/hyperdht) instance ([`swarm.dht`](/reference/building-blocks/hyperswarm#swarmdht)) and a [Corestore](/reference/helpers/corestore) namespace, passing the blind peers' public keys as `keys`. Then register the cores or Autobases you want kept available:

```js skip="snippet-illustration"
import Hyperswarm from 'hyperswarm'
import Corestore from 'corestore'
import BlindPeering from 'blind-peering'

const swarm = new Hyperswarm()
const store = new Corestore('./store')
swarm.on('connection', (conn) => store.replicate(conn))

// Public keys of the blind peers to mirror to (z32 or hex).
const blindPeerKeys = [/* 'a1b2c3…' */]

const blinds = new BlindPeering(swarm.dht, store.namespace('blind-peering'), {
  keys: blindPeerKeys
})

// Ask the blind peers to keep a single Hypercore available…
await blinds.addCore(core)

// …or a whole Autobase (all of its writer and view cores).
await blinds.addAutobase(base)
```

`addCore` / `addAutobase` connect to the closest configured blind peers and request that they replicate and seed the given cores. The blind peer downloads the encrypted blocks and serves them to other peers on demand—without ever being able to read them.

Tear it down [#tear-it-down]

Close the client before the swarm and store so its connections release cleanly:

```js skip="snippet-illustration"
await blinds.close()
await swarm.destroy()
await store.close()
```

Run your own blind peer [#run-your-own-blind-peer]

To control availability yourself rather than relying on shared blind peers, run the [`blind-peer-cli`](https://github.com/holepunchto/blind-peer-cli) server (`npm i -g blind-peer-cli`, then `blind-peer`) on an always-on machine. It prints a public key—pass that key in the client's `keys` array. See [Availability and blind peering](/explanation/availability-and-blind-peering) for the full setup, including a systemd unit.

See also [#see-also]

* [Availability and blind peering](/explanation/availability-and-blind-peering)—the threat model: why a blind peer never needs to be trusted with your data.
* [Add blind peering to a chat app](/how-to/blind-peering/add-blind-peering-to-a-chat-app)—the same client wired into a full desktop app with a UI.
* [Work with many Hypercores using Corestore](/how-to/store-and-replicate/work-with-many-hypercores-using-corestore)—the store the client namespaces into.
* [Autobase reference](/reference/building-blocks/autobase)—the multi-writer log `addAutobase` keeps available.


# Connect to many peers by topic with Hyperswarm



In [Connect two peers by key with HyperDHT](/how-to/connect-to-peers/connect-two-peers-by-key-with-hyperdht), two peers connected directly using the first peer's public key.
Hyperswarm helps to discover peers swarming a common topic, and connect to as many of them as possible.
This will become clearer in [Replicate and persist with Hypercore](/how-to/store-and-replicate/replicate-and-persist-with-hypercore),
but it's the best way to distribute peer-to-peer data structures.

The [Hyperswarm](/reference/building-blocks/hyperswarm) module provides a higher-level interface over the underlying [HyperDHT](/reference/building-blocks/hyperdht),
abstracting away the mechanics of establishing and maintaining connections.
Instead, 'join' topics, and the swarm discovers peers automatically. It also handles reconnection in the event of failures.

In [Connect two peers by key with HyperDHT](/how-to/connect-to-peers/connect-two-peers-by-key-with-hyperdht),
we needed to explicitly indicate which peer was the server and which was the client.
By using Hyperswarm, we create two peers, have them join a common topic, and let the swarm deal with connections.

{/*
  Shared snippet (content/_snippets/) included via Fumadocs <include> by how-tos
  whose Pear-end (worker) logic works with EITHER boilerplate (desktop or
  terminal). Carries the cross-platform portability point too, so it REPLACES
  _pear-end-portability-callout on these guides—one orientation callout, not two.
  For frontend-specific how-tos, use _frontend-template-callout.mdx instead.
  See: https://www.fumadocs.dev/docs/markdown#include
  */}

<Callout type="info">
  **Pear-end logic—start from a boilerplate.** The code in this guide lives in the Bare [worker](/explanation/workers): peer-to-peer logic, no UI. The same worker runs unchanged on desktop, terminal, and mobile—only the shell differs (see [Runtime and languages](/explanation/runtime-and-languages)). Start from a boilerplate in [Start from a template](/getting-started/from-a-template)—desktop ([`hello-pear-electron`](/getting-started/from-a-template/start-from-hello-pear-electron)) or terminal ([`hello-pear-bare`](/getting-started/from-a-template/start-from-hello-pear-bare))—and add this capability on top.
</Callout>

Create the peer-app project [#create-the-peer-app-project]

Create the `peer-app` project with the following commands:

```sh example=hyperswarm-chat step=setup
mkdir peer-app
cd peer-app
npm init -y
npm pkg set type="module"
npm install hyperswarm hypercore-crypto b4a bare-process
```

Alter the peer-app/index.js file to the following. Create a single [Hyperswarm](/reference/building-blocks/hyperswarm) instance (L7). On each `connection` event, track the connection and log incoming data from that peer (L13–L20). Broadcast anything typed on stdin to every open connection (L23–L28). Then join a common topic as both client and server—reusing a topic passed on the command line, or generating a fresh one (L31–L32). The [`discovery.flushed()`](/reference/building-blocks/hyperswarm#await-discoveryflushed) promise resolves once the topic has been announced to the DHT, at which point the topic is logged for other peers to copy (L35–L37).

```javascript file=<rootDir>/examples/how-to/connect-to-peers/connect-to-many-peers-by-topic-with-hyperswarm/peer-app/index.js title="peer-app/index.js" lineNumbers {7,13-20,23-28,31-32,35-37} skip="example-import"

import Hyperswarm from 'hyperswarm'
import crypto from 'hypercore-crypto'
import b4a from 'b4a'
import process from 'bare-process'

const swarm = new Hyperswarm()
const name = b4a.toString(swarm.keyPair.publicKey, 'hex')
process.once('SIGINT', () => swarm.destroy().then(() => process.exit(0)))

// Keep track of all connections and console.log incoming data
const conns = []
swarm.on('connection', conn => {
  const peer = b4a.toString(conn.remotePublicKey, 'hex')
  console.log('* got a connection from:', peer, '*')
  conns.push(conn)
  conn.once('close', () => conns.splice(conns.indexOf(conn), 1))
  conn.on('data', data => console.log(`${peer}: ${data}`))
  conn.on('error', e => console.log(`Connection error: ${e}`))
})

// Broadcast stdin to all connections
process.stdin.on('data', d => {
  console.log(`${name}: ${d}`)
  for (const conn of conns) {
    conn.write(d)
  }
})

// Join a common topic
const topic = Bare.argv[2] ? b4a.from(Bare.argv[2], 'hex') : crypto.randomBytes(32)
const discovery = swarm.join(topic, { client: true, server: true })

// The flushed promise will resolve when the topic has been fully announced to the DHT
discovery.flushed().then(() => {
  console.log('joined topic:', b4a.toString(topic, 'hex'))
})
```

{/* @harness example=hyperswarm-chat step=copy from=examples/how-to/connect-to-peers/connect-to-many-peers-by-topic-with-hyperswarm/peer-app/index.js to=peer-app/index.js */}

Run the swarm [#run-the-swarm]

In one terminal, move one directory up and run `peer-app` with `bare`:

```sh example=hyperswarm-chat step=run process=peer1 expect="joined topic:" capture-topic="joined topic: ([0-9a-f]+)" timeout=45000
bare peer-app
```

This will display the topic. Copy/paste that topic into as many additional terminals as desired:

```sh example=hyperswarm-chat step=run process=peer2 cmd="bare peer-app ${topic}" expect="got a connection from:" timeout=45000
bare peer-app <SUPPLY TOPIC HERE>
```

Each peer will log information about the other connected peers. Start typing into any terminal, and it will be broadcast to all connected peers.

<Callout type="info">
  **Use one [Hyperswarm](/reference/building-blocks/hyperswarm) instance per application.** A single swarm can join multiple topics and dedups peer connections shared between them. This speeds up connections by reducing [HyperDHT](/reference/building-blocks/hyperdht) records per topic and simplifies managing the maximum number of connections your app makes.
</Callout>

Connections established here are ephemeral—once both peers go offline the conversation is lost.

See also [#see-also]

* [Replicate and persist with Hypercore](/how-to/store-and-replicate/replicate-and-persist-with-hypercore)—persist messages so a reader catches up after the writer disconnects.
* [Peer-to-peer, demystified](/explanation/peer-to-peer-demystified)—how topic discovery and hole punching work under Hyperswarm.
* [Connect two peers by key with HyperDHT](/how-to/connect-to-peers/connect-two-peers-by-key-with-hyperdht)—direct one-to-one connection by public key.
* [Hyperswarm reference](/reference/building-blocks/hyperswarm)—full API for topic joins, connection events, and peer management.
* [HyperDHT reference](/reference/building-blocks/hyperdht)—the lower-level DHT layer Hyperswarm is built on.


# Connect two peers by key with HyperDHT



[`HyperDHT`](/reference/building-blocks/hyperdht) helps clients connect to a server peer with a known public key.
HyperDHT uses a series of holepunching techniques to establish direct connections between the peers, even if they're located on home networks with tricky NATs.

In the HyperDHT, peers are identified by a public key, not by an IP address.
The public key is looked up in a decentralized hash table, which maps the key to an IP address and port.
This means users can connect to each other irrespective of their location, even if they move between different networks.

<Callout type="warn">
  HyperDHT's holepunching will fail if both the client peer and the server peer are on randomizing [NATs](https://en.wikipedia.org/wiki/Network_address_translation), in which case the connection must be relayed through a third peer. HyperDHT does not do any relaying by default.

  For example, Keet implements its relaying system wherein other call participants can serve as relays -- the more participants in the call, the stronger overall connectivity becomes.
</Callout>

Use the HyperDHT to create a basic CLI chat app where a client peer connects to a server peer by public key.
The example consists of two applications: [`client-app`](#create-the-client-app) and [`server-app`](#create-the-server-app).

{/*
  Shared snippet (content/_snippets/) included via Fumadocs <include> by how-tos
  whose Pear-end (worker) logic works with EITHER boilerplate (desktop or
  terminal). Carries the cross-platform portability point too, so it REPLACES
  _pear-end-portability-callout on these guides—one orientation callout, not two.
  For frontend-specific how-tos, use _frontend-template-callout.mdx instead.
  See: https://www.fumadocs.dev/docs/markdown#include
  */}

<Callout type="info">
  **Pear-end logic—start from a boilerplate.** The code in this guide lives in the Bare [worker](/explanation/workers): peer-to-peer logic, no UI. The same worker runs unchanged on desktop, terminal, and mobile—only the shell differs (see [Runtime and languages](/explanation/runtime-and-languages)). Start from a boilerplate in [Start from a template](/getting-started/from-a-template)—desktop ([`hello-pear-electron`](/getting-started/from-a-template/start-from-hello-pear-electron)) or terminal ([`hello-pear-bare`](/getting-started/from-a-template/start-from-hello-pear-bare))—and add this capability on top.
</Callout>

<Callout type="info">
  This guide is a terminal-only walkthrough. For the **desktop equivalent**—the same peer connection wired into an Electron + Bare worker shell—follow the [Getting Started path](/getting-started), which builds a `pear://` chat app on top of the [`hello-pear-electron` template](/getting-started/from-a-template/start-from-hello-pear-electron).
</Callout>

Create the server app [#create-the-server-app]

The `server-app` creates a key pair, starts a server listening on it, and logs the public key. Copy that key—the client uses it to connect.

Create the server project [#create-the-server-project]

Create the `server-app` project with the following commands:

```sh example=hyperdht-chat step=setup
mkdir server-app
cd server-app
npm init -y
npm pkg set type="module"
npm install hyperdht b4a bare-process
```

Add the server logic [#add-the-server-logic]

Alter `server-app/index.js` to the following.

The server starts a DHT node (L5) and generates a key pair that serves as its identity in the DHT (L8), then derives a hex string `name` from the public key to print and share (L9). `dht.createServer` registers a connection handler (L11–L13) that logs each connecting peer, wires incoming data to the console, and forwards local stdin to the connection (L15–L19). Finally, [`server.listen(keyPair)`](/reference/building-blocks/hyperdht#await-serverlistenkeypair) announces the key on the DHT and logs the public key for the client to copy (L22–L24):

```javascript file=<rootDir>/examples/how-to/connect-to-peers/connect-two-peers-by-key-with-hyperdht/server-app/index.js title="server-app/index.js" lineNumbers {5,8-9,11-13,15-19,22-24} skip="example-import"
import DHT from 'hyperdht'
import b4a from 'b4a'
import process from 'bare-process'

const dht = new DHT()

// This keypair is the peer identifier in the DHT
const keyPair = DHT.keyPair()
const name = b4a.toString(keyPair.publicKey, 'hex')

const server = dht.createServer(conn => {
  const peer = b4a.toString(conn.remotePublicKey, 'hex')
  console.log('* got a connection from:', peer, '*')

  conn.on('data', data => console.log(`${peer}: ${data}`))
  process.stdin.on('data', d => {
    console.log(`${name}: ${d}`)
    conn.write(d)
  })
})

server.listen(keyPair).then(() => {
  console.log('listening on:', name)
})

// Unannounce the public key before exiting the process
// (Not strictly required, but it helps avoid DHT pollution.)
process.once('SIGINT', () => server.close().then(() => process.exit(0)))
```

{/* @harness example=hyperdht-chat step=copy from=examples/how-to/connect-to-peers/connect-two-peers-by-key-with-hyperdht/server-app/index.js to=server-app/index.js */}

Run the server [#run-the-server]

To run the `server-app`, move one directory up and run the following command:

```sh example=hyperdht-chat step=run process=server expect="listening on:" capture-key="listening on: ([0-9a-f]+)"
bare server-app
```

Create the client app [#create-the-client-app]

Create the client project [#create-the-client-project]

In another terminal create the `client-app` project with the following commands:

```sh example=hyperdht-chat step=setup
mkdir client-app
cd client-app
npm init -y
npm pkg set type="module"
npm install hyperdht b4a bare-process
```

Add the client logic [#add-the-client-logic]

Alter `client-app/index.js` to the following.

The client reads the server's public key from the command-line argument and fails fast if it is missing (L6–L7), then decodes it from hex (L10). It starts its own DHT node (L12–L13) and calls `dht.connect(publicKey)` to begin hole punching toward the server (L15). The `open` handler logs the connected peer once the link is established (L16–L19), the `data` handler prints incoming messages (L21–L24), and local stdin is written to the connection (L26–L29):

```javascript file=<rootDir>/examples/how-to/connect-to-peers/connect-two-peers-by-key-with-hyperdht/client-app/index.js title="client-app/index.js" lineNumbers {6-7,10,12-13,15,16-19,21-24,26-29} skip="example-import"

import DHT from 'hyperdht'
import b4a from 'b4a'
import process from 'bare-process'

const key = Bare.argv[2]
if (!key) throw new Error('provide a key')

console.log('Connecting to:', key)
const publicKey = b4a.from(key, 'hex')

const dht = new DHT()
const name = b4a.toString(dht.defaultKeyPair.publicKey, 'hex')

const conn = dht.connect(publicKey)
conn.once('open', () => {
  const peer = b4a.toString(conn.remotePublicKey, 'hex')
  console.log('* got a connection from:', peer, '*')
})

conn.on('data', data => {
  const peer = b4a.toString(conn.remotePublicKey, 'hex')
  console.log(`${peer}: ${data}`)
})

process.stdin.on('data', d => {
  console.log(`${name}: ${d}`)
  conn.write(d)
})
```

{/* @harness example=hyperdht-chat step=copy from=examples/how-to/connect-to-peers/connect-two-peers-by-key-with-hyperdht/client-app/index.js to=client-app/index.js */}

Run the chat client [#run-the-chat-client]

To run the `client-app`, move one directory up and run the following command:

```sh example=hyperdht-chat step=run process=client cmd="bare client-app ${key}" expect="Connecting to:" timeout=15000
bare client-app <SUPPLY KEY HERE>
```

{/* @harness example=hyperdht-chat step=expect process=server contains="got a connection from:" timeout=30000 */}

The `client-app` will spin up a client, and the public key copied earlier must be supplied as a command line argument for connecting to the server.
The client process will log `* got a connection from:` into the console when it connects to the server.

Once it's connected, try typing in both terminals.

See also [#see-also]

* [Connect to many peers by topic with Hyperswarm](/how-to/connect-to-peers/connect-to-many-peers-by-topic-with-hyperswarm)—discover peers by a shared topic instead of a known public key.
* [Peer-to-peer, demystified](/explanation/peer-to-peer-demystified)—hole punching, public-key identity, and when to use HyperDHT vs [Hyperswarm](/reference/building-blocks/hyperswarm).
* [HyperDHT reference](/reference/building-blocks/hyperdht)—full API for the DHT node, servers, and connections used in this guide.
* [Secretstream](/reference/helpers/secretstream)—the Noise-encrypted stream layer wrapping every HyperDHT connection.
* [Dependencies and network](/explanation/dependencies-and-network)—the IP-level information peers observe during a HyperDHT connection.


# Host multiple rooms in one chat app



import { Steps, Step } from 'fumadocs-ui/components/steps'

This guide shows you how to **extend [`pear-chat`](https://github.com/holepunchto/pear-docs/tree/preview/examples/getting-started/pear-chat) from a single room to an account model that owns and joins many rooms**. The reference implementation is [`pear-chat-multi-rooms`](https://github.com/holepunchto/pear-docs/tree/preview/examples/how-to/connect-to-peers/multi-rooms).

{/*
  Shared snippet (content/_snippets/) included via Fumadocs <include> by the chat-app delta how-tos.
  Reminds readers these guides teach portable Pear-end (worker) logic, not desktop-specific code.
  See: https://www.fumadocs.dev/docs/markdown#include
  */}

<Callout type="info">
  **This guide is about the Pear-end, not the shell.** The code below lives in the Bare [worker](/explanation/workers)—the peer-to-peer logic, not the user interface. Because the Pear-end never imports DOM APIs and never assumes a UI framework, the same worker is portable across **desktop (Electron)**, **mobile (React Native via Bare iOS / Bare Android)**, and **terminal**. The example apps ship an Electron shell, but only the UI half changes per platform—the logic here stays the same. See [Runtime and languages](/explanation/runtime-and-languages) for the cross-platform model and current support.
</Callout>

This is a **delta-only** how-to. The shared scaffold is explained in the [Reshape into a production app](/getting-started/build-a-peer-to-peer-chat/reshape-into-a-production-app) tutorial—read it first.

Before you begin [#before-you-begin]

* A working clone of `pear-chat` (or your own app built from the getting-started path).
* Familiarity with [Autobase](/reference/building-blocks/autobase)—each room is one Autobase.

What changes [#what-changes]

| Layer     | Change                                                                                                                                        |
| --------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| Worker    | Introduce a `ChatAccount` that holds a map of `ChatRoom`s keyed by a generated room id.                                                       |
| Schema    | Add a `room` collection persisting the rooms a user has joined (`{ id, name, invite, info }`).                                                |
| Transport | Add `add-room` and `join-room` message types, push a `rooms` event, and make the `messages` event and `add-message` command carry a `roomId`. |
| Renderer  | Add a left-rail room list with a "new room" button and an invite-paste input.                                                                 |

The Electron shell, the build/forge configuration, and the per-room ChatRoom code stay identical to the getting-started chat app.

Steps [#steps]

<Steps>
  <Step>
    Replace room with a ChatAccount on WorkerTask [#replace-room-with-a-chataccount-on-workertask]

    In `workers/worker-task.js`, swap the single `ChatRoom` for a `ChatAccount` (L6). The worker keeps the same [Corestore](/reference/helpers/corestore) + [Hyperswarm](/reference/building-blocks/hyperswarm) setup (L17–L19), but delegates all room management to the account (L21) and forwards its `messages` event over the worker pipe as JSON tagged with the `roomId` (L24–L26).

    `_open` opens the account (L30–L31), then handles `add-room`, `join-room`, and `add-message` on the pipe (L44–L50). `_close` tears down account → swarm → store (L55–L59):

    ```js file=<rootDir>/examples/how-to/connect-to-peers/multi-rooms/workers/worker-task.js title="workers/worker-task.js" lineNumbers {6,17-19,21-26,30-31,44-50,55-59} skip="example-import"
    const Corestore = require('corestore')
    const debounce = require('debounceify')
    const Hyperswarm = require('hyperswarm')
    const ReadyResource = require('ready-resource')

    const ChatAccount = require('./chat-account')

    class WorkerTask extends ReadyResource {
      constructor (pipe, storage, opts = {}) {
        super()

        this.pipe = pipe
        this.storage = storage
        this.invite = opts.invite
        this.name = opts.name || `User ${Date.now()}`

        this.store = new Corestore(storage)
        this.swarm = new Hyperswarm()
        this.swarm.on('connection', (conn) => this.store.replicate(conn))

        this.account = new ChatAccount(this.store, this.swarm)
        this.debounceRooms = debounce(() => this._rooms())
        this.account.on('update', () => this.debounceRooms())
        this.account.on('messages', (roomId, messages) => {
          this.pipe.write(JSON.stringify({ type: 'messages', roomId, messages }))
        })
      }

      async _open () {
        await this.store.ready()
        await this.account.ready()

        if (this.invite) {
          await this.account.joinRoom(this.invite)
        }

        this.pipe.on('data', async (data) => {
          let message
          try {
            message = JSON.parse(data)
          } catch {
            return
          }
          if (message.type === 'add-room') {
            await this.account.addRoom(message.name, { at: Date.now() })
          } else if (message.type === 'join-room') {
            await this.account.joinRoom(message.invite)
          } else if (message.type === 'add-message') {
            await this.account.addMessage(message.roomId, message.text, { name: this.name, at: Date.now() })
          }
        })
        await this.debounceRooms()
      }

      async _close () {
        await this.account.close()
        await this.swarm.destroy()
        await this.store.close()
      }

      async _rooms () {
        const rooms = Object.entries(this.account.rooms).map(([id, room]) => ({
          id,
          name: room.name,
          invite: room.invite,
          info: room.info
        }))
        // A just-joined room has no `info` yet — it only arrives once its
        // ChatAccount 'update' syncs the room metadata from the peer who created
        // it (see joinRoom in chat-account.js). If _rooms() runs in that window,
        // `.info` is undefined and a bare `.at` access throws, taking the whole
        // worker down.
        rooms.sort((a, b) => (a.info?.at ?? 0) - (b.info?.at ?? 0))
        this.pipe.write(JSON.stringify({ type: 'rooms', rooms }))
      }
    }

    module.exports = WorkerTask
    ```
  </Step>

  <Step>
    Build ChatAccount [#build-chataccount]

    Create `workers/chat-account.js` modelled on `chat-room.js`. The account is itself an [Autobase](/reference/building-blocks/autobase)-backed HyperDB that stores the user's room list:

    * each entry is `{ id, name, invite, info }`, where `id` is a generated handle and `invite` is the room's pairing code.
    * On `_open`, the account opens its base, then `openRooms()` materialises one `ChatRoom` per stored entry, each in its own Corestore namespace (`this.store.namespace(id)`) (L156–L168).
    * `addRoom` (L170–L184) and `joinRoom` (L186–L206) spin up a new `ChatRoom`, then append the room metadata to the account base so it survives restarts:

    ```js file=<rootDir>/examples/how-to/connect-to-peers/multi-rooms/workers/chat-account.js#L156-L206 title="workers/chat-account.js" lineNumbers {156-168,170-184,186-206} skip="example-import"
      async openRooms () {
        const rooms = await this.view.find('@pear-chat-multi-rooms/rooms', { reverse: true, limit: 100 }).toArray()
        await Promise.all(rooms.map(async (item) => {
          const roomStore = this.store.namespace(item.id)
          const room = new ChatRoom(roomStore, this.swarm, { name: item.name, info: item.info, invite: item.invite })
          this.rooms[item.id] = room

          this._watchMessages(item.id)
          await room.ready()

          await this._messages(item.id)
        }))
      }

      async addRoom (name, info) {
        const id = Math.random().toString(16).slice(2)

        const roomStore = this.store.namespace(id)
        const room = new ChatRoom(roomStore, this.swarm, { name, info })
        this.rooms[id] = room

        this._watchMessages(id)
        await room.ready()

        await room.addRoomInfo()
        await this.base.append(
          ChatDispatch.encode('@pear-chat-multi-rooms/add-room', { id, name: room.name, invite: room.invite, info: room.info })
        )
      }

      async joinRoom (invite) {
        const id = Math.random().toString(16).slice(2)

        const roomStore = this.store.namespace(id)
        const room = new ChatRoom(roomStore, this.swarm, { invite })
        this.rooms[id] = room

        room.on('update', async () => {
          const remoteRoom = await room.getRoomInfo()

          if (remoteRoom && remoteRoom.name !== room.name) {
            room.name = remoteRoom.name
            room.info = remoteRoom.info
            await this.base.append(
              ChatDispatch.encode('@pear-chat-multi-rooms/add-room', { id, name: room.name, invite, info: room.info })
            )
          }
        })
        this._watchMessages(id)
        await room.ready()
      }
    ```

    The key change: each room is an independent Autobase in its own namespace, so the account never co-mingles room data. The account base only stores room metadata (id, name, invite, info), encrypted by the account's own Autobase. See [Storage and distribution](/explanation/storage-and-distribution) for the underlying mental model.
  </Step>

  <Step>
    Extend the schema [#extend-the-schema]

    This step touches all three builders in `schema.js`, so it is easiest to follow the full [`pear-chat-multi-rooms` `schema.js`](https://github.com/holepunchto/pear-docs/blob/preview/examples/how-to/connect-to-peers/multi-rooms/schema.js). The changes are:

    1. **Rename the namespace** from `pear-chat` to `pear-chat-multi-rooms` in all three `.namespace(...)` calls (schema, db, dispatch). The type references below (`@pear-chat-multi-rooms/...`) resolve against this name—if you leave the namespace as `pear-chat`, `node schema.js` throws `TypeError: Cannot read properties of undefined (reading 'frameable')` because the referenced type does not exist.
    2. **Register** a `room` schema (`{ id, name, invite, info }`), plus a `rooms` HyperDB collection and an `add-room` HyperDispatch entry.

    The roomId that the renderer uses to address a specific room is carried on the plain-JSON messages exchanged over the worker pipe, so the schema only needs to persist the room metadata. The new `room` registration looks like this (L26–L34):

    ```js file=<rootDir>/examples/how-to/connect-to-peers/multi-rooms/schema.js#L26-L34 title="schema.js" lineNumbers {26-34} skip="example-import"
    schema.register({
      name: 'room',
      fields: [
        { name: 'id', type: 'string', required: true },
        { name: 'name', type: 'string', required: true },
        { name: 'invite', type: 'string', required: true },
        { name: 'info', type: 'json' }
      ]
    })
    ```

    Regenerate `spec/` from a **clean** directory:

    ```bash skip="desktop-gui"
    rm -rf spec && npm run build:db
    ```

    <Callout type="warning">
      Delete `spec/` before regenerating. The schema generators (`hyperschema`, `hyperdispatch`, `hyperdb`) **merge** into the existing manifests rather than overwriting them, so regenerating on top of the old `pear-chat` spec leaves stale registrations next to the new `pear-chat-multi-rooms` ones—the generated `spec/` then carries duplicate definitions.
    </Callout>
  </Step>

  <Step>
    Update the renderer [#update-the-renderer]

    In [`renderer/index.html`](https://github.com/holepunchto/pear-docs/blob/preview/examples/how-to/connect-to-peers/multi-rooms/renderer/index.html) and [`renderer/app.js`](https://github.com/holepunchto/pear-docs/blob/preview/examples/how-to/connect-to-peers/multi-rooms/renderer/app.js), split the layout into a left rail (the room list) and a right pane (the active room).
    The renderer:

    1. sends `{ type: 'add-room', name }` and `{ type: 'join-room', invite }` over the worker pipe,
    2. renders the left rail from the `{ type: 'rooms', rooms }` events the worker pushes,
    3. the existing message send becomes `{ type: 'add-message', text, roomId }`, and
    4. incoming `{ type: 'messages', roomId, messages }` events are filed under their `roomId`, so the renderer just shows the selected room's messages.
  </Step>
</Steps>

Run it [#run-it]

```bash skip="desktop-gui"
npm run build
npm start -- --storage /tmp/multi-user1 --name user1
```

Type a room name and click **Create**. Select the room in the left rail, then click **Copy invite** in the room header to copy the **room invite** (not the `Account Invite` line in the terminal—that pairs a whole account, not a single room). In a second terminal:

```bash skip="desktop-gui"
npm start -- --storage /tmp/multi-user2 --name user2 --invite <room-invite>
```

Or start without `--invite` and paste the room invite into the join field in the UI.

user2's app shows the joined room in its left rail. Both peers can now create or join additional rooms—each one is an independent [Autobase](/reference/building-blocks/autobase) with its own pairing flow.

Where to go next [#where-to-go-next]

* [Add blind peering to a chat app](/how-to/blind-peering/add-blind-peering-to-a-chat-app)—keep individual rooms reachable when their writers are offline.
* [Work with many Hypercores using Corestore](/how-to/store-and-replicate/work-with-many-hypercores-using-corestore)—the pattern that makes hosting many rooms in one app cheap.
* [Storage and distribution](/explanation/storage-and-distribution)—why each room can be its own [Autobase](/reference/building-blocks/autobase) without paying per-room infrastructure costs.


# Connect to peers



import { Cards, Card } from 'fumadocs-ui/components/card'

Recipes for finding other peers and opening direct, end-to-end-encrypted connections.

<Cards>
  <Card href="/how-to/connect-to-peers/connect-two-peers-by-key-with-hyperdht" title="Connect two peers by key with HyperDHT" description="Connect client and server peers by public key using HyperDHT hole punching." />

  <Card href="/how-to/connect-to-peers/connect-to-many-peers-by-topic-with-hyperswarm" title="Connect to many peers by topic with Hyperswarm" description="Discover peers on a topic and keep connections alive with Hyperswarm." />

  <Card href="/how-to/connect-to-peers/host-multiple-rooms-in-one-chat-app" title="Host multiple rooms in one chat app" description="Extend the pear-chat scaffold from a single room to an account that owns and switches between many rooms." />
</Cards>


# Add Keet identity to a chat app



import { Steps, Step } from 'fumadocs-ui/components/steps'

This guide shows you how to **add a Keet-style portable identity** to [`pear-chat`](https://github.com/holepunchto/pear-docs/tree/preview/examples/getting-started/pear-chat) so a user's identity survives across devices and reinstalls. The reference implementation is [`pear-chat-identity`](https://github.com/holepunchto/pear-docs/tree/preview/examples/how-to/manage-identity/keet-identity).

{/*
  Shared snippet (content/_snippets/) included via Fumadocs <include> by the chat-app delta how-tos.
  Reminds readers these guides teach portable Pear-end (worker) logic, not desktop-specific code.
  See: https://www.fumadocs.dev/docs/markdown#include
  */}

<Callout type="info">
  **This guide is about the Pear-end, not the shell.** The code below lives in the Bare [worker](/explanation/workers)—the peer-to-peer logic, not the user interface. Because the Pear-end never imports DOM APIs and never assumes a UI framework, the same worker is portable across **desktop (Electron)**, **mobile (React Native via Bare iOS / Bare Android)**, and **terminal**. The example apps ship an Electron shell, but only the UI half changes per platform—the logic here stays the same. See [Runtime and languages](/explanation/runtime-and-languages) for the cross-platform model and current support.
</Callout>

This is a **delta-only** how-to. The shared scaffold is explained in the [Reshape into a production app](/getting-started/build-a-peer-to-peer-chat/reshape-into-a-production-app) tutorial—read it first.

Before you begin [#before-you-begin]

* A working clone of `pear-chat` (or your own app built from the getting-started path).
* Comfort with [Corestore](/reference/helpers/corestore) and the [Autobase](/reference/building-blocks/autobase)-backed room model.

What changes [#what-changes]

| Layer        | Change                                                                                                                                               |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| Dependencies | Add [`keet-identity-key`](https://www.npmjs.com/package/keet-identity-key) and [`hypercore-crypto`](https://www.npmjs.com/package/hypercore-crypto). |
| Worker       | Generate or load a mnemonic, derive a Keet identity key inside `WorkerTask`, and use it to sign every message.                                       |
| Schema       | Extend the `message` struct so each message carries a `proof` field that ties it to a stable identity.                                               |

The Electron shell, worker transport (plain JSON over a `FramedStream`), and vanilla renderer stay as in the getting-started chat app.

Steps [#steps]

<Steps>
  <Step>
    Add the dependencies [#add-the-dependencies]

    ```bash skip="desktop-gui"
    npm install keet-identity-key hypercore-crypto
    ```
  </Step>

  <Step>
    Persist a mnemonic [#persist-a-mnemonic]

    In `workers/index.js`, resolve the mnemonic before constructing `WorkerTask`. A `--mnemonic` flag wins if supplied (L27); otherwise read `identity-mnemonic.txt` from the app storage directory (L28, L30), and if that file does not exist yet, generate a fresh 24-word phrase with [`keet-identity-key`](https://www.npmjs.com/package/keet-identity-key) (L33). Persist it back (L35) so every subsequent start loads the same identity. Treat the mnemonic file as **sensitive**—do not check it into version control, and back it up the way you would a wallet seed.

    ```js file=<rootDir>/examples/how-to/manage-identity/keet-identity/workers/index.js#L27-L35 title="workers/index.js" lineNumbers {27,28,30,33,35} skip="example-import"
      let mnemonic = cmd.flags.mnemonic
      const mnemonicPath = path.join(appStorage, 'identity-mnemonic.txt')
      if (!mnemonic) {
        mnemonic = await fs.promises.readFile(mnemonicPath, 'utf-8').catch((err) => {
          if (err.code !== 'ENOENT') throw err
        })
        mnemonic = mnemonic || Identity.generateMnemonic()
      }
      await fs.promises.writeFile(mnemonicPath, mnemonic)
    ```
  </Step>

  <Step>
    Derive an identity and attest a device inside WorkerTask [#derive-an-identity-and-attest-a-device-inside-workertask]

    Pass the resolved mnemonic into `WorkerTask` as a constructor argument (`new WorkerTask(pipe, storage, mnemonic, cmd.flags)`). In `workers/worker-task.js`, the constructor stores the mnemonic (L16) and builds a `ChatRoomIdentity` room (L24). In `_open`, load the identity from that mnemonic and bootstrap a per-device key pair the identity attests (L34–L36). Each appended message is signed with the device key via `Identity.attestData` (L49–L50), so the worker stamps every line with a verifiable proof—and `_messages` verifies each proof with `Identity.verify` (L68–L71) before forwarding messages to the renderer. The [`pear-chat-identity`](https://github.com/holepunchto/pear-docs/tree/preview/examples/how-to/manage-identity/keet-identity) example keeps the original storage-namespaced [Autobase](/reference/building-blocks/autobase) (via `ChatRoomIdentity`) but extends the message schema to carry the proof:

    ```js file=<rootDir>/examples/how-to/manage-identity/keet-identity/workers/worker-task.js title="workers/worker-task.js" lineNumbers {16,24,34-36,49-50,68-71} skip="example-import"
    const Corestore = require('corestore')
    const debounce = require('debounceify')
    const crypto = require('hypercore-crypto')
    const Hyperswarm = require('hyperswarm')
    const Identity = require('keet-identity-key')
    const ReadyResource = require('ready-resource')

    const ChatRoomIdentity = require('./chat-room-identity')

    class WorkerTask extends ReadyResource {
      constructor (pipe, storage, mnemonic, opts = {}) {
        super()

        this.pipe = pipe
        this.storage = storage
        this.mnemonic = mnemonic
        this.invite = opts.invite
        this.name = opts.name || `User ${Date.now()}`

        this.store = new Corestore(storage)
        this.swarm = new Hyperswarm()
        this.swarm.on('connection', (conn) => this.store.replicate(conn))

        this.room = new ChatRoomIdentity(this.store, this.swarm, this.invite)
        this.debounceMessages = debounce(() => this._messages())
        this.room.on('update', () => this.debounceMessages())

        this.identity = null
        this.deviceKeyPair = null
        this.deviceProof = null
      }

      async _open () {
        this.identity = await Identity.from({ mnemonic: this.mnemonic })
        this.deviceKeyPair = crypto.keyPair()
        this.deviceProof = await this.identity.bootstrap(this.deviceKeyPair.publicKey)

        await this.store.ready()
        await this.room.ready()

        this.pipe.on('data', async (data) => {
          let message
          try {
            message = JSON.parse(data)
          } catch {
            return
          }
          if (message.type === 'add-message') {
            const proof = Identity.attestData(Buffer.from(message.text), this.deviceKeyPair, this.deviceProof)
            await this.room.addMessage(message.text, proof, { name: this.name, at: Date.now() })
          }
        })
        await this.debounceMessages()

        this.pipe.write(JSON.stringify({ type: 'invite', invite: await this.room.getInvite() }))
      }

      async _close () {
        await this.room.close()
        await this.swarm.destroy()
        await this.store.close()
      }

      async _messages () {
        const messages = await this.room.getMessages()
        messages.sort((a, b) => a.info.at - b.info.at)
        for (const msg of messages) {
          const res = Identity.verify(msg.proof, Buffer.from(msg.text), {
            expectedIdentity: this.identity.identityPublicKey
          })
          msg.info.verified = !!res
        }
        this.pipe.write(JSON.stringify({ type: 'messages', messages }))
      }
    }

    module.exports = WorkerTask
    ```
  </Step>

  <Step>
    Add the identity-aware room [#add-the-identity-aware-room]

    `worker-task.js` now imports `ChatRoomIdentity` instead of the tutorial's `ChatRoom`. Create `workers/chat-room-identity.js` as a copy of the tutorial's [`chat-room.js`](https://github.com/holepunchto/pear-docs/blob/preview/examples/getting-started/pear-chat/workers/chat-room.js) with three changes:

    1. Rename the class to `ChatRoomIdentity` (L11),
    2. Rename its `@pear-chat/*` HyperDB/HyperDispatch collections to `@pear-chat-identity/*` (L111, L114, L117), and
    3. Widen `addMessage` to take and persist a `proof` alongside each message (L149–L153).
       Without this file the worker fails to boot with `MODULE_NOT_FOUND: ./chat-room-identity`:

    ```js file=<rootDir>/examples/how-to/manage-identity/keet-identity/workers/chat-room-identity.js title="workers/chat-room-identity.js" lineNumbers {11,111,114,117,149-153} skip="example-import"
    const Autobase = require('autobase')
    const b4a = require('b4a')
    const BlindPairing = require('blind-pairing')
    const HyperDB = require('hyperdb')
    const ReadyResource = require('ready-resource')
    const z32 = require('z32')

    const ChatDispatch = require('../spec/dispatch')
    const ChatDb = require('../spec/db')

    class ChatRoomIdentity extends ReadyResource {
      constructor (store, swarm, invite) {
        super()

        this.store = store
        this.swarm = swarm
        this.invite = invite

        this.pairing = new BlindPairing(swarm)

        /** @type {{ add: function(string, function(any, { view: HyperDB, base: Autobase })) }} */
        this.router = new ChatDispatch.Router()
        this._setupRouter()

        this.localBase = Autobase.getLocalCore(this.store)
        this.base = null
        this.pairMember = null
      }

      async _open () {
        await this.localBase.ready()
        const localKey = this.localBase.key
        const isEmpty = this.localBase.length === 0

        let key
        let encryptionKey
        if (isEmpty && this.invite) {
          const res = await new Promise((resolve) => {
            this.pairing.addCandidate({
              invite: z32.decode(this.invite),
              userData: localKey,
              onadd: resolve
            })
          })
          key = res.key
          encryptionKey = res.encryptionKey
        }

        // if base is not initialized, key and encryptionKey must be provided
        // if base is already initialized in this store namespace, key and encryptionKey can be omitted
        await this.localBase.close()
        this.base = new Autobase(this.store, key, {
          encrypt: true,
          encryptionKey,
          open: this._openBase.bind(this),
          close: this._closeBase.bind(this),
          apply: this._applyBase.bind(this)
        })

        const writablePromise = new Promise((resolve) => {
          this.base.on('update', () => {
            if (this.base.writable) resolve()
            if (!this.base._interrupting) this.emit('update')
          })
        })
        await this.base.ready()
        this.swarm.join(this.base.discoveryKey)
        if (!this.base.writable) await writablePromise

        this.view.core.download({ start: 0, end: -1 })

        this.pairMember = this.pairing.addMember({
          discoveryKey: this.base.discoveryKey,
          /** @type {function(import('blind-pairing-core').MemberRequest)} */
          onadd: async (request) => {
            const inv = await this.view.findOne('@pear-chat-identity/invites', { id: request.inviteId })
            if (!inv) return
            request.open(inv.publicKey)
            await this.addWriter(request.userData)
            request.confirm({
              key: this.base.key,
              encryptionKey: this.base.encryptionKey
            })
          }
        })
      }

      async _close () {
        await this.pairMember?.close()
        await this.base?.close()
        await this.localBase.close()
        await this.pairing.close()
      }

      _openBase (store) {
        return HyperDB.bee(store.get('view'), ChatDb, { extension: false, autoUpdate: true })
      }

      async _closeBase (view) {
        await view.close()
      }

      async _applyBase (nodes, view, base) {
        for (const node of nodes) {
          await this.router.dispatch(node.value, { view, base })
        }
        await view.flush()
      }

      _setupRouter () {
        this.router.add('@pear-chat-identity/add-writer', async (data, context) => {
          await context.base.addWriter(data.key)
        })
        this.router.add('@pear-chat-identity/add-invite', async (data, context) => {
          await context.view.insert('@pear-chat-identity/invites', data)
        })
        this.router.add('@pear-chat-identity/add-message', async (data, context) => {
          await context.view.insert('@pear-chat-identity/messages', data)
        })
      }

      /** @type {HyperDB} */
      get view () {
        return this.base.view
      }

      async getInvite () {
        const existing = await this.view.findOne('@pear-chat-identity/invites', {})
        if (existing) {
          return z32.encode(existing.invite)
        }
        const { id, invite, publicKey, expires } = BlindPairing.createInvite(this.base.key)
        await this.base.append(
          ChatDispatch.encode('@pear-chat-identity/add-invite', { id, invite, publicKey, expires })
        )
        return z32.encode(invite)
      }

      async addWriter (key) {
        await this.base.append(
          ChatDispatch.encode('@pear-chat-identity/add-writer', { key: b4a.isBuffer(key) ? key : b4a.from(key) })
        )
      }

      async getMessages ({ reverse = true, limit = 100 } = {}) {
        return await this.view.find('@pear-chat-identity/messages', { reverse, limit }).toArray()
      }

      async addMessage (text, proof, info) {
        const id = Math.random().toString(16).slice(2)
        await this.base.append(
          ChatDispatch.encode('@pear-chat-identity/add-message', { id, text, proof, info })
        )
      }
    }

    module.exports = ChatRoomIdentity
    ```
  </Step>

  <Step>
    Extend the schema [#extend-the-schema]

    `chat-room-identity.js` references a `pear-chat-identity` namespace and a new `proof` field, so update `schema.js` to match:

    1. Rename the namespace from `pear-chat` to `pear-chat-identity`,
    2. Add a `proof` field (`type: 'buffer'`) to the `message` struct that feeds the `messages` collection, and
    3. Then regenerate `spec/` from a **clean** directory:

    ```bash skip="desktop-gui"
    rm -rf spec && npm run build:db
    ```

    <Callout type="warning">
      Delete `spec/` before regenerating. The schema generators (`hyperschema`, `hyperdispatch`, `hyperdb`) **merge** into the existing manifests rather than overwriting them, so if you regenerate on top of the old `pear-chat` spec the stale registrations linger alongside the new `pear-chat-identity` ones. Starting from a clean `spec/` keeps only the `pear-chat-identity` namespace.
    </Callout>

    `ChatRoomIdentity.addMessage` then stores the `proof` alongside each message. `_messages` verifies each one with `Identity.verify(msg.proof, Buffer.from(msg.text), { expectedIdentity: this.identity.identityPublicKey })`, so anyone replicating the room can confirm which identity authored each line—across reinstalls and across machines, since the same mnemonic always yields the same identity.
  </Step>

  <Step>
    Surface the identity in the UI [#surface-the-identity-in-the-ui]

    The worker already verifies every message in `_messages` and stamps `msg.info.verified` (step 3), and that boolean rides along with each message in the same `{ type: 'messages', messages }` JSON payload the renderer already receives. So the renderer needs **no new message type**—it just reads the extra field.

    In `renderer/app.js`, each message row reads `message.info?.verified` (L43) and renders a verified/unverified badge next to the sender's name (L44–L47), then appends it to the row's metadata line (L53):

    ```js file=<rootDir>/examples/how-to/manage-identity/keet-identity/renderer/app.js#L43-L54 title="renderer/app.js" lineNumbers {43-47,53} skip="example-import"
        const verified = message.info?.verified
        const badge = document.createElement('span')
        badge.className = `text-[10px] ${verified ? 'text-emerald-400' : 'text-rose-400'}`
        badge.title = verified ? 'Signature verified' : 'Signature invalid'
        badge.textContent = verified ? '● verified' : '○ unverified'

        const time = document.createElement('span')
        time.className = 'ml-auto text-xs text-neutral-500'
        time.textContent = new Date(message.info?.at).toLocaleTimeString()

        meta.append(name, badge, time)

    ```

    The badge turns green only when the proof on that message validates against the identity that authored it—so a peer replicating the room can see, per line, which messages are provably from a given identity across reinstalls and devices.
  </Step>
</Steps>

Run it [#run-it]

```bash skip="desktop-gui"
npm run build
npm start -- --storage /tmp/identity-user1 --name user1
```

In development, `electron/main.js` namespaces `--storage <dir>` by your app's `productName` (from `package.json`—it's `PearChat` if you're building on top of the getting-started app) and the worker writes into an `app-storage` subdirectory. So with `--storage /tmp/identity-user1` the files land at `/tmp/identity-user1/<productName>/app-storage/`:

* `…/app-storage/corestore/`—the [Hypercore](/reference/building-blocks/hypercore) data
* `…/app-storage/identity-mnemonic.txt`—the mnemonic, a sibling of `corestore/`

The `app-storage` folder only appears once the app worker has run (the [`pear-runtime`](/reference/pear/runtime) folder next to it is the separate updater store). The exact path is easiest to copy from the terminal: the worker logs a `Storage: …/app-storage/corestore` line on startup, and the mnemonic sits next to that `corestore/` directory.

Quit the app, blow away the [Corestore](/reference/helpers/corestore) but **keep `identity-mnemonic.txt`** (substitute your own `productName` for `<productName>`):

```bash skip="desktop-gui"
rm -rf /tmp/identity-user1/<productName>/app-storage/corestore
npm start -- --storage /tmp/identity-user1 --name user1
```

user1's identity key is unchanged. Copy `identity-mnemonic.txt` into another machine's matching `app-storage` directory and the same identity follows there.

Where to go next [#where-to-go-next]

* [Create a portable identity with Keet identity keys](/how-to/manage-identity/create-a-portable-identity-with-keet-identity-key)—the Pear/Bare identity primitive behind this app, with no UI.
* [Connect two peers by key with HyperDHT](/how-to/connect-to-peers/connect-two-peers-by-key-with-hyperdht)—once you have an identity key, you can dial it directly.
* [Add blind peering to a chat app](/how-to/blind-peering/add-blind-peering-to-a-chat-app)—keep the room reachable while the identity-holding device is offline.
* [Workers](/explanation/workers)—why the identity lives in the worker, not the renderer.


# Create a portable identity with Keet identity keys



<Callout type="info">
  **This guide focuses on the Pear/Bare logic.** It shows [`keet-identity-key`](https://www.npmjs.com/package/keet-identity-key) on its own—no Electron, no UI. For the same identity wired into a full desktop chat app, see the worked example [`pear-chat-identity`](https://github.com/holepunchto/pear-docs/tree/preview/examples/how-to/manage-identity/keet-identity) and its walkthrough, [Add Keet identity to a chat app](/how-to/manage-identity/add-keet-identity-to-a-chat-app).
</Callout>

A [Hypercore](/reference/building-blocks/hypercore) key identifies a *log*, not a *person*.
[`keet-identity-key`](https://www.npmjs.com/package/keet-identity-key) gives you a **portable identity**: a key derived from a 24-word mnemonic that stays the same across devices and reinstalls.
Each device generates its own throwaway key pair, which the identity **attests**—so you can sign data on any device and anyone can verify it was authored by the same person, without ever copying the identity's secret onto that device.

Without the identity, you would need to share a secret between devices to sign data—and that secret would need to be copied onto each device.
With the identity, you can sign data on any device and anyone can verify it was authored by the same person, without ever copying the identity's secret onto that device.

<Callout type="info">
  This is purely Pear-end logic: it runs in a [Bare](/reference/modules/bare-modules) worker (or any Bare/Node process) and never touches a UI.
</Callout>

{/*
  Shared snippet (content/_snippets/) included via Fumadocs <include> by how-tos
  whose Pear-end (worker) logic works with EITHER boilerplate (desktop or
  terminal). Carries the cross-platform portability point too, so it REPLACES
  _pear-end-portability-callout on these guides—one orientation callout, not two.
  For frontend-specific how-tos, use _frontend-template-callout.mdx instead.
  See: https://www.fumadocs.dev/docs/markdown#include
  */}

<Callout type="info">
  **Pear-end logic—start from a boilerplate.** The code in this guide lives in the Bare [worker](/explanation/workers): peer-to-peer logic, no UI. The same worker runs unchanged on desktop, terminal, and mobile—only the shell differs (see [Runtime and languages](/explanation/runtime-and-languages)). Start from a boilerplate in [Start from a template](/getting-started/from-a-template)—desktop ([`hello-pear-electron`](/getting-started/from-a-template/start-from-hello-pear-electron)) or terminal ([`hello-pear-bare`](/getting-started/from-a-template/start-from-hello-pear-bare))—and add this capability on top.
</Callout>

The model [#the-model]

| Concept             | What it is                                                                      |
| ------------------- | ------------------------------------------------------------------------------- |
| **Mnemonic**        | 24 words. The root secret—back it up like a wallet seed.                        |
| **Identity**        | Derived from the mnemonic. Its `identityPublicKey` is stable everywhere.        |
| **Device key pair** | A fresh, per-device key. Never leaves the device.                               |
| **Device proof**    | The identity's signature attesting that the device key speaks for it.           |
| **Data proof**      | A signature over a payload, made with the device key, anchored to the identity. |

Add the dependencies [#add-the-dependencies]

```sh skip="install-instruction"
npm install keet-identity-key hypercore-crypto
```

Derive the identity and attest a device [#derive-the-identity-and-attest-a-device]

Generate (or load) a mnemonic (L5), derive the identity from it (L7), then mint a fresh per-device key pair (L11) and bootstrap it—the identity attests the device key and returns a `deviceProof` (L12):

```js file=<rootDir>/examples/how-to/manage-identity/create-a-portable-identity-with-keet-identity-key/index.js#L1-L12 title="index.js" lineNumbers {5,7,11-12} skip="example-import"
import Identity from 'keet-identity-key'
import crypto from 'hypercore-crypto'

// Generate once and persist it somewhere safe (treat it like a wallet seed).
const mnemonic = Identity.generateMnemonic()

const identity = await Identity.from({ mnemonic })
// identity.identityPublicKey is the same on every device that loads this mnemonic.

// Each device gets its own ephemeral key pair, attested by the identity.
const deviceKeyPair = crypto.keyPair()
const deviceProof = await identity.bootstrap(deviceKeyPair.publicKey)
```

Persist the mnemonic, not the device key—a new device re-derives the identity from the same mnemonic and bootstraps a fresh device key of its own.

Sign data [#sign-data]

Take a payload (L15) and attest it with the device key. The resulting proof (L16) carries the chain back to the identity:

```js file=<rootDir>/examples/how-to/manage-identity/create-a-portable-identity-with-keet-identity-key/index.js#L15-L16 title="index.js" lineNumbers {15-16} skip="example-import"
const payload = Buffer.from('hello from this device')
const proof = Identity.attestData(payload, deviceKeyPair, deviceProof)
```

Attach `proof` to whatever you append to your [Hypercore](/reference/building-blocks/hypercore)/Autobase alongside the payload.

Verify data [#verify-data]

Any peer replicating the data can verify it was authored by the expected identity—pass the proof, the payload, and the expected `identityPublicKey`, and `verify` returns truthy only for a valid proof (L19–L21). No shared secret needed:

```js file=<rootDir>/examples/how-to/manage-identity/create-a-portable-identity-with-keet-identity-key/index.js#L19-L22 title="index.js" lineNumbers {19-21} skip="example-import"
const ok = Identity.verify(proof, payload, {
  expectedIdentity: identity.identityPublicKey
})
// ok is truthy when the proof is valid for that identity.
```

Because verification only needs the public `identityPublicKey`, you can stamp every message with a proof and let every reader confirm authorship across reinstalls and across machines.

See also [#see-also]

* [Add Keet identity to a chat app](/how-to/manage-identity/add-keet-identity-to-a-chat-app)—this primitive wired into a full desktop chat, stamping every message with a verifiable identity.
* [Connect two peers by key with HyperDHT](/how-to/connect-to-peers/connect-two-peers-by-key-with-hyperdht)—once you have a stable identity key, you can dial it directly.
* [Secretstream](/reference/helpers/secretstream)—the noise-based encrypted transport that authenticates connections by public key.
* [Workers](/explanation/workers)—why identity belongs in the worker, not the renderer.


# Manage identity



import { Cards, Card } from 'fumadocs-ui/components/card'

Recipes for giving users a portable cryptographic identity that outlives any single device.

<Cards>
  <Card href="/how-to/manage-identity/create-a-portable-identity-with-keet-identity-key" title="Create a portable identity with Keet identity keys" description="Derive a portable identity from a mnemonic, attest a per-device key, then sign and verify data with it." />

  <Card href="/how-to/manage-identity/add-keet-identity-to-a-chat-app" title="Add Keet identity to a chat app" description="Anchor a chat user to a portable identity key derived from a mnemonic." />
</Cards>


# Release & distribute your app



import { Cards, Card } from 'fumadocs-ui/components/card'

Everything for shipping a Pear app to users and keeping it updated over the air. For the conceptual picture behind the flow, see [Release pipeline](/explanation/deployment-releasing-apps-p2p).

<Cards>
  <Card href="/how-to/operate-an-app/github-actions" title="CI/CD with GitHub Actions" description="Build, sign, and publish a Pear app from CI so shipping is a git push." />

  <Card href="/how-to/operate-an-app/build-and-package" title="Build & package" description="Produce signed distributables, standalone binaries, and app-store packages." />

  <Card href="/how-to/operate-an-app/manual-deployment" title="Manual deployment" description="The full-control stage → provision release flow, plus release troubleshooting." />

  <Card href="/how-to/operate-an-app/multisig" title="Multisig" description="Set up quorum signing and run the production multisig release flow." />

  <Card href="/how-to/operate-an-app/publish-a-changelog" title="Publish a changelog for your app" description="Ship a CHANGELOG.md so users read release notes over peer-to-peer with pear changelog." />

  <Card href="/how-to/operate-an-app/migration" title="Migrate from pear run to Pear OTA" description="Move off the removed pear run runtime and global Pear API onto Pear OTA (pear-runtime)." />
</Cards>


# Migrate from pear run to Pear OTA



import { Steps, Step } from 'fumadocs-ui/components/steps'

<Callout type="warn">
  **`pear run` was removed in Pear v3**, along with the ambient global `Pear` API. An unmigrated app is at its end of life—running `pear run` now exits with an error. Migrate onto **[Pear OTA](/reference/pear/runtime)** (the `pear-runtime` library) to restore updates.
</Callout>

Pear has evolved from a runtime baked into the [Pear CLI](/reference/pear/cli) (`pear run`) into an embeddable runtime library, **[Pear OTA](/reference/pear/runtime)** (the `pear-runtime` module), that integrates into any JavaScript environment. The CLI keeps the deployment commands (`pear stage`, `pear build`, `pear provision`, `pear multisig`); the runtime moves into your own process. This exposes peer-to-peer over-the-air updates and Bare workers to any JS project instead of locking them behind the CLI runtime.

This page is the operator how-to for moving an existing v1 app across. To upgrade the CLI itself from v2, run `npx pear`—see [Install & upgrade](/reference/pear/cli#install) in the CLI reference. For the background on why this changed, see [Runtime and languages](/explanation/runtime-and-languages).

Why this changed [#why-this-changed]

Running every app on a single vendor-signed Electron build made shipping trivial—no OS signing keys, no native compiling—but it turned out to be fragile. The same build served many apps, so it could not be tested against each one before an update; OS updates, virus scanners, and process managers did not expect the non-standard runtime; and Dock/Tray branding was glitchy (a restarted app could show the Pear icon). Splitting the runtime into a library lets the CLI focus on deployment and productionization while your app owns a standard, testable runtime.

What changes [#what-changes]

| `pear run` (removed)                                                    | Pear OTA — `pear-runtime`                                                                                                                         |
| ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| The CLI runtime launches the app and provides the ambient `Pear` global | You import [`pear-runtime`](/reference/pear/runtime) in your own JS entrypoint                                                                    |
| `pear stage` deploys the app contents                                   | [`pear build`](https://github.com/holepunchto/hello-pear-electron#build-deploy-directory) produces a build folder that *is* the deployment folder |
| `global.Pear.worker.run()` spawns workers                               | [`pear-runtime`](/reference/pear/runtime)'s `run()` method (backed by `bare-sidecar`, which bundles the native Bare runtime)                      |

Steps [#steps]

<Steps>
  <Step>
    Start from the boilerplate [#start-from-the-boilerplate]

    The fastest migration is to scaffold a fresh Electron app that already has `pear-runtime` integrated, then move your code into it. Use the [`hello-pear-electron`](https://github.com/holepunchto/hello-pear-electron) boilerplate:

    ```bash skip="manual-walkthrough"
    git clone https://github.com/holepunchto/hello-pear-electron
    cd hello-pear-electron
    npm install
    npm start
    ```

    Move your HTML, JS, CSS, assets, and dependencies into the template's structure. For a guided tour of where each piece goes, see [Start from the hello-pear-electron template](/getting-started/from-a-template/start-from-hello-pear-electron).

    The build directory layout `pear-runtime` expects is produced by the [`pear build`](https://github.com/holepunchto/hello-pear-electron#build-deploy-directory) command (Pear v2.5.0+). Your `package.json` needs an `upgrade` field set to the application's `pear://` link—see [Configuration](/reference/pear/configuration#packagejson).
  </Step>

  <Step>
    Remove the global Pear API [#remove-the-global-pear-api]

    Any code using the `Pear` global must be removed and replaced. For Electron:

    | v1 global `Pear` API       | v2 replacement                                                                   |
    | -------------------------- | -------------------------------------------------------------------------------- |
    | `global.Pear.worker.run()` | [`pear-runtime`](/reference/pear/runtime) `run()`                                |
    | `global.Pear.updates()`    | `pear.updater` `updating`/`updated` events                                       |
    | `global.Pear.exit()`       | `process.exit()`                                                                 |
    | `global.Pear.exitCode`     | `process.exitCode`                                                               |
    | `global.Pear.restart()`    | `app.relaunch()` (Electron)                                                      |
    | `global.Pear.teardown()`   | [`graceful-goodbye`](https://github.com/holepunchto/graceful-goodbye) or similar |
    | `global.Pear.app.args`     | `process.argv.slice(2)`                                                          |
    | `global.Pear.app.applink`  | `require('./package.json').upgrade`                                              |

    The remaining state on `global.Pear.app` (which supersedes the deprecated `global.Pear.config`) is either self-referential (no longer relevant) or link parsing—replace link parsing with direct deep-link protocol handling.
  </Step>

  <Step>
    Deploy with the production flow [#deploy-with-the-production-flow]

    `pear-runtime` pairs with the CLI's deployment commands rather than `pear run`. Use `pear stage` for internal previews, staging, and ephemeral variations—**not** for production. For production rigour, run `pear stage`, [`pear provision`](/reference/pear/cli#pear-provision), and `pear multisig` in sequence:

    * [`pear provision`](/reference/pear/cli#pear-provision) (Pear v2.6.0+) strips interim operations by block-syncing from a source drive, reducing the disk space an app needs. Use it to create a prerelease.
    * [`pear multisig`](/reference/pear/cli#pear-multisig) manages cryptographic cosigning: define the signers, define the quorum, then sign against the prerelease.

    <Callout type="warn">
      Until you migrate to this deployment flow, you risk losing write access if something happens to the machine holding the key—with no way to recover, because there is no way to push an update that switches to a new application link. Unlike all other Pear application drives, a `pear multisig`'d drive is **not** machine-bound, which removes that single point of failure. Use `pear multisig` for any serious production sign-off.
    </Callout>

    See [Deploy your application](/how-to/operate-an-app/manual-deployment/deployment) for the full step-by-step release flow.
  </Step>
</Steps>

See also [#see-also]

* [`pear-runtime` reference](/reference/pear/runtime)—the module that replaces the global `pear run` API.
* [Start from a template](/getting-started/from-a-template)—the desktop and terminal boilerplates to migrate into.
* [Deploy your application](/how-to/operate-an-app/manual-deployment/deployment)—the stage → provision → multisig production flow.
* [Runtime and languages](/explanation/runtime-and-languages)—why the runtime moved out of the CLI and into a library.
* [Configuration](/reference/pear/configuration#packagejson)—where the `upgrade` link and entrypoint are declared.


# Publish a changelog for your app



import { Steps, Step } from 'fumadocs-ui/components/steps'

Any Pear application can ship a `CHANGELOG.md`. Stage it with the rest of your project and your users—or any third party—read your release notes straight from the app drive with [`pear changelog pear://<link>`](/reference/pear/cli#pear-changelog), semver-filtered and pretty-printed. It is the same command that prints the Pear platform's own changelog when you run [`pear changelog`](/reference/pear/cli#pear-changelog) with no link (a known regression makes the no-link form error on some 3.0.x builds—pass an explicit `pear://<link>`, as this guide does throughout).

The changelog lives in the app's [Hyperdrive](/reference/building-blocks/hyperdrive), so it is versioned, replicated, and readable peer-to-peer with no server and no separate publishing step—it travels with every stage and provision.

<Callout type="info">
  This is your **application's own** changelog. It is distinct from the docs-team [Release Overview](/release-overview), which is a curated view of changes across Pear and its modules. To publish release notes for *your* app, follow this guide.
</Callout>

{/*
  Shared snippet (content/_snippets/) included via Fumadocs <include> by guides that
  run `pear` CLI commands, so readers can install the CLI before following the steps.
  See: https://www.fumadocs.dev/docs/markdown#include
  */}

<Callout type="info">
  **Need the `pear` CLI?** Install it from **[install.pears.com](https://install.pears.com)**, or prefix any command below with `npx`. See [Install & upgrade](/reference/pear/cli#install) for details.
</Callout>

How it works [#how-it-works]

`pear changelog` reads a single file at the **root of your app drive**: `/CHANGELOG.md`. Under the hood the [`pear-changelog`](https://github.com/holepunchto/pear-changelog) module parses it into one entry per release, then the command filters by version and prints each entry's notes. The filename and drive-root location are the entire contract—there is no manifest field to set and nothing to register.

<Steps>
  <Step>
    Write CHANGELOG.md [#write-changelogmd]

    Create a `CHANGELOG.md` at your **project root** (next to `package.json`). The format is lightweight:

    * A header block at the top (typically a `# Title`)—everything before the first `##` heading is ignored by the parser. Don't start the file with a `##` heading: the parser only recognizes headings that follow a line, so the first release would be dropped.
    * One release per level-2 heading (`## <version>`), **newest first**.
    * The **first space-separated token of each heading must be a [SemVer](https://semver.org/) version** (a leading `v` is allowed and stripped). Everything under a heading until the next `##` is free-form Markdown.

    ```md file=<rootDir>/examples/how-to/operate-an-app/publish-a-changelog/CHANGELOG.md title="CHANGELOG.md" skip="example-import"
    # Acme Chat Changelog

    ## v1.2.0

    ### Features
    - Group threads with @mentions.

    ### Fixes
    - Reconnect automatically after the sidecar restarts.

    ## v1.1.0

    ### Features
    - Full-text message search.

    ## v1.0.0

    Initial release.
    ```

    <Callout type="warning">
      Keep the version as the **first word** of the heading, followed by a space. Bracketed [Keep a Changelog](https://keepachangelog.com/) headings such as `## [1.2.0] - 2026-01-01` aren't valid versions—those releases drop out of the default view and of any `--of` range (only `--full` still shows them). Use `## v1.2.0` or `## 1.2.0` instead. You can still add a date after the version, for example, `## v1.2.0 — 2026-01-01`.
    </Callout>
  </Step>

  <Step>
    Check the format locally [#check-the-format-locally]

    Before staging, confirm each release parses—with the same [`pear-changelog`](https://github.com/holepunchto/pear-changelog) module the CLI uses. This checks that headings are *recognized*; it does not apply the SemVer filter, so keep the version-format rules above in mind too. Install it as a dev dependency:

    {/* @harness example=publish-changelog step=copy from=examples/how-to/operate-an-app/publish-a-changelog/package.json to=package.json */}

    {/* @harness example=publish-changelog step=copy from=examples/how-to/operate-an-app/publish-a-changelog/CHANGELOG.md to=CHANGELOG.md */}

    ```sh example=publish-changelog step=setup
    npm install --save-dev pear-changelog
    ```

    Create `check-changelog.js` next to the changelog:

    ```js file=<rootDir>/examples/how-to/operate-an-app/publish-a-changelog/check-changelog.js title="check-changelog.js" skip="example-import"
    const { readFileSync } = require('node:fs')
    const { parse } = require('pear-changelog')

    for (const [version] of parse(readFileSync('CHANGELOG.md'))) {
      console.log('release:', version)
    }
    ```

    {/* @harness example=publish-changelog step=copy from=examples/how-to/operate-an-app/publish-a-changelog/check-changelog.js to=check-changelog.js */}

    Run it with Node:

    ```sh example=publish-changelog step=run process=check expect="release: v1.0.0"
    node check-changelog.js
    ```

    {/* @harness example=publish-changelog step=expect process=check contains="release: v1.2.0" */}

    {/* @harness example=publish-changelog step=expect process=check contains="release: v1.1.0" */}

    It prints one line per release the parser found, newest first:

    ```text skip="sample-output"
    release: v1.2.0
    release: v1.1.0
    release: v1.0.0
    ```

    If a release is missing from the output, its heading didn't parse—`pear changelog` won't show it either. The reverse isn't guaranteed: a release can parse here yet still be filtered out by `pear changelog` when its version isn't valid SemVer (see the format warning above).
  </Step>

  <Step>
    Stage and seed it with your app [#stage-and-seed-it-with-your-app]

    A root `CHANGELOG.md` is staged like any other project file—no extra flags. Just make sure it is not excluded by a [`pear.stage.ignore`](/reference/pear/configuration#pear-stage-ignore) entry or dropped by a [`pear.stage.only`](/reference/pear/configuration#pear-stage-only) filter that omits it.

    <Callout type="warning">
      Deploying a desktop app? The deployment directory that [`pear build`](/reference/pear/cli#pear-build) assembles contains only `package.json` and `by-arch/`—your project's `CHANGELOG.md` is not copied in. Add it before staging: `cp CHANGELOG.md ../<name>-<version>/`.
    </Callout>

    ```bash skip="release-flow"
    pear stage --dry-run pear://<link>   # confirm CHANGELOG.md appears in the diff
    pear stage pear://<link>
    ```

    Then [`pear seed`](/reference/pear/cli#pear-seed) the link so peers can fetch it. Once staged, the file is retrievable at `pear://<link>/CHANGELOG.md`. Bump `CHANGELOG.md` in the same commit as your version bump so each release carries its own notes—see [Ship your app](/getting-started/build-a-peer-to-peer-chat/ship) for the full stage → provision flow.
  </Step>

  <Step>
    Read it back [#read-it-back]

    Anyone with the link reads your changelog with:

    ```bash skip="live-swarm"
    pear changelog pear://<link>
    ```

    By default this prints up to the **10 newest releases within the current major version**, each with its full notes, separated by a divider. Tune it with the flags:

    | Flag              | Effect                                                                                                                               |
    | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
    | `--of <semver>`   | Filter to a version range, for example,  `--of 1.x.x` or `--of '>=1.1.0 <2.0.0'`. Defaults to the latest major.                      |
    | `--max`, `-m <n>` | Cap the number of entries shown (default `10`).                                                                                      |
    | `--full`          | Show every release (overrides `--max`); without `--of`, it also widens the range to all majors.                                      |
    | `--json`          | Emit newline-delimited JSON—one tagged object per release plus a final status object. Filter on `"tag": "changelog"` when scripting. |

    ```bash skip="live-swarm"
    pear changelog pear://<link> --of 1.x.x     # only the 1.x releases
    pear changelog pear://<link> --full         # the entire history
    pear changelog pear://<link> --json         # machine-readable
    ```
  </Step>
</Steps>

Use it for release announcements [#use-it-for-release-announcements]

Because the changelog is queryable by version range, it doubles as your source of truth for release notes. When you cut a release, pull the exact entries for the range you shipped and paste them into your announcement:

```bash skip="live-swarm"
pear changelog pear://<link> --of '>=1.1.0'   # everything since 1.1.0
```

Relationship to pear dump [#relationship-to-pear-dump]

`pear changelog` is the structured view of the same file that [`pear dump`](/reference/pear/cli#pear-dump) returns raw:

```bash skip="live-swarm"
pear dump pear://<link>/CHANGELOG.md -   # raw Markdown, unparsed, to stdout
```

Use `pear dump` when you want the exact file bytes; use `pear changelog` when you want it parsed, semver-filtered, and formatted.

See also [#see-also]

* [`pear changelog` reference](/reference/pear/cli#pear-changelog)—the command and its flags.
* [`pear-changelog` module](https://github.com/holepunchto/pear-changelog)—the parser that defines the format, with a `diff()` API for comparing changelogs.
* [Ship your app](/getting-started/build-a-peer-to-peer-chat/ship)—the stage and provision flow the changelog travels with.
* [Deploy your application](/how-to/operate-an-app/manual-deployment/deployment)—the full operator release flow.
* [Configuration](/reference/pear/configuration#pear-stage)—`pear.stage` options that control what gets staged.


# Store and replicate



import { Cards, Card } from 'fumadocs-ui/components/card'

Recipes for persisting data to append-only logs and replicating it across peers.

<Cards>
  <Card href="/how-to/store-and-replicate/replicate-and-persist-with-hypercore" title="Replicate and persist with Hypercore" description="Persist messages and streams with append-only Hypercore replication." />

  <Card href="/how-to/store-and-replicate/work-with-many-hypercores-using-corestore" title="Work with many Hypercores using Corestore" description="Manage and co-replicate many named cores from one Corestore." />

  <Card href="/how-to/store-and-replicate/share-append-only-databases-with-hyperbee" title="Share append-only databases with Hyperbee" description="Set up writer and reader peers with Hyperbee, Corestore, and Hyperswarm." />
</Cards>


# Replicate and persist with Hypercore



{/* <Cards>
  <Card title="Build with Pear - Episode 05: Replication and Persistence" href="https://www.youtube.com/watch?v=5t2mOi0BeDg" external />
  </Cards> */}

In this guide you'll extend the ephemeral chat example in [Connect Many Peers](/how-to/connect-to-peers/connect-to-many-peers-by-topic-with-hyperswarm) by using Hypercore to add two significant new features:

* **Persistence**: The owner of the Hypercore can add messages at any time, and they'll be persisted to disk. Whenever they come online, readers can replicate these messages over [Hyperswarm](/reference/building-blocks/hyperswarm).
* **Many Readers:** New messages added to the Hypercore will be broadcast to interested readers. The owner gives each reader a reading capability ([`core.key`](/reference/building-blocks/hypercore#corekey)) and a corresponding discovery key ([`core.discoveryKey`](/reference/building-blocks/hypercore#corediscoverykey)). The former is used to authorize the reader, ensuring that they have permission to read messages, and the latter is used to discover the owner (and other readers) on the swarm.

[`Hypercore`](/reference/building-blocks/hypercore) is a secure, distributed append-only log. It is built for sharing enormous datasets and streams of real-time data.
It has a secure transport protocol, making it easy to build fast and scalable peer-to-peer applications.

The following example consists of two Pear Terminal Applications: [`writer-app`](#create-the-writer-app) and [`reader-app`](#create-the-reader-app).
When these two applications are opened, two peers are created and connected to each other. Hypercore stores the data entered into the command line.

{/*
  Shared snippet (content/_snippets/) included via Fumadocs <include> by how-tos
  whose Pear-end (worker) logic works with EITHER boilerplate (desktop or
  terminal). Carries the cross-platform portability point too, so it REPLACES
  _pear-end-portability-callout on these guides—one orientation callout, not two.
  For frontend-specific how-tos, use _frontend-template-callout.mdx instead.
  See: https://www.fumadocs.dev/docs/markdown#include
  */}

<Callout type="info">
  **Pear-end logic—start from a boilerplate.** The code in this guide lives in the Bare [worker](/explanation/workers): peer-to-peer logic, no UI. The same worker runs unchanged on desktop, terminal, and mobile—only the shell differs (see [Runtime and languages](/explanation/runtime-and-languages)). Start from a boilerplate in [Start from a template](/getting-started/from-a-template)—desktop ([`hello-pear-electron`](/getting-started/from-a-template/start-from-hello-pear-electron)) or terminal ([`hello-pear-bare`](/getting-started/from-a-template/start-from-hello-pear-bare))—and add this capability on top.
</Callout>

Create the writer app [#create-the-writer-app]

The `writer-app` stores command-line input to a Hypercore instance and replicates that instance to other peers over [Hyperswarm](/reference/building-blocks/hyperswarm).

Create the writer-app directory and add dependencies [#create-the-writer-app-directory-and-add-dependencies]

Create the `writer-app` project with these commands:

```sh example=hypercore-replicate step=setup
mkdir writer-app
cd writer-app
npm init -y
npm pkg set type="module"
npm install bare-path bare-process hypercore hyperswarm b4a
```

This command installs the following dependencies:

* [`bare-path`](https://www.npmjs.com/package/bare-path): A module for working with paths.
* [`bare-process`](https://www.npmjs.com/package/bare-process): A module for working with processes.
* [`hyperswarm`](/reference/building-blocks/hyperswarm): A module for working with Hyperswarm.
* [`hypercore`](/reference/building-blocks/hypercore): A module for working with Hypercore.
* [`b4a`](https://www.npmjs.com/package/b4a): A module for working with buffers.

Add the app logic [#add-the-app-logic]

Create the `writer-app/index.js` file with the following content.

The writer creates a Hyperswarm and destroys it cleanly on `SIGINT` (L8–L9), then opens a local Hypercore backed by `./storage/writer-storage` (L11). `core.key` and `core.discoveryKey` are only available after [`core.ready()`](/reference/building-blocks/hypercore#await-coreready) resolves, so it awaits that before logging the hex-encoded key readers will need (L14–L15). Every chunk of stdin is appended as its own block (L18). Finally it joins the swarm on the `discoveryKey` and replicates the core to each incoming connection (L22–L23):

```javascript file=<rootDir>/examples/how-to/store-and-replicate/replicate-and-persist-with-hypercore/writer-app/index.js title="writer-app/index.js" lineNumbers {8-9,11,14-15,18,22-23} skip="example-import"

import path from 'bare-path'
import process from 'bare-process'
import Hyperswarm from 'hyperswarm'
import Hypercore from 'hypercore'
import b4a from 'b4a'

const swarm = new Hyperswarm()
process.once('SIGINT', () => swarm.destroy().then(() => process.exit(0)))

const core = new Hypercore(path.join('./storage', 'writer-storage'))

// core.key and core.discoveryKey will only be set after core.ready resolves
await core.ready()
console.log('hypercore key:', b4a.toString(core.key, 'hex'))

// Append all stdin data as separate blocks to the core
process.stdin.on('data', (data) => core.append(data))

// core.discoveryKey is *not* a read capability for the core
// It's only used to discover other peers who *might* have the core
swarm.join(core.discoveryKey)
swarm.on('connection', conn => core.replicate(conn))
```

{/* @harness example=hypercore-replicate step=copy from=examples/how-to/store-and-replicate/replicate-and-persist-with-hypercore/writer-app/index.js to=writer-app/index.js */}

Create the reader app [#create-the-reader-app]

The `reader-app` uses Hyperswarm to connect to the writer peer and synchronize its local Hypercore with the writer's Hypercore.

Create the reader-app directory and add dependencies [#create-the-reader-app-directory-and-add-dependencies]

Create the `reader-app` project with these commands:

```sh example=hypercore-replicate step=setup
mkdir reader-app
cd reader-app
npm init -y
npm pkg set type="module"
npm install bare-path bare-process hypercore hyperswarm
```

This command installs the following dependencies:

* [`bare-path`](https://www.npmjs.com/package/bare-path): A module for working with paths.
* [`bare-process`](https://www.npmjs.com/package/bare-process): A module for working with processes.
* [`hyperswarm`](/reference/building-blocks/hyperswarm): A module for working with Hyperswarm.
* [`hypercore`](/reference/building-blocks/hypercore): A module for working with Hypercore.

Add the reader-app logic [#add-the-reader-app-logic]

Create the `reader-app/index.js` file with the following content.

Like the writer, the reader sets up a Hyperswarm with `SIGINT` cleanup (L7–L8). It opens its Hypercore with the writer's key passed on the command line (`Bare.argv[2]`), which makes it a read-only replica, and awaits `core.ready()` (L10–L11). It joins the swarm on the same `discoveryKey` and replicates over each connection (L13–L14), then [`swarm.flush()`](/reference/building-blocks/hyperswarm#await-swarmflush) waits until all discoverable peers are connected (L17) before [`core.update()`](/reference/building-blocks/hypercore#await-coreupdateoptions) pulls the latest length from the writer (L19). It records the current [`core.length`](/reference/building-blocks/hypercore#corelength) and tails the core from that point with a live read stream, logging each new block as it arrives (L21–L24):

```javascript file=<rootDir>/examples/how-to/store-and-replicate/replicate-and-persist-with-hypercore/reader-app/index.js title="reader-app/index.js" lineNumbers {7-8,10-11,13-14,17,19,21-24} skip="example-import"

import path from 'bare-path'
import process from 'bare-process'
import Hyperswarm from 'hyperswarm'
import Hypercore from 'hypercore'

const swarm = new Hyperswarm()
process.once('SIGINT', () => swarm.destroy().then(() => process.exit(0)))

const core = new Hypercore(path.join('./storage', 'reader-storage'), Bare.argv[2])
await core.ready()

swarm.join(core.discoveryKey)
swarm.on('connection', conn => core.replicate(conn))

// swarm.flush() will wait until *all* discoverable peers have been connected to
await swarm.flush()

await core.update()

let position = core.length
console.log(`Skipping ${core.length} earlier blocks...`)
for await (const block of core.createReadStream({ start: core.length, live: true })) {
  console.log(`Block ${position++}: ${block}`)
}
```

{/* @harness example=hypercore-replicate step=copy from=examples/how-to/store-and-replicate/replicate-and-persist-with-hypercore/reader-app/index.js to=reader-app/index.js */}

Run the writer and reader [#run-the-writer-and-reader]

In one terminal, run `writer-app` with `bare`:

```sh example=hypercore-replicate step=run process=writer expect="hypercore key:" capture-key="hypercore key: ([0-9a-f]+)" timeout=20000
bare writer-app
```

The `writer-app` will output the [Hypercore](/reference/building-blocks/hypercore) key.

In another terminal, open the `reader-app` and pass it the key:

```sh example=hypercore-replicate step=run process=reader cmd="bare reader-app ${key}" expect="Skipping" timeout=45000
bare reader-app <SUPPLY THE KEY HERE>
```

{/* @harness example=hypercore-replicate step=send process=writer data="hello\n" delay=2000 */}

{/* @harness example=hypercore-replicate step=expect process=reader contains="hello" timeout=30000 */}

As inputs are made to the terminal running the writer application, outputs should be shown in the terminal running the reader application.

See also [#see-also]

* [Work with many Hypercores using Corestore](/how-to/store-and-replicate/work-with-many-hypercores-using-corestore)—recommended pattern when you need more than one core per process.
* [From append-only logs to files](/explanation/from-logs-to-files)—how Hypercore, Hyperblobs, and [Hyperdrive](/reference/building-blocks/hyperdrive) relate.
* [Share append-only databases with Hyperbee](/how-to/store-and-replicate/share-append-only-databases-with-hyperbee)—key/value store built on Hypercore.
* [Storage and distribution](/explanation/storage-and-distribution)—where these cores live on disk.
* [Hypercore reference](/reference/building-blocks/hypercore)—full API for the append-only log used in this guide.
* [Hyperswarm reference](/reference/building-blocks/hyperswarm)—full API for the topic-based discovery and replication used here.


# Share append-only databases with Hyperbee



[Hyperbee](/reference/building-blocks/hyperbee) is an append-only B-tree based on [Hypercore](/reference/building-blocks/hypercore).
It provides a key/value-store API with methods to insert and get key/value pairs, perform atomic batch insertions, and create sorted iterators.
This guide uses [Corestore](/reference/helpers/corestore) and [Hyperswarm](/reference/building-blocks/hyperswarm) to manage and replicate the underlying core; see [Work with many Hypercores using Corestore](/how-to/store-and-replicate/work-with-many-hypercores-using-corestore) if those concepts are unfamiliar.

{/*
  Shared snippet (content/_snippets/) included via Fumadocs <include> by how-tos
  whose Pear-end (worker) logic works with EITHER boilerplate (desktop or
  terminal). Carries the cross-platform portability point too, so it REPLACES
  _pear-end-portability-callout on these guides—one orientation callout, not two.
  For frontend-specific how-tos, use _frontend-template-callout.mdx instead.
  See: https://www.fumadocs.dev/docs/markdown#include
  */}

<Callout type="info">
  **Pear-end logic—start from a boilerplate.** The code in this guide lives in the Bare [worker](/explanation/workers): peer-to-peer logic, no UI. The same worker runs unchanged on desktop, terminal, and mobile—only the shell differs (see [Runtime and languages](/explanation/runtime-and-languages)). Start from a boilerplate in [Start from a template](/getting-started/from-a-template)—desktop ([`hello-pear-electron`](/getting-started/from-a-template/start-from-hello-pear-electron)) or terminal ([`hello-pear-bare`](/getting-started/from-a-template/start-from-hello-pear-bare))—and add this capability on top.
</Callout>

This guide consists of three applications:

* [`bee-writer-app`](#create-the-bee-writer-app) - stores 1,000 entries from a given dictionary file into a Hyperbee instance.
* [`bee-reader-app`](#create-the-bee-reader-app) - queries the Hyperbee instance for key/value pairs.
* [`core-reader-app`](#inspect-the-hyperbee-as-a-hypercore) - inspects the Hyperbee as a Hypercore.

Create the bee writer app [#create-the-bee-writer-app]

The `bee-writer-app` stores 1,000 entries from a given dictionary file into a Hyperbee instance. The Corestore instance used to create the Hyperbee instance is replicated using Hyperswarm. This enables other peers to replicate their Corestore instance and sparsely (on-demand) download the dictionary data into their local Hyperbee instances.

Create the bee-writer-app directory and add dependencies [#create-the-bee-writer-app-directory-and-add-dependencies]

Start the `bee-writer-app` project with the following commands:

```sh example=hyperbee-kv step=setup
mkdir bee-writer-app
cd bee-writer-app
npm init -y
npm pkg set type="module"
npm install corestore hyperswarm hyperbee b4a bare-fs bare-process
```

This will install the following dependencies:

* [`bare-fs`](https://www.npmjs.com/package/bare-fs): A module for working with file systems.
* [`bare-process`](https://www.npmjs.com/package/bare-process): A module for working with processes.
* [`hyperswarm`](/reference/building-blocks/hyperswarm): A module for working with Hyperswarm.
* [`corestore`](/reference/helpers/corestore): A module for working with Corestore.
* [`hyperbee`](/reference/building-blocks/hyperbee): A module for working with Hyperbee.
* [`b4a`](https://www.npmjs.com/package/b4a): A module for working with buffers.

Add the bee-writer-app logic [#add-the-bee-writer-app-logic]

Create the `bee-writer-app/index.js` file with the following content:

A [Corestore](/reference/helpers/corestore) holds the backing core (L8), and a [Hyperswarm](/reference/building-blocks/hyperswarm) replicates it on every connection (L10–L14). The Hyperbee is built on a named core (L17) with UTF-8 key/value encoding (L20–L23). Once the core is ready (L26) it joins the swarm on the core's discovery key (L29), and the writable key is printed only after the topic is announced to the DHT (L32–L34). On the first run ([`core.length <= 1`](/reference/building-blocks/hypercore#corelength)), the dictionary is loaded and inserted in a single atomic batch (L38–L47); on later runs it just re-seeds the existing data (L48–L50).

```javascript file=<rootDir>/examples/how-to/store-and-replicate/share-append-only-databases-with-hyperbee/bee-writer-app/index.js title="bee-writer-app/index.js" lineNumbers {8,10-14,17,20-23,26,29,32-34,38-47} skip="example-import"
import fsp from 'bare-fs/promises'
import process from 'bare-process'
import Hyperswarm from 'hyperswarm'
import Corestore from 'corestore'
import Hyperbee from 'hyperbee'
import b4a from 'b4a'
// create a corestore instance with the given location
const store = new Corestore('./bee-writer-storage')

const swarm = new Hyperswarm()
process.once('SIGINT', () => swarm.destroy().then(() => process.exit(0)))

// replication of corestore instance
swarm.on('connection', conn => store.replicate(conn))

// creation of Hypercore instance (if not already created)
const core = store.get({ name: 'my-bee-core' })

// creation of Hyperbee instance using the core instance 
const bee = new Hyperbee(core, {
  keyEncoding: 'utf-8',
  valueEncoding: 'utf-8'
})

// wait till all the properties of the hypercore are initialized
await core.ready()

// join a topic
const discovery = swarm.join(core.discoveryKey)

// Only display the key once the Hyperbee has been announced to the DHT
discovery.flushed().then(() => {
  console.log('bee key:', b4a.toString(core.key, 'hex'))
})

// Only import the dictionary the first time this script is executed
// The first block will always be the Hyperbee header block
if (core.length <= 1) {
  console.log('importing dictionary...')
  const dict = JSON.parse(
    await fsp.readFile(new URL('./dict.json', import.meta.url))
  )
  const batch = bee.batch()
  for (const { key, value } of dict) {
    await batch.put(key, value)
  }
  await batch.flush()
} else {
  // Otherwise just seed the previously-imported dictionary
  console.log('seeding dictionary...')
}
```

Save the dict.json file [#save-the-dictjson-file]

Save the `dict.json` file to the `bee-writer-app` directory. The `dict.json` file contains 1,000 dictionary words. This file holds the data that will be stored in the Hyperbee instance, and will be imported into the Hyperbee instance if it is the first time the script is run.

<Callout type="info">
  [Click here to save `dict.json`](/dict.json).
</Callout>

{/* @harness example=hyperbee-kv step=copy from=examples/how-to/store-and-replicate/share-append-only-databases-with-hyperbee/bee-writer-app/index.js to=bee-writer-app/index.js */}

{/* @harness example=hyperbee-kv step=copy from=public/dict.json to=bee-writer-app/dict.json */}

Run the bee-writer-app [#run-the-bee-writer-app]

In one terminal, run `bee-writer-app` with `bare`.

```sh example=hyperbee-kv step=run process=writer expect="bee key:" capture-key="bee key: ([0-9a-f]+)" timeout=60000
bare bee-writer-app
```

Create the bee reader app [#create-the-bee-reader-app]

The `bee-reader-app` creates a `Corestore` instance and replicates it using the `Hyperswarm` instance to the same topic as `bee-writer-app`. On every word entered in the command line, it will download the respective data to the local `Hyperbee` instance.

Create the bee-reader-app directory and add dependencies [#create-the-bee-reader-app-directory-and-add-dependencies]

Create the `bee-reader-app` project with the following commands:

```sh example=hyperbee-kv step=setup
mkdir bee-reader-app
cd bee-reader-app
npm init -y
npm pkg set type="module"
npm install corestore hyperswarm hyperbee b4a bare-pipe bare-process
```

This will install the following dependencies:

* [`bare-process`](https://www.npmjs.com/package/bare-process): A module for working with processes.
* [`hyperswarm`](/reference/building-blocks/hyperswarm): A module for working with Hyperswarm.
* [`corestore`](/reference/helpers/corestore): A module for working with Corestore.
* [`hyperbee`](/reference/building-blocks/hyperbee): A module for working with Hyperbee.
* [`b4a`](https://www.npmjs.com/package/b4a): A module for working with buffers.

Add the bee-reader-app logic [#add-the-bee-reader-app-logic]

Create the `bee-reader-app/index.js` file with the following content:

The reader takes the writer's public key as a command-line argument (L8–L10) and opens that core through its own [Corestore](/reference/helpers/corestore) (L13), replicated over [Hyperswarm](/reference/building-blocks/hyperswarm) (L15–L19). The core is reopened from the supplied key (L22) and wrapped in a Hyperbee with matching UTF-8 encoding (L25–L28). After `ready()` (L31) it joins the same topic (L37) and reads words from stdin (L39): each query calls `bee.get(word)` and prints the value, downloading only the blocks needed to satisfy it (L41–L48).

```javascript file=<rootDir>/examples/how-to/store-and-replicate/share-append-only-databases-with-hyperbee/bee-reader-app/index.js title="bee-reader-app/index.js" lineNumbers {8-10,13,15-19,22,25-28,31,37,39,41-48} skip="example-import"
import process from 'bare-process'
import Hyperswarm from 'hyperswarm'
import Corestore from 'corestore'
import Hyperbee from 'hyperbee'
import Pipe from 'bare-pipe'
import b4a from 'b4a'

const key = Bare.argv[2]

if (!key) throw new Error('provide a key')

// creation of a corestore instance 
const store = new Corestore('./bee-reader-storage')

const swarm = new Hyperswarm()
process.once('SIGINT', () => swarm.destroy().then(() => process.exit(0)))

// replication of the corestore instance on connection with other peers
swarm.on('connection', (conn) => store.replicate(conn))

// create or get the hypercore using the public key supplied as command-line argument
const core = store.get({ key: b4a.from(key, 'hex') })

// create a hyperbee instance using the hypercore instance
const bee = new Hyperbee(core, {
  keyEncoding: 'utf-8',
  valueEncoding: 'utf-8'
})

// wait till the hypercore properties to be initialized
await core.ready()

// logging the public key of the hypercore instance
console.log('core key here is:', core.key.toString('hex'))

// Attempt to connect to peers
swarm.join(core.discoveryKey)

const stdin = new Pipe(0)

stdin.on('data', (data) => {
  const word = data.toString().trim()
  if (!word.length) return
  bee.get(word).then(node => {
    if (!node || !node.value) console.log(`No dictionary entry for ${word}`)
    else console.log(`${word} -> ${node.value}`)
    setImmediate(console.log) // flush hack
  }, console.error)
})
```

{/* @harness example=hyperbee-kv step=copy from=examples/how-to/store-and-replicate/share-append-only-databases-with-hyperbee/bee-reader-app/index.js to=bee-reader-app/index.js */}

Run the bee-reader-app [#run-the-bee-reader-app]

In another terminal, run the `bee-reader-app` with `bare` and pass it the core key from the [`bee-writer-app`](#run-the-bee-writer-app).

```sh example=hyperbee-kv step=run process=reader cmd="bare bee-reader-app ${key}" expect="core key here is:" timeout=45000
bare bee-reader-app <SUPPLY THE KEY HERE>
```

{/* @harness example=hyperbee-kv step=send process=reader data="hello\n" delay=3000 */}

{/* @harness example=hyperbee-kv step=expect process=reader contains="hello" timeout=30000 */}

Query the database by entering a key from the [`dict file`](#save-the-dictjson-file) to lookup into the `bee-reader-app` terminal and hitting return.

<Callout type="info">
  Each application has its own Corestore directory: `./bee-reader-storage` for the reader and `./bee-writer-storage` for the writer.
  Look at the disk space for the `bee-reader-app` storage path after each query and notice that it's significantly smaller than `bee-writer-app`.
  This is because Hyperbee only downloads the [Hypercore](/reference/building-blocks/hypercore) blocks it needs to satisfy each query, a feature called **sparse downloading**.
</Callout>

<Callout type="tip">
  A Hyperbee is itself a Hypercore: its B-tree nodes are stored as Hypercore blocks.
  That's what makes the next section possible—inspecting the same data as a raw Hypercore.
</Callout>

Inspect the Hyperbee as a Hypercore [#inspect-the-hyperbee-as-a-hypercore]

Create the core-reader-app directory and add dependencies [#create-the-core-reader-app-directory-and-add-dependencies]

Finally create the `core-reader-app` project with the following commands:

```sh skip="manual-walkthrough"
mkdir core-reader-app
cd core-reader-app
npm init -y
npm pkg set type="module"
npm install corestore hyperswarm hyperbee b4a bare-process
```

This will install the following dependencies:

* [`bare-process`](https://www.npmjs.com/package/bare-process): A module for working with processes.
* [`hyperswarm`](/reference/building-blocks/hyperswarm): A module for working with Hyperswarm.
* [`corestore`](/reference/helpers/corestore): A module for working with Corestore.
* [`hyperbee`](/reference/building-blocks/hyperbee): A module for working with Hyperbee.
* [`b4a`](https://www.npmjs.com/package/b4a): A module for working with buffers.

Add the core-reader-app logic [#add-the-core-reader-app-logic]

Create the `core-reader-app/index.js` file with the following content:

This app treats the Hyperbee purely as a [Hypercore](/reference/building-blocks/hypercore). It imports Hyperbee's `Node` encoding directly so it can decode tree nodes (L6), takes the writer's key as an argument (L8–L10), and opens the core through a [Corestore](/reference/helpers/corestore) (L13) replicated over [Hyperswarm](/reference/building-blocks/hyperswarm) (L15–L19). The core is reopened from the key and made ready (L22–L24), then joins the topic and waits for the swarm to flush (L27–L28). After pulling the latest metadata with [`core.update()`](/reference/building-blocks/hypercore#await-coreupdateoptions) (L31), it fetches the last block by sequence number (L33–L34) and logs it both raw and decoded through `Node.decode` (L37–L38).

```javascript file=<rootDir>/examples/how-to/store-and-replicate/share-append-only-databases-with-hyperbee/core-reader-app/index.js title="core-reader-app/index.js" lineNumbers {6,8-10,13,15-19,22-24,27-28,31,33-34,37-38} skip="example-import"

import process from 'bare-process'
import Hyperswarm from 'hyperswarm'
import Corestore from 'corestore'
import b4a from 'b4a'
import { Node } from 'hyperbee/lib/messages.js'

const key = Bare.argv[2]

if (!key) throw new Error('provide a key')

// creation of a corestore instance 
const store = new Corestore('./reader-storage')

const swarm = new Hyperswarm()
process.once('SIGINT', () => swarm.destroy().then(() => process.exit(0)))

// replication of the corestore instance on connection with other peers
swarm.on('connection', conn => store.replicate(conn))

// create or get the hypercore using the public key supplied as command-line argument
const core = store.get({ key: b4a.from(key, 'hex') })
// wait till the properties of the hypercore instance are initialized
await core.ready()

// join a topic
swarm.join(core.discoveryKey)
await swarm.flush()

// update the meta-data information of the hypercore instance
await core.update()

const seq = core.length - 1
const lastBlock = await core.get(core.length - 1)

// print the information about the last block or the latest block of the hypercore instance
console.log(`Raw Block ${seq}:`, lastBlock)
console.log(`Decoded Block ${seq}`, Node.decode(lastBlock))
```

Run the core-reader-app [#run-the-core-reader-app]

In another terminal, run the `core-reader-app` with `bare`, passing the core key from the [`bee-writer-app`](#run-the-bee-writer-app):

```sh skip="manual-walkthrough"
bare core-reader-app <SUPPLY KEY HERE>
```

You can now examine the Hyperbee as if it were just a Hypercore.

The `core-reader-app` will continually download and log the last block of the Hypercore containing the Hyperbee data.
Note that these blocks are encoded using Hyperbee's `Node` encoding, which has been imported directly from `Hyperbee` for the purposes of explanation.

See also [#see-also]

* [Create a full peer-to-peer filesystem with Hyperdrive](/how-to/stream-and-share-media/create-a-full-peer-to-peer-filesystem-with-hyperdrive)—a richer data structure built on the same Hyperbee primitive.
* [Work with many Hypercores using Corestore](/how-to/store-and-replicate/work-with-many-hypercores-using-corestore)—the Corestore patterns this guide builds on.
* [Hyperbee reference](/reference/building-blocks/hyperbee)—full API.
* [Corestore reference](/reference/helpers/corestore)—full API for the store used to manage and replicate the backing core.


# Work with many Hypercores using Corestore



An append-only log like Hypercore is powerful on its own, but it's most useful as a building-block for constructing larger data structures, such as databases or filesystems.
Building these data structures often requires many cores, each with different responsibilities. For example, [Hyperdrive](/reference/building-blocks/hyperdrive) uses one core to store file metadata and another to store file contents.

[`Corestore`](/reference/helpers/corestore) is a [Hypercore](/reference/building-blocks/hypercore) factory that makes it easier to manage large collections of named Hypercores. This guide demonstrates a pattern often in use: co-replicating many cores using Corestore, where several 'internal cores' are linked to from a primary core. Only the primary core is announced on the swarm—the keys for the others are recorded inside that core.

In [Replicate and persist with Hypercore](/how-to/store-and-replicate/replicate-and-persist-with-hypercore), only a single Hypercore instance was replicated. But in this guide, you'll replicate a single Corestore instance, which will internally manage the replication of a collection of Hypercores. You'll achieve this with two Pear Terminal Applications: [`multicore-writer-app`](#create-the-multicore-writer-app) and [`multicore-reader-app`](#create-the-multicore-reader-app).

{/*
  Shared snippet (content/_snippets/) included via Fumadocs <include> by the chat-app delta how-tos.
  Reminds readers these guides teach portable Pear-end (worker) logic, not desktop-specific code.
  See: https://www.fumadocs.dev/docs/markdown#include
  */}

<Callout type="info">
  **This guide is about the Pear-end, not the shell.** The code below lives in the Bare [worker](/explanation/workers)—the peer-to-peer logic, not the user interface. Because the Pear-end never imports DOM APIs and never assumes a UI framework, the same worker is portable across **desktop (Electron)**, **mobile (React Native via Bare iOS / Bare Android)**, and **terminal**. The example apps ship an Electron shell, but only the UI half changes per platform—the logic here stays the same. See [Runtime and languages](/explanation/runtime-and-languages) for the cross-platform model and current support.
</Callout>

<Callout type="info">
  **Use one Corestore instance per application.** Multiple Corestores over the same storage cause file-locking errors and duplicate core storage. A single Corestore:

  * Reduces open file handles.
  * Reduces storage by deduping Hypercore storage.
  * Requires only one replication stream per peer connection.
  * Simplifies referring to Hypercores by name.

  If named cores collide across components, namespace them ([`store.namespace('a')`](/reference/helpers/corestore#storenamespacename))—retrieving cores by `key` is unaffected by namespacing.
</Callout>

Create the multicore writer app [#create-the-multicore-writer-app]

Create the multicore writer app directory and add dependencies [#create-the-multicore-writer-app-directory-and-add-dependencies]

Create the `multicore-writer-app` project with these commands:

```sh example=corestore-multi step=setup
mkdir multicore-writer-app
cd multicore-writer-app
npm init -y
npm pkg set type="module"
npm install bare-process corestore hyperswarm b4a
```

This will install the following dependencies:

* [`bare-process`](https://www.npmjs.com/package/bare-process): A module for working with processes.
* [`corestore`](/reference/helpers/corestore): A module for working with Corestore.
* [`hyperswarm`](/reference/building-blocks/hyperswarm): A module for working with Hyperswarm.
* [`b4a`](https://www.npmjs.com/package/b4a): A module for working with buffers.

Add the multicore writer app logic [#add-the-multicore-writer-app-logic]

Create the `multicore-writer-app/index.js` file with the following content:

The `multicore-writer-app` uses a Corestore instance to create three Hypercores, which are then replicated with other peers using `Hyperswarm`:

* One Corestore and one Hyperswarm back the whole app (L7–L8). `core1` bootstraps the system—its first block records the keys of `core2` and `core3` (L22–L26), so a reader only needs `core1`'s key to discover the rest. Writing the bootstrap list before announcing on the swarm ensures `core1.get(0)` resolves as soon as a reader connects.
* The three named cores are created up front (L13–L15); names map to local key pairs and are never sent to readers.
* Only `core1`'s discovery key is announced on the swarm (L32)—`core2` and `core3` ride along because [`store.replicate(conn)`](/reference/helpers/corestore#storereplicateoptsorstream) replicates every loaded core over a single stream (L36).
* The main core key is logged so it can be passed to the [`multicore-reader-app`](#create-the-multicore-reader-app) (L28).
* Terminal input is routed by length: short messages append to `core2`, long ones to `core3` (L39–L46).

```javascript file=<rootDir>/examples/how-to/store-and-replicate/work-with-many-hypercores-using-corestore/multicore-writer-app/index.js title="multicore-writer-app/index.js" lineNumbers {7-8,13-15,22-26,28,32,36,39-46} skip="example-import"

import Hyperswarm from 'hyperswarm'
import Corestore from 'corestore'
import b4a from 'b4a'
import process from 'bare-process'

const store = new Corestore('./multicore-writer-storage')
const swarm = new Hyperswarm()
process.once('SIGINT', () => swarm.destroy().then(() => process.exit(0)))

// A name is a purely-local, and maps to a key pair. It's not visible to readers.
// Since a name always corresponds to a key pair, these are all writable
const core1 = store.get({ name: 'core-1', valueEncoding: 'json' })
const core2 = store.get({ name: 'core-2' })
const core3 = store.get({ name: 'core-3' })
await Promise.all([core1.ready(), core2.ready(), core3.ready()])

// Since Corestore does not exchange keys, they need to be exchanged elsewhere.
// Here, we'll record the other keys in the first block of core1. Do this
// *before* announcing on the swarm so that as soon as a reader connects,
// `core1.get(0)` resolves and the bootstrap key list is available.
if (core1.length === 0) {
  await core1.append({
    otherKeys: [core2, core3].map((core) => b4a.toString(core.key, 'hex'))
  })
}

console.log('main core key:', b4a.toString(core1.key, 'hex'))

// Here we'll only join the swarm with the core1's discovery key
// We don't need to announce core2 and core3, because they'll be replicated with core1
swarm.join(core1.discoveryKey)

// Corestore replication internally manages to replicate every loaded core
// Corestore *does not* exchange keys (read capabilities) during replication.
swarm.on('connection', (conn) => store.replicate(conn))

// Record all short messages in core2, and all long ones in core3
process.stdin.on('data', (data) => {
  if (data.length < 5) {
    console.log('appending short data to core2')
    core2.append(data)
  } else {
    console.log('appending long data to core3')
    core3.append(data)
  }
})
```

{/* @harness example=corestore-multi step=copy from=examples/how-to/store-and-replicate/work-with-many-hypercores-using-corestore/multicore-writer-app/index.js to=multicore-writer-app/index.js */}

Create the multicore reader app [#create-the-multicore-reader-app]

The `multicore-reader-app` connects to the previous peer with `Hyperswarm` and replicates the local `Corestore` instance to receive the data from it. This requires the copied key to be supplied as an argument when executing the file, which will then be used to create a core with the same public key as the other peer (that is, the same discovery key for both the reader and writer peers).

Create the multicore reader app directory and add dependencies [#create-the-multicore-reader-app-directory-and-add-dependencies]

Create the `multicore-reader-app` project with these commands:

```sh example=corestore-multi step=setup
mkdir multicore-reader-app
cd multicore-reader-app
npm init -y
npm pkg set type="module"
npm install corestore hyperswarm b4a bare-process
```

This will install the following dependencies:

* [`bare-process`](https://www.npmjs.com/package/bare-process): A module for working with processes.
* [`corestore`](/reference/helpers/corestore): A module for working with Corestore.
* [`hyperswarm`](/reference/building-blocks/hyperswarm): A module for working with Hyperswarm.
* [`b4a`](https://www.npmjs.com/package/b4a): A module for working with buffers.

Add the multicore reader app logic [#add-the-multicore-reader-app-logic]

Create the `multicore-reader-app/index.js` file with the following content. The reader takes the writer's main core key as a command-line argument (L6–L8) and opens its own Corestore (L10–L11). On each connection it replicates the whole store (L17), then gets `core1` from the supplied key, joins the swarm on its discovery key, and flushes discovery (L20–L25). [`core.get(0)`](/reference/building-blocks/hypercore#await-coregetindex-options) then blocks until the writer's first block—the bootstrap key list—has actually replicated; unlike [`core.update()`](/reference/building-blocks/hypercore#await-coreupdateoptions) it waits for the data itself, and a timeout surfaces a clear error if the writer is never reachable instead of reading an empty core or hanging (L27–L36). It reads the bootstrap key list from that block (L39) and, for every key, gets the corresponding core and logs each new block as it is appended (L40–L50):

```javascript file=<rootDir>/examples/how-to/store-and-replicate/work-with-many-hypercores-using-corestore/multicore-reader-app/index.js title="multicore-reader-app/index.js" lineNumbers {6-8,10-11,17,20-25,27-36,39,40-50} skip="example-import"
import process from 'bare-process'
import Corestore from 'corestore'
import Hyperswarm from 'hyperswarm'
import b4a from 'b4a'

if (!Bare.argv[2]) throw new Error('provide a key')

const key = b4a.from(Bare.argv[2], 'hex')

const store = new Corestore('./multicore-reader-storage')
await store.ready()

const swarm = new Hyperswarm()
process.once('SIGINT', () => swarm.destroy().then(() => process.exit(0)))

// replication of corestore instance on every connection
swarm.on('connection', (conn) => store.replicate(conn))

// creation/getting of a hypercore instance using the key passed
const core = store.get({ key, valueEncoding: 'json' })
// wait till all the properties of the hypercore instance are initialized
await core.ready()

swarm.join(core.discoveryKey)
await swarm.flush()

// core.get(0) blocks until the writer's first block (the bootstrap key list) has
// replicated from a connected peer — unlike core.update(), it waits for the data
// itself rather than just peer discovery. The timeout surfaces a clear error if
// the writer is never reachable, instead of leaving the reader hanging forever.
let firstBlock
try {
  firstBlock = await core.get(0, { timeout: 30000 })
} catch {
  throw new Error('Could not connect to the writer peer')
}

// read the bootstrap key list (the other core keys) from the first block
const { otherKeys } = firstBlock
for (const key of otherKeys) {
  const core = store.get({ key: b4a.from(key, 'hex') })
  // on every append to the hypercore, 
  // download the latest block of the core and log it to the console
  core.on('append', () => {
    const seq = core.length - 1
    core.get(seq).then(block => {
      console.log(`Block ${seq} in Core ${key}: ${block}`) 
    })
  })
}
```

{/* @harness example=corestore-multi step=copy from=examples/how-to/store-and-replicate/work-with-many-hypercores-using-corestore/multicore-reader-app/index.js to=multicore-reader-app/index.js */}

Run the writer and reader [#run-the-writer-and-reader]

Run the multicore writer app [#run-the-multicore-writer-app]

In one terminal, run `multicore-writer-app` with `bare`.

```sh example=corestore-multi step=run process=writer expect="main core key:" capture-key="main core key: ([0-9a-f]+)" timeout=20000
bare multicore-writer-app
```

The `multicore-writer-app` will output the main core key.

Run the multicore reader app [#run-the-multicore-reader-app]

In another terminal, open the `multicore-reader-app` and pass it the key:

```sh example=corestore-multi step=run process=reader cmd="bare multicore-reader-app ${key}" expect-alive=8000 timeout=45000
bare multicore-reader-app <SUPPLY THE KEY HERE>
```

{/* @harness example=corestore-multi step=send process=writer data="this is a longer message\n" delay=2000 */}

{/* @harness example=corestore-multi step=expect process=reader contains="Block 0 in Core" timeout=30000 */}

As inputs are made to the terminal running the writer application, outputs should be shown in the terminal running the reader application.

See also [#see-also]

* [Share append-only databases with Hyperbee](/how-to/store-and-replicate/share-append-only-databases-with-hyperbee)—key/value store on top of Hypercore.
* [Create a full peer-to-peer filesystem with Hyperdrive](/how-to/stream-and-share-media/create-a-full-peer-to-peer-filesystem-with-hyperdrive)—filesystem on top of two Hypercores.
* [Host multiple rooms in one chat app](/how-to/connect-to-peers/host-multiple-rooms-in-one-chat-app)—this co-replication pattern applied in a full app, where one Corestore backs many rooms.
* [Corestore reference](/reference/helpers/corestore)—full API for the store factory, namespacing, and replication surface used here.
* [Hypercore reference](/reference/building-blocks/hypercore)—full API for the individual append-only log each Corestore session manages.


# Bundle a Bare app



A Bare program ships in one of two shapes depending on where it runs: as an **embeddable bundle** loaded by a [worklet](/how-to/run-on-native/embed-bare-in-react-native) inside a native app, or as a **standalone executable** with no peer dependencies. This guide covers both, plus where native addons fit in.

Embeddable bundle with bare-pack [#embeddable-bundle-with-bare-pack]

[`bare-pack`](/reference/modules/bare-modules) traverses your module graph and produces a single [`bare-bundle`](https://github.com/holepunchto/bare-bundle) with import specifiers pre-resolved and addons and assets embedded. Build one for the platform you're embedding into:

```sh skip="install-instruction"
npm i -g bare-pack
```

```console skip="native-build"
bare-pack --linked --host ios --out app.bundle.mjs app.js
```

Two flags matter for mobile: `--host <platform>[-<arch>[-<environment>]]` targets a specific system (pass it more than once for a combined bundle), and `--linked` makes addons resolve to `linked:` specifiers—required on iOS and Android, which link native code ahead of time rather than loading it from disk at runtime.

Load the result in a worklet by giving `start()` a filename with the `.bundle` extension:

```js skip="snippet-illustration"
import { Worklet } from 'react-native-bare-kit'
import bundle from './app.bundle.mjs'

const worklet = new Worklet()
worklet.start('/app.bundle', bundle)
```

Standalone executable with bare-build [#standalone-executable-with-bare-build]

[`bare-build`](https://github.com/holepunchto/bare-build) packages your code as a native application bundle or a standalone executable for desktop and mobile. It ships portable runtimes for every supported system, so the output runs with no Node.js, Bare, or [Pear CLI](/reference/pear/cli) installed:

```sh skip="install-instruction"
npm i -g bare-build
```

```console skip="native-build"
bare-build \
  --host darwin-arm64 --host darwin-x64 \
  --standalone \
  --identifier com.example.App \
  app.js
```

The output format depends on platform and mode—`--standalone` emits a self-extracting executable (Mach-O on macOS/iOS, ELF on Linux/Android, PE on Windows), while `--package` emits an installer (`.pkg`, `.AppImage`, `.msix`, …).

<Callout type="info">
  The portable runtimes run only Bare's I/O event loop, which suits headless CLIs and services. A native GUI app needs tight integration with the system event loop—pass a native runtime such as `--runtime bare-app-kit/runtime` (macOS) or `--runtime bare-ndk/runtime` (Android) instead.
</Callout>

This is the path the [`hello-pear-bare`](/getting-started/from-a-template/start-from-hello-pear-bare) template wires behind `npm run make`, which detects your host and builds the matching target.

Native addons and prebuilt runtimes [#native-addons-and-prebuilt-runtimes]

Native addons are compiled separately with [`bare-make`](https://github.com/holepunchto/bare-make) (a CMake-based generator using Ninja + Clang); `bare-pack` then embeds the results. To build addons for every platform you ship to, the [Bare native-addon prebuild actions](/reference/ci-and-release/github-actions#bare-native-addon-prebuilds) run `bare-make` across a CI matrix. If you only need the runtime itself, [`bare-runtime`](https://github.com/holepunchto/bare-runtime) provides prebuilt Bare binaries for macOS, iOS, Linux, Android, and Windows.

See also [#see-also]

* [Embed Bare in a React Native app](/how-to/run-on-native/embed-bare-in-react-native)—load the bundle in a worklet.
* [Start from the hello-pear-bare template](/getting-started/from-a-template/start-from-hello-pear-bare)—a terminal app that builds standalone with `bare-build`.
* [Bare modules](/reference/modules/bare-modules)—`bare-pack`, `bare-bundle`, `bare-make`, and the rest of the build tooling.
* [One core, many platforms](/explanation/bare-on-native)—why the embeddable-bundle path exists.


# Embed Bare in a React Native app



import { Steps, Step } from 'fumadocs-ui/components/steps'

This guide runs a [Bare](/explanation/bare-runtime) core inside a React Native app using [`react-native-bare-kit`](/reference/bare/bare-kit), and wires a two-way message channel between the UI and the core. This is the practical version of the pattern described in [One core, many platforms](/explanation/bare-on-native): your peer-to-peer logic lives in the worklet, your UI stays native.

You'll need an existing React Native or Expo project to add this to.

<Steps>
  <Step>
    Install the kit [#install-the-kit]

    ```sh skip="install-instruction"
    npm i react-native-bare-kit b4a
    ```

    For Expo, follow the [`bare-expo`](https://github.com/holepunchto/bare-expo) example, which shows the config-plugin setup; the worklet code below is identical.
  </Step>

  <Step>
    Write the Bare core [#write-the-bare-core]

    The worklet entry script runs on its own thread. It reaches the host through the `BareKit.IPC` channel—an instance of [`Bare.IPC`](/reference/bare/runtime#bareipc). Here it echoes back whatever it receives:

    ```js skip="snippet-illustration"
    // app.js—runs inside the worklet
    const { IPC } = BareKit

    IPC.on('data', (data) => {
      const message = data.toString()
      IPC.write(Buffer.from(`echo: ${message}`))
    })
    ```

    This is ordinary Bare code: it can `require` any [`bare-*` module](/reference/modules/bare-modules) and open a [Hyperswarm](/reference/building-blocks/hyperswarm) or [Corestore](/reference/helpers/corestore) just as it would on the desktop.
  </Step>

  <Step>
    Start the worklet from React Native [#start-the-worklet-from-react-native]

    In your React Native component—for example `App.tsx`, not the worklet's `/app.js`—create a `Worklet`, start it with the core's source, and read and write the `IPC` object it exposes:

    ```js skip="snippet-illustration"
    import { Worklet } from 'react-native-bare-kit'
    import b4a from 'b4a'

    const source = `
    const { IPC } = BareKit
    IPC.on('data', (data) => IPC.write(Buffer.from('echo: ' + data.toString())))
    `

    const worklet = new Worklet()
    worklet.start('/app.js', source)

    const { IPC } = worklet
    IPC.on('data', (data) => console.log(b4a.toString(data)))
    IPC.write(b4a.from('Hello from React Native!'))
    ```

    The worklet honours the Bare [lifecycle](/reference/bare/runtime#lifecycle), so call `worklet.suspend()` and `worklet.resume()` from your app's background/foreground handlers to keep the core in step with the OS.
  </Step>

  <Step>
    Run it [#run-it]

    Build and run on a simulator or device with your usual React Native toolchain. Worklet `console.*` output is written to the system log under the `bare` identifier—view it with the platform's native logging tools (Console.app on iOS, `logcat` on Android).

    ```text skip="sample-output"
    echo: Hello from React Native!
    ```
  </Step>
</Steps>

<Callout type="warn">
  The worklet must stop all active I/O when backgrounded or the OS will force-terminate it. See [Handle app suspension](/how-to/run-on-native/handle-app-suspension) for patterns covering TCP servers, Hyperswarm, timers, and IPC handles.
</Callout>

Next steps [#next-steps]

* Inlining source is fine for a snippet, but real apps ship a prebuilt bundle. See [Bundle a Bare app](/how-to/run-on-native/bundle-a-bare-app) to produce a `.bundle` and load it with `worklet.start('/app.bundle', bundle)`.
* Passing raw bytes gets unwieldy fast. See [Type a native RPC bridge](/how-to/run-on-native/type-a-native-rpc-bridge) to put typed, schema-generated methods on top of this IPC channel.
* For the full Worklet and IPC API, see the [`bare-kit` reference](/reference/bare/bare-kit).


# Handle app suspension



import { Callout } from 'fumadocs-ui/components/callout'

<Callout type="warn">
  Getting suspension wrong is silent: the OS gives the app no warning before it force-terminates it.
  A backgrounded app that leaves an HTTP server listening, a TCP socket open, or a live timer running
  will be killed—usually within a few seconds on iOS and Android.
</Callout>

Mobile operating systems suspend apps when they move to the background. Bare models this explicitly
through its [lifecycle](/reference/bare/runtime#lifecycle):

1. the host calls `Bare.suspend()`, which emits a `suspend` event so your code can stop outstanding work,
2. then the loop drains and emits `idle`,
3. and finally blocks—keeping the process alive but quiet.
4. `Bare.resume()` brings it back.

The problem is step 2. The loop goes `idle` only when it has **no remaining referenced handles**: no open sockets, no listening servers, no active timers, no pending file operations.
If any referenced handle survives the `suspend` event, the loop never emits `idle`, the process never fully suspends, and the OS terminates it without warning when its patience runs out.

<Callout type="info">
  For the state machine behind this, see [Inside Bare](/explanation/bare-runtime#the-lifecycle).
</Callout>

The two patterns [#the-two-patterns]

Every handle you manage falls into one of two categories.

Pattern A — unref() for handles that survive suspension [#pattern-a--unref-for-handles-that-survive-suspension]

Some handles must stay open across a suspend/resume cycle—for example, the IPC channel between a
[bare-kit worklet](/reference/bare/bare-kit) and its host. Calling [`.unref()`](/reference/bare/modules/bare-ipc#unref-this) removes the handle
from the loop's reference count without closing it, so the loop can go idle while the handle stays
alive. Call [`.ref()`](/reference/bare/modules/bare-ipc#ref-this) on `resume` to recount it.

```js skip="snippet-illustration"
const IPC = require('bare-ipc')
const [portA] = IPC.open()
const ipc = portA.connect()

Bare.on('suspend', () => ipc.unref())
Bare.on('resume', () => ipc.ref())
```

Pattern B—close on suspend, recreate on resume [#pattern-bclose-on-suspend-recreate-on-resume]

Most active I/O should not survive suspension. Stop it on `suspend` and start it again on
`resume`. The OS connection timeout is shorter than you might expect—don't rely on connections
surviving while the process is idle.

Examples [#examples]

Stop a bare-tcp server [#stop-a-bare-tcp-server]

`server.close()` stops accepting new connections, but existing connections are still referenced.
Destroy them first, or the loop will not go idle.

```js skip="snippet-illustration"
const net = require('bare-tcp')

let server = null

function startServer () {
  server = net.createServer((socket) => {
    socket.on('data', (data) => socket.write(data)) // echo
  })
  server.listen(3000)
}

startServer()

Bare.on('suspend', () => {
  for (const socket of server.connections) socket.destroy()
  server.close()
  server = null
})

Bare.on('resume', () => startServer())
```

<Callout type="info">
  See [`bare-tcp`](/reference/bare/modules/bare-tcp) for the full server and socket API.
</Callout>

Suspend Hyperswarm [#suspend-hyperswarm]

Each `connection` event gives you a live socket stream that Hyperswarm tracks internally. Rather than
tearing the swarm down, call [`swarm.suspend()`](/reference/building-blocks/hyperswarm#await-swarmsuspend-log---)
to pause its connections, listening server, and discovery, and
[`swarm.resume()`](/reference/building-blocks/hyperswarm#await-swarmresume-log---) to bring them
back—the swarm instance and its joined topics survive the cycle.

```js skip="snippet-illustration"
const Hyperswarm = require('hyperswarm')
const Corestore = require('corestore')

const store = new Corestore('./data')
const topic = Buffer.alloc(32) // your 32-byte topic

const swarm = new Hyperswarm()
swarm.on('connection', (conn) => store.replicate(conn))
swarm.join(topic)

Bare.on('suspend', async () => {
  await swarm.suspend() // pause connections, server, and discovery
  await store.suspend() // flush buffered writes to disk
})

Bare.on('resume', async () => {
  await store.resume()
  await swarm.resume() // reconnect and rejoin discovery
})
```

Suspending the swarm stops the replication streams and DHT socket—the handles it holds in the
loop—while keeping the swarm and its joined topics, so `resume` reconnects without rejoining. The
`store` does not keep the loop referenced while idle, but it may hold buffered writes that have not
yet reached disk. Call [`store.suspend()`](/reference/helpers/corestore#await-storesuspendoptions)
to flush them before the process suspends, and [`store.resume()`](/reference/helpers/corestore#await-storeresume)
on the way back—if the OS force-terminates the app before a flush, recent writes can be lost.

<Callout type="info">
  See [Hyperswarm](/reference/building-blocks/hyperswarm) and [Corestore](/reference/helpers/corestore).
</Callout>

Unref the bare-kit IPC channel [#unref-the-bare-kit-ipc-channel]

The IPC channel between a worklet and its native host must survive suspension so the host can
still send messages (for example, a `resume` instruction). Use [`.unref()`](/reference/bare/modules/bare-ipc#unref-this) / [`.ref()`](/reference/bare/modules/bare-ipc#ref-this) (Pattern A):

```js skip="snippet-illustration"
// worklet entry — runs inside Bare
const { IPC } = BareKit

Bare.on('suspend', () => IPC.unref())
Bare.on('resume', () => IPC.ref())

IPC.on('data', (data) => {
  IPC.write(Buffer.from(`echo: ${data}`))
})
```

<Callout type="info">
  See [`bare-ipc`](/reference/bare/modules/bare-ipc) for the [`.ref()`](/reference/bare/modules/bare-ipc#ref-this) / [`.unref()`](/reference/bare/modules/bare-ipc#unref-this) API, and
  [`bare-kit`](/reference/bare/bare-kit) for the host-side worklet API.
</Callout>

Clear timers [#clear-timers]

Active [`setInterval`](/reference/bare/modules/bare-timers#setinterval) and
[`setTimeout`](/reference/bare/modules/bare-timers#settimeout) callbacks hold a
reference in the event loop just like open sockets. Clear them on `suspend` and restart on `resume`.

```js skip="snippet-illustration"
let heartbeat = null

function startHeartbeat () {
  heartbeat = setInterval(() => sync(), 30_000)
}

startHeartbeat()

Bare.on('suspend', () => {
  clearInterval(heartbeat)
  heartbeat = null
})

Bare.on('resume', () => startHeartbeat())
```

<Callout type="info">
  See [`bare-timers`](/reference/bare/modules/bare-timers) for the full timer API, including
  [`.ref()`](/reference/bare/modules/bare-timers#task) / [`.unref()`](/reference/bare/modules/bare-timers#task)
  for a timer that must keep running across the cycle.
</Callout>

How the host triggers suspension [#how-the-host-triggers-suspension]

On mobile, the embedder calls [`bare_suspend()`](/reference/bare/runtime#lifecycle) and [`bare_resume()`](/reference/bare/runtime#lifecycle) from the C API when the OS
fires its own app-lifecycle callbacks.

<Callout type="info">
  [`react-native-bare-kit`](https://github.com/holepunchto/react-native-bare-kit) subscribes to React Native
  [`AppState`](https://reactnative.dev/docs/appstate) changes and calls `worklet.suspend()` and
  `worklet.resume()` on your behalf. You do not need to wire this up yourself; adding your own
  listeners is redundant but harmless.
</Callout>

If you need explicit control—for example, to coordinate suspension with custom host
logic—you can drive the worklet directly:

```js skip="snippet-illustration"
// React Native host component
import { AppState } from 'react-native'
import { Worklet } from 'react-native-bare-kit'

const worklet = new Worklet()
worklet.start('/app.js', source)

AppState.addEventListener('change', (state) => {
  if (state === 'background') worklet.suspend()
  else if (state === 'active') worklet.resume()
})
```

Whether suspension is triggered by `react-native-bare-kit` or from your own host code, the JavaScript
inside the worklet responds to the resulting [`suspend`](/reference/bare/runtime#events) and
[`resume`](/reference/bare/runtime#events) events via `Bare.on('suspend')` and `Bare.on('resume')`.

<Callout type="info">
  See [Embed Bare in a React Native app](/how-to/run-on-native/embed-bare-in-react-native) for the
  full worklet setup.
</Callout>

***

See also [#see-also]

* [Inside Bare](/explanation/bare-runtime#the-lifecycle)—why the lifecycle model exists and the state machine behind it.
* [Bare runtime API](/reference/bare/runtime#lifecycle)—the full `suspend`, `wakeup`, `idle`, and `resume` event reference.
* [One core, many platforms](/explanation/bare-on-native)—embedding Bare in a native app.
* [Embed Bare in a React Native app](/how-to/run-on-native/embed-bare-in-react-native)—the worklet and IPC setup this page builds on.
* [`bare-kit` reference](/reference/bare/bare-kit)—worklet API and host IPC channel.
* [`bare-tcp`](/reference/bare/modules/bare-tcp)—TCP server and socket.
* [`bare-ipc`](/reference/bare/modules/bare-ipc)—IPC streams and `ref()` / `unref()`.
* [`bare-timers`](/reference/bare/modules/bare-timers)—timer functions and their `ref()` / `unref()`.


# Run on mobile & native



import { Cards, Card } from 'fumadocs-ui/components/card'

Recipes for running Bare peer-to-peer logic inside mobile and native shells.

<Cards>
  <Card href="/how-to/run-on-native/embed-bare-in-react-native" title="Embed Bare in a React Native app" description="Run a Bare worklet from a React Native or Expo app and exchange messages over the bare-kit IPC channel." />

  <Card href="/how-to/run-on-native/type-a-native-rpc-bridge" title="Type a native RPC bridge" description="Replace raw IPC bytes with a typed, schema-generated RPC seam using hyperschema and bare-rpc." />

  <Card href="/how-to/run-on-native/bundle-a-bare-app" title="Bundle a Bare app" description="Package a Bare program as an embeddable bundle or a standalone executable." />

  <Card href="/how-to/run-on-native/handle-app-suspension" title="Handle app suspension" description="Stop active I/O handles cleanly when a Bare process is suspended on mobile." />
</Cards>


# Type a native RPC bridge



import { Steps, Step } from 'fumadocs-ui/components/steps'

Once a [worklet](/how-to/run-on-native/embed-bare-in-react-native) is exchanging bytes with its host, the next problem is structure: framing messages and parsing them by hand on both sides is error-prone, and the two sides drift apart over time. This guide puts a [typed RPC seam](/explanation/bare-on-native#the-typed-rpc-seam) on the channel—methods generated from a single schema—as described in [One core, many platforms](/explanation/bare-on-native).

The pieces: [`hyperschema`](https://github.com/holepunchto/hyperschema) defines the data structures and generates [`compact-encoding`](/reference/helpers/compact-encoding) codecs; [`bare-rpc`](/reference/modules/bare-modules) frames requests and replies over the IPC stream.

<Steps>
  <Step>
    Install the tools [#install-the-tools]

    ```sh skip="install-instruction"
    npm i hyperschema bare-rpc compact-encoding
    ```
  </Step>

  <Step>
    Define a schema [#define-a-schema]

    Register your structures on a namespace. Because schemas are versioned and append-only, you can add optional fields later without breaking older peers:

    ```js skip="snippet-illustration"
    // build-schema.js
    const Hyperschema = require('hyperschema')

    const schema = Hyperschema.from('./schema')
    const ns = schema.namespace('app')

    ns.register({
      name: 'message',
      fields: [
        { name: 'id', type: 'uint', required: true },
        { name: 'text', type: 'string' }
      ]
    })

    Hyperschema.toDisk(schema)
    ```

    Running this writes a `schema.json` (for versioning) and a generated `index.js` of `compact-encoding` definitions you resolve by name and version:

    ```js skip="snippet-illustration"
    const c = require('compact-encoding')
    const { resolveStruct } = require('./schema')

    const message = resolveStruct('@app/message', 1)
    const bytes = c.encode(message, { id: 1, text: 'hello' })
    ```

    To generate wire-compatible Swift types for an iOS shell, run the Swift toolchain (`hyperschema-swift`, `compact-encoding-swift`) against the same schema; for the C and Kotlin paths, see [One core, many platforms](/explanation/bare-on-native).
  </Step>

  <Step>
    Frame calls with bare-rpc [#frame-calls-with-bare-rpc]

    Give each method a unique command number. In the worklet (the core), construct an `RPC` over the `BareKit.IPC` stream and handle incoming requests:

    ```js skip="snippet-illustration"
    // inside the worklet
    import RPC from 'bare-rpc'
    import c from 'compact-encoding'
    import { resolveStruct } from './schema'

    const SEND_MESSAGE = 1
    const message = resolveStruct('@app/message', 1)
    const { IPC } = BareKit

    const rpc = new RPC(IPC, (req) => {
      if (req.command === SEND_MESSAGE) {
        const { text } = c.decode(message, req.data)
        console.log('received:', text)
        req.reply('ok')
      }
    })
    ```

    On the host side, construct an `RPC` over the worklet's IPC and send a request:

    ```js skip="snippet-illustration"
    // in the React Native host
    import RPC from 'bare-rpc'
    import c from 'compact-encoding'

    const rpc = new RPC(worklet.IPC)

    const req = rpc.request(SEND_MESSAGE)
    req.send(c.encode(message, { id: 1, text: 'hello' }))

    const reply = await req.reply()
    console.log(reply.toString()) // ok
    ```

    A Swift shell does the same through the generated `HRPC` class and a small transport delegate that forwards bytes to and from the worklet—no hand-written parsing.
  </Step>

  <Step>
    Stream when one message isn't enough [#stream-when-one-message-isnt-enough]

    For more than request/response, `bare-rpc` exposes streams on a request—`req.createRequestStream()` and `req.createResponseStream()`—covering the five patterns the seam supports: unary, send-only events, response-stream, request-stream, and duplex.

    ```js skip="snippet-illustration"
    const req = rpc.request(SUBSCRIBE)
    const updates = req.createResponseStream()
    for await (const chunk of updates) {
      // handle each streamed update
    }
    ```
  </Step>
</Steps>

See also [#see-also]

* [One core, many platforms](/explanation/bare-on-native)—the architecture and the Swift/Android codegen story.
* [`bare-kit` reference](/reference/bare/bare-kit)—the IPC channel this RPC rides on.
* [Compact encoding](/reference/helpers/compact-encoding)—the codec `hyperschema` generates.
* [Embed Bare in a React Native app](/how-to/run-on-native/embed-bare-in-react-native)—the worklet this seam connects to.


# Back up photos in a peer-to-peer app



import { Steps, Step } from 'fumadocs-ui/components/steps'

This guide shows you how to **back up photos peer-to-peer** by adapting the [`hello-pear-electron`](https://github.com/holepunchto/hello-pear-electron) scaffold to decode local images with [`bare-ffmpeg`](https://www.npmjs.com/package/bare-ffmpeg)/[`bare-media`](https://www.npmjs.com/package/bare-media) and push them into a [Hyperblobs](https://www.npmjs.com/package/hyperblobs) store. The reference implementation is [`pear-photo-backup`](https://github.com/holepunchto/pear-docs/tree/preview/examples/how-to/stream-and-share-media/photo-backup).

{/*
  Shared snippet (content/_snippets/) included via Fumadocs <include> by how-tos
  that have a frontend (UI), so they build on the desktop boilerplate. Carries a
  short portability nod too, so it REPLACES _pear-end-portability-callout on these
  guides—one orientation callout, not two. For how-tos whose logic works with
  either template, use _from-a-template-callout.mdx instead.
  See: https://www.fumadocs.dev/docs/markdown#include
  */}

<Callout type="info">
  **Start from the desktop boilerplate.** This guide has a frontend, so it builds on [`hello-pear-electron`](/getting-started/from-a-template/start-from-hello-pear-electron)—the renderer, preload bridge, and Bare [worker](/explanation/workers) it extends. Read [Start from the hello-pear-electron template](/getting-started/from-a-template/start-from-hello-pear-electron) first. The Pear-end logic itself is portable—only the UI is desktop-specific (see [Runtime and languages](/explanation/runtime-and-languages)); the terminal template [`hello-pear-bare`](/getting-started/from-a-template/start-from-hello-pear-bare) has no UI layer. See all starting points in [Start from a template](/getting-started/from-a-template).
</Callout>

* [Stream a live camera in a peer-to-peer app](/how-to/stream-and-share-media/stream-a-live-camera-in-a-peer-to-peer-app)—the sibling how-to that establishes the same Hyperblobs + blob-server pattern for live frames.

Before you begin [#before-you-begin]

* A working clone of `hello-pear-electron` (or your own app built from the getting-started path).
* Comfort with [Hyperblobs](https://www.npmjs.com/package/hyperblobs) and the [Bare](/explanation/runtime-and-languages) native module set.

What changes [#what-changes]

| Layer            | Change                                                                                                                                                                                                                                                                                                                                                                                                              |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Dependencies     | Add [`bare-ffmpeg`](https://www.npmjs.com/package/bare-ffmpeg), [`bare-media`](https://www.npmjs.com/package/bare-media), [`get-mime-type`](https://www.npmjs.com/package/get-mime-type), [`hyperblobs`](https://www.npmjs.com/package/hyperblobs), [`hypercore-blob-server`](https://www.npmjs.com/package/hypercore-blob-server), [`hypercore-id-encoding`](https://www.npmjs.com/package/hypercore-id-encoding). |
| Worker           | Store the full file as one Hyperblob and generate a small inline **preview** (a `data:` URL)—`bare-media` for images, `bare-ffmpeg` for video—recorded alongside the blob id in the view.                                                                                                                                                                                                                           |
| Worker transport | Use a JSON-over-pipe control surface: the renderer sends `{ type: 'add-video', path }` and the worker emits `{ type: 'videos', videos }` events whose entries carry a blob-server link plus the inline preview.                                                                                                                                                                                                     |
| Renderer         | Show a grid that renders each entry's inline preview and opens the full blob via its link.                                                                                                                                                                                                                                                                                                                          |

Steps [#steps]

<Steps>
  <Step>
    Add the dependencies [#add-the-dependencies]

    ```bash skip="desktop-gui"
    npm install bare-ffmpeg bare-media get-mime-type hyperblobs hypercore-blob-server hypercore-id-encoding
    ```

    `bare-ffmpeg` and `bare-media` are **Bare** native modules—they ship prebuilt binaries via [`bare-sidecar`](https://www.npmjs.com/package/bare-sidecar) and only work inside the Bare worker, never in Electron's main or renderer.
  </Step>

  <Step>
    Store the file and generate a preview inside the worker [#store-the-file-and-generate-a-preview-inside-the-worker]

    `workers/video-room.js` (`VideoRoom`, shared with the video-stream how-to but extended for images) defines `addVideo` (L181), which checks the MIME type with [`get-mime-type`](https://www.npmjs.com/package/get-mime-type) and rejects anything that is not an image or video (L183–L186). It then streams the full file bytes into a Hyperblobs write stream (L188–L194) and captures the resulting blob id (L195). Only then does it generate a small inline preview—`bare-media` for images, `bare-ffmpeg` for video (L197)—and append the record to the base (L200–L202):

    ```js file=<rootDir>/examples/how-to/stream-and-share-media/photo-backup/workers/video-room.js#L181-L203 title="workers/video-room.js" lineNumbers {181,183-186,188-194,195,197,200-202} skip="example-import"
      async addVideo (filePath, info) {
        const name = path.basename(filePath)
        const type = getMimeType(name)
        if (!(type.startsWith('image/') || type.startsWith('video/'))) {
          throw new Error('Only image/video files are allowed')
        }

        const rs = fs.createReadStream(filePath)
        const ws = this.blobs.createWriteStream()
        await new Promise((resolve, reject) => {
          ws.on('error', reject)
          ws.on('close', resolve)
          rs.pipe(ws)
        })
        const blob = { key: idEnc.normalize(this.blobs.core.key), ...ws.id }

        const preview = type.startsWith('image/') ? await createPreviewImage(filePath) : await createPreviewVideo(filePath)

        const id = Math.random().toString(16).slice(2)
        await this.base.append(
          VideoDispatch.encode('@pear-photo-backup/add-video', { id, name, type, blob, info: { ...info, preview } })
        )
      }
    ```

    The preview is a base64 `data:` URL kept inline in the record's `info`, so the grid can paint immediately without fetching the full blob. Images are resized with `bare-media`: `createPreviewImage` decodes the file, resizes it to a 256×256 bound, and re-encodes it as WebP (L6–L9), then returns the bytes as a base64 `data:` URL (L10):

    ```js file=<rootDir>/examples/how-to/stream-and-share-media/photo-backup/workers/create-preview-image.js title="workers/create-preview-image.js" lineNumbers {6-9,10} skip="example-import"
    const { image } = require('bare-media')

    const MIMETYPE = 'image/webp'

    async function createPreviewImage (filePath) {
      const buffer = await image(filePath)
        .decode()
        .resize({ maxWidth: 256, maxHeight: 256 })
        .encode({ mimetype: MIMETYPE })
      return `data:${MIMETYPE};base64,${buffer.toString('base64')}`
    }

    module.exports = createPreviewImage
    ```

    `workers/create-preview-video.js` is the `bare-ffmpeg` counterpart for video files (a stub in the reference app—wire up `bare-ffmpeg` frame extraction here to generate a video thumbnail). Both preview helpers are worker-side modules (they call `bare-media`/`bare-ffmpeg`), so they live alongside the worker in `workers/`, not in the renderer. Each record stored in the view is `{ id, name, type, blob, info: { preview, ... } }`—small metadata plus a blob id pointing at the full bytes.
  </Step>

  <Step>
    Reuse the standard close order [#reuse-the-standard-close-order]

    Photo backup does not add an interval or any other timer, so `WorkerTask._close` keeps the same chain as hello-pear-electron: room → swarm → store. The room itself closes its blob server and blobs core first (`VideoRoom._close`). The [`graceful-goodbye`](https://www.npmjs.com/package/graceful-goodbye) handler in `workers/index.js` fires it.
  </Step>

  <Step>
    Render a photo grid [#render-a-photo-grid]

    In the renderer, render `<img src={entry.info.preview} loading="lazy">` straight from the inline preview, and open the full-size image (or video) via `entry.info.link`—the blob-server URL the worker attaches in `getVideos`. Use the renderer's drag-and-drop to call `getPathForFile(file)` on each dropped file (exposed by the preload bridge) and write `{ type: 'add-video', path }` over the worker pipe, which the worker forwards to its `addVideo` handler.
  </Step>
</Steps>

Run it [#run-it]

```bash skip="desktop-gui"
npm run build

# host
npm start -- --storage /tmp/photos-host --name host
```

Drag and drop photos into the window. The thumbnails appear in the grid immediately. Quit the host, restart it with the same `--storage` path, and the grid replays from disk.

```bash skip="desktop-gui"
# friend backing up the same album
npm start -- --storage /tmp/photos-friend --name friend --invite <invite>
```

The friend's app replicates the room's Hyperblobs and shows the same grid. Originals are downloaded lazily—only the thumbnails are pulled eagerly.

Where to go next [#where-to-go-next]

* [Store and serve large media with Hyperblobs](/how-to/stream-and-share-media/store-and-serve-large-media-with-hyperblobs)—the Pear/Bare blob primitive behind this app, with no UI.
* [Stream a live camera in a peer-to-peer app](/how-to/stream-and-share-media/stream-a-live-camera-in-a-peer-to-peer-app)—the same Hyperblobs + blob-server pattern for live frames.
* [Stream stored video in a peer-to-peer app](/how-to/stream-and-share-media/stream-stored-video-in-a-peer-to-peer-app)—the same blob mechanics for stored video.
* [Bare modules](/reference/modules/bare-modules)—what `bare-ffmpeg` and `bare-media` ship and why they live in the worker.


# Create a full peer-to-peer filesystem with Hyperdrive



This guide will show you how to create a full peer-to-peer filesystem with Hyperdrive.

[Hyperdrive](/reference/building-blocks/hyperdrive) is a wrapper around two [Hypercores](/reference/building-blocks/hypercore):

* one is a [Hyperbee](/reference/building-blocks/hyperbee) index for storing file metadata, and
* the other is used to store file contents.

In this guide, you will create three Pear Terminal Applications:

* [`drive-writer-app`](#create-the-drive-writer-app) that mirrors a local directory into a Hyperdrive,
* [`drive-reader-app`](#create-the-drive-reader-app) that replicates the Hyperdrive with a reader peer, and
* [`drive-bee-reader-app`](#inspect-the-hyperdrive-as-a-hyperbee) that inspects the Hyperdrive as a Hyperbee

When the writer modifies its drive—adding, removing, or changing files—the reader's local copy updates to match. To do this, you need two additional tools:

* [`MirrorDrive`](/reference/helpers/mirrordrive): the diff-and-sync engine that mirrors one drive into another (used here via `local.mirror(drive)` and [`drive.mirror(local)`](/reference/building-blocks/hyperdrive#drivemirrorout-options)), and
* [`LocalDrive`](/reference/helpers/localdrive): a local filesystem adapter that exposes a Hyperdrive-like interface over a directory on disk.

These tools handle all interactions between Hyperdrives and the local filesystem.

{/*
  Shared snippet (content/_snippets/) included via Fumadocs <include> by the chat-app delta how-tos.
  Reminds readers these guides teach portable Pear-end (worker) logic, not desktop-specific code.
  See: https://www.fumadocs.dev/docs/markdown#include
  */}

<Callout type="info">
  **This guide is about the Pear-end, not the shell.** The code below lives in the Bare [worker](/explanation/workers)—the peer-to-peer logic, not the user interface. Because the Pear-end never imports DOM APIs and never assumes a UI framework, the same worker is portable across **desktop (Electron)**, **mobile (React Native via Bare iOS / Bare Android)**, and **terminal**. The example apps ship an Electron shell, but only the UI half changes per platform—the logic here stays the same. See [Runtime and languages](/explanation/runtime-and-languages) for the cross-platform model and current support.
</Callout>

<Callout type="info">
  **This guide focuses on the Pear/Bare logic**—plain terminal apps, no UI. For the same file-sharing capability wired into a full desktop app with a front end, see [Share files in a peer-to-peer app](/how-to/stream-and-share-media/share-files-in-a-peer-to-peer-app) and its worked example [`pear-file-sharing`](https://github.com/holepunchto/pear-docs/tree/preview/examples/how-to/stream-and-share-media/file-sharing). The drive logic is identical; only the UI half changes.
</Callout>

Create the drive-writer-app [#create-the-drive-writer-app]

Create the drive-writer-app directory and add dependencies [#create-the-drive-writer-app-directory-and-add-dependencies]

Start by creating the `drive-writer-app` project with these commands:

```sh example=hyperdrive-fs step=setup
mkdir drive-writer-app
cd drive-writer-app
npm init -y
npm pkg set type="module"
npm install corestore localdrive hyperswarm hyperdrive debounceify b4a bare-process
```

This will install the following dependencies:

* [`bare-process`](https://www.npmjs.com/package/bare-process): A module for working with processes.
* [`hyperswarm`](/reference/building-blocks/hyperswarm): A module for working with Hyperswarm.
* [`hyperdrive`](/reference/building-blocks/hyperdrive): A module for working with Hyperdrive.
* [`localdrive`](/reference/helpers/localdrive): A module for working with Localdrive.
* [`corestore`](/reference/helpers/corestore): A module for working with Corestore.
* [`debounceify`](https://www.npmjs.com/package/debounceify): A module for debouncing functions.
* [`b4a`](https://www.npmjs.com/package/b4a): A module for working with buffers.

Add the drive-writer-app logic [#add-the-drive-writer-app-logic]

Create the `drive-writer-app/index.js` file with the following content:

```javascript file=<rootDir>/examples/how-to/stream-and-share-media/create-a-full-peer-to-peer-filesystem-with-hyperdrive/drive-writer-app/index.js title="drive-writer-app/index.js" lineNumbers {11-16,19-23,26,31-34,39-42,45-49} skip="example-import"

import process from 'bare-process'
import Hyperswarm from 'hyperswarm'
import Hyperdrive from 'hyperdrive'
import Localdrive from 'localdrive'
import Corestore from 'corestore'
import debounce from 'debounceify'
import b4a from 'b4a'

// create a Corestore instance 
const store = new Corestore('./drive-writer-storage')
const swarm = new Hyperswarm()
process.once('SIGINT', () => swarm.destroy().then(() => process.exit(0)))

// replication of the corestore instance on connection with other peers
swarm.on('connection', conn => store.replicate(conn))

// A local drive provides a Hyperdrive interface to a local directory
const local = new Localdrive('./writer-dir')

// A Hyperdrive takes a Corestore because it needs to create many cores
// One for a file metadata Hyperbee, and one for a content Hypercore
const drive = new Hyperdrive(store)

// wait till the properties of the hyperdrive instance are initialized
await drive.ready()

// Import changes from the local drive into the Hyperdrive
const mirror = debounce(mirrorDrive)

const discovery = swarm.join(drive.discoveryKey)
await discovery.flushed()

console.log('drive key:', b4a.toString(drive.key, 'hex'))

// start the mirroring process (i.e copying) of content from writer-dir to the drive
// whenever something is entered (other than '/n' or Enter )in the command-line
process.stdin.setEncoding('utf-8')
process.stdin.on('data', (data) => {
  if (!data.match('\n')) return
  mirror()
})

// this function copies the contents from writer-dir directory to the drive
async function mirrorDrive () {
  console.log('started mirroring changes from \'./writer-dir\' into the drive...')
  const mirror = local.mirror(drive)
  await mirror.done()
  console.log('finished mirroring:', mirror.count)
}
```

The `drive-writer-app` creates a [`Corestore`](/reference/helpers/corestore) and replicates it over [`Hyperswarm`](/reference/building-blocks/hyperswarm) so other peers can fetch the data (L11–L16). It wraps the local `./writer-dir` directory in a [`Localdrive`](/reference/helpers/localdrive) and creates the [`Hyperdrive`](/reference/building-blocks/hyperdrive) on top of the store (L19–L23), then waits for it to initialize (L26). After joining the swarm on the drive's discovery key, it prints the drive key that [`drive-reader-app`](#create-the-drive-reader-app) will need (L31–L34). Pressing `Enter` in the terminal triggers a debounced mirror (L39–L42), and `mirrorDrive` copies the contents of `./writer-dir` into the drive (L45–L49).

{/* @harness example=hyperdrive-fs step=copy from=examples/how-to/stream-and-share-media/create-a-full-peer-to-peer-filesystem-with-hyperdrive/drive-writer-app/index.js to=drive-writer-app/index.js */}

Run the `drive-writer-app` with:

```sh example=hyperdrive-fs step=run process=writer expect="drive key:" capture-key="drive key: ([0-9a-f]+)" timeout=45000
bare drive-writer-app
```

It outputs a key which will be passed to [`drive-reader-app`](#create-the-drive-reader-app) upon execution.

Create the drive-reader-app [#create-the-drive-reader-app]

Create the drive-reader-app directory and add dependencies [#create-the-drive-reader-app-directory-and-add-dependencies]

Leave the [`drive-writer-app`](#create-the-drive-writer-app) running and in a new terminal create the `drive-reader-app` project with the following commands:

```sh example=hyperdrive-fs step=setup
mkdir drive-reader-app
cd drive-reader-app
npm init -y
npm pkg set type="module"
npm install corestore localdrive hyperswarm hyperdrive debounceify b4a bare-process
```

This will install the following dependencies:

* [`bare-process`](https://www.npmjs.com/package/bare-process): A module for working with processes.
* [`hyperswarm`](/reference/building-blocks/hyperswarm): A module for working with Hyperswarm.
* [`hyperdrive`](/reference/building-blocks/hyperdrive): A module for working with Hyperdrive.
* [`localdrive`](/reference/helpers/localdrive): A module for working with Localdrive.
* [`corestore`](/reference/helpers/corestore): A module for working with Corestore.
* [`debounceify`](https://www.npmjs.com/package/debounceify): A module for debouncing functions.
* [`b4a`](https://www.npmjs.com/package/b4a): A module for working with buffers.

Add the drive-reader-app logic [#add-the-drive-reader-app-logic]

Create the `drive-reader-app/index.js` file with the following content:

```javascript file=<rootDir>/examples/how-to/stream-and-share-media/create-a-full-peer-to-peer-filesystem-with-hyperdrive/drive-reader-app/index.js title="drive-reader-app/index.js" lineNumbers {10-12,15-21,24-27,32-36,39-42,44-48} skip="example-import"

import process from 'bare-process'
import Hyperswarm from 'hyperswarm'
import Hyperdrive from 'hyperdrive'
import Localdrive from 'localdrive'
import Corestore from 'corestore'
import debounce from 'debounceify'
import b4a from 'b4a'

const key = Bare.argv[2]

if (!key) throw new Error('provide a key')

// create a Corestore instance
const store = new Corestore('./drive-reader-storage')

const swarm = new Hyperswarm()
process.once('SIGINT', () => swarm.destroy().then(() => process.exit(0)))

// replication of store on connection with other peers
swarm.on('connection', conn => store.replicate(conn))

// create a local copy of the remote drive
const local = new Localdrive('./reader-dir')

// create a hyperdrive using the public key passed as a command-line argument
const drive = new Hyperdrive(store, b4a.from(key, 'hex'))

// wait till all the properties of the drive are initialized
await drive.ready()

const mirror = debounce(mirrorDrive)

// call the mirror function whenever content gets appended 
// to the Hypercore instance of the hyperdrive
drive.core.on('append', mirror)

// join a topic
swarm.join(drive.discoveryKey, { client: true, server: false })

// start the mirroring process (i.e copying the contents from remote drive to local dir)
mirror()

async function mirrorDrive () {
  console.log('started mirroring remote drive into \'./reader-dir\'...')
  const mirror = drive.mirror(local)
  await mirror.done()
  console.log('finished mirroring:', mirror.count)
}
```

The `drive-reader-app` reads the writer's drive key from the command-line arguments (L10–L12) and replicates a [`Corestore`](/reference/helpers/corestore) over [`Hyperswarm`](/reference/building-blocks/hyperswarm) (L15–L21). It wraps the local `./reader-dir` directory in a [`Localdrive`](/reference/helpers/localdrive) and opens the remote [`Hyperdrive`](/reference/building-blocks/hyperdrive) from that key (L24–L27). It re-runs a debounced mirror whenever new content is appended to the drive's core (L32–L36), joins the swarm as a client and runs the first mirror immediately (L39–L42). `mirrorDrive` copies the contents of the remote drive into `./reader-dir` and logs when each pass completes (L44–L48).

{/* @harness example=hyperdrive-fs step=copy from=examples/how-to/stream-and-share-media/create-a-full-peer-to-peer-filesystem-with-hyperdrive/drive-reader-app/index.js to=drive-reader-app/index.js */}

Run the drive-reader-app [#run-the-drive-reader-app]

Run the `drive-reader-app` with `bare`, passing the key printed by the [`drive-writer-app`](#create-the-drive-writer-app):

```sh example=hyperdrive-fs step=run process=reader cmd="bare drive-reader-app ${key}" expect="started mirroring remote drive" timeout=45000
bare drive-reader-app <SUPPLY_KEY_HERE>
```

`LocalDrive` does not create the directory passed to it until something has been written, so create `writer-dir` (`mkdir writer-dir`) beside the app directories before importing files. The next section walks through a full round trip from `writer-dir` to `reader-dir`.

Just as a [Hyperbee](/reference/building-blocks/hyperbee) is **just** a [Hypercore](/reference/building-blocks/hypercore), a Hyperdrive is **just** a Hyperbee - which is **just** a Hypercore.

Test the filesystem [#test-the-filesystem]

With both apps still running, add, remove, or modify files inside `writer-dir`, then press `Enter` in the writer's terminal to import those local changes into the drive. Observe that the new changes mirror into `reader-dir`.

For example, create one file in the writer directory:

```sh example=hyperdrive-fs step=setup
mkdir -p writer-dir
printf 'hello from hyperdrive\n' > writer-dir/hello.txt
```

{/* @harness example=hyperdrive-fs step=send process=writer data="\n" delay=500 */}

{/* @harness example=hyperdrive-fs step=expect process=writer contains="started mirroring changes from './writer-dir' into the drive..." timeout=45000 */}

Inspect the Hyperdrive as a Hyperbee [#inspect-the-hyperdrive-as-a-hyperbee]

`Hyperdrive` exposes its metadata index as [`drive.db`](/reference/building-blocks/hyperdrive#drivedb), which is the underlying Hyperbee backing the file structure.
You can inspect that Hyperbee directly when you want to see the raw file-entry metadata that [`drive.entry()`](/reference/building-blocks/hyperdrive#await-driveentrypath-options) wraps, or when you want to access the metadata index directly.

Create the drive-bee-reader-app directory and add dependencies [#create-the-drive-bee-reader-app-directory-and-add-dependencies]

In a new terminal, create the `drive-bee-reader-app` project with these commands:

```sh example=hyperdrive-fs step=setup
mkdir drive-bee-reader-app
cd drive-bee-reader-app
npm init -y
npm pkg set type="module"
npm install corestore hyperswarm hyperdrive b4a bare-process
```

This will install the following dependencies:

* [`bare-process`](https://www.npmjs.com/package/bare-process): A module for working with processes.
* [`hyperswarm`](/reference/building-blocks/hyperswarm): A module for working with Hyperswarm.
* [`corestore`](/reference/helpers/corestore): A module for working with Corestore.
* [`hyperdrive`](/reference/building-blocks/hyperdrive): A module for working with Hyperdrive.
* [`b4a`](https://www.npmjs.com/package/b4a): A module for working with buffers.

Add the drive-bee-reader-app logic [#add-the-drive-bee-reader-app-logic]

Create the `drive-bee-reader-app/index.js` file with the following content:

```javascript file=<rootDir>/examples/how-to/stream-and-share-media/create-a-full-peer-to-peer-filesystem-with-hyperdrive/drive-bee-reader-app/index.js title="drive-bee-reader-app/index.js" lineNumbers {8-10,12-17,19-21,24,29-37,39,41-49} skip="example-import"

import process from 'bare-process'
import Hyperswarm from 'hyperswarm'
import Hyperdrive from 'hyperdrive'
import Corestore from 'corestore'
import b4a from 'b4a'

const key = Bare.argv[2]

if (!key) throw new Error('provide a key')

const store = new Corestore('./drive-bee-reader-storage')

const swarm = new Hyperswarm()
process.once('SIGINT', () => swarm.destroy().then(() => process.exit(0)))

swarm.on('connection', conn => store.replicate(conn))

const drive = new Hyperdrive(store, b4a.from(key, 'hex'))
await drive.ready()
await drive.db.ready()

// Hyperdrive stores file metadata in the "files" sub-bee.
const files = drive.db.sub('files', { keyEncoding: 'utf-8' })

const discovery = swarm.join(drive.discoveryKey, { client: true, server: false })
await discovery.flushed()

let dbEntry = null
for (let attempt = 0; attempt < 60; attempt++) {
  await drive.update()
  dbEntry = await files.peek()
  if (dbEntry) break
  await new Promise(resolve => setTimeout(resolve, 500))
}

if (!dbEntry) throw new Error('expected at least one file entry to appear in drive.db')

const driveEntry = await drive.entry(dbEntry.key)

console.log('hyperbee entry:', JSON.stringify({
  key: dbEntry.key,
  value: dbEntry.value
}))

console.log('drive entry:', JSON.stringify({
  key: driveEntry.key,
  value: driveEntry.value
}))

await swarm.destroy()
await drive.close()
```

Like the reader, this app reads the drive key from the command line (L8–L10) and replicates a [`Corestore`](/reference/helpers/corestore) over [`Hyperswarm`](/reference/building-blocks/hyperswarm) (L12–L17). It opens the [`Hyperdrive`](/reference/building-blocks/hyperdrive) and awaits both [`drive.ready()`](/reference/building-blocks/hyperdrive#await-driveready) and `drive.db.ready()` (L19–L21), then reaches into the metadata index directly: file entries live in the `files` sub-[Hyperbee](/reference/building-blocks/hyperbee) (L24). It polls [`drive.update()`](/reference/building-blocks/hyperdrive#await-driveupdateoptions) until the first entry replicates in (L29–L37), looks the same file up through the higher-level `drive.entry()` API (L39), and logs both the raw Hyperbee entry and the `drive.entry()` view side by side (L41–L49).

{/* @harness example=hyperdrive-fs step=copy from=examples/how-to/stream-and-share-media/create-a-full-peer-to-peer-filesystem-with-hyperdrive/drive-bee-reader-app/index.js to=drive-bee-reader-app/index.js */}

Run the drive-bee-reader-app [#run-the-drive-bee-reader-app]

Run the `drive-bee-reader-app` with `bare`, passing the key printed by the [`drive-writer-app`](#create-the-drive-writer-app):

```sh example=hyperdrive-fs step=run process=bee-reader cmd="bare drive-bee-reader-app ${key}" expect="hyperbee entry:" timeout=45000
bare drive-bee-reader-app <SUPPLY_KEY_HERE>
```

See also [#see-also]

* [Share files in a peer-to-peer app](/how-to/stream-and-share-media/share-files-in-a-peer-to-peer-app)—the same Hyperdrive sharing wrapped in a desktop UI.
* [Storage and distribution](/explanation/storage-and-distribution)—where these drives live on disk and how peers receive new versions.
* [Deploy your application](/how-to/operate-an-app/manual-deployment/deployment)—staging and seeding when you're ready to ship.
* [Hyperdrive reference](/reference/building-blocks/hyperdrive)—full API for the distributed filesystem used in this guide.
* [Corestore reference](/reference/helpers/corestore)—full API for the shared storage and replication manager passed to Hyperdrive.
* [Localdrive reference](/reference/helpers/localdrive)—full API for the local filesystem adapter mirrored to and from Hyperdrive.
* [Mirrordrive reference](/reference/helpers/mirrordrive)—full API for the diff-and-sync engine driving `drive.mirror(...)` and `local.mirror(...)` here.


# Stream and share media



import { Cards, Card } from 'fumadocs-ui/components/card'

Recipes for moving files and streaming media directly between peers.

<Cards>
  <Card href="/how-to/stream-and-share-media/create-a-full-peer-to-peer-filesystem-with-hyperdrive" title="Create a full peer-to-peer filesystem with Hyperdrive" description="Mirror local folders into Hyperdrive and replicate with reader peers." />

  <Card href="/how-to/stream-and-share-media/store-and-serve-large-media-with-hyperblobs" title="Store and serve large media with Hyperblobs" description="Store large files as blobs on a Hypercore, replicate over Hyperswarm, and serve them over local HTTP with range requests." />

  <Card href="/how-to/stream-and-share-media/share-files-in-a-peer-to-peer-app" title="Share files in a peer-to-peer app" description="Swap a chat room for a Hyperdrive so peers can publish and fetch files." />

  <Card href="/how-to/stream-and-share-media/back-up-photos-in-a-peer-to-peer-app" title="Back up photos in a peer-to-peer app" description="Decode local photos with bare-ffmpeg/bare-media and push them into a Hyperblobs store." />

  <Card href="/how-to/stream-and-share-media/stream-stored-video-in-a-peer-to-peer-app" title="Stream stored video in a peer-to-peer app" description="Serve stored video over hypercore-blob-server so peers can stream it." />

  <Card href="/how-to/stream-and-share-media/stream-a-live-camera-in-a-peer-to-peer-app" title="Stream a live camera in a peer-to-peer app" description="Chunk live camera frames into Hyperblobs and serve them to peers." />
</Cards>


# Share files in a peer-to-peer app



import { Steps, Step } from 'fumadocs-ui/components/steps'

This guide shows you how to **swap the [`hello-pear-electron`](https://github.com/holepunchto/hello-pear-electron) room for a [Hyperdrive](/reference/building-blocks/hyperdrive)** so peers share files instead of messages. The reference implementation is [`pear-file-sharing`](https://github.com/holepunchto/pear-docs/tree/preview/examples/how-to/stream-and-share-media/file-sharing).

{/*
  Shared snippet (content/_snippets/) included via Fumadocs <include> by how-tos
  that have a frontend (UI), so they build on the desktop boilerplate. Carries a
  short portability nod too, so it REPLACES _pear-end-portability-callout on these
  guides—one orientation callout, not two. For how-tos whose logic works with
  either template, use _from-a-template-callout.mdx instead.
  See: https://www.fumadocs.dev/docs/markdown#include
  */}

<Callout type="info">
  **Start from the desktop boilerplate.** This guide has a frontend, so it builds on [`hello-pear-electron`](/getting-started/from-a-template/start-from-hello-pear-electron)—the renderer, preload bridge, and Bare [worker](/explanation/workers) it extends. Read [Start from the hello-pear-electron template](/getting-started/from-a-template/start-from-hello-pear-electron) first. The Pear-end logic itself is portable—only the UI is desktop-specific (see [Runtime and languages](/explanation/runtime-and-languages)); the terminal template [`hello-pear-bare`](/getting-started/from-a-template/start-from-hello-pear-bare) has no UI layer. See all starting points in [Start from a template](/getting-started/from-a-template).
</Callout>

* [Create a full peer-to-peer filesystem with Hyperdrive](/how-to/stream-and-share-media/create-a-full-peer-to-peer-filesystem-with-hyperdrive)—the building block this guide layers a desktop UI on top of.

Before you begin [#before-you-begin]

* A working clone of `hello-pear-electron` (or your own app built from the getting-started path).
* Familiarity with [Hyperdrive](/reference/building-blocks/hyperdrive) and [Localdrive](/reference/helpers/localdrive).

What changes [#what-changes]

| Layer           | Change                                                                                                                                                                                                                                                                               |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Dependencies    | Add [`hyperdrive`](https://www.npmjs.com/package/hyperdrive), [`localdrive`](https://www.npmjs.com/package/localdrive), and [`hypercore-id-encoding`](https://www.npmjs.com/package/hypercore-id-encoding).                                                                          |
| Worker          | Add a `DriveRoom`: each peer owns a [Hyperdrive](/reference/building-blocks/hyperdrive) mirrored from a local `my-drive` folder, and the [Autobase](/reference/building-blocks/autobase) view tracks the set of drive keys so peers mirror each others' drives into `shared-drives`. |
| Worker teardown | Cancel the mirror/file-list interval timers in `_close` before closing the room → swarm → store.                                                                                                                                                                                     |
| Worker messages | Push a `drives` message (each drive plus its files) and handle an `add-file` message that copies a chosen file into `my-drive`.                                                                                                                                                      |
| Renderer        | Render a per-drive file list with an "add file" picker.                                                                                                                                                                                                                              |

Steps [#steps]

<Steps>
  <Step>
    Add the dependencies [#add-the-dependencies]

    ```bash skip="desktop-gui"
    npm install hyperdrive localdrive hypercore-id-encoding
    ```
  </Step>

  <Step>
    Add a DriveRoom worker [#add-a-driveroom-worker]

    Create `workers/drive-room.js` (`DriveRoom`) by adapting `chat-room.js`. The pairing, [Autobase](/reference/building-blocks/autobase), and writer plumbing stay the same; what changes is the data each peer publishes:

    * Each peer owns one **[Hyperdrive](/reference/building-blocks/hyperdrive)** (`this.myDrive`) backed by a local `my-drive` folder (`this.myLocalDrive`, a [`localdrive`](https://www.npmjs.com/package/localdrive)). `_uploadMyDrive` (L160) publishes the drive key to the Autobase (L162), joins the swarm on it (L163), and mirrors the folder into the Hyperdrive on a 1-second timer (L165–L166), so dropping a file into `my-drive` publishes it to peers.
    * The Autobase view stores just the **set of drive keys** (`@pear-file-sharing/drives`). `_downloadSharedDrives` (L141) replicates every peer's Hyperdrive: it opens a per-key `LocalDrive` under `shared-drives` (L147), reuses `myDrive` or constructs a peer Hyperdrive from the key (L149), mirrors the drive down on every `append` (L152–L153), and joins the swarm on its discovery key (L156).

    ```js file=<rootDir>/examples/how-to/stream-and-share-media/file-sharing/workers/drive-room.js#L141-L167 title="workers/drive-room.js" lineNumbers {141,147,149,152-153,156,160,162-163,165-166} skip="example-import"
      async _downloadSharedDrives () {
        const drives = await this.getDrives()
        await Promise.all(drives.map(async (item) => {
          const key = idEnc.normalize(item.key)
          if (this.drives[key]) return

          const local = new LocalDrive(path.join(this.sharedDrivesPath, key))
          this.localDrives[key] = local
          const drive = key === idEnc.normalize(this.myDrive.key) ? this.myDrive : new Hyperdrive(this.store, item.key)
          this.drives[key] = drive

          const mirror = debounce(() => drive.mirror(local).done())
          drive.core.on('append', () => mirror())

          await drive.ready()
          this.swarm.join(drive.discoveryKey)
        }))
      }

      async _uploadMyDrive () {
        await this.myDrive.ready()
        this.addDrive(this.myDrive.key, { name: this.name })
        this.swarm.join(this.myDrive.discoveryKey)

        const mirror = debounce(() => this.myLocalDrive.mirror(this.myDrive).done())
        this.uploadInterval = setInterval(() => mirror(), 1000)
      }
    ```
  </Step>

  <Step>
    Preserve the clearInterval teardown [#preserve-the-clearinterval-teardown]

    `pear-file-sharing` runs two polling loops: `DriveRoom._uploadMyDrive` mirrors the user's `my-drive` folder into the Hyperdrive, and `WorkerTask` rebuilds the file list for the renderer. Both store their timer handles, and `_close` clears them (L62) before the standard room → swarm → store chain (L63–L65). **Do not drop this**, or shutdown leaks an interval timer:

    ```js file=<rootDir>/examples/how-to/stream-and-share-media/file-sharing/workers/worker-task.js#L61-L66 title="workers/worker-task.js" lineNumbers {62,63-65} skip="example-import"
      async _close () {
        clearInterval(this.intervalFiles)
        await this.room.close()
        await this.swarm.destroy()
        await this.store.close()
      }
    ```

    `DriveRoom._close` does the same for its own `uploadInterval`. The [`graceful-goodbye`](https://www.npmjs.com/package/graceful-goodbye) hook in `workers/index.js` is what fires this on SIGINT / IPC end.
  </Step>

  <Step>
    Surface the drives over the worker pipe [#surface-the-drives-over-the-worker-pipe]

    The worker uses a HyperDispatch for its Autobase, with `add-drive` standing in for `add-message` (`schema.js` registers the `drive`/`drives` schemas and the `add-drive` dispatch). Regenerate `spec/`:

    ```bash skip="desktop-gui"
    npm run build:db
    ```

    The worker–renderer transport stays the plain-JSON-over-[`framed-stream`](https://www.npmjs.com/package/framed-stream) pipe in hello-pear-electron—no HRPC. `WorkerTask._open` wires both ends: it parses each plain-JSON message off the pipe (L44–L50), and an `add-file` message copies the chosen file into the `my-drive` folder (L51–L53) where `_uploadMyDrive` picks it up. A 1-second interval starts `_drives` (L56), and the initial invite is written back to the renderer (L58):

    ```js file=<rootDir>/examples/how-to/stream-and-share-media/file-sharing/workers/worker-task.js#L37-L59 title="workers/worker-task.js" lineNumbers {44-50,51-53,56,58} skip="example-import"
      async _open () {
        await this.store.ready()
        await this.room.ready()

        await fs.promises.mkdir(this.myDrivePath, { recursive: true })
        await fs.promises.mkdir(this.sharedDrivesPath, { recursive: true })

        this.pipe.on('data', async (data) => {
          let message
          try {
            message = JSON.parse(data)
          } catch {
            return
          }
          if (message.type === 'add-file') {
            await fs.promises.copyFile(message.uri, path.join(this.myDrivePath, message.name))
          }
        })

        this.intervalFiles = setInterval(() => this._drives(), 1000)

        this.pipe.write(JSON.stringify({ type: 'invite', invite: await this.room.getInvite() }))
      }
    ```

    `_drives` reads each mirrored drive folder off disk and writes the full list—drive name plus its files as `file://` URIs—back to the renderer as a `drives` message. It walks every known drive (L69), reads its mirrored folder recursively (L74–L77), builds the drive plus its files as `file://` URIs (L84–L85), pins the user's own drive first (L89–L92), and writes the `drives` message over the pipe (L94):

    ```js file=<rootDir>/examples/how-to/stream-and-share-media/file-sharing/workers/worker-task.js#L68-L95 title="workers/worker-task.js" lineNumbers {69,74-77,84-85,89-92,94} skip="example-import"
      async _drives () {
        const rawDrives = await this.room.getDrives()
        const drives = await Promise.all(rawDrives.map(async (drive) => {
          const key = idEnc.normalize(drive.key)
          const dir = path.join(this.sharedDrivesPath, key)
          await fs.promises.mkdir(dir, { recursive: true })
          const files = await fs.promises.readdir(dir, { recursive: true }).catch((err) => {
            if (err.code === 'ENOENT') return []
            throw err
          })
          const isMyDrive = key === idEnc.normalize(this.room.myDrive.key)
          return {
            ...drive,
            info: {
              ...drive.info,
              isMyDrive,
              uri: `file://${isMyDrive ? this.myDrivePath : dir}`,
              files: files.map((name) => ({ name, uri: `file://${path.join(dir, name)}` }))
            }
          }
        }))
        drives.sort((a, b) => {
          if (a.info.isMyDrive && !b.info.isMyDrive) return -1
          if (!a.info.isMyDrive && b.info.isMyDrive) return 1
          return a.info.name.localeCompare(b.info.name)
        })
        this.pipe.write(JSON.stringify({ type: 'drives', drives }))
      }
    ```
  </Step>

  <Step>
    Update the renderer [#update-the-renderer]

    In the vanilla `renderer/app.js`, render a list grouped by drive—each peer's drive and its files, with the user's own drive pinned first. Add a drag-and-drop zone plus a "browse" file picker that send an `add-file` message over the worker pipe. Use `bridge.getPathForFile(file)` (L35)—backed by `webUtils.getPathForFile`, already exposed in `electron/preload.js` of hello-pear-electron—to turn each picked file into a local path the worker can copy, then send it as an `add-file` message (L36). `renderDrives` builds one card per drive and links each file to its `file://` URI (L43–L100). The drop zone (L111–L115) and the "browse" picker (L117–L120) both feed `addFiles`, and incoming worker messages route `drives`/`invite` events to the renderer (L131–L132):

    ```js file=<rootDir>/examples/how-to/stream-and-share-media/file-sharing/renderer/app.js title="renderer/app.js" lineNumbers {35,36,43-100,111-115,117-120,131-132} skip="example-import"
    const bridge = window.bridge
    const decoder = new TextDecoder('utf-8')

    const SPECIFIER = '/workers/index.js'

    const countEl = document.getElementById('count')
    const dropzoneEl = document.getElementById('dropzone')
    const fileInputEl = document.getElementById('fileInput')
    const drivesEl = document.getElementById('drives')
    const emptyEl = document.getElementById('empty')
    const inviteBarEl = document.getElementById('invite-bar')
    const inviteEl = document.getElementById('invite')
    const copyEl = document.getElementById('copy')

    let invite = ''

    function setInvite (value) {
      invite = value
      if (!invite) {
        inviteBarEl.classList.add('hidden')
        return
      }
      inviteEl.textContent = invite
      inviteBarEl.classList.remove('hidden')
    }

    copyEl.addEventListener('click', () => {
      if (!invite) return
      bridge.writeClipboard(invite)
      copyEl.textContent = 'Copied'
      setTimeout(() => { copyEl.textContent = 'Copy' }, 1500)
    })

    function addFile (file) {
      const uri = bridge.getPathForFile(file)
      bridge.writeWorkerIPC(SPECIFIER, JSON.stringify({ type: 'add-file', name: file.name, uri }))
    }

    function addFiles (files) {
      for (const file of files) addFile(file)
    }

    function renderDrives (drives) {
      const totalFiles = drives.reduce((sum, d) => sum + d.info.files.length, 0)
      countEl.textContent =
        `${drives.length} drive${drives.length === 1 ? '' : 's'} · ${totalFiles} file${totalFiles === 1 ? '' : 's'}`

      // Re-render the list from scratch; keep the empty-state element in the DOM.
      for (const node of [...drivesEl.children]) {
        if (node !== emptyEl) node.remove()
      }
      emptyEl.style.display = drives.length === 0 ? '' : 'none'

      for (const drive of drives) {
        const card = document.createElement('div')
        card.className = 'rounded-2xl border border-neutral-800 bg-neutral-900 px-4 py-3'

        const head = document.createElement('div')
        head.className = 'flex items-center gap-2 mb-2'

        const title = document.createElement('a')
        title.className = 'text-sm font-medium text-neutral-100 hover:text-white hover:underline truncate'
        title.href = drive.info.uri
        title.textContent = drive.info.name

        head.append(title)

        if (drive.info.isMyDrive) {
          const badge = document.createElement('span')
          badge.className = 'rounded-full bg-neutral-800 px-2 py-0.5 text-[10px] uppercase tracking-wider text-neutral-400'
          badge.textContent = 'You'
          head.append(badge)
        }

        card.append(head)

        if (drive.info.files.length === 0) {
          const empty = document.createElement('div')
          empty.className = 'text-xs text-neutral-500'
          empty.textContent = 'Empty drive.'
          card.append(empty)
        } else {
          const list = document.createElement('ul')
          list.className = 'space-y-1'
          for (const file of drive.info.files) {
            const item = document.createElement('li')
            item.className = 'text-sm'
            const link = document.createElement('a')
            link.className = 'text-neutral-300 hover:text-neutral-100 hover:underline break-all'
            link.href = file.uri
            link.textContent = file.name
            item.append(link)
            list.append(item)
          }
          card.append(list)
        }

        drivesEl.append(card)
      }
    }

    dropzoneEl.addEventListener('dragover', (event) => {
      event.preventDefault()
      dropzoneEl.classList.add('border-neutral-600', 'bg-neutral-900')
    })

    dropzoneEl.addEventListener('dragleave', () => {
      dropzoneEl.classList.remove('border-neutral-600', 'bg-neutral-900')
    })

    dropzoneEl.addEventListener('drop', (event) => {
      event.preventDefault()
      dropzoneEl.classList.remove('border-neutral-600', 'bg-neutral-900')
      addFiles(event.dataTransfer.files)
    })

    fileInputEl.addEventListener('change', (event) => {
      addFiles(event.target.files)
      event.target.value = ''
    })

    bridge.startWorker(SPECIFIER)

    const offWorkerIPC = bridge.onWorkerIPC(SPECIFIER, (data) => {
      let message
      try {
        message = JSON.parse(decoder.decode(data))
      } catch {
        return
      }
      if (message.type === 'drives') renderDrives(message.drives)
      if (message.type === 'invite') setInvite(message.invite)
    })

    const offWorkerExit = bridge.onWorkerExit(SPECIFIER, (code) => {
      console.log('worker exited with code', code)
      offWorkerIPC()
      offWorkerExit()
    })
    ```
  </Step>
</Steps>

Run it [#run-it]

```bash skip="desktop-gui"
npm run build

# user1: create room + print invite + watch folder
npm start -- --storage /tmp/files-user1 --name user1
```

Drop files into the path printed as `My drive:` in the terminal. They appear in the file list. In a second terminal:

```bash skip="desktop-gui"
npm start -- --storage /tmp/files-user2 --name user2 --invite <invite>
```

user2's app lists user1's files. They are mirrored down into the `shared-drives` folder automatically, and each entry links to the local `file://` path on disk.

Where to go next [#where-to-go-next]

* [Create a full peer-to-peer filesystem with Hyperdrive](/how-to/stream-and-share-media/create-a-full-peer-to-peer-filesystem-with-hyperdrive)—the underlying mechanics.
* [Stream stored video in a peer-to-peer app](/how-to/stream-and-share-media/stream-stored-video-in-a-peer-to-peer-app)—same scaffold, range-served blobs instead of files.
* [From append-only logs to files](/explanation/from-logs-to-files)—why a [Hyperdrive](/reference/building-blocks/hyperdrive) ends up looking like a filesystem.


# Store and serve large media with Hyperblobs



<Callout type="info">
  **This guide focuses on the Pear/Bare logic.** It shows [`hyperblobs`](https://www.npmjs.com/package/hyperblobs) and [`hypercore-blob-server`](https://www.npmjs.com/package/hypercore-blob-server) on their own—no Electron, no UI. For the same blob plumbing wired into full desktop apps, see [Stream stored video in a peer-to-peer app](/how-to/stream-and-share-media/stream-stored-video-in-a-peer-to-peer-app), [Stream a live camera in a peer-to-peer app](/how-to/stream-and-share-media/stream-a-live-camera-in-a-peer-to-peer-app), and [Back up photos in a peer-to-peer app](/how-to/stream-and-share-media/back-up-photos-in-a-peer-to-peer-app). The blob logic is identical across all three; only the UI and the frame/file source change. To share a whole folder of files over [Hyperdrive](/reference/building-blocks/hyperdrive) instead, see [Share files in a peer-to-peer app](/how-to/stream-and-share-media/share-files-in-a-peer-to-peer-app).
</Callout>

A [Hypercore](/reference/building-blocks/hypercore) is an append-only log of small blocks—great for messages, awkward for a 200 MB video. [`Hyperblobs`](https://www.npmjs.com/package/hyperblobs) solves that: it chunks arbitrarily large binary data across a Hypercore and hands back a small **blob id** that addresses it. [`hypercore-blob-server`](https://www.npmjs.com/package/hypercore-blob-server) then serves any blob over local HTTP (`127.0.0.1`) so a `<video>` or `<img>` tag—or any HTTP client—can stream it **with range requests**, fetching only the bytes it needs.

This is purely Pear-end logic: it runs in a [Bare](/reference/modules/bare-modules) worker (or any Bare/Node process) and never touches a UI.

{/*
  Shared snippet (content/_snippets/) included via Fumadocs <include> by how-tos
  whose Pear-end (worker) logic works with EITHER boilerplate (desktop or
  terminal). Carries the cross-platform portability point too, so it REPLACES
  _pear-end-portability-callout on these guides—one orientation callout, not two.
  For frontend-specific how-tos, use _frontend-template-callout.mdx instead.
  See: https://www.fumadocs.dev/docs/markdown#include
  */}

<Callout type="info">
  **Pear-end logic—start from a boilerplate.** The code in this guide lives in the Bare [worker](/explanation/workers): peer-to-peer logic, no UI. The same worker runs unchanged on desktop, terminal, and mobile—only the shell differs (see [Runtime and languages](/explanation/runtime-and-languages)). Start from a boilerplate in [Start from a template](/getting-started/from-a-template)—desktop ([`hello-pear-electron`](/getting-started/from-a-template/start-from-hello-pear-electron)) or terminal ([`hello-pear-bare`](/getting-started/from-a-template/start-from-hello-pear-bare))—and add this capability on top.
</Callout>

How addressing works [#how-addressing-works]

Writing a blob returns an **id** describing where the bytes live in the core:

```js skip="id-shape"
{ byteOffset, blockOffset, blockLength, byteLength }
```

Combine that id with the blobs **core key** and you have everything a peer needs to fetch the blob—directly as bytes, or through a blob-server link.

Add the dependencies [#add-the-dependencies]

```sh skip="deps"
npm install corestore hyperswarm hyperblobs hypercore-blob-server hypercore-id-encoding
```

Write and seed a blob [#write-and-seed-a-blob]

The writer:

* opens a [Corestore](/reference/helpers/corestore) namespace and wraps it with `Hyperblobs` (L12–L13)
* announces the blobs core on [Hyperswarm](/reference/building-blocks/hyperswarm) so readers can find it (L16)
* streams a local file through `createWriteStream()` (L18–L24)
* and prints the `{ key, ...id }` payload other peers need (L27–L28):

```javascript file=<rootDir>/examples/how-to/stream-and-share-media/store-and-serve-large-media-with-hyperblobs/writer-app/index.js title="writer-app/index.js" lineNumbers {12-13,16,18-24,27-28} skip="example-import"
import Corestore from 'corestore'
import Hyperswarm from 'hyperswarm'
import Hyperblobs from 'hyperblobs'
import idEnc from 'hypercore-id-encoding'
import fs from 'bare-fs'
import process from 'bare-process'

const store = new Corestore('./writer-store')
const swarm = new Hyperswarm()
swarm.on('connection', (conn) => store.replicate(conn))

const blobs = new Hyperblobs(store.get({ name: 'blobs' }))
await blobs.ready()

// Announce the blobs core so readers can discover and replicate it.
swarm.join(blobs.core.discoveryKey, { server: true, client: false })

// Store a local file as a blob.
const ws = blobs.createWriteStream()
fs.createReadStream('./clip.mp4').pipe(ws)
await new Promise((resolve, reject) => {
  ws.on('error', reject)
  ws.on('close', resolve)
})

// Share this with readers — the core key plus the blob id.
const blob = { key: idEnc.normalize(blobs.core.key), ...ws.id }
console.log('blob:', JSON.stringify(blob))

// Keep seeding until interrupted, then tear down cleanly.
process.once('SIGINT', async () => {
  await blobs.close()
  await swarm.destroy()
  await store.close()
  process.exit(0)
})
```

Read or serve the blob on another peer [#read-or-serve-the-blob-on-another-peer]

The reader:

* parses that JSON blob descriptor from the command line (L9)
* opens the remote core by key and replicates it (L15–L17)
* **Option A** pulls the raw bytes with `blobs.get()` and the id fields (L20–L27)
* **Option B**—what desktop apps use—starts [`hypercore-blob-server`](https://www.npmjs.com/package/hypercore-blob-server) and prints a local `link` the renderer can pass to `<video>` or `<img>` (L30–L33)

  Option B is what desktop apps use: the worker hands the `link` to the renderer, and the browser streams the media straight from `hypercore-blob-server`, requesting byte ranges as the user scrubs.

```javascript file=<rootDir>/examples/how-to/stream-and-share-media/store-and-serve-large-media-with-hyperblobs/reader-app/index.js title="reader-app/index.js" lineNumbers {9,15-17,20-27,30-33} skip="example-import"
import Corestore from 'corestore'
import Hyperswarm from 'hyperswarm'
import Hyperblobs from 'hyperblobs'
import BlobServer from 'hypercore-blob-server'
import idEnc from 'hypercore-id-encoding'
import process from 'bare-process'

// { key, byteOffset, blockOffset, blockLength, byteLength }
const blob = JSON.parse(process.argv[2])

const store = new Corestore('./reader-store')
const swarm = new Hyperswarm()
swarm.on('connection', (conn) => store.replicate(conn))

const core = store.get({ key: idEnc.decode(blob.key) })
await core.ready()
swarm.join(core.discoveryKey, { client: true, server: false })

// Option A — read the raw bytes.
const blobs = new Hyperblobs(core)
const bytes = await blobs.get({
  byteOffset: blob.byteOffset,
  blockOffset: blob.blockOffset,
  blockLength: blob.blockLength,
  byteLength: blob.byteLength
})
console.log('read bytes:', bytes.byteLength)

// Option B — serve over local HTTP so a <video>/<img> can stream it with range requests.
const server = new BlobServer(store.session())
await server.listen()
const link = server.getLink(blob.key, { blob, type: 'video/mp4' })
console.log('stream from:', link)

// Close the server and blobs before the swarm and store on exit.
process.once('SIGINT', async () => {
  await server.close()
  await blobs.close()
  await swarm.destroy()
  await store.close()
  process.exit(0)
})
```

Tear it down [#tear-it-down]

Each app cleans up on `Ctrl+C`: the `SIGINT` handler at the end of every file closes the blobs (and, in the reader, the HTTP server) **before** the swarm and store, so in-flight reads and the local server shut down before the underlying core does.

See also [#see-also]

* [Share files in a peer-to-peer app](/how-to/stream-and-share-media/share-files-in-a-peer-to-peer-app)—replicate a folder of files over [Hyperdrive](/reference/building-blocks/hyperdrive) instead of chunking individual blobs.
* [Stream stored video in a peer-to-peer app](/how-to/stream-and-share-media/stream-stored-video-in-a-peer-to-peer-app)—this primitive behind a desktop video player.
* [Stream a live camera in a peer-to-peer app](/how-to/stream-and-share-media/stream-a-live-camera-in-a-peer-to-peer-app)—the same blobs, fed by live camera frames.
* [Back up photos in a peer-to-peer app](/how-to/stream-and-share-media/back-up-photos-in-a-peer-to-peer-app)—decode images with `bare-ffmpeg` before storing them as blobs.
* [From append-only logs to files](/explanation/from-logs-to-files)—how Hypercore, Hyperblobs, and Hyperdrive relate.
* [Hypercore reference](/reference/building-blocks/hypercore)—the append-only log Hyperblobs chunks data across.


# Stream a live camera in a peer-to-peer app



import { Steps, Step } from 'fumadocs-ui/components/steps'

This guide shows you how to **stream a live camera feed peer-to-peer** by adapting the [`hello-pear-electron`](https://github.com/holepunchto/hello-pear-electron) scaffold to push camera frames through [Hyperblobs](https://www.npmjs.com/package/hyperblobs) and serve them via [`hypercore-blob-server`](https://www.npmjs.com/package/hypercore-blob-server). The reference implementation is [`pear-live-cam`](https://github.com/holepunchto/pear-docs/tree/preview/examples/how-to/stream-and-share-media/live-cam).

{/*
  Shared snippet (content/_snippets/) included via Fumadocs <include> by how-tos
  that have a frontend (UI), so they build on the desktop boilerplate. Carries a
  short portability nod too, so it REPLACES _pear-end-portability-callout on these
  guides—one orientation callout, not two. For how-tos whose logic works with
  either template, use _from-a-template-callout.mdx instead.
  See: https://www.fumadocs.dev/docs/markdown#include
  */}

<Callout type="info">
  **Start from the desktop boilerplate.** This guide has a frontend, so it builds on [`hello-pear-electron`](/getting-started/from-a-template/start-from-hello-pear-electron)—the renderer, preload bridge, and Bare [worker](/explanation/workers) it extends. Read [Start from the hello-pear-electron template](/getting-started/from-a-template/start-from-hello-pear-electron) first. The Pear-end logic itself is portable—only the UI is desktop-specific (see [Runtime and languages](/explanation/runtime-and-languages)); the terminal template [`hello-pear-bare`](/getting-started/from-a-template/start-from-hello-pear-bare) has no UI layer. See all starting points in [Start from a template](/getting-started/from-a-template).
</Callout>

Before you begin [#before-you-begin]

* A working clone of `hello-pear-electron` (or your own app built from the getting-started path).
* A camera the host machine can access. The renderer uses the browser `getUserMedia` API.

What changes [#what-changes]

| Layer        | Change                                                                                                                                                                                                                            |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Dependencies | Add [`hyperblobs`](https://www.npmjs.com/package/hyperblobs), [`hypercore-blob-server`](https://www.npmjs.com/package/hypercore-blob-server), and [`hypercore-id-encoding`](https://www.npmjs.com/package/hypercore-id-encoding). |
| Roles        | Distinguish a **creator** (camera owner) from **viewers** at startup via a CLI flag and a small `role` message over the worker pipe.                                                                                              |
| Worker       | Add a Hyperblobs core in the worker; each camera fragment becomes a blob, and `hypercore-blob-server` serves a per-fragment HTTP link.                                                                                            |
| Renderer     | Creator: capture `MediaStream` → MediaRecorder → tagged binary frames over the worker pipe. Viewer: feed each fragment's `info.link` into a `MediaSource`.                                                                        |

The Electron shell, preload bridge, packaging, and graceful teardown stay as in hello-pear-electron.

Steps [#steps]

<Steps>
  <Step>
    Add the dependencies [#add-the-dependencies]

    ```bash skip="desktop-gui"
    npm install hyperblobs hypercore-blob-server hypercore-id-encoding
    ```
  </Step>

  <Step>
    Differentiate creator vs. viewer at startup [#differentiate-creator-vs-viewer-at-startup]

    In `workers/index.js` the example fetches the room's pairing invite (L32) and derives a role: anyone who passed `--invite` is a `viewer`, otherwise they own the camera as the `creator` (L33). The worker then surfaces that role so the renderer can branch on it:

    ```js file=<rootDir>/examples/how-to/stream-and-share-media/live-cam/workers/index.js#L30-L33 title="workers/index.js" lineNumbers {32-33} skip="example-import"
      pipe.resume()

      const invite = await workerTask.room.getInvite()
      const role = cmd.flags.invite ? 'viewer' : 'creator'
    ```

    The renderer listens for the `role` message and either opens the camera (creator) or plays the replicated fragments (viewer).
  </Step>

  <Step>
    Build the room around Hyperblobs [#build-the-room-around-hyperblobs]

    `workers/live-cam-room.js` (`LiveCamRoom`) uses [Autobase](/reference/building-blocks/autobase) + pairing plumbing, and adds a Hyperblobs core plus a `hypercore-blob-server` (both constructed in the constructor and opened in `_open`). `addFragment` (L194–L208) writes each camera fragment as one blob (L195–L198), then appends a view entry tagged with a `session` id and an incrementing `fragIdx` (L203–L205)—that ordering is what lets viewers reassemble a continuous stream. On the read side, `getVideos` (L178–L192) lazily opens and joins the swarm for each fragment's blob core (L181–L186), attaches a blob-server `link` to every fragment (L188–L190), and returns them sorted by `session` then `fragIdx` (L191) so the renderer can fetch and replay them in order:

    ```js file=<rootDir>/examples/how-to/stream-and-share-media/live-cam/workers/live-cam-room.js#L178-L208 title="workers/live-cam-room.js" lineNumbers {181-186,188-191,195-198,203-205} skip="example-import"
      async getVideos ({ limit = 100 } = {}) {
        const videos = await this.view.find('@pear-live-cam/videos', { limit }).toArray()
        for (const item of videos) {
          if (!this.blobsCores[item.blob.key]) {
            const blobsCore = this.store.get({ key: idEnc.decode(item.blob.key) })
            this.blobsCores[item.blob.key] = blobsCore
            await blobsCore.ready()
            this.swarm.join(blobsCore.discoveryKey)
          }
        }
        return videos.map(item => {
          const link = this.blobServer.getLink(item.blob.key, { blob: item.blob })
          return { ...item, info: { ...item.info, link } }
        }).sort((a, b) => (a.info.session - b.info.session) || (a.info.fragIdx - b.info.fragIdx))
      }

      async addFragment (frag) {
        const ws = this.blobs.createWriteStream()
        ws.write(frag)
        ws.end()
        await new Promise((resolve) => ws.on('close', resolve))

        const blob = { key: idEnc.normalize(this.blobs.core.key), ...ws.id }

        const id = Math.random().toString(16).slice(2)
        await this.base.append(
          LiveCamDispatch.encode('@pear-live-cam/add-video', { id, blob, info: { session: this.session, fragIdx: this.fragIdx } })
        )
        if (this.fragIdx % 30 === 0) console.log('[live-cam] fragments uploaded: ' + (this.fragIdx + 1))
        this.fragIdx += 1
      }
    ```

    Pairing still uses [`blind-pairing`](https://www.npmjs.com/package/blind-pairing)—viewers join the creator's swarm via an invite code exactly as in the getting-started chat path.
  </Step>

  <Step>
    Wire MediaRecorder in the renderer [#wire-mediarecorder-in-the-renderer]

    In the creator path (`renderer/app.js`), guard on the pinned mime type (L123–L125)—Chromium reliably encodes WebM/VP8 only (`video/webm; codecs="vp8"`)—then request the camera (L126) and start a `MediaRecorder` on the stream (L132), emitting a chunk every `TIMESLICE_MS` (L147). Video frames are large, so each `dataavailable` chunk is converted to raw bytes and sent over the worker pipe (L140–L141) rather than as JSON—only small control/event messages are JSON-encoded:

    ```js file=<rootDir>/examples/how-to/stream-and-share-media/live-cam/renderer/app.js#L123-L147 title="renderer/app.js — creator" lineNumbers {123-126,132,140-141,147} skip="example-import"
        if (!window.MediaRecorder || !window.MediaRecorder.isTypeSupported(RECORDER_MIME)) {
          throw new Error('MediaRecorder does not support ' + RECORDER_MIME)
        }
        stream = await navigator.mediaDevices.getUserMedia({ video: true, audio: false })
        // Hidden preview keeps Chromium pumping frames into the stream.
        previewEl.srcObject = stream
        previewEl.play().catch(() => {})
        recordingEl.classList.remove('hidden')

        const recorder = new window.MediaRecorder(stream, { mimeType: RECORDER_MIME })
        let firstUpload = false
        recorder.ondataavailable = async (e) => {
          if (!e.data || e.data.size === 0) return
          if (!firstUpload) {
            console.log('[live-cam] first chunk encoded, ' + e.data.size + ' bytes')
            firstUpload = true
          }
          const buf = new Uint8Array(await e.data.arrayBuffer())
          sendFragment(buf)
        }
        recorder.onerror = (e) => {
          console.error('[live-cam] recorder error:', e?.error?.message || e)
          setCaptureError(e?.error?.message || 'recorder error')
        }
        recorder.start(TIMESLICE_MS)
    ```

    In the viewer path, each replicated fragment carries an `info.link` from the blob server. The player appends them to a `MediaSource` strictly in `session` + `fragIdx` order—WebM/VP8 is one continuous stream, so a gap or out-of-order append puts the `<video>` element into a permanent error state.
  </Step>
</Steps>

Run it [#run-it]

```bash skip="desktop-gui"
npm run build

# creator
npm start -- --storage /tmp/cam-creator --name camera-host
```

Copy the invite from stdout. In a second terminal:

```bash skip="desktop-gui"
npm start -- --storage /tmp/cam-viewer --name viewer --invite <invite>
```

The creator's camera preview shows in their window; the viewer's window plays the live feed off the replicated Hyperblob.

Where to go next [#where-to-go-next]

* [Store and serve large media with Hyperblobs](/how-to/stream-and-share-media/store-and-serve-large-media-with-hyperblobs)—the Pear/Bare blob primitive behind this app, with no UI.
* [Stream stored video in a peer-to-peer app](/how-to/stream-and-share-media/stream-stored-video-in-a-peer-to-peer-app)—same blob mechanics for finished video files.
* [Back up photos in a peer-to-peer app](/how-to/stream-and-share-media/back-up-photos-in-a-peer-to-peer-app)—the same scaffold with `bare-ffmpeg`/`bare-media` for media decoding.
* [Hypercore](/reference/building-blocks/hypercore)—the append-only log that backs Hyperblobs.


# Stream stored video in a peer-to-peer app



import { Steps, Step } from 'fumadocs-ui/components/steps'

This guide shows you how to **stream a stored video file peer-to-peer** by adapting the [`hello-pear-electron`](https://github.com/holepunchto/hello-pear-electron) scaffold to publish video blobs through [Hyperblobs](https://www.npmjs.com/package/hyperblobs) and serve them with [`hypercore-blob-server`](https://www.npmjs.com/package/hypercore-blob-server). The reference implementation is [`pear-video-stream`](https://github.com/holepunchto/pear-docs/tree/preview/examples/how-to/stream-and-share-media/video-stream).

{/*
  Shared snippet (content/_snippets/) included via Fumadocs <include> by how-tos
  that have a frontend (UI), so they build on the desktop boilerplate. Carries a
  short portability nod too, so it REPLACES _pear-end-portability-callout on these
  guides—one orientation callout, not two. For how-tos whose logic works with
  either template, use _from-a-template-callout.mdx instead.
  See: https://www.fumadocs.dev/docs/markdown#include
  */}

<Callout type="info">
  **Start from the desktop boilerplate.** This guide has a frontend, so it builds on [`hello-pear-electron`](/getting-started/from-a-template/start-from-hello-pear-electron)—the renderer, preload bridge, and Bare [worker](/explanation/workers) it extends. Read [Start from the hello-pear-electron template](/getting-started/from-a-template/start-from-hello-pear-electron) first. The Pear-end logic itself is portable—only the UI is desktop-specific (see [Runtime and languages](/explanation/runtime-and-languages)); the terminal template [`hello-pear-bare`](/getting-started/from-a-template/start-from-hello-pear-bare) has no UI layer. See all starting points in [Start from a template](/getting-started/from-a-template).
</Callout>

* [Stream a live camera in a peer-to-peer app](/how-to/stream-and-share-media/stream-a-live-camera-in-a-peer-to-peer-app)—the live counterpart that builds on the same blob plumbing.

Before you begin [#before-you-begin]

* A working clone of `hello-pear-electron` (or your own app built from the getting-started path).
* A stored video file (`.mp4`, `.webm`) you want to share.

What changes [#what-changes]

| Layer            | Change                                                                                                                                                                                                                                                                                            |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Dependencies     | Add [`hyperblobs`](https://www.npmjs.com/package/hyperblobs), [`hypercore-blob-server`](https://www.npmjs.com/package/hypercore-blob-server), [`hypercore-id-encoding`](https://www.npmjs.com/package/hypercore-id-encoding), and [`get-mime-type`](https://www.npmjs.com/package/get-mime-type). |
| Worker           | Add a Hyperblobs core in the worker; store each video as one blob and attach a blob-server link to every entry.                                                                                                                                                                                   |
| Worker transport | Add an `add-video` ingest (an `{ type: 'add-video', filePath }` control message) and a `videos` snapshot whose entries carry a playable link.                                                                                                                                                     |
| Renderer         | Render a video player on the selected entry's link.                                                                                                                                                                                                                                               |

The Electron shell, preload bridge, packaging, and graceful teardown stay as in hello-pear-electron.

Steps [#steps]

<Steps>
  <Step>
    Add the dependencies [#add-the-dependencies]

    ```bash skip="desktop-gui"
    npm install hyperblobs hypercore-blob-server hypercore-id-encoding get-mime-type
    ```
  </Step>

  <Step>
    Publish each video as a Hyperblob [#publish-each-video-as-a-hyperblob]

    `workers/video-room.js` (`VideoRoom`) keeps the tutorial's [Autobase](/reference/building-blocks/autobase) + pairing, and constructs a Hyperblobs core plus a `hypercore-blob-server`. `addVideo` resolves the file name and checks the MIME type with [`get-mime-type`](https://www.npmjs.com/package/get-mime-type), rejecting anything that is not a `video/*` type (L180–L184). It then pipes the file off disk into a blobs write stream (L186–L192), captures the resulting `blob` descriptor (the blobs core key plus the write stream's byte id, L193), and appends `{ id, name, type, blob, info }` to the base so the view records it (L196–L198):

    ```js file=<rootDir>/examples/how-to/stream-and-share-media/video-stream/workers/video-room.js#L179-L199 title="workers/video-room.js" lineNumbers {180-184,186-193,196-198} skip="example-import"
      async addVideo (filePath, info) {
        const name = path.basename(filePath)
        const type = getMimeType(name)
        if (!type || !type.startsWith('video/')) {
          throw new Error('Only video files are allowed')
        }

        const rs = fs.createReadStream(filePath)
        const ws = this.blobs.createWriteStream()
        await new Promise((resolve, reject) => {
          ws.on('error', reject)
          ws.on('close', resolve)
          rs.pipe(ws)
        })
        const blob = { key: idEnc.normalize(this.blobs.core.key), ...ws.id }

        const id = Math.random().toString(16).slice(2)
        await this.base.append(
          VideoDispatch.encode('@pear-video-stream/add-video', { id, name, type, blob, info })
        )
      }
    ```
  </Step>

  <Step>
    Serve the blob locally [#serve-the-blob-locally]

    The server speaks HTTP **range requests**, so the player handles seeking without downloading the whole file. `getVideos` reads the stored entries from the view (L164), and for each one whose blobs core it has not seen yet, opens that core and joins its swarm topic on demand (L165–L172). It then maps every entry to attach a playable `info.link` from `blobServer.getLink` before returning to the renderer (L173–L176):

    ```js file=<rootDir>/examples/how-to/stream-and-share-media/video-stream/workers/video-room.js#L163-L177 title="workers/video-room.js" lineNumbers {164,165-172,173-176} skip="example-import"
      async getVideos ({ reverse = true, limit = 100 } = {}) {
        const videos = await this.view.find('@pear-video-stream/videos', { reverse, limit }).toArray()
        for (const item of videos) {
          if (!this.blobsCores[item.blob.key]) {
            const blobsCore = this.store.get({ key: idEnc.decode(item.blob.key) })
            this.blobsCores[item.blob.key] = blobsCore
            await blobsCore.ready()
            this.swarm.join(blobsCore.discoveryKey)
          }
        }
        return videos.map(item => {
          const link = this.blobServer.getLink(item.blob.key, { blob: item.blob, type: item.type })
          return { ...item, info: { ...item.info, link } }
        })
      }
    ```
  </Step>

  <Step>
    Render a <video> element [#render-a-video-element]

    In the renderer, create a `<video controls>` element and set its `src` to `video.info.link` for the selected entry. The first peer who clicks Play triggers a range request, the worker pulls the byte range from the Hyperblob, and the player streams.
  </Step>
</Steps>

Run it [#run-it]

```bash skip="desktop-gui"
npm run build

# host
npm start -- --storage /tmp/video-host --name host
```

Drop a video file into the window (the renderer forwards the path via `webUtils.getPathForFile`). In a second terminal:

```bash skip="desktop-gui"
npm start -- --storage /tmp/video-viewer --name viewer --invite <invite>
```

The viewer sees the entry, clicks Play, and the player streams range by range over the replicated Hyperblobs.

Where to go next [#where-to-go-next]

* [Store and serve large media with Hyperblobs](/how-to/stream-and-share-media/store-and-serve-large-media-with-hyperblobs)—the Pear/Bare blob primitive behind this app, with no UI.
* [Stream a live camera in a peer-to-peer app](/how-to/stream-and-share-media/stream-a-live-camera-in-a-peer-to-peer-app)—same blob mechanics for live frames.
* [Back up photos in a peer-to-peer app](/how-to/stream-and-share-media/back-up-photos-in-a-peer-to-peer-app)—same scaffold with `bare-ffmpeg`/`bare-media` for media decoding.
* [Storage and distribution](/explanation/storage-and-distribution)—why range-served blobs scale well in a P2P swarm.


# Bare Kit



{/* Maintainer note: this page's doc-states come from src/lib/bare-kit-docs-states.json,
  generated from holepunchto/react-native-bare-kit's index.d.ts by
  scripts/gen-bare-docs-states.ts — run `npm run gen:bare-docs-states` to refresh, then
  review the printed delta and add/adjust the markers below for anything that changed.
  `Since` = added in that release, `Until` = removed in it; pass `label` to override the
  badge text. Four tools, by the size of what changed:
  <Since v="x.y.z" />                  inline badge on a sentence. Never hidden — it is the warning.
  <VersionSection since="x.y.z" />     one line directly under a heading; gates that whole section.
  <VersionGate since="x.y.z">…</…>     gates a block that is not a whole section, for example a single <Callout>.
  --flag  Description  [!version since=x.y.z]    gates one row inside a fenced help block.
  This axis tracks `react-native-bare-kit` specifically (the only canonical typed surface —
  the native iOS/Android `Worklet` bindings ship no .d.ts) and is independent of `bare-cli`
  and `bare-runtime`.

  As of 2026-08-06, `WorkletEvents.idle` (added)/`.start`/`.terminate` (removed, 0.14.0) and
  the `suspend`/`wakeup` payload types are not yet documented in prose on this page at all —
  worth a follow-up to add a "## Events" section, at which point those deltas should get
  markers too. The `Worklet.constructor` overload change (0.10.5, adding `new Worklet(id,
  options)`) is similarly undocumented here — see the existing aside in the versioning plan
  about this page lagging the .d.ts on `update()` and the two-constructor form. */}

[`bare-kit`](https://github.com/holepunchto/bare-kit) embeds [Bare](/reference/bare/runtime) in native application development. It provides a web-worker-like API for starting and managing isolated Bare threads—called **worklets**—each exposing an IPC channel with bindings for several languages. [`react-native-bare-kit`](https://github.com/holepunchto/react-native-bare-kit) wraps the same API for React Native and Expo. For the architecture this enables, see [One core, many platforms](/explanation/bare-on-native).

<Callout type="info">
  A *worklet* is an isolated Bare thread managed by the host app. The name avoids confusion with the worker threads of [`bare-worker`](/reference/modules/bare-modules).
</Callout>

Worklet [#worklet]

A worklet runs a Bare entry script on a background thread. Create one, start it with an entry filename and source, and manage its [lifecycle](/reference/bare/runtime#lifecycle).

Constructor [#constructor]

* `new Worklet([options])`— create a worklet.
* `new Worklet(id, [options])` <Since v="0.10.5" />— create a worklet with an explicit `id`, distinguishing it from other worklets managed by the same host.

Actions [#actions]

* `start(filename, source[, arguments])`— start the worklet running `source` as `filename`.
* `suspend()`— suspend execution.
* `suspend(linger)`— suspend, keeping the process alive for `linger` milliseconds before it fully exits.
* `resume()`— resume a suspended worklet.
* `wakeup([deadline])`— wake the worklet during suspension. Work may run until `deadline`, after which it suspends again.
* `update(state)`— notify the worklet of a host app-lifecycle change (React Native's `AppStateStatus`), so it can react to foreground/background transitions.
* `terminate()`— terminate the worklet.

<Callout type="info">
  `suspend`, `resume`, `wakeup`, and `update` are also available as **static** methods (`Worklet.suspend()`, etc.), driving every worklet the host manages at once rather than one instance.
</Callout>

<VersionGate since="0.9.2">
  A configuration object can optionally set a `memoryLimit` or attach assets. <Since v="0.9.2" />
</VersionGate>

React Native [#react-native]

```js
import { Worklet } from 'react-native-bare-kit'
import b4a from 'b4a'

const worklet = new Worklet()

const source = `
const { IPC } = BareKit

IPC.on('data', (data) => console.log(data.toString()))
IPC.write(Buffer.from('Hello from Bare!'))
`

worklet.start('/app.js', source)

const { IPC } = worklet
IPC.on('data', (data) => console.log(b4a.toString(data)))
IPC.write(b4a.from('Hello from React Native!'))
```

iOS [#ios]

```objc
#import <BareKit/BareKit.h>

BareWorkletConfiguration *options = [BareWorkletConfiguration defaultWorkletConfiguration];
options.memoryLimit = 1024 * 1024 * 24; // 24 MiB

BareWorklet *worklet = [[BareWorklet alloc] initWithConfiguration:options];

NSString *source = @"console.log('hello from the worklet')";
[worklet start:@"/app.js" source:[source dataUsingEncoding:NSUTF8StringEncoding] arguments:@[]];
```

Android [#android]

```java
import to.holepunch.bare.kit.Worklet;
import java.nio.charset.StandardCharsets;

Worklet.Options options = new Worklet.Options()
  .memoryLimit(24 * 1024 * 1024); // 24 MiB

Worklet worklet = new Worklet(options);

String source = "console.log('hello from the worklet')";
worklet.start("/app.js", source, StandardCharsets.UTF_8, null);
```

<VersionGate since="0.9.1">
  IPC [#ipc]

  Bare Kit provides an IPC abstraction for communication between the host app and a worklet, with both synchronous and asynchronous read/write.

  <Callout type="warn">
    IPC operations are **non-blocking** regardless of which API you use. They may return partial results—for example writing fewer bytes than requested—and require polling to complete.
  </Callout>

  **Polling API** (callback-driven, use when you want event-triggered reads/writes):

  * `readable`— callback invoked when data is available to read.
  * `writable`— callback invoked when data can be written.
  * `read()`— synchronously read available data; returns nothing when none is available.
  * `write(data)`— synchronously write data; returns the number of bytes written.

  **Async API** (completion-based, use when you want a single async operation):

  * `read(callback)`— asynchronously read data with a completion callback.
  * `write(data, callback)`— asynchronously write data with a completion callback.

  **Utility:**

  * `close()`— close the IPC connection.

  Inside the worklet the channel is reached through the `BareKit.IPC` global (an instance of [`Bare.IPC`](/reference/bare/runtime#bareipc)); on the host it's a `BareIPC` (iOS) or the `IPC` object on the React Native `Worklet`.

  For typed, schema-generated messaging over this channel instead of raw bytes, layer [`bare-rpc`](/reference/modules/bare-modules) on top—see [Type a native RPC bridge](/how-to/run-on-native/type-a-native-rpc-bridge).
</VersionGate>

Loading a bundle [#loading-a-bundle]

Instead of inline source, a worklet can start from a bundle produced by [`bare-pack`](/reference/modules/bare-modules). The entry filename's extension must be `.bundle`:

```js
import { Worklet } from 'react-native-bare-kit'
import bundle from './my.bundle.js' // output by bare-pack

const worklet = new Worklet()
worklet.start('/app.bundle', bundle)
```

See [Bundle a Bare app](/how-to/run-on-native/bundle-a-bare-app) for producing the bundle.

Logging [#logging]

`console.*` calls inside the worklet write to the system log (via [`liblog`](https://github.com/holepunchto/liblog)) under the `bare` identifier, so worklet output shows up in the platform's native logging tools.

See also [#see-also]

* [One core, many platforms](/explanation/bare-on-native)—the shell/seam/core pattern this enables.
* [Embed Bare in a React Native app](/how-to/run-on-native/embed-bare-in-react-native)—a step-by-step walkthrough.
* [Bare runtime API](/reference/bare/runtime)—the `Bare` global and lifecycle the worklet runs.
* [Bare modules](/reference/modules/bare-modules)—`bare-rpc`, `bare-pack`, and the rest of the userland.


# Bare CLI



{/* Maintainer note: this page's doc-states come from src/lib/bare-cli-docs-states.json,
  generated from holepunchto/bare's bin/bare.js by scripts/gen-bare-docs-states.ts — run
  `npm run gen:bare-docs-states` to refresh, then review the printed delta and add/adjust
  the markers below for anything that changed. `Since` = added in that release, `Until` =
  removed in it; pass `label` to override the badge text. Four tools, by the size of what
  changed:
  <Since v="x.y.z" />                  inline badge on a sentence. Never hidden — it is the warning.
  <VersionSection since="x.y.z" />     one line directly under a heading; gates that whole section.
  <VersionGate since="x.y.z">…</…>     gates a block that is not a whole section, for example a single <Callout>.
  --flag  Description  [!version since=x.y.z]    gates one row inside a fenced help block.
  This axis is independent of `bare-runtime` and `bare-kit` — each Bare page tracks its own
  surface, not one shared "Bare version" (see docs/plans/DOCS-VERSIONING-DESIGN.md and the
  plan for versioning these three pages). */}

<mark style={{ backgroundColor: '#7dde9a', padding: '2px 8px', borderRadius: '4px', fontSize: '0.85em', fontWeight: 500 }}>
  stable
</mark>

<Callout type="info">
  This page tracks the Bare CLI surface as of Bare 1.31.0 (unchanged since 1.28.1). `--inspect-port` and `--expose-gc` are annotated below with the release that added them.
</Callout>

The `bare` command runs a script on the [Bare runtime](/reference/bare/runtime) or starts a REPL. Install it globally with:

```sh
npm i -g bare
```

Usage [#usage]

```
bare [flags] [filename] [...args]
```

Evaluate a script, or start a REPL session if no script is provided.

Arguments [#arguments]

```
  [filename]              Optional. The name of a script to evaluate
  [...args]               Additional arguments made available to the script
```

Arguments after `filename` are passed through to the script and are available as [`Bare.argv`](/reference/bare/runtime#bareargv).

Flags [#flags]

```text version-lines="5:since:1.28.1,6:since:1.27.0"
  --version|-v            Print the Bare version
  --eval|-e <script>      Evaluate an inline script
  --print|-p <script>     Evaluate an inline script and print the result
  --inspect               Activate the inspector
  --inspect-port <port>   Port for the inspector (default: 9229)
  --expose-gc             Expose garbage collection APIs
  --help|-h               Show help
```

Module loading [#module-loading]

The specified `filename` (or inline `--eval` script) is run with `Module.load()`, which resolves both CommonJS and ESM and provides interop between them. For the supported formats and resolution rules, see [`bare-module`](https://github.com/holepunchto/bare-module).

See also [#see-also]

* [Bare runtime API](/reference/bare/runtime)—the `Bare` global available to scripts you run.
* [Inside Bare](/explanation/bare-runtime)—what the runtime is and why it's minimal.
* [Start from the hello-pear-bare template](/getting-started/from-a-template/start-from-hello-pear-bare)—a terminal app run with `bare bin.js`.
* [Bare modules](/reference/modules/bare-modules)—the standard library available to scripts.


# Bare runtime API



{/* Maintainer note: this page's doc-states come from src/lib/bare-runtime-docs-states.json,
  generated from holepunchto/bare's npm/index.d.ts by scripts/gen-bare-docs-states.ts — run
  `npm run gen:bare-docs-states` to refresh, then review the printed delta and add/adjust
  the markers below for anything that changed. `Since` = added in that release, `Until` =
  removed in it; pass `label` to override the badge text. Four tools, by the size of what
  changed:
  <Since v="x.y.z" />                  inline badge on a sentence. Never hidden — it is the warning.
  <VersionSection since="x.y.z" />     one line directly under a heading; gates that whole section.
  <VersionGate since="x.y.z">…</…>     gates a block that is not a whole section, for example a single <Callout>.
  --flag  Description  [!version since=x.y.z]    gates one row inside a fenced help block.
  This axis is independent of `bare-cli` and `bare-kit` — each Bare page tracks its own
  surface, not one shared "Bare version".

  As of 2026-08-06, across the tracked window (1.23.5 -> 1.31.0):

  `Bare.Addon`/`Bare.Thread` becoming top-level siblings in 1.31.0 (same release as the
  delta below) is a .d.ts authoring change only — both remain reachable as
  `Bare.Addon`/`Bare.Thread` at runtime via the namespace merge, so that part is not a real
  surface change. BUT the same commit (holepunchto/bare#172, "Add `new Addon(url)` and
  deprecate existing addon APIs") also added a genuine new `Addon` constructor and deprecated
  four existing members — `Addon.cache`/`.load()`/`.resolve()`, `Thread.create()` — which
  IS a real, marker-worthy change and is now reflected in the `## Bare.Addon` / `## Bare.Thread`
  sections below with `<Since v="1.31.0" />`. First pass at this delta wrongly lumped the whole
  block in with the cosmetic rename because most of it (host/url/exports/etc.) genuinely was
  just the rename — the giveaway missed on first read was that `Addon.constructor` had no `-`
  counterpart, i.e. it wasn't a rename at all. `scripts/bare-model-surface.ts`'s fingerprint was
  also blind to `deprecated` status at the time (fixed since — it's now a first-class fingerprinted
  field, and deprecated members surface explicitly in the printed delta, including across a
  rename boundary). `Bare.simulator` was ALSO marked `@deprecated` back in 1.27.0, per the
  delta below — left undocumented here on purpose, since it was never described on this page to
  begin with and isn't worth introducing now just to badge it deprecated.

  The `Bare.versions` index-signature parameter rename (`package` -> `library`, 1.28.2) is a
  type-only cosmetic change — no marker needed. `Bare.exiting`/`Bare.suspended`/
  `Bare.suspending` were removed in 1.27.0 but carried no JSDoc upstream and were never
  documented on this page, so there is nothing accurate to backfill with <Until> — do not
  guess their semantics from the property names alone. */}

<mark style={{ backgroundColor: '#7dde9a', padding: '2px 8px', borderRadius: '4px', fontSize: '0.85em', fontWeight: 500 }}>
  stable
</mark>

The core JavaScript API of [Bare](/explanation/bare-runtime) is exposed through the global `Bare` namespace. This page documents that surface. For the command-line runner, see the [`bare` CLI](/reference/bare/cli); for the standard-library modules layered on top, see [Bare modules](/reference/modules/bare-modules).

Process properties [#process-properties]

Bare.platform [#bareplatform]

The operating system Bare was compiled for. One of `android`, `darwin`, `ios`, `linux`, `win32`.

Bare.arch [#barearch]

The processor architecture Bare was compiled for. One of `arm`, `arm64`, `ia32`, `mips`, `mipsel`, `riscv64`, `x64`.

Bare.argv [#bareargv]

The command-line arguments passed to the process when launched.

Bare.pid [#barepid]

The ID of the current process.

Bare.exitCode [#bareexitcode]

The code returned once the process exits. If the process exits via `Bare.exit()` without a code, `Bare.exitCode` is used.

Bare.version [#bareversion]

The Bare version string.

Bare.versions [#bareversions]

An object of version strings for Bare and its dependencies.

Lifecycle methods [#lifecycle-methods]

Bare.exit([code]) [#bareexitcode-1]

Immediately terminate the process or current thread with exit status `code`, defaulting to `Bare.exitCode`.

Bare.suspend([linger]) [#baresuspendlinger]

Suspend the process and all threads, emitting a `suspend` event so work can stop. When no work remains and the process would otherwise exit, an `idle` event is emitted and the loop blocks instead of exiting.

Bare.wakeup([deadline]) [#barewakeupdeadline]

Wake the process and all threads during suspension, emitting a `wakeup` event. Work may run until `deadline`, after which the process suspends again.

Bare.idle() [#bareidle]

Immediately suspend the event loop and trigger the `idle` event.

Bare.resume() [#bareresume]

Resume the process and all threads after suspension, emitting a `resume` event. May be called from a `suspend`, `wakeup`, or `idle` listener to cancel suspension.

Events [#events]

Listeners attach with `Bare.on(event, listener)`.

uncaughtException— (err) [#uncaughtexception-err]

A JavaScript exception was thrown without being caught. By default uncaught exceptions are printed to `stderr` and the process is aborted; adding a listener overrides that default.

unhandledRejection— (reason, promise) [#unhandledrejection-reason-promise]

A promise was rejected without being handled. Default behaviour (print to `stderr`, abort) is overridden by adding a listener.

beforeExit— (code) [#beforeexit-code]

Emitted when the loop runs out of work, before the process or thread exits. Scheduling more work here keeps the process alive and re-arms the event. Not emitted on explicit `Bare.exit()` or an uncaught exception.

exit— (code) [#exit-code]

Emitted when the process or thread exits.

<Callout type="warn">
  Additional work **must not** be scheduled from an `exit` listener. If the process is forcefully terminated from within an `exit` listener, the remaining listeners will not run.
</Callout>

suspend— (linger), wakeup— (deadline), idle— (), resume— () [#suspend-linger-wakeup-deadline-idle--resume-]

The lifecycle events described under [Lifecycle methods](#lifecycle-methods). Defer or pause outstanding work on `suspend`, do bounded work on `wakeup`, expect the loop to block after `idle`, and continue work on `resume`. A listener may call `Bare.resume()` to cancel the suspension before it completes.

Lifecycle [#lifecycle]

Bare exposes process suspension so it can behave on platforms with strict application-lifecycle rules—mobile in particular. A suspended loop stays alive but idle rather than exiting, and can be woken for bounded bursts of work. The same transitions are available from C (`bare_suspend()`, `bare_wakeup()`, `bare_resume()`) and from JavaScript.

<Mermaid
  chart="stateDiagram-v2
  direction LR
  [*] --> Active
  Active --> Suspending: Bare.suspend()
  Active --> Terminated: Bare.exit()
  Active --> Exiting
  Suspending --> Active: Bare.resume()
  Suspending --> Awake: Bare.wakeup()
  Suspending --> Suspended: Bare.idle()
  Suspending --> Terminated: Bare.exit()
  Suspending --> Idle
  Awake --> Active: Bare.resume()
  Awake --> Suspended: Bare.idle()
  Awake --> Terminated: Bare.exit()
  Awake --> Idle
  Idle --> Suspended
  Idle --> Active: Bare.resume()
  Idle --> Terminated: Bare.exit()
  Suspended --> Active
  Suspended --> Awake: Bare.wakeup()
  Terminated --> Exiting
  Exiting --> [*]"
/>

For the rationale, see [Inside Bare](/explanation/bare-runtime#the-lifecycle); for driving it from a native host, see [One core, many platforms](/explanation/bare-on-native).

Bare.Addon [#bareaddon]

Loads native addons—typically C/C++ shared libraries.

<Callout type="info">
  This is an advanced API most users never touch directly; native addons are normally loaded for you by the modules that need them.
</Callout>

* `new Addon(url)` <Since v="1.31.0" /> — load a static or dynamic addon from a `url` whose protocol is `builtin:`, `linked:`, or `file:`. Throws for any other protocol, or if loading fails. Returns an `addon` with `addon.url` and `addon.exports`.
* `Addon.host`— the target triplet identifying the current addon host.
* <Until v="1.31.0" label="Deprecated in 1.31.0" /> `Addon.cache`, `Addon.load(url)`, `Addon.resolve(specifier, parentURL[, options])`— superseded by `new Addon(url)`. Still work, but new code should use the constructor.

Bare.Thread [#barethread]

Lightweight threads with synchronous joins—similar to Node.js workers but with a minimal surface.

* `Thread.isMainThread`— `true` on the main thread.
* `Thread.self`— the current thread as a `ThreadProxy`, or `null` on the main thread. `Thread.self.data` is the data passed on creation.
* `new Thread([filename][, options][, callback])`— start a thread running `filename`. If `callback` is given, its body runs on the new thread with `Thread.self.data` as its argument. Options: `data`, `transfer`, `source`, `encoding`, `stackSize`.
* <Until v="1.31.0" label="Deprecated in 1.31.0" /> `Thread.create(...)`— equivalent to `new Thread(...)`. Still works, but new code should use the constructor.
* `thread.joined`— whether the thread has been joined.
* `thread.join()`— block until the thread exits.
* `thread.suspend([linger])`, `thread.wakeup([deadline])`, `thread.resume()`, `thread.terminate()`— drive the thread's lifecycle, equivalent to calling the matching `Bare.*` method inside it.

Higher-level worker threads are available in [`bare-worker`](/reference/modules/bare-modules).

Bare.IPC [#bareipc]

Optional streaming communication between an embedder and JavaScript. Defaults to `null`, meaning no streaming channel is set. When an embedder provides one, `Bare.IPC` is a [`bare-stream`](/reference/modules/bare-modules) `Duplex`. The higher-level [`bare-kit`](/reference/bare/bare-kit) IPC abstraction is built on this.

Embedding [#embedding]

Bare can be embedded with the C API in [`include/bare.h`](https://github.com/holepunchto/bare/blob/main/include/bare.h):

```c
#include <bare.h>
#include <uv.h>

bare_t *bare;
bare_setup(uv_default_loop(), platform, &env /* Optional */, argc, argv, options, &bare);
bare_load(bare, filename, source, &module /* Optional */);
bare_run(bare, UV_RUN_DEFAULT);

int exit_code;
bare_teardown(bare, UV_RUN_DEFAULT, &exit_code);
```

If `source` is `NULL`, the contents of `filename` are read at runtime. For platform shells that wrap this API, see [`bare-ios`](https://github.com/holepunchto/bare-ios) and [`bare-android`](https://github.com/holepunchto/bare-android), or use [`bare-kit`](/reference/bare/bare-kit), which packages embedding behind a worklet API.

See also [#see-also]

* [Inside Bare](/explanation/bare-runtime)—what the runtime adds and why.
* [`bare` CLI](/reference/bare/cli)—run scripts and start a REPL.
* [`bare-kit` reference](/reference/bare/bare-kit)—embed a Bare worklet in a native app.
* [Bare modules](/reference/modules/bare-modules)—the `bare-*` standard library.


# Autobase



<Status level="stable" />

Autobase is a higher-level composition over underlying [Hypercores](/reference/building-blocks/hypercore). Writers append causal nodes to local cores, Autobase linearizes that graph into an eventually consistent order, and your `apply` handler materializes a deterministic view, often into a [Hyperbee](/reference/building-blocks/hyperbee).

The apply handler [#the-apply-handler]

Treat `apply` like a **pure reducer**: given an ordered batch of nodes and a view handle, derive the next view state deterministically. Mutate only the `view` passed into `apply`. Do not:

* read or write external globals,
* open network connections, or
* assume ordering that Autobase has not yet committed.
  **Side effects belong outside the linearization path.**

Autobase can reorder previously seen nodes when new causal information arrives. If `apply` is non-deterministic, different peers will diverge. Writer management (`host.addWriter`, indexer flags) and migration between `apply` versions are advanced topics—keep them inside `apply` only when they operate on the provided `view` and `host` handles.

Install [#install]

```sh
npm i autobase
```

Quickstart [#quickstart]

This minimal flow opens a view, appends one record, updates the linearizer, and reads the materialized value back from `base.view`.

```js
import Corestore from 'corestore'
import Autobase from 'autobase'

const store = new Corestore('./autobase-demo')
const base = new Autobase(store, null, {
  valueEncoding: 'json',
  open: (viewStore) => viewStore.get({ name: 'messages', valueEncoding: 'json' }),
  apply: async (nodes, view) => {
    for (const { value } of nodes) await view.append(value)
  }
})

await base.ready()
await base.append({ type: 'message', text: 'hello from Autobase' })
await base.update()

console.log(await base.view.get(0))
// { type: 'message', text: 'hello from Autobase' }
```

Autobase can reorder previously seen nodes as new causal information arrives. Keep `open` and `apply` deterministic, derive state from the provided `store`, and mutate only the provided `view` inside `apply`.

API Reference [#api-reference]

Constructor and lifecycle [#constructor-and-lifecycle]

new Autobase(store, bootstrap, opts) [#new-autobasestore-bootstrap-opts]

[src](https://github.com/holepunchto/autobase/blob/v7.28.1/index.js#L77)

Instantiate an Autobase.

| Parameter   | Type                                                                | Default | Description                                                                                                                                                        |
| ----------- | ------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `store`     | [`Corestore`](/reference/helpers/corestore)                         | —       | The Corestore that holds the system, writer, and view cores.                                                                                                       |
| `bootstrap` | [`Buffer\|string`](https://nodejs.org/api/buffer.html#class-buffer) | —       | Key of an existing Autobase to load; omit or pass `null` to create a new one.                                                                                      |
| `opts`      | `object`                                                            | `{}`    | Configuration: `open`, `apply`, `close`, `valueEncoding`, `ackInterval`, `fastForward`, `encrypt`/`encryptionKey`, `optimistic`, and more (see the options table). |

| Option          | Default | Description                                                                                                   |
| --------------- | ------- | ------------------------------------------------------------------------------------------------------------- |
| `open`          | —       | create the view                                                                                               |
| `apply`         | —       | handle nodes to update view                                                                                   |
| `optimistic`    | `false` | Autobase supports optimistic appends                                                                          |
| `close`         | —       | close the view                                                                                                |
| `valueEncoding` | —       | encoding                                                                                                      |
| `ackInterval`   | `10000` | enable auto acking with the interval                                                                          |
| `encryptionKey` | —       | Key to encrypt the base                                                                                       |
| `encrypt`       | `false` | Encrypt the base if unencrypted & no encryptionKey is set                                                     |
| `encrypted`     | `false` | Expect the base to be encrypted, will throw an error otherwise, defaults to true if encryptionKey is set      |
| `fastForward`   | `true`  | Enable fast forwarding. If passing \{ key: base.core.key }, they autobase will fastforward to that key first. |
| `wakeup`        | —       | Set a custom wakeup protocol for hinting which writers are active, see `protomux-wakeup` for protocol details |
| `bigBatches`    | `false` | Enable big batches. See `base.setBigBatches()` for details.                                                   |

```js
const base = new Autobase(store, bootstrap, {
  optimistic: true,
  async apply(nodes, view, host) {
    for (const node of nodes) {
      const { value } = node
      // Verify block
      if (value.password !== 'secrets') continue

      // Acknowledge only even numbers
      if (value.num % 2 === 0) await host.ackWriter(node.from.key)

      await view.append(value.num)
    }
  }
})

// Passing the password 'secrets' represents being verifiable
await base.append({ num: 3, password: 'secrets' }, { optimistic: true }) // will not be applied because `ackWriter` isnt called
await base.append({ num: 2, password: 'secrets' }, { optimistic: true }) // will be applied
await base.append({ num: 4, password: 'incorrect' }, { optimistic: true }) // will not be applied because the block isn't verifiable
```

When `optimistic` is enabled, validate optimistic blocks inside `apply` before calling `host.ackWriter(key)`. Otherwise any peer that can write to the underlying network path could attempt to inject values.

await base.ready() [#await-baseready]

Resolves once the base and its view are open and ready to use.

State and derived view [#state-and-derived-view]

base.view [#baseview]

[src](https://github.com/holepunchto/autobase/blob/v7.28.1/index.js#L187)

The view of the autobase derived from writer inputs. The view is created in the `open` handler and can have any shape. The most common `view` is a [hyperbee](https://github.com/holepunchto/hyperbee).

* Returns: `*`

base.key [#basekey]

[src](https://github.com/holepunchto/autobase/blob/v7.28.1/index.js#L90)

The primary key of the autobase.

* Returns: [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer)

base.discoveryKey [#basediscoverykey]

[src](https://github.com/holepunchto/autobase/blob/v7.28.1/index.js#L91)

The discovery key associated with the autobase.

* Returns: [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer)

base.isIndexer [#baseisindexer]

[src](https://github.com/holepunchto/autobase/blob/v7.28.1/index.js#L110)

Whether the instance is an indexer.

* Returns: `boolean`

base.writable [#basewritable]

[src](https://github.com/holepunchto/autobase/blob/v7.28.1/index.js#L242)

Whether the instance is a writer for the autobase.

* Returns: `boolean`

base.length [#baselength]

[src](https://github.com/holepunchto/autobase/blob/v7.28.1/index.js#L258)

The length of the system core. This is neither the length of the local writer nor the length of the view. The system core tracks the autobase as a whole.

* Returns: `number`

base.signedLength [#basesignedlength]

[src](https://github.com/holepunchto/autobase/blob/v7.28.1/index.js#L250)

The index of the system core that has been signed by a quorum of indexers. The system up until this point will not change.

* Returns: `number`

base.paused [#basepaused]

[src](https://github.com/holepunchto/autobase/blob/v7.28.1/index.js#L166)

Whether the base is currently paused.

* Returns: `boolean` — `true` if the autobase is currently paused, otherwise returns `false`.

Writes and linearization [#writes-and-linearization]

await base.append(value, opts) [#await-baseappendvalue-opts]

[src](https://github.com/holepunchto/autobase/blob/v7.28.1/index.js#L1010)

Append a new entry to the autobase.

| Parameter | Type                                                                                                    | Description                               |
| --------- | ------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
| `value`   | [`*\|Array<*>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) | The value, or array of values, to append. |
| `opts`    | [`AppendOptions`](#appendoptions)                                                                       | Append options.                           |

* Returns: [`Promise<number>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) — Resolves to the new core length once the value (or batch) has been appended.
* Throws:
  * if the autobase is closing.
  * if the local writer is not active/writable.

await base.update() [#await-baseupdate]

[src](https://github.com/holepunchto/autobase/blob/v7.28.1/index.js#L894)

Fetch all available data and update the linearizer.

* Returns: [`Promise<void>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) — Resolves once the linearizer has advanced.

```js
await base.update()
```

await base.ack(bg = false) [#await-baseackbg--false]

[src](https://github.com/holepunchto/autobase/blob/v7.28.1/index.js#L934)

Manually acknowledge the current state by appending a `null` node that references known head nodes. `null` nodes are ignored by the `apply` handler and only serve as a way to acknowledge the current linearized state. Only indexers can ack.

| Parameter | Type      | Default | Description                                                                                                                             |
| --------- | --------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `bg`      | `boolean` | `false` | If `bg` is set to `true`, the ack will not be appended immediately but will set the automatic ack timer to trigger as soon as possible. |

* Returns: [`Promise<void>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) — Resolves once the ack has been handled.

```js
await base.ack()
```

Only indexers can acknowledge. An ack appends a `null` node that references the known heads so peers can converge faster without changing the view.

base.heads() [#baseheads]

[src](https://github.com/holepunchto/autobase/blob/v7.28.1/index.js#L297)

Gets the current writer heads. A writer head is a node which has no causal dependents, aka it is the latest write. If there is more than one head, there is a causal fork which is pretty common.

* Returns: [`Array<object>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) — The head nodes (empty until the base is ready).

```js
const heads = base.heads()
```

await base.pause() [#await-basepause]

[src](https://github.com/holepunchto/autobase/blob/v7.28.1/index.js#L1983)

Pauses the autobase, preventing the next apply from running until `resume()` is called.

* Returns: `void`

```js
base.pause()
```

await base.resume() [#await-baseresume]

[src](https://github.com/holepunchto/autobase/blob/v7.28.1/index.js#L1987)

Resumes a paused autobase and will check for an update.

* Returns: `void`

```js
base.resume()
```

base.setBigBatches(enable = true) [#basesetbigbatchesenable--true]

[src](https://github.com/holepunchto/autobase/blob/v7.28.1/index.js#L326)

Set the autobase to enable or disable big batches. Big batches allow autobase to run the `apply` function on more blocks at once at the expense of being slower and less responsive.

| Parameter | Type      | Default | Description                    |
| --------- | --------- | ------- | ------------------------------ |
| `enable`  | `boolean` | `true`  | Whether to enable big batches. |

* Returns: `void`

```js
base.setBigBatches(true)
```

Big batches let Autobase call `apply` with more nodes at once, trading responsiveness for larger deterministic batches.

Replication and metadata [#replication-and-metadata]

await base.hash() [#await-basehash]

[src](https://github.com/holepunchto/autobase/blob/v7.28.1/index.js#L266)

Merkle-tree hash of the system core at its current length.

* Returns: [`Promise<Buffer>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) — the hash of the system core's merkle tree roots.

```js
const hash = await base.hash()
```

base.replicate(isInitiator || stream, opts) [#basereplicateisinitiator--stream-opts]

[src](https://github.com/holepunchto/autobase/blob/v7.28.1/index.js#L291)

Creates a replication stream for replicating the autobase. Arguments are the same as [corestores's `.replicate()`](https://github.com/holepunchto/corestore?tab=readme-ov-file#const-stream--storereplicateoptsorstream).

| Parameter     | Type                                                    | Description                                                                          |
| ------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| `isInitiator` | [`boolean\|Stream`](https://nodejs.org/api/stream.html) | `true`/`false` to open a new stream, or an existing replication stream to attach to. |
| `opts`        | `object`                                                | Replication options forwarded to the underlying Corestore.                           |

* Returns: [`Stream`](https://nodejs.org/api/stream.html) — The replication stream.

```js
const swarm = new Hyperswarm()

// Join a topic
swarm.join(base.discoveryKey)

swarm.on('connection', (connection) => base.replicate(connection))
```

await base.setUserData(key, value) [#await-basesetuserdatakey-value]

[src](https://github.com/holepunchto/autobase/blob/v7.28.1/index.js#L1129)

Sets the [User Data](https://github.com/holepunchto/hypercore#user-data) value for the provided `key`. `key` is a string. `value` can be either a string or a buffer.

| Parameter | Type                                                                |
| --------- | ------------------------------------------------------------------- |
| `key`     | `string`                                                            |
| `value`   | [`Buffer\|string`](https://nodejs.org/api/buffer.html#class-buffer) |

* Returns: [`Promise<void>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) — Resolves once written.

```js
await base.setUserData('nickname', 'alice')
```

await base.getUserData(key) [#await-basegetuserdatakey]

[src](https://github.com/holepunchto/autobase/blob/v7.28.1/index.js#L1136)

Read a local-only value previously stored with `setUserData()`.

| Parameter | Type     | Description  |
| --------- | -------- | ------------ |
| `key`     | `string` | is a string. |

* Returns: [`Promise<Buffer\|null>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) — the [User Data](https://github.com/holepunchto/hypercore#user-data) value for the provided `key`.

```js
const nickname = await base.getUserData('nickname')
```

Static helpers [#static-helpers]

Autobase.getLocalCore(store, handlers, encryptionKey) [#autobasegetlocalcorestore-handlers-encryptionkey]

[src](https://github.com/holepunchto/autobase/blob/v7.28.1/index.js#L1093)

Generate a local core to be used for an Autobase.

| Parameter       | Type                                                        | Description                                        |
| --------------- | ----------------------------------------------------------- | -------------------------------------------------- |
| `store`         | [`Corestore`](/reference/helpers/corestore)                 | The Corestore to open the core from.               |
| `handlers`      | `object`                                                    | are any options passed to `store` to get the core. |
| `encryptionKey` | [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer) | Encryption key, when the core is encrypted.        |

* Returns: [`Hypercore`](/reference/building-blocks/hypercore) — The local writer core.

```js
const core = Autobase.getLocalCore(store)
```

await Autobase.getUserData(core) [#await-autobasegetuserdatacore]

[src](https://github.com/holepunchto/autobase/blob/v7.28.1/index.js#L1106)

Get user data associated with an autobase `core`. `referrer` is the `.key` of the autobase the `core` is from. `view` is the `name` of the view.

| Parameter | Type                                                | Description                            |
| --------- | --------------------------------------------------- | -------------------------------------- |
| `core`    | [`Hypercore`](/reference/building-blocks/hypercore) | The bootstrap/local core to read from. |

* Returns: [`Promise<{referrer: Buffer, view: string\|null}>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) — The referrer and view name.

```js
const { referrer, view } = await Autobase.getUserData(core)
```

await Autobase.isAutobase(core, opts) [#await-autobaseisautobasecore-opts]

[src](https://github.com/holepunchto/autobase/blob/v7.28.1/index.js#L1115)

Detect whether a core's first block is an Autobase oplog message.

| Parameter | Type                                                | Default | Description                                                                                                                                           |
| --------- | --------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `core`    | [`Hypercore`](/reference/building-blocks/hypercore) | —       | The core to inspect.                                                                                                                                  |
| `opts`    | `object`                                            | `{}`    | are the same options as [core.get(index, opts)](https://github.com/holepunchto/hypercore?tab=readme-ov-file#const-block--await-coregetindex-options). |

* Returns: [`Promise<boolean>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) — whether the core is an autobase core.

```js
const isBase = await Autobase.isAutobase(core)
```

View store helper [#view-store-helper]

store.get(name || { name, valueEncoding }) [#storegetname---name-valueencoding-]

Load a `Hypercore` by name (passed as `name`). `name` should be passed as a string.

* Throws: if no `name` is provided.

This `store` instance is the `AutoStore` passed into `open`, and it is the intended place to create the cores that make up your deterministic view.

Apply host calls [#apply-host-calls]

await host.addWriter(key, { indexer = true }) [#await-hostaddwriterkey--indexer--true-]

Add a writer with the given `key` to the autobase allowing their local core to append. If `indexer` is `true`, it will be added as an indexer.

| Parameter   | Default  |
| ----------- | -------- |
| `{ indexer` | `true }` |

* Throws: if called on the read-only public view.

await host.removeWriter(key) [#await-hostremovewriterkey]

Remove a writer from the autobase. This will throw if the writer cannot be removed.

* Throws: if called on the read-only public view, or if it would remove the last indexer.

This throws when the writer cannot be removed, such as when it would leave the system without a removable indexer set.

await host.ackWriter(key) [#await-hostackwriterkey]

Acknowledge a writer even if they haven't been added before. This is most useful for applying `optimistic` blocks from writers that are not currently a writer.

* Throws: if called on the read-only public view.

host.interrupt(reason) [#hostinterruptreason]

Interrupt the applying of writer blocks optionally giving a `reason`. This will emit an `interrupt` event passing the `reason` to the callback and halt all further applying. The base is not closed, but `base.interrupted` is set to the `reason` and later `base.append()` calls reject.

* Throws: if called on the read-only public view.

Interrupting halts applying and emits the `interrupt` event so the application can upgrade its `apply` logic or recover intentionally.

host.removeable(key) [#hostremoveablekey]

[src](https://github.com/holepunchto/autobase/blob/v7.28.1/lib/apply-calls.js#L91)

Whether the writer with `key` can be removed without leaving the system
without a removable indexer set.

| Parameter | Type                                                        | Description       |
| --------- | ----------------------------------------------------------- | ----------------- |
| `key`     | [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer) | The writer's key. |

* Returns: `boolean` — whether the writer for the given `key` can be removed.

```js
if (host.removeable(writerKey)) await host.removeWriter(writerKey)
```

The last indexer cannot be removed.

Events [#events]

base.on('update', () => { ... }) [#baseonupdate-----]

[src](https://github.com/holepunchto/autobase/blob/v7.28.1/index.js#L2060)

Triggered when the autobase view updates after `apply` has finished running.

base.on('interrupt', (reason) => { ... }) [#baseoninterrupt-reason----]

[src](https://github.com/holepunchto/autobase/blob/v7.28.1/index.js#L838)

Triggered when `host.interrupt(reason)` is called in the `apply` handler. See [`host.interrupt(reason)`](#hostinterruptreason) for when interrupts are used.

base.on('fast-forward', (to, from) => { ... }) [#baseonfast-forward-to-from----]

[src](https://github.com/holepunchto/autobase/blob/v7.28.1/index.js#L1502)

Triggered when the autobase fast forwards to a state already with a quorum. `to` and `from` are the `.signedLength` after and before the fast forward respectively.

base.on('is-indexer', () => { ... }) [#baseonis-indexer-----]

[src](https://github.com/holepunchto/autobase/blob/v7.28.1/index.js#L1712)

Triggered when the autobase instance is an indexer.

base.on('is-non-indexer', () => { ... }) [#baseonis-non-indexer-----]

[src](https://github.com/holepunchto/autobase/blob/v7.28.1/index.js#L1723)

Triggered when the autobase instance is not an indexer.

base.on('writable', () => { ... }) [#baseonwritable-----]

Triggered when the autobase instance is now a writer.

base.on('unwritable', () => { ... }) [#baseonunwritable-----]

Triggered when the autobase instance is no longer a writer.

base.on('warning', (warning) => { ... }) [#baseonwarning-warning----]

Triggered when a warning is triggered.

base.on('error', (err) => { ... }) [#baseonerror-err----]

[src](https://github.com/holepunchto/autobase/blob/v7.28.1/index.js#L852)

Triggered when an error is triggered while updating the autobase.

Types [#types]

AppendOptions [#appendoptions]

Options for `base.append()`.

| Property     | Type      | Default | Description                                                                                                      |
| ------------ | --------- | ------- | ---------------------------------------------------------------------------------------------------------------- |
| `optimistic` | `boolean` | `false` | Allow appending on an optimistic Autobase while not a writer; the block is only applied if validated in `apply`. |

See also [#see-also]

* [Work with many Hypercores using Corestore](/how-to/store-and-replicate/work-with-many-hypercores-using-corestore)—manage the groups of cores that Autobase coordinates.
* [Corestore](/reference/helpers/corestore)—storage and replication manager typically used for Autobase system, writer, and view cores.
* [Hypercore](/reference/building-blocks/hypercore)—append-only log primitive that Autobase writers build on.
* [Hyperbee](/reference/building-blocks/hyperbee)—common materialized-view target for deterministic indexed state.


# Hyperbee



<Status level="stable" />

`Hyperbee` stores sorted key/value entries in an append-only B-tree backed by [`Hypercore`](/reference/building-blocks/hypercore). Use it when you need ordered lookups, range scans, atomic batches, namespaces, and point-in-time snapshots over one replicated log.

Install [#install]

```sh
npm i hyperbee
```

Quickstart [#quickstart]

```js
import Hypercore from 'hypercore'
import Hyperbee from 'hyperbee'

const core = new Hypercore('./bee-storage')
const db = new Hyperbee(core, {
  keyEncoding: 'utf-8',
  valueEncoding: 'json'
})

await db.ready()
await db.put('config', { theme: 'dark', retries: 3 })

const entry = await db.get('config')
console.log(entry.value.theme)

await db.close()
```

API Reference [#api-reference]

Constructor and readiness [#constructor-and-readiness]

new Hyperbee(core, [options]) [#new-hyperbeecore-options]

[src](https://github.com/holepunchto/hyperbee/blob/v2.27.3/index.js#L405)

Make a new Hyperbee instance. `core` should be a [Hypercore](https://github.com/holepunchto/hypercore).

| Parameter | Type                                                | Default |
| --------- | --------------------------------------------------- | ------- |
| `core`    | [`Hypercore`](/reference/building-blocks/hypercore) | —       |
| `options` | [`HyperbeeOptions`](#hyperbeeoptions)               | `{}`    |

Read and diff streams sort keys by their encoded byte values, so choose `keyEncoding` deliberately if lexicographic order matters.

await db.ready() [#await-dbready]

Waits until internal state is loaded.

Properties and identity [#properties-and-identity]

db.core [#dbcore]

[src](https://github.com/holepunchto/hyperbee/blob/v2.27.3/index.js#L409)

The underlying Hypercore backing this bee.

* Returns: [`Hypercore`](/reference/building-blocks/hypercore)

db.version [#dbversion]

[src](https://github.com/holepunchto/hyperbee/blob/v2.27.3/index.js#L467)

Number that indicates how many modifications were made, useful as a version identifier.

* Returns: `number`

db.id [#dbid]

[src](https://github.com/holepunchto/hyperbee/blob/v2.27.3/index.js#L471)

String containing the id (z-base-32 of the public key) identifying this bee.

* Returns: `string`

db.key [#dbkey]

[src](https://github.com/holepunchto/hyperbee/blob/v2.27.3/index.js#L475)

Buffer containing the public key identifying this bee.

* Returns: [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer)

db.discoveryKey [#dbdiscoverykey]

[src](https://github.com/holepunchto/hyperbee/blob/v2.27.3/index.js#L479)

Buffer containing a key derived from `db.key`.

* Returns: [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer)

db.writable [#dbwritable]

[src](https://github.com/holepunchto/hyperbee/blob/v2.27.3/index.js#L483)

Boolean indicating if we can put or delete data in this bee.

* Returns: `boolean`

db.readable [#dbreadable]

[src](https://github.com/holepunchto/hyperbee/blob/v2.27.3/index.js#L487)

Boolean indicating if we can read from this bee. After closing the bee this will be `false`.

* Returns: `boolean`

Writes and batches [#writes-and-batches]

await db.put(key, [value], [options]) [#await-dbputkey-value-options]

[src](https://github.com/holepunchto/hyperbee/blob/v2.27.3/index.js#L647)

Insert a new key. Value can be optional.

| Parameter | Type                        | Description                                        |
| --------- | --------------------------- | -------------------------------------------------- |
| `key`     | `*`                         | The key to insert (encoded per `keyEncoding`).     |
| `value`   | `*`                         | The value to store; optional for key-only entries. |
| `options` | [`PutOptions`](#putoptions) | —                                                  |

* Returns: [`Promise<void>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) — Resolves once the write is committed to the core.

```js
{
  cas (prev, next) { return true }
}
```

```js
await db.put('number', '123', { cas })
console.log(await db.get('number')) // => { seq: 1, key: 'number', value: '123' }

await db.put('number', '123', { cas })
console.log(await db.get('number')) // => { seq: 1, key: 'number', value: '123' }
// Without cas this would have been { seq: 2, ... }, and the next { seq: 3 }

await db.put('number', '456', { cas })
console.log(await db.get('number')) // => { seq: 2, key: 'number', value: '456' }

function cas(prev, next) {
  // You can use same-data or same-object lib, depending on the value complexity
  return prev.value !== next.value
}
```

The `cas` comparator receives the current node as `prev` and the potential new node as `next`. It runs only when the key already exists.

await db.del(key, [options]) [#await-dbdelkey-options]

[src](https://github.com/holepunchto/hyperbee/blob/v2.27.3/index.js#L656)

Delete a key.

| Parameter | Type                        | Description                                    |
| --------- | --------------------------- | ---------------------------------------------- |
| `key`     | `*`                         | The key to delete (encoded per `keyEncoding`). |
| `options` | [`PutOptions`](#putoptions) | —                                              |

* Returns: [`Promise<void>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) — Resolves once the deletion is committed to the core.

```js
{
  cas (prev, next) { return true }
}
```

```js
// This won't get deleted
await db.del('number', { cas })
console.log(await db.get('number')) // => { seq: 1, key: 'number', value: 'value' }

// Change the value so the next time we try to delete it then "cas" will return true
await db.put('number', 'can-be-deleted')

await db.del('number', { cas })
console.log(await db.get('number')) // => null

function cas(prev) {
  return prev.value === 'can-be-deleted'
}
```

The delete comparator runs only when the key exists. Deleting a missing key succeeds without calling `cas`.

db.batch() [#dbbatch]

[src](https://github.com/holepunchto/hyperbee/blob/v2.27.3/index.js#L652)

Make a new atomic batch that is either fully processed or not processed at all.

| Parameter | Type                            | Description    |
| --------- | ------------------------------- | -------------- |
| `opts`    | [`BatchOptions`](#batchoptions) | Batch options. |

* Returns: [`Batch`](/reference/building-blocks/hyperbee) — A new batch; queue writes on it and call `flush()` to commit.

```js
const batch = db.batch()
await batch.put('key', 'value')
await batch.flush()
```

Use batches when you need grouped writes or lower overhead for many updates.

await batch.put(key, [value], [options]) [#await-batchputkey-value-options]

[src](https://github.com/holepunchto/hyperbee/blob/v2.27.3/index.js#L1117)

Insert a key into a batch.

| Parameter | Type                        | Description                                                             |
| --------- | --------------------------- | ----------------------------------------------------------------------- |
| `key`     | `*`                         | The key to insert (encoded per the batch's `keyEncoding`).              |
| `value`   | `*`                         | The value to store (encoded per the batch's `valueEncoding`); optional. |
| `options` | [`PutOptions`](#putoptions) | `options` are the same as `db.put` method.                              |

* Returns: [`Promise<void>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) — Resolves after queuing the write inside the batch.

```js
await batch.put('key', 'value')
```

await batch.get(key) [#await-batchgetkey]

[src](https://github.com/holepunchto/hyperbee/blob/v2.27.3/index.js#L1033)

Get a key, value out of a batch.

| Parameter | Type                        | Description                                                 |
| --------- | --------------------------- | ----------------------------------------------------------- |
| `key`     | `*`                         | The key to look up (encoded per the batch's `keyEncoding`). |
| `opts`    | [`GetOptions`](#getoptions) | Read options.                                               |

* Returns: [`Promise<Entry\|null>`](#entry) — The pending or committed entry visible within the batch, or `null` when missing.

```js
const entry = await batch.get('key')
```

await batch.del(key, [options]) [#await-batchdelkey-options]

[src](https://github.com/holepunchto/hyperbee/blob/v2.27.3/index.js#L1206)

Delete a key into the batch.

| Parameter | Type                        | Description                                                |
| --------- | --------------------------- | ---------------------------------------------------------- |
| `key`     | `*`                         | The key to delete (encoded per the batch's `keyEncoding`). |
| `options` | [`PutOptions`](#putoptions) | `options` are the same as `db.del` method.                 |

* Returns: [`Promise<void>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) — Resolves after queuing the delete inside the batch.

```js
await batch.del('key')
```

await batch.flush() [#await-batchflush]

[src](https://github.com/holepunchto/hyperbee/blob/v2.27.3/index.js#L1327)

Commit the batch to the database, and releases any locks it has acquired.

* Returns: [`Promise<void>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) — Resolves after committing the queued operations and releasing the batch lock.

```js
await batch.flush()
```

await batch.close() [#await-batchclose]

[src](https://github.com/holepunchto/hyperbee/blob/v2.27.3/index.js#L1278)

Destroy a batch, and releases any locks it has acquired on the db.

* Returns: [`Promise<void>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) — Resolves after discarding the batch and releasing any lock it holds.

```js
await batch.close()
```

Call `batch.close()` when you want to abort a batch without writing it.

Reads and iteration [#reads-and-iteration]

await db.get(key) [#await-dbgetkey]

[src](https://github.com/holepunchto/hyperbee/blob/v2.27.3/index.js#L637)

Get a key's value. Returns `null` if key doesn't exists.

| Parameter | Type                        | Description                                     |
| --------- | --------------------------- | ----------------------------------------------- |
| `key`     | `*`                         | The key to look up (encoded per `keyEncoding`). |
| `opts`    | [`GetOptions`](#getoptions) | Read options.                                   |

* Returns: [`Promise<Entry\|null>`](#entry) — The entry, or `null` if the key is not present.

```js
const entry = await db.get('key') // => { seq, key, value } or null
```

await db.getBySeq(seq, [options]) [#await-dbgetbyseqseq-options]

[src](https://github.com/holepunchto/hyperbee/blob/v2.27.3/index.js#L642)

Get the key and value from a block number.

| Parameter | Type                        | Description             |
| --------- | --------------------------- | ----------------------- |
| `seq`     | `number`                    | is the Hypercore index. |
| `options` | [`GetOptions`](#getoptions) | Read options.           |

* Returns: [`Promise<{key: *, value: *}>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) — The block's key and value.

```js
const { key, value } = await db.getBySeq(1)
```

db.createReadStream([range], [options]) [#dbcreatereadstreamrange-options]

[src](https://github.com/holepunchto/hyperbee/blob/v2.27.3/index.js#L543)

Make a read stream. Sort order is based on the binary value of the keys.

| Parameter | Type                                      | Description                                                   |
| --------- | ----------------------------------------- | ------------------------------------------------------------- |
| `range`   | [`Range`](#range)                         | should specify the range you want to read and looks like this |
| `options` | [`ReadStreamOptions`](#readstreamoptions) | —                                                             |

* Returns: [`Readable`](https://nodejs.org/api/stream.html#class-streamreadable) — A stream of `Entry` objects.

await db.peek([range], [options]) [#await-dbpeekrange-options]

[src](https://github.com/holepunchto/hyperbee/blob/v2.27.3/index.js#L499)

Similar to doing a read stream and returning the first value, but a bit faster than that.

| Parameter | Type                                      | Description                                                           |
| --------- | ----------------------------------------- | --------------------------------------------------------------------- |
| `range`   | [`Range`](#range)                         | bounds to search within.                                              |
| `options` | [`ReadStreamOptions`](#readstreamoptions) | Read options (`reverse` selects the last entry instead of the first). |

* Returns: [`Promise<Entry\|null>`](#entry) — The first matching entry, or `null` if the range is empty.

```js
const first = await db.peek({ gte: 'a', lt: 'd' })
```

History and change tracking [#history-and-change-tracking]

db.createHistoryStream([options]) [#dbcreatehistorystreamoptions]

[src](https://github.com/holepunchto/hyperbee/blob/v2.27.3/index.js#L548)

Create a stream of all entries ever inserted or deleted from the db.

| Parameter | Type                                            |
| --------- | ----------------------------------------------- |
| `options` | [`HistoryStreamOptions`](#historystreamoptions) |

* Returns: [`Readable`](https://nodejs.org/api/stream.html#class-streamreadable) — A stream of `Entry` objects, each with an added `type` (`'put'` or `'del'`).

db.createDiffStream(otherVersion, [options]) [#dbcreatediffstreamotherversion-options]

[src](https://github.com/holepunchto/hyperbee/blob/v2.27.3/index.js#L557)

Efficiently create a stream of the shallow changes between two versions of the db.

| Parameter | Type                                                      | Description                                                                   |
| --------- | --------------------------------------------------------- | ----------------------------------------------------------------------------- |
| `right`   | [`number\|Hyperbee`](/reference/building-blocks/hyperbee) | The other version to diff against: a version number, or another bee/snapshot. |
| `range`   | [`Range`](#range)                                         | `options` are the same as `db.createReadStream`, except for `reverse`.        |
| `opts`    | [`ReadStreamOptions`](#readstreamoptions)                 | Read options.                                                                 |

* Returns: [`Readable`](https://nodejs.org/api/stream.html#class-streamreadable) — A stream of `{ left, right }` pairs, where each side is an `Entry` or `null`.

| Property | Type     | Description                 |
| -------- | -------- | --------------------------- |
| `left`   | `Object` | The entry in the `db`       |
| `right`  | `Object` | The entry in `otherVersion` |

Causally equal entries are omitted from the diff, so the stream only yields actual changes between versions.

await db.getAndWatch(key, [options]) [#await-dbgetandwatchkey-options]

[src](https://github.com/holepunchto/hyperbee/blob/v2.27.3/index.js#L666)

`entryWatcher.node` contains the current entry in the same format as the result of `bee.get(key)`, and will be updated as it changes.

| Parameter | Type                                      | Description                                   |
| --------- | ----------------------------------------- | --------------------------------------------- |
| `key`     | `*`                                       | The key to watch (encoded per `keyEncoding`). |
| `options` | [`EntryWatchOptions`](#entrywatchoptions) | Watch options.                                |

* Returns: [`Promise<EntryWatcher>`](/reference/building-blocks/hyperbee) — a watcher which listens to changes on the given key.
* Throws: if called on a non-main Hyperbee, or if the Hyperbee is closed.

```js
const w = await db.getAndWatch('config')
w.on('update', () => console.log(w.node.value))
```

Listen to `entryWatcher.on('update')` when you need push-style notifications for a single key.

await entryWatcher.close() [#await-entrywatcherclose]

Stop a single-key watcher.

* Returns: Resolves after stopping the watcher created by `db.getAndWatch(...)`.

```js
await entryWatcher.close()
```

db.watch([range]) [#dbwatchrange]

[src](https://github.com/holepunchto/hyperbee/blob/v2.27.3/index.js#L661)

Listens to changes that are on the optional `range`.

| Parameter | Type                            | Description                                                                                |
| --------- | ------------------------------- | ------------------------------------------------------------------------------------------ |
| `range`   | [`Range`](#range)               | bounds to narrow what changes are watched; same as `db.createReadStream` except `reverse`. |
| `opts`    | [`WatchOptions`](#watchoptions) | Watch options.                                                                             |

* Returns: [`Watcher`](/reference/building-blocks/hyperbee) — a new value after a change, `current` and `previous` are snapshots that are auto-closed before next value.
* Throws: if called on a non-main Hyperbee (a sub, checkout, or snapshot).

```js
for await (const [current, previous] of watcher) {
  console.log(current.version)
  console.log(previous.version)
}
```

Watchers are not supported on subs or checkouts. Use `range` to narrow the scope on the root bee instead.

await watcher.ready() [#await-watcherready]

Wait for a range watcher to be tracking changes.

* Returns: Resolves when a range watcher has loaded and is actively tracking changes.

```js
await watcher.ready()
```

await watcher.close() [#await-watcherclose]

Stop a range watcher.

* Returns: Resolves after stopping the range watcher. Breaking out of the async iterator also stops it.

```js
await watcher.close()
```

Snapshots and sub-bees [#snapshots-and-sub-bees]

db.checkout(version) [#dbcheckoutversion]

[src](https://github.com/holepunchto/hyperbee/blob/v2.27.3/index.js#L762)

Get a read-only snapshot of a previous version.

| Parameter | Type                                  | Default | Description                                  |
| --------- | ------------------------------------- | ------- | -------------------------------------------- |
| `version` | `number`                              | —       | The version (see `db.version`) to check out. |
| `opts`    | [`CheckoutOptions`](#checkoutoptions) | `{}`    | Snapshot options.                            |

* Returns: [`Hyperbee`](/reference/building-blocks/hyperbee) — A read-only bee pinned to that version.

```js
const old = db.checkout(5)
const entry = await old.get('key')
```

db.snapshot() [#dbsnapshot]

[src](https://github.com/holepunchto/hyperbee/blob/v2.27.3/index.js#L786)

Shorthand for getting a checkout for the current version.

| Parameter | Type                                  | Description       |
| --------- | ------------------------------------- | ----------------- |
| `opts`    | [`CheckoutOptions`](#checkoutoptions) | Snapshot options. |

* Returns: [`Hyperbee`](/reference/building-blocks/hyperbee) — A read-only bee pinned to the current version.

```js
const snap = db.snapshot()
```

db.sub('sub-prefix', options = {}) [#dbsubsub-prefix-options--]

[src](https://github.com/holepunchto/hyperbee/blob/v2.27.3/index.js#L793)

Create a sub-database where all entries will be prefixed by a given value.

| Parameter | Type                                                                | Default | Description                                |
| --------- | ------------------------------------------------------------------- | ------- | ------------------------------------------ |
| `prefix`  | [`string\|Buffer`](https://nodejs.org/api/buffer.html#class-buffer) | —       | The namespace prefix applied to every key. |
| `opts`    | [`SubOptions`](#suboptions)                                         | `{}`    | —                                          |

* Returns: [`Hyperbee`](/reference/building-blocks/hyperbee) — A bee scoped to the prefixed keyspace.

```js
const root = new Hyperbee(core, { keyEncoding: 'utf-8', valueEncoding: 'utf-8' })
const sub = root.sub('a')

// In root, this will have the key ('a' + separator + 'b')
await sub.put('b', 'hello')

// Returns => { seq: 1, key: 'b', value: 'hello' }
await sub.get('b')
```

Sub-bees are useful when one Hyperbee needs multiple logical keyspaces without creating extra cores.

await db.getHeader([options]) [#await-dbgetheaderoptions]

[src](https://github.com/holepunchto/hyperbee/blob/v2.27.3/index.js#L816)

`options` are the same as the `core.get` method.

| Parameter | Type                        |
| --------- | --------------------------- |
| `options` | [`GetOptions`](#getoptions) |

* Returns: [`Promise<object>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) — the header contained in the first block.
* Throws: `DECODING_ERROR` if the stored header cannot be decoded.

```js
const header = await db.getHeader()
```

Replication and lifecycle [#replication-and-lifecycle]

db.replicate(isInitiator, [opts]) [#dbreplicateisinitiator-opts]

[src](https://github.com/holepunchto/hyperbee/blob/v2.27.3/index.js#L491)

See more about how replicate works at core.replicate.

| Parameter     | Type                                                    | Description                                                                                 |
| ------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| `isInitiator` | [`boolean\|Stream`](https://nodejs.org/api/stream.html) | `true`/`false` to open a fresh replication stream, or an existing stream to replicate over. |
| `opts`        | `object`                                                | Replication options, forwarded to `core.replicate`.                                         |

* Returns: [`Stream`](https://nodejs.org/api/stream.html) — The replication stream.

```js
const stream = db.replicate(true)
stream.pipe(remoteStream).pipe(stream)
```

In larger apps, replication is often handled through a shared [`Corestore`](/reference/helpers/corestore) rather than per-bee streams.

await db.close() [#await-dbclose]

Fully close this bee, including its core.

Static helpers [#static-helpers]

await Hyperbee.isHyperbee(core, [options]) [#await-hyperbeeishyperbeecore-options]

[src](https://github.com/holepunchto/hyperbee/blob/v2.27.3/index.js#L853)

This requests the first block on the core, so it can throw depending on the options.

| Parameter | Type                                                | Description                                      |
| --------- | --------------------------------------------------- | ------------------------------------------------ |
| `core`    | [`Hypercore`](/reference/building-blocks/hypercore) | The core to inspect.                             |
| `options` | [`GetOptions`](#getoptions)                         | `options` are the same as the `core.get` method. |

* Returns: [`Promise<boolean>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) — `true` if the core contains a Hyperbee, `false` otherwise.

```js
if (await Hyperbee.isHyperbee(core)) {
  const db = new Hyperbee(core)
}
```

Types [#types]

Entry [#entry]

A single entry as returned by reads such as `db.get()`, `db.peek()`, and the
read stream. `key` and `value` are decoded with the bee's `keyEncoding` /
`valueEncoding` (raw `Buffer`s when no encoding is set).

| Property | Type     | Default | Description                                                                                              |
| -------- | -------- | ------- | -------------------------------------------------------------------------------------------------------- |
| `seq`    | `number` | —       | [Hypercore](/reference/building-blocks/hypercore) index (block number) at which this entry was inserted. |
| `key`    | `*`      | —       | The entry's key, decoded per `keyEncoding`.                                                              |
| `value`  | `*`      | —       | The entry's value, decoded per `valueEncoding` (`null` for a deletion).                                  |

HyperbeeOptions [#hyperbeeoptions]

Options for `new Hyperbee()`.

| Property        | Type             | Default    | Description                                                                                           |
| --------------- | ---------------- | ---------- | ----------------------------------------------------------------------------------------------------- |
| `keyEncoding`   | `string\|object` | `'binary'` | Key encoding: `"binary"` (default), `"utf-8"`, `"ascii"`, `"json"`, or an abstract-encoding instance. |
| `valueEncoding` | `string\|object` | `'binary'` | Value encoding; same options as `keyEncoding`.                                                        |

PutOptions [#putoptions]

Options for `db.put()`, `db.del()` and their batch equivalents.

| Property | Type            | Default | Description                                                                  |
| -------- | --------------- | ------- | ---------------------------------------------------------------------------- |
| `cas`    | `CASComparator` | —       | Compare-and-swap comparator; the write only proceeds when it returns `true`. |

Range [#range]

Range bounds for read, diff, and watch streams. Keys are compared by their
encoded byte value.

| Property | Type | Default | Description                                     |
| -------- | ---- | ------- | ----------------------------------------------- |
| `gt`     | `*`  | —       | Only return keys greater than this.             |
| `gte`    | `*`  | —       | Only return keys greater than or equal to this. |
| `lt`     | `*`  | —       | Only return keys less than this.                |
| `lte`    | `*`  | —       | Only return keys less than or equal to this.    |

ReadStreamOptions [#readstreamoptions]

Options for `db.createReadStream()` and `db.peek()`.

| Property  | Type      | Default | Description                                              |
| --------- | --------- | ------- | -------------------------------------------------------- |
| `reverse` | `boolean` | `false` | Yield entries in reverse (descending) order.             |
| `limit`   | `number`  | `-1`    | Maximum number of entries to return (`-1` for no limit). |

HistoryStreamOptions [#historystreamoptions]

Options for `db.createHistoryStream()`.

| Property  | Type      | Default | Description                                                                      |
| --------- | --------- | ------- | -------------------------------------------------------------------------------- |
| `live`    | `boolean` | `false` | Keep the stream open and wait for new data instead of ending.                    |
| `reverse` | `boolean` | `false` | Iterate from newest to oldest.                                                   |
| `gte`     | `number`  | —       | Start at this seq (inclusive); negative values are added to the current version. |
| `gt`      | `number`  | —       | Start after this seq.                                                            |
| `lte`     | `number`  | —       | Stop at this seq (inclusive).                                                    |
| `lt`      | `number`  | —       | Stop before this seq.                                                            |
| `limit`   | `number`  | `-1`    | Maximum number of entries to return (`-1` for no limit).                         |

SubOptions [#suboptions]

Options for `db.sub()`.

| Property        | Type                                                        | Default | Description                                                                                 |
| --------------- | ----------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------- |
| `sep`           | [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer) | —       | Namespace separator placed between the prefix and key (defaults to the parent's separator). |
| `keyEncoding`   | `string\|object`                                            | —       | Key encoding for the sub (defaults to the parent's).                                        |
| `valueEncoding` | `string\|object`                                            | —       | Value encoding for the sub (defaults to the parent's).                                      |

GetOptions [#getoptions]

Options for point reads such as `db.get()` and `db.getBySeq()`. The encoding
overrides apply to this call only; remaining options are forwarded to the
underlying `core.get()`.

| Property        | Type             | Default | Description                                                   |
| --------------- | ---------------- | ------- | ------------------------------------------------------------- |
| `keyEncoding`   | `string\|object` | —       | Override the key encoding for this read.                      |
| `valueEncoding` | `string\|object` | —       | Override the value encoding for this read.                    |
| `wait`          | `boolean`        | `true`  | Wait for the block to download from a peer if it isn't local. |
| `timeout`       | `number`         | `0`     | Max milliseconds to wait for a block (`0` = no timeout).      |

BatchOptions [#batchoptions]

Options for `db.batch()`.

| Property        | Type             | Default | Description                                                     |
| --------------- | ---------------- | ------- | --------------------------------------------------------------- |
| `keyEncoding`   | `string\|object` | —       | Override the key encoding for this batch.                       |
| `valueEncoding` | `string\|object` | —       | Override the value encoding for this batch.                     |
| `update`        | `boolean`        | `true`  | Update the underlying core before the first operation resolves. |

WatchOptions [#watchoptions]

Options for `db.watch()`.

| Property        | Type             | Default | Description                                                       |
| --------------- | ---------------- | ------- | ----------------------------------------------------------------- |
| `keyEncoding`   | `string\|object` | —       | Key encoding for the yielded snapshots (defaults to the bee's).   |
| `valueEncoding` | `string\|object` | —       | Value encoding for the yielded snapshots (defaults to the bee's). |

EntryWatchOptions [#entrywatchoptions]

Options for `db.getAndWatch()`.

| Property        | Type             | Default | Description                                                   |
| --------------- | ---------------- | ------- | ------------------------------------------------------------- |
| `keyEncoding`   | `string\|object` | —       | Key encoding for the watched entry (defaults to the bee's).   |
| `valueEncoding` | `string\|object` | —       | Value encoding for the watched entry (defaults to the bee's). |

CheckoutOptions [#checkoutoptions]

Options for `db.checkout()` and `db.snapshot()`.

| Property        | Type             | Default | Description                                              |
| --------------- | ---------------- | ------- | -------------------------------------------------------- |
| `keyEncoding`   | `string\|object` | —       | Key encoding for the snapshot (defaults to the bee's).   |
| `valueEncoding` | `string\|object` | —       | Value encoding for the snapshot (defaults to the bee's). |

Errors [#errors]

Coded errors this module can throw — catch them via `err.code`.

| Error            | Thrown when                             |
| ---------------- | --------------------------------------- |
| `DECODING_ERROR` | if the stored header cannot be decoded. |

See also [#see-also]

* [Share append-only databases with Hyperbee](/how-to/store-and-replicate/share-append-only-databases-with-hyperbee)—replication walkthrough with reader and writer peers.
* [Work with many Hypercores using Corestore](/how-to/store-and-replicate/work-with-many-hypercores-using-corestore)—recommended multi-core replication pattern.
* [Corestore](/reference/helpers/corestore)—manage many Hypercores and Hyperbees from one store.
* [Hypercore](/reference/building-blocks/hypercore)—append-only log that stores Hyperbee nodes.
* [Hyperdrive](/reference/building-blocks/hyperdrive)—filesystem abstraction that builds on Hyperbee-style metadata indexing.


# Hypercore



<Status level="stable" />

Hypercore is a secure, distributed append-only log for sharing large datasets and realtime streams. It supports sparse replication, verified reads, optional block encryption, and session-based workflows for building higher-level local-first and peer-to-peer data structures.

<Callout type="info">
  For how Hypercore relates to Hyperblobs and [Hyperdrive](/reference/building-blocks/hyperdrive), see [From append-only logs to files](/explanation/from-logs-to-files).
</Callout>

Install [#install]

```sh
npm i hypercore
```

Quickstart [#quickstart]

```js
import Hypercore from 'hypercore'

const core = new Hypercore('./my-first-core', { valueEncoding: 'utf-8' })
await core.ready()

await core.append('hello')
await core.append('from hypercore')

console.log('length:', core.length)
console.log('first block:', await core.get(0))
console.log('second block:', await core.get(1))

for await (const block of core.createReadStream()) {
  console.log('streamed:', block)
}

await core.close()
```

API Reference [#api-reference]

Constructors and sessions [#constructors-and-sessions]

new Hypercore(storage, [key], [options]) [#new-hypercorestorage-key-options]

[src](https://github.com/holepunchto/hypercore/blob/v11.34.0/index.js#L46)

Make a new Hypercore instance.

| Parameter | Type                                                                | Description                                                                                                                    |
| --------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `storage` | `string\|object`                                                    | should be set to a directory where you want to store the data and core metadata.                                               |
| `key`     | [`Buffer\|string`](https://nodejs.org/api/buffer.html#class-buffer) | can be set to a Hypercore key which is a hash of Hypercore's internal auth manifest, describing how to validate the Hypercore. |
| `options` | [`HypercoreOptions`](#hypercoreoptions)                             | —                                                                                                                              |

| Option                 | Default     | Description                                                                                                                      |
| ---------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `createIfMissing`      | `true`      | create a new Hypercore key pair if none was present in storage                                                                   |
| `overwrite`            | `false`     | overwrite any old Hypercore that might already exist                                                                             |
| `force`                | `false`     | Advanced option. Will force overwrite even if the header's key & the passed key don't match                                      |
| `valueEncoding`        | —           | defaults to binary                                                                                                               |
| `encodeBatch`          | —           | optionally apply an encoding to complete batches                                                                                 |
| `keyPair`              | `kp`        | optionally pass the public key and secret key as a key pair                                                                      |
| `encryption`           | —           | the block encryption key                                                                                                         |
| `onwait`               | —           | hook that is called if gets are waiting for download                                                                             |
| `timeout`              | `0`         | wait at max some milliseconds (0 means no timeout)                                                                               |
| `writable`             | `true`      | disable appends and truncates                                                                                                    |
| `inflightRange`        | `null`      | Advanced option. Set to \[minInflight, maxInflight] to change the min and max inflight blocks per peer when downloading.         |
| `ongc`                 | —           | A callback called when the session is garbage collected                                                                          |
| `onseq`                | —           | A callback called when core.get(index) is called.                                                                                |
| `notDownloadingLinger` | `20000`     | How many milliseconds to wait after downloading finishes keeping the connection open. Defaults to a random number between 20-40s |
| `allowFork`            | `true`      | Enables updating core when it forks                                                                                              |
| `userData`             | —           | An object to assign to the local User Data storage                                                                               |
| `manifest`             | `undefined` | Advanced option. Set the manifest when creating the hypercore. See Manifest section for more info                                |
| `preload`              | `undefined` | Advanced option. A promise that returns constructor options overrides before the core is opened                                  |
| `storage`              | `undefined` | An alternative to passing storage as a dedicated argument                                                                        |
| `key`                  | `null`      | An alternative to passing key as a dedicated argument                                                                            |

```js
const core = new Hypercore('./directory') // store data in ./directory
```

User Data is a local-only key/value store with string keys and string or `Buffer` values. It is not replicated and is useful for peer-specific metadata such as encryption keys or app state.

The manifest controls how a core is authenticated, including `version`, `hash`, `quorum`, `signers`, `prologue`, `linked`, and manifest-level `userData`. Changing the manifest changes the resulting Hypercore key.

core.session([options]) [#coresessionoptions]

[src](https://github.com/holepunchto/hypercore/blob/v11.34.0/index.js#L218)

Creates a new Hypercore instance that shares the same underlying core.

| Parameter | Type                                | Default | Description                                                             |
| --------- | ----------------------------------- | ------- | ----------------------------------------------------------------------- |
| `options` | [`SessionOptions`](#sessionoptions) | `{}`    | Options are inherited from the parent instance, unless they are re-set. |

* Returns: [`Hypercore`](/reference/building-blocks/hypercore) — A new Hypercore session sharing the same underlying storage.
* Throws: `SESSION_CLOSED` if called on a core that is already closing.

```js
const core = new Hypercore('./atom-example')
await core.ready()

await core.append('block 1')

const atom = core.state.storage.createAtom()
const atomicSession = core.session({ atom })

await core.append('block 2') // Add blocks not using the atom

await atomicSession.append('atom block 2') // Add different block to atom
await atom.flush()

console.log((await core.get(core.length - 1)).toString()) // prints 'atom block 2' not 'block 2'
```

await core.commit(session, opts = {}) [#await-corecommitsession-opts--]

[src](https://github.com/holepunchto/hypercore/blob/v11.34.0/index.js#L550)

Attempt to apply blocks from the session to the `core`. `core` must be a default core, aka a non-named session.

| Parameter | Type                                                | Default | Description                                                        |
| --------- | --------------------------------------------------- | ------- | ------------------------------------------------------------------ |
| `session` | [`Hypercore`](/reference/building-blocks/hypercore) | —       | The named or atom session whose staged blocks should be committed. |
| `opts`    | [`CommitOptions`](#commitoptions)                   | `{}`    | —                                                                  |

* Returns: [`Promise<{length: number, byteLength: number}\|null>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) — `null` if committing failed.
* Throws: `INVALID_OPERATION` if no database batch was passed, or the tree changed during the batch.

| Option       | Default     | Description                                                   |
| ------------ | ----------- | ------------------------------------------------------------- |
| `length`     | —           | the core's length after committing the blocks                 |
| `treeLength` | —           | The expected length of the core's merkle tree prior to commit |
| `keyPair`    | —           | The keypair to use when committing                            |
| `signature`  | `undefined` | The signature for the blocks being committed                  |

core.snapshot([options]) [#coresnapshotoptions]

[src](https://github.com/holepunchto/hypercore/blob/v11.34.0/index.js#L210)

Same as [`core.session(options)`](#coresessionoptions), but backed by a storage snapshot so will not truncate nor append.

| Parameter | Type                                | Description                                                                    |
| --------- | ----------------------------------- | ------------------------------------------------------------------------------ |
| `options` | [`SessionOptions`](#sessionoptions) | Options forwarded to `core.session()` with `snapshot: true` set automatically. |

* Returns: [`Hypercore`](/reference/building-blocks/hypercore) — A new read-only Hypercore session locked to the current length.

```js
const snap = core.snapshot()
console.log(snap.length) // frozen at the moment snapshot() was called
```

Writing and local mutation [#writing-and-local-mutation]

await core.append(block, options = {}) [#await-coreappendblock-options--]

[src](https://github.com/holepunchto/hypercore/blob/v11.34.0/index.js#L1089)

Append a block of data (or an array of blocks) to the core. Returns the new length and byte length of the core.

| Parameter | Type                                                                       | Default | Description                                       |
| --------- | -------------------------------------------------------------------------- | ------- | ------------------------------------------------- |
| `block`   | [`Buffer\|Array<Buffer>`](https://nodejs.org/api/buffer.html#class-buffer) | —       | A single block, or an array of blocks, to append. |
| `options` | [`AppendOptions`](#appendoptions)                                          | `{}`    | —                                                 |

* Returns: [`Promise<{length: number, byteLength: number}>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) — The new `length` and `byteLength` of the core after appending.
* Throws:
  * `SESSION_CLOSED` if the core has been closed.
  * `SESSION_NOT_WRITABLE` if the core is not writable.
  * `INVALID_OPERATION` if the append is inconsistent with the manifest prologue.
  * `BAD_ARGUMENT` if an appended block exceeds the maximum suggested block size.

| Option      | Default     | Description                                                                 |
| ----------- | ----------- | --------------------------------------------------------------------------- |
| `writable`  | `false`     | Enabled ignores writable check. Does not override whether core is writable. |
| `maxLength` | `undefined` | The maximum resulting length of the core after appending                    |
| `keyPair`   | —           | KeyPair used to sign the blocks                                             |
| `signature` | `null`      | Set signature for blocks                                                    |

```js
// simple call append with a new block of data
await core.append(Buffer.from('I am a block of data'))

// pass an array to append multiple blocks as a batch
await core.append([Buffer.from('batch block 1'), Buffer.from('batch block 2')])
```

core.createWriteStream() [#corecreatewritestream]

[src](https://github.com/holepunchto/hypercore/blob/v11.34.0/index.js#L1045)

Make a write stream to append chunks as blocks.

* Returns: `object` — A Writable stream; each chunk written becomes one block appended to the core.

```js
const ws = core.createWriteStream()

// Listen for stream finishing
const done = new Promise((resolve) => ws.on('finish', resolve))

for (const data of ['hello', 'world']) ws.write(data)
ws.end()

await done

console.log(await core.get(core.length - 2)) // 'hello'
console.log(await core.get(core.length - 1)) // 'world'
```

await core.clear(start, [end], [options]) [#await-coreclearstart-end-options]

[src](https://github.com/holepunchto/hypercore/blob/v11.34.0/index.js#L872)

Clear stored blocks between `start` and `end`, reclaiming storage when possible.

| Parameter | Type                            | Default     | Description                                    |
| --------- | ------------------------------- | ----------- | ---------------------------------------------- |
| `start`   | `number`                        | —           | Zero-based index of the first block to clear.  |
| `end`     | `number`                        | `start + 1` | Exclusive end index (defaults to `start + 1`). |
| `options` | [`ClearOptions`](#clearoptions) | —           | —                                              |

* Returns: [`Promise<{blocks: number}\|null>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) — `{ blocks }` with the count of cleared blocks when `opts.diff` is true, otherwise `null`.
* Throws:
  * `SESSION_CLOSED` if the core has been closed.
  * `ASSERTION` if the `start`/`end` range is invalid.

```js
await core.clear(4) // clear block 4 from your local cache
await core.clear(0, 10) // clear block 0-10 from your local cache
```

await core.truncate(newLength, [options]) [#await-coretruncatenewlength-options]

[src](https://github.com/holepunchto/hypercore/blob/v11.34.0/index.js#L1067)

Truncate the core to a smaller length.

| Parameter   | Type                                  | Default | Description                                                         |
| ----------- | ------------------------------------- | ------- | ------------------------------------------------------------------- |
| `newLength` | `number`                              | `0`     | The target length to truncate to (must be ≤ current `core.length`). |
| `options`   | [`TruncateOptions`](#truncateoptions) | `{}`    | —                                                                   |

* Returns: [`Promise<void>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) — Resolves once the truncation has been signed and written to storage.
* Throws:
  * `SESSION_CLOSED` if the core has been closed.
  * `SESSION_NOT_WRITABLE` if the core is not writable.
  * `INVALID_OPERATION` if the truncation would break the manifest prologue.

Reading, streams, and proofs [#reading-streams-and-proofs]

await core.get(index, [options]) [#await-coregetindex-options]

[src](https://github.com/holepunchto/hypercore/blob/v11.34.0/index.js#L841)

Get a block of data. If the data is not available locally this method will prioritize and wait for the data to be downloaded.

| Parameter | Type                        | Description                                |
| --------- | --------------------------- | ------------------------------------------ |
| `index`   | `number`                    | Zero-based index of the block to retrieve. |
| `options` | [`GetOptions`](#getoptions) | —                                          |

* Returns: [`Promise<Buffer\|null>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) — The block value (decoded per `valueEncoding`), or `null` if the block is not available and `wait` is `false`.
* Throws:
  * `SESSION_CLOSED` if the core has been closed.
  * `ASSERTION` if `index` is not a valid block index.

| Option           | Default     | Description                                                  |
| ---------------- | ----------- | ------------------------------------------------------------ |
| `wait`           | `true`      | wait for block to be downloaded                              |
| `onwait`         | —           | hook that is called if the get is waiting for download       |
| `timeout`        | `0`         | wait at max some milliseconds (0 means no timeout)           |
| `activeRequests` | `undefined` | Advanced option. Pass BlockRequest for replicating the block |
| `valueEncoding`  | —           | defaults to the core's valueEncoding                         |
| `decrypt`        | `true`      | automatically decrypts the block if encrypted                |
| `raw`            | `false`     | Return block without decoding                                |

```js
// get block #42
const block = await core.get(42)

// get block #43, but only wait 5s
const blockIfFast = await core.get(43, { timeout: 5000 })

// get block #44, but only if we have it locally
const blockLocal = await core.get(44, { wait: false })
```

await core.has(start, [end]) [#await-corehasstart-end]

[src](https://github.com/holepunchto/hypercore/blob/v11.34.0/index.js#L809)

Check if the core has all blocks between `start` and `end`.

| Parameter | Type     | Default     | Description                                                                   |
| --------- | -------- | ----------- | ----------------------------------------------------------------------------- |
| `start`   | `number` | —           | Zero-based index of the first block to check.                                 |
| `end`     | `number` | `start + 1` | Exclusive end index (defaults to `start + 1`, that is checks a single block). |

* Returns: [`Promise<boolean>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) — `true` if every block in `[start, end)` is available locally.
* Throws: `ASSERTION` if the `start`/`end` range is invalid.

```js
const hasBlock = await core.has(5)
const hasRange = await core.has(0, 10)
```

await core.update([options]) [#await-coreupdateoptions]

[src](https://github.com/holepunchto/hypercore/blob/v11.34.0/index.js#L734)

Waits for initial proof of the new core length until all `findingPeers` calls have finished.

| Parameter | Type                              |
| --------- | --------------------------------- |
| `options` | [`UpdateOptions`](#updateoptions) |

* Returns: [`Promise<boolean>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) — `true` if the core was updated to a new length, `false` otherwise.

| Option           | Default     | Description                                           |
| ---------------- | ----------- | ----------------------------------------------------- |
| `wait`           | `false`     | —                                                     |
| `activeRequests` | `undefined` | Advanced option. Pass requests for replicating blocks |
| `force`          | `false`     | Force an update even if core is writable.             |

```js
const updated = await core.update()

console.log('core was updated?', updated, 'length is', core.length)
```

const [index, relativeOffset] = await core.seek(bytes, [options]) [#const-index-relativeoffset--await-coreseekbytes-options]

[src](https://github.com/holepunchto/hypercore/blob/v11.34.0/index.js#L767)

Seek to a byte offset.

| Parameter | Type                          | Description                                     |
| --------- | ----------------------------- | ----------------------------------------------- |
| `bytes`   | `number`                      | The byte offset to seek to (zero-based).        |
| `options` | [`SeekOptions`](#seekoptions) | Options controlling wait and timeout behaviour. |

* Returns: [`Promise<[number, number]>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) — `[index, relativeOffset]`, where `index` is the data block the `bytes` is contained in and `relativeOffset` is the relative byte offset in the data block.
* Throws:
  * `SESSION_CLOSED` if the core has been closed.
  * `ASSERTION` if `bytes` is not a valid byte offset.

| Option           | Default     | Description                                           |
| ---------------- | ----------- | ----------------------------------------------------- |
| `wait`           | `true`      | wait for data to be downloaded                        |
| `timeout`        | `0`         | wait at max some milliseconds (0 means no timeout)    |
| `activeRequests` | `undefined` | Advanced option. Pass requests for replicating blocks |

```js
await core.append([Buffer.from('abc'), Buffer.from('d'), Buffer.from('efg')])

const first = await core.seek(1) // returns [0, 1]
const second = await core.seek(3) // returns [1, 0]
const third = await core.seek(5) // returns [2, 1]
```

core.createReadStream([options]) [#corecreatereadstreamoptions]

[src](https://github.com/holepunchto/hypercore/blob/v11.34.0/index.js#L1041)

Make a read stream to read a range of data out at once.

| Parameter | Type                                      |
| --------- | ----------------------------------------- |
| `options` | [`ReadStreamOptions`](#readstreamoptions) |

* Returns: `object` — A Readable stream that emits decoded blocks.

```js
// read the full core
const fullStream = core.createReadStream()

// read from block 10-14
const partialStream = core.createReadStream({ start: 10, end: 15 })

// pipe the stream somewhere using the .pipe method on Node.js or consume it as
// an async iterator

for await (const data of fullStream) {
  console.log('data:', data)
}
```

core.createByteStream([options]) [#corecreatebytestreamoptions]

[src](https://github.com/holepunchto/hypercore/blob/v11.34.0/index.js#L1049)

Make a byte stream to read a range of bytes.

| Parameter | Type                                      |
| --------- | ----------------------------------------- |
| `options` | [`ByteStreamOptions`](#bytestreamoptions) |

* Returns: `object` — A Readable stream that emits raw Buffer chunks spanning the requested byte range.

```js
// Read the full core
const fullStream = core.createByteStream()

// Read from byte 3, and from there read 50 bytes
const partialStream = core.createByteStream({ byteOffset: 3, byteLength: 50 })

// Consume it as an async iterator
for await (const data of fullStream) {
  console.log('data:', data)
}

// Or pipe it somewhere like any stream:
partialStream.pipe(process.stdout)
```

await core.treeHash([length]) [#await-coretreehashlength]

[src](https://github.com/holepunchto/hypercore/blob/v11.34.0/index.js#L1135)

Get the Merkle Tree hash of the core at a given length, defaulting to the current length of the core.

| Parameter | Type     | Default | Description                                         |
| --------- | -------- | ------- | --------------------------------------------------- |
| `length`  | `number` | `-1`    | Tree length to hash at (defaults to `core.length`). |

* Returns: [`Promise<Buffer>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) — A 32-byte BLAKE2b hash of the Merkle tree roots at the given length.

```js
const hash = await core.treeHash()
console.log(hash.toString('hex'))
```

await core.proof(opts) [#await-coreproofopts]

[src](https://github.com/holepunchto/hypercore/blob/v11.34.0/index.js#L1149)

Generate a proof (a `TreeProof` instance) for the request `opts`.

| Parameter | Type                            |
| --------- | ------------------------------- |
| `opts`    | [`ProofOptions`](#proofoptions) |

* Returns: [`Promise<object>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) — A settled `TreeProof` object that can be serialised and sent to a remote peer.

await core.verifyFullyRemote(proof) [#await-coreverifyfullyremoteproof]

[src](https://github.com/holepunchto/hypercore/blob/v11.34.0/index.js#L1166)

Note that you cannot seek & provide a block / hash request when upgrading.

| Parameter | Type     | Description                                                   |
| --------- | -------- | ------------------------------------------------------------- |
| `proof`   | `object` | A proof object as produced by a remote core's `core.proof()`. |

* Returns: [`Promise<object>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) — the merkle tree batch from the proof.

```js
const batch = await core.verifyFullyRemote(remoteProof)
```

await core.signable([length], [fork]) [#await-coresignablelength-fork]

[src](https://github.com/holepunchto/hypercore/blob/v11.34.0/index.js#L1127)

Produce the signable payload for a given tree state. The payload encodes the
core's `key`, tree hash (`core.treeHash()`), `length`, and `fork`.

| Parameter | Type     | Default | Description                                         |
| --------- | -------- | ------- | --------------------------------------------------- |
| `length`  | `number` | `-1`    | The length to sign for (defaults to `core.length`). |
| `fork`    | `number` | `-1`    | The fork ID to include (defaults to `core.fork`).   |

* Returns: [`Promise<Buffer>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) — a buffer which encodes the core's `key`, tree hash (`core.treeHash()`), `length`, & `fork`.

```js
const payload = await core.signable()
const sig = sodium.crypto_sign_detached(payload, secretKey)
```

core.download([range]) [#coredownloadrange]

[src](https://github.com/holepunchto/hypercore/blob/v11.34.0/index.js#L1053)

Download a range of data.

| Parameter | Type                              | Description                                                    |
| --------- | --------------------------------- | -------------------------------------------------------------- |
| `range`   | [`DownloadRange`](#downloadrange) | The block range to download. Omit to download the entire core. |

* Returns: `object` — A Download handle with a `.done()` promise and a `.destroy()` method to cancel.

| Option           | Default                | Description                                           |
| ---------------- | ---------------------- | ----------------------------------------------------- |
| `start`          | `startIndex`           | —                                                     |
| `end`            | `nonInclusiveEndIndex` | —                                                     |
| `blocks`         | —                      | —                                                     |
| `linear`         | `false`                | download range linearly and not randomly              |
| `activeRequests` | `undefined`            | Advanced option. Pass requests for replicating blocks |

```js
const download = core.download({ start: 0, end: 10 })
await download.done()
```

```js
// Note that this will never be considered downloaded as the range
// will keep waiting for new blocks to be appended.
core.download({ start: 0, end: -1 })
```

```js
core.download({ blocks: [4, 9, 7] })
```

```js
// will stop downloading now
range.destroy()
```

Extensions and replication [#extensions-and-replication]

core.registerExtension(name, handlers = {}) [#coreregisterextensionname-handlers--]

[src](https://github.com/holepunchto/hypercore/blob/v11.34.0/index.js#L1224)

Register a custom protocol extension. This is a legacy implementation and is no longer recommended. Creating a [`Protomux`](https://github.com/holepunchto/protomux) protocol is recommended instead.

| Parameter  | Type     | Default | Description                                                  |
| ---------- | -------- | ------- | ------------------------------------------------------------ |
| `name`     | `string` | —       | The unique name that identifies this extension across peers. |
| `handlers` | `object` | `{}`    | —                                                            |

* Returns: `object` — The extension object with `send(message, peer)`, `broadcast(message)`, and `destroy()` methods.

| Option      | Description                                               |
| ----------- | --------------------------------------------------------- |
| `encoding`  | Compact encoding to use for messages. Defaults to buffer  |
| `onmessage` | Callback for when a message for the extension is received |

This extension API is documented as legacy. For new protocol work, the upstream README recommends creating a [`Protomux`](/reference/helpers/protomux) protocol instead.

ext.send(message, peer) [#extsendmessage-peer]

Sends the `message` to a specific `peer`.

ext.broadcast(message) [#extbroadcastmessage]

Sends the `message` to all peers.

ext.destroy() [#extdestroy]

Unregister and remove extension from the hypercore.

core.replicate(isInitiatorOrReplicationStream, opts = {}) [#corereplicateisinitiatororreplicationstream-opts--]

[src](https://github.com/holepunchto/hypercore/blob/v11.34.0/index.js#L557)

Create a replication stream. You should pipe this to another Hypercore instance.

| Parameter                        | Type                                              | Default | Description                                                                                         |
| -------------------------------- | ------------------------------------------------- | ------- | --------------------------------------------------------------------------------------------------- |
| `isInitiatorOrReplicationStream` | `boolean\|object`                                 | —       | `true`/`false` for the noise handshake role, or an existing stream / Protomux to attach to.         |
| `opts`                           | [`ProtocolStreamOptions`](#protocolstreamoptions) | `{}`    | are same as [`Hypercore.createProtocolStream()`](#hypercorecreateprotocolstreamisinitiator-opts--). |

* Returns: `object` — The replication stream (a raw duplex stream with a Protomux attached).

```js
// assuming we have two cores, localCore + remoteCore, sharing the same key
// on a server
const net = require('net')
const server = net.createServer(function (socket) {
  socket.pipe(remoteCore.replicate(false)).pipe(socket)
})

// on a client
const socket = net.connect(...)
socket.pipe(localCore.replicate(true)).pipe(socket)
```

core.findingPeers() [#corefindingpeers]

[src](https://github.com/holepunchto/hypercore/blob/v11.34.0/index.js#L712)

Create a hook that tells Hypercore you are finding peers for this core in the background. Call `done` when your current discovery iteration is done. If you're using [Hyperswarm](/reference/building-blocks/hyperswarm), you'd normally call this after a `swarm.flush()` finishes.

* Returns: `function` — A `done()` callback to call when peer discovery is complete.

```js
const done = core.findingPeers()
swarm.flush().then(done, done)
```

Storage inspection and mark-and-sweep [#storage-inspection-and-mark-and-sweep]

await core.info([options]) [#await-coreinfooptions]

[src](https://github.com/holepunchto/hypercore/blob/v11.34.0/index.js#L728)

Get information about this core, such as its total size in bytes.

| Parameter | Type                          |
| --------- | ----------------------------- |
| `options` | [`InfoOptions`](#infooptions) |

* Returns: [`Promise<object>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) — An `Info` object with `key`, `discoveryKey`, `length`, `contiguousLength`, `byteLength`, `fork`, `padding`, and optional `storage` fields.

```js
Info {
  key: Buffer(...),
  discoveryKey: Buffer(...),
  length: 18,
  contiguousLength: 16,
  byteLength: 742,
  fork: 0,
  padding: 8,
  storage: {
    oplog: 8192,
    tree: 4096,
    blocks: 4096,
    bitfield: 4096
  }
}
```

await core.startMarking() [#await-corestartmarking]

[src](https://github.com/holepunchto/hypercore/blob/v11.34.0/index.js#L995)

This enables marking mode for the "mark & sweep" approach to clear hypercore storage. When called the current markings are cleared.

* Returns: [`Promise<void>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) — Resolves once marking mode is active and previous marks are cleared.
* Throws: `ASSERTION` if the core is already in gc mode, or is a named or atomic session.

```js
await core.startMarking()
await core.get(2)
await core.get(4)
await core.sweep() // All blocks but blocks 2 & 4 are cleared
```

await core.markBlock(start, end = start + 1) [#await-coremarkblockstart-end--start--1]

[src](https://github.com/holepunchto/hypercore/blob/v11.34.0/index.js#L972)

Manually mark a block or range of blocks to be retained when sweeping. Useful to mark blocks without loading them into memory. `end` is non-inclusive and defaults to `start + 1` so `core.markBlock(index)` only marks the block at `index`.

| Parameter | Type     | Default     | Description                                  |
| --------- | -------- | ----------- | -------------------------------------------- |
| `start`   | `number` | —           | Zero-based index of the first block to mark. |
| `end`     | `number` | `start + 1` | —                                            |

* Returns: [`Promise<void>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) — Resolves once all marks in the range have been written to storage.

```js
await core.markBlock(5)       // mark block 5
await core.markBlock(0, 10)   // mark blocks 0–9
```

await core.clearMarkings() [#await-coreclearmarkings]

[src](https://github.com/holepunchto/hypercore/blob/v11.34.0/index.js#L986)

Manually remove all markings. Automatically called when calling `core.startMarking()`.

* Returns: [`Promise<void>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) — Resolves once all marks have been cleared from storage.

```js
await core.clearMarkings()
```

await core.sweep(opts) [#await-coresweepopts]

[src](https://github.com/holepunchto/hypercore/blob/v11.34.0/index.js#L1011)

Clear all unmarked blocks from storage.

| Parameter | Type                            | Default |
| --------- | ------------------------------- | ------- |
| `opts`    | [`SweepOptions`](#sweepoptions) | `{}`    |

* Returns: [`Promise<void>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) — Resolves once all unmarked blocks have been cleared.

The README describes the full mark-and-sweep flow as `startMarking()`, read or manually mark the blocks you want to keep, then `sweep()` to clear everything else.

Lifecycle and local configuration [#lifecycle-and-local-configuration]

await core.close([{ error }]) [#await-coreclose-error-]

[src](https://github.com/holepunchto/hypercore/blob/v11.34.0/index.js#L490)

Fully close this core. Passing an error via `{ error }` is optional and all pending replicator requests will be rejected with the error.

| Parameter | Type                            | Default | Description             |
| --------- | ------------------------------- | ------- | ----------------------- |
| `options` | [`CloseOptions`](#closeoptions) | `{}`    | Optional close options. |

* Returns: [`Promise<void>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) — Resolves once the session (and underlying core if no other sessions remain) is fully closed.

```js
await core.close()
```

await core.purge() [#await-corepurge]

[src](https://github.com/holepunchto/hypercore/blob/v11.34.0/index.js#L897)

Close every session on this core and permanently delete its storage from disk. Unlike `core.clear()`, which drops selected blocks, `purge()` removes the entire core.

* Returns: [`Promise<void>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) — Resolves once the core's storage has been deleted.

await core.ready() [#await-coreready]

[src](https://github.com/holepunchto/hypercore/blob/v11.34.0/index.js#L666)

Wait for the core to fully open.

* Returns: [`Promise<void>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) — Resolves once the core is ready for reading and writing.

```js
const core = new Hypercore('./storage')
await core.ready()
console.log(core.key) // now available
```

await core.setEncryption(encryption) [#await-coresetencryptionencryption]

[src](https://github.com/holepunchto/hypercore/blob/v11.34.0/index.js#L259)

Set the encryption, which should satisfy the [HypercoreEncryption](https://github.com/holepunchto/hypercore-encryption) interface.

| Parameter    | Type           | Description                                                                                               |
| ------------ | -------------- | --------------------------------------------------------------------------------------------------------- |
| `encryption` | `object\|null` | An encryption provider with `padding`, `encrypt`, and `decrypt` methods, or `null` to disable encryption. |

* Returns: [`Promise<void>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) — Resolves once the encryption provider has been installed.
* Throws: `ASSERTION` if the provider does not satisfy the `HypercoreEncryption` interface.

```js
await core.setEncryption(new DefaultEncryption(encryptionKey, core.key))
```

await core.setEncryptionKey(key, [opts]) [#await-coresetencryptionkeykey-opts]

[src](https://github.com/holepunchto/hypercore/blob/v11.34.0/index.js#L253)

Set the encryption key.

| Parameter | Type                                                        | Description                                                        |
| --------- | ----------------------------------------------------------- | ------------------------------------------------------------------ |
| `key`     | [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer) | The 32-byte encryption key to use for block encryption/decryption. |
| `opts`    | [`SetEncryptionKeyOptions`](#setencryptionkeyoptions)       | —                                                                  |

* Returns: [`Promise<void>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) — Resolves once the encryption provider has been installed.

core.setKeyPair(keyPair) [#coresetkeypairkeypair]

[src](https://github.com/holepunchto/hypercore/blob/v11.34.0/index.js#L279)

Update the core's `keyPair`. Advanced as the `keyPair` is used throughout Hypercore, for example verifying blocks, identifying the core, etc.

| Parameter | Type                                                                                        | Description                                  |
| --------- | ------------------------------------------------------------------------------------------- | -------------------------------------------- |
| `keyPair` | [`{publicKey: Buffer, secretKey: Buffer}`](https://nodejs.org/api/buffer.html#class-buffer) | The new Ed25519 key pair to use for signing. |

* Returns: `void`

```js
core.setKeyPair({ publicKey: pubKey, secretKey: secKey })
```

core.setActive(active) [#coresetactiveactive]

[src](https://github.com/holepunchto/hypercore/blob/v11.34.0/index.js#L283)

Set the core to be active or not. A core is considered 'active' if it should linger to download blocks from peers.

| Parameter | Type      | Description                                                    |
| --------- | --------- | -------------------------------------------------------------- |
| `active`  | `boolean` | Pass `true` to mark the core as active, `false` to deactivate. |

* Returns: `void`

```js
core.setActive(false) // stop lingering for peer downloads
```

await core.setGroup(topic) [#await-coresetgrouptopic]

[src](https://github.com/holepunchto/hypercore/blob/v11.34.0/index.js#L274)

Set the group `topic` that the hypercore belongs to. Useful for grouping hypercores together that need to update a larger data structure (eg. `autobee`) that is comprised of them. See `corestore`'s `store.notifyGroup(topic)` for more details.

| Parameter | Type                                                        | Description          |
| --------- | ----------------------------------------------------------- | -------------------- |
| `topic`   | [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer) | is a 32 byte buffer. |

await core.setUserData(key, value) [#await-coresetuserdatakey-value]

[src](https://github.com/holepunchto/hypercore/blob/v11.34.0/index.js#L675)

Set a key in the User Data key-value store.

| Parameter | Type                                                                | Description                                  |
| --------- | ------------------------------------------------------------------- | -------------------------------------------- |
| `key`     | `string`                                                            | The user-data key (a string).                |
| `value`   | [`Buffer\|string`](https://nodejs.org/api/buffer.html#class-buffer) | The value to store (Buffer or UTF-8 string). |

* Returns: [`Promise<void>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) — Resolves once the value has been persisted to storage.

```js
await core.setUserData('version', Buffer.from('1.0'))
```

await core.getUserData(key) [#await-coregetuserdatakey]

[src](https://github.com/holepunchto/hypercore/blob/v11.34.0/index.js#L682)

Reads the local user-data value stored under `key`, resolving with its `Buffer`/string value or `null` if unset. User data is local-only and not replicated.

| Parameter | Type     | Description  |
| --------- | -------- | ------------ |
| `key`     | `string` | is a string. |

* Returns: [`Promise<Buffer\|null>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) — the value for a key in the User Data key-value store.

```js
const value = await core.getUserData('version')
console.log(value && value.toString()) // '1.0'
```

Properties [#properties]

core.writable [#corewritable]

[src](https://github.com/holepunchto/hypercore/blob/v11.34.0/index.js#L76)

Can we append to or truncate this core?

* Returns: `boolean`

core.readable [#corereadable]

[src](https://github.com/holepunchto/hypercore/blob/v11.34.0/index.js#L75)

Can we read from this core? After closing the core this will be false.

* Returns: `boolean`

core.id [#coreid]

[src](https://github.com/holepunchto/hypercore/blob/v11.34.0/index.js#L593)

String containing the id (z-base-32 of the public key) identifying this core.

* Returns: `string\|null` — The z-base-32 encoded public key, or `null` before the core is opened.

core.key [#corekey]

[src](https://github.com/holepunchto/hypercore/blob/v11.34.0/index.js#L597)

Buffer containing the public key identifying this core.

* Returns: [`Buffer\|null`](https://nodejs.org/api/buffer.html#class-buffer) — The 32-byte public key, or `null` before the core is opened.

core.keyPair [#corekeypair]

[src](https://github.com/holepunchto/hypercore/blob/v11.34.0/index.js#L74)

Object containing buffers of the core's public and secret key

* Returns: [`{publicKey: Buffer, secretKey: Buffer\|null}\|null`](https://nodejs.org/api/buffer.html#class-buffer)

core.discoveryKey [#corediscoverykey]

[src](https://github.com/holepunchto/hypercore/blob/v11.34.0/index.js#L601)

Buffer containing a key derived from the core's public key. In contrast to `core.key` this key does not allow you to verify the data but can be used to announce or look for peers that are sharing the same core, without leaking the core key.

* Returns: [`Buffer\|null`](https://nodejs.org/api/buffer.html#class-buffer) — The 32-byte discovery key, or `null` before the core is opened.

core.length [#corelength]

[src](https://github.com/holepunchto/hypercore/blob/v11.34.0/index.js#L609)

How many blocks of data are available on this core.

* Returns: `number` — The total number of blocks in the core (0 before the core is opened).

core.byteLength [#corebytelength]

[src](https://github.com/holepunchto/hypercore/blob/v11.34.0/index.js#L621)

The cumulative size, in bytes, of all blocks in the core.

* Returns: `number` — Total byte length of the core (0 before the core is opened).

core.manifest [#coremanifest]

[src](https://github.com/holepunchto/hypercore/blob/v11.34.0/index.js#L605)

The core's manifest—the signed description of its cryptographic configuration (version, signers, prologue, and so on).

* Returns: `object \| null` — The manifest object, or `null` before the core is opened.

core.signedLength [#coresignedlength]

[src](https://github.com/holepunchto/hypercore/blob/v11.34.0/index.js#L614)

How many blocks of data are available on this core that have been signed by a quorum. This is equal to `core.length` for Hypercores with a single signer.

* Returns: `number` — The number of quorum-signed blocks (0 before the core is opened).

core.contiguousLength [#corecontiguouslength]

[src](https://github.com/holepunchto/hypercore/blob/v11.34.0/index.js#L632)

How many blocks are contiguously available starting from the first block of this core.

* Returns: `number` — The local contiguous length (0 before the core is opened).

core.remoteContiguousLength [#coreremotecontiguouslength]

[src](https://github.com/holepunchto/hypercore/blob/v11.34.0/index.js#L627)

How many blocks are contiguously available starting from the first block of this core on any known remote. This is only updated when a remote thinks it is fully contiguous such that they have all known blocks.

* Returns: `number` — The remote contiguous length (0 before the core is opened).

core.fork [#corefork]

[src](https://github.com/holepunchto/hypercore/blob/v11.34.0/index.js#L641)

What is the current fork id of this core?

* Returns: `number` — The current fork counter (incremented on each truncation; 0 before the core is opened).

core.padding [#corepadding]

[src](https://github.com/holepunchto/hypercore/blob/v11.34.0/index.js#L646)

How much padding is applied to each block of this core? Will be `0` unless block encryption is enabled.

* Returns: `number` — Number of padding bytes prepended to each block (0 when encryption is disabled).

core.peers [#corepeers]

[src](https://github.com/holepunchto/hypercore/blob/v11.34.0/index.js#L654)

Array of current peers the core is replicating with.

* Returns: [`Array<object>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) — Live array of Replicator peer objects (empty before the core is opened).

Events [#events]

core.on('close') [#coreonclose]

[src](https://github.com/holepunchto/hypercore/blob/v11.34.0/index.js#L329)

Emitted when the core has been fully closed.

core.on('ready') [#coreonready]

[src](https://github.com/holepunchto/hypercore/blob/v11.34.0/index.js#L342)

Emitted after the core has initially opened all its internal state.

core.on('append') [#coreonappend]

Emitted when the core has been appended to (that is has a new length / byteLength), either locally or remotely.

core.on('truncate', ancestors, forkId) [#coreontruncate-ancestors-forkid]

Emitted when the core has been truncated, either locally or remotely.

core.on('peer-add') [#coreonpeer-add]

Emitted when a new connection has been established with a peer.

core.on('peer-remove') [#coreonpeer-remove]

Emitted when a peer's connection has been closed.

core.on('upload', index, byteLength, peer) [#coreonupload-index-bytelength-peer]

Emitted when a block is uploaded to a peer.

core.on('download', index, byteLength, peer) [#coreondownload-index-bytelength-peer]

Emitted when a block is downloaded from a peer.

core.on('remote-contiguous-length', length) [#coreonremote-contiguous-length-length]

Emitted when the max known contiguous `length` from a remote, that is `core.remoteContiguousLength`, is updated. Note this is not emitted when core is truncated.

core.on('migrate', key) [#coreonmigrate-key]

Emitted when the core migrates to a new key—for example after a manifest change. The listener receives the new `core.key`.

Static helpers [#static-helpers]

Hypercore.MAX_SUGGESTED_BLOCK_SIZE [#hypercoremax_suggested_block_size]

[src](https://github.com/holepunchto/hypercore/blob/v11.34.0/index.js#L116)

The constant for max size (15MB) for blocks appended to Hypercore. This max ensures blocks are replicated smoothly.

* Returns: `number`

Hypercore.key(manifest, options = {}) [#hypercorekeymanifest-options--]

[src](https://github.com/holepunchto/hypercore/blob/v11.34.0/index.js#L597)

`options` include:

| Parameter  | Type                                                                | Default | Description                                                                    |
| ---------- | ------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------ |
| `manifest` | [`Buffer\|object`](https://nodejs.org/api/buffer.html#class-buffer) | —       | A 32-byte public key Buffer, or a full manifest object with a `signers` array. |
| `options`  | [`KeyOptions`](#keyoptions)                                         | `{}`    | —                                                                              |

* Returns: [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer) — the key for a given manifest.

Hypercore.discoveryKey(key) [#hypercorediscoverykeykey]

[src](https://github.com/holepunchto/hypercore/blob/v11.34.0/index.js#L601)

Derive the discovery key from a Hypercore public key. The discovery key
can safely be shared to announce the core without exposing the read key.

| Parameter | Type                                                        | Description                       |
| --------- | ----------------------------------------------------------- | --------------------------------- |
| `key`     | [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer) | The 32-byte Hypercore public key. |

* Returns: [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer) — the discovery key for the provided `key`.

```js
const dKey = Hypercore.discoveryKey(core.key)
```

Hypercore.blockEncryptionKey(key, encryptionKey) [#hypercoreblockencryptionkeykey-encryptionkey]

[src](https://github.com/holepunchto/hypercore/blob/v11.34.0/index.js#L142)

Derive a block-level encryption key from the Hypercore public key and a
master encryption key using BLAKE2b.

| Parameter       | Type                                                        | Description                        |
| --------------- | ----------------------------------------------------------- | ---------------------------------- |
| `key`           | [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer) | The 32-byte Hypercore public key.  |
| `encryptionKey` | [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer) | The 32-byte master encryption key. |

* Returns: [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer) — a block encryption key derived from the `key` and `encryptionKey`.

```js
const blockKey = Hypercore.blockEncryptionKey(core.key, encryptionKey)
```

Hypercore.getProtocolMuxer(stream) [#hypercoregetprotocolmuxerstream]

[src](https://github.com/holepunchto/hypercore/blob/v11.34.0/index.js#L146)

Extract the Protomux instance attached to a Hypercore protocol stream.

| Parameter | Type     | Description                                                                                            |
| --------- | -------- | ------------------------------------------------------------------------------------------------------ |
| `stream`  | `object` | A Hypercore protocol stream (as returned by `core.replicate()` or `Hypercore.createProtocolStream()`). |

* Returns: `object` — a protomux instance from the provided `stream` Hypercore protocol stream.

```js
const stream = core.replicate(true)
const mux = Hypercore.getProtocolMuxer(stream)
```

Hypercore.createCore(storage, opts) [#hypercorecreatecorestorage-opts]

[src](https://github.com/holepunchto/hypercore/blob/v11.34.0/index.js#L150)

Create the raw internal Core object directly, bypassing the Hypercore
session layer. Useful for low-level tooling that needs direct storage access.

| Parameter | Type                                    | Description                                             |
| --------- | --------------------------------------- | ------------------------------------------------------- |
| `storage` | `string\|object`                        | Path to a storage directory, or a CoreStorage instance. |
| `opts`    | [`HypercoreOptions`](#hypercoreoptions) | Options forwarded to the Core constructor.              |

* Returns: `object` — the internal core using the `storage` and `opts` without creating a full Hypercore instance.

```js
const core = Hypercore.createCore('./storage', { key: myKey })
```

Hypercore.createProtocolStream(isInitiator, opts = {}) [#hypercorecreateprotocolstreamisinitiator-opts--]

[src](https://github.com/holepunchto/hypercore/blob/v11.34.0/index.js#L154)

Create an encrypted noise stream with a protomux instance attached used for Hypercore's replication protocol.

| Parameter     | Type                                              | Default | Description                                                                                                            |
| ------------- | ------------------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------- |
| `isInitiator` | `boolean\|object`                                 | —       | can be a framed stream, a protomux or a boolean for whether the stream should be the initiator in the noise handshake. |
| `opts`        | [`ProtocolStreamOptions`](#protocolstreamoptions) | `{}`    | —                                                                                                                      |

* Returns: `object` — The outer raw stream with a `.noiseStream.userData` Protomux attached.

Hypercore.defaultStorage(storage, opts = {}) [#hypercoredefaultstoragestorage-opts--]

[src](https://github.com/holepunchto/hypercore/blob/v11.34.0/index.js#L188)

Wrap a path or existing CoreStorage object into a CoreStorage instance.
Called internally by the constructor; exposed for advanced use.

| Parameter | Type                                              | Default | Description                                                                 |
| --------- | ------------------------------------------------- | ------- | --------------------------------------------------------------------------- |
| `storage` | `string\|object`                                  | —       | Directory path string or an existing CoreStorage instance (returned as-is). |
| `opts`    | [`DefaultStorageOptions`](#defaultstorageoptions) | `{}`    | Extra options forwarded to the CoreStorage constructor.                     |

* Returns: `object` — a default hypercore storage.

```js
const storage = Hypercore.defaultStorage('./my-core')
```

Types [#types]

HypercoreOptions [#hypercoreoptions]

Options for creating or opening a Hypercore instance.

| Property        | Type                                                                                        | Default | Description                                                                           |
| --------------- | ------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------- |
| `key`           | [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer)                                 | —       | The public key of the core (32 bytes). Omit to create a new writable core.            |
| `keyPair`       | [`{publicKey: Buffer, secretKey: Buffer}`](https://nodejs.org/api/buffer.html#class-buffer) | —       | Ed25519 key pair for signing appended blocks.                                         |
| `encryptionKey` | [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer)                                 | —       | A 32-byte key to enable block encryption.                                             |
| `encryption`    | `object`                                                                                    | —       | Custom encryption provider satisfying the HypercoreEncryption interface.              |
| `valueEncoding` | `string\|object`                                                                            | —       | Encoding for block values (for example `'utf8'`, `'json'`, a compact-encoding codec). |
| `writable`      | `boolean`                                                                                   | `true`  | Set `false` to open the session read-only.                                            |
| `weak`          | `boolean`                                                                                   | `false` | Do not keep the underlying core alive when this session is the last one.              |
| `snapshot`      | `boolean`                                                                                   | `false` | Snapshot the core length at open time; blocks beyond that length are invisible.       |
| `timeout`       | `number`                                                                                    | `0`     | Default timeout in ms for `get()` / `seek()` (0 = no timeout).                        |
| `wait`          | `boolean`                                                                                   | `true`  | Wait for blocks to download when `get()` / `seek()` are called.                       |
| `onwait`        | `function`                                                                                  | —       | Called whenever `get()` triggers a network wait: `onwait(index, core)`.               |
| `onseq`         | `function`                                                                                  | —       | Called on each `get()` call with the block index: `onseq(index, core)`.               |
| `compat`        | `boolean`                                                                                   | `false` | Enable legacy (v9) manifest compatibility mode.                                       |
| `exclusive`     | `boolean`                                                                                   | `false` | Acquire an exclusive write lock on the core.                                          |

KeyOptions [#keyoptions]

Options for Hypercore.key() static method.

| Property    | Type                                                        | Default | Description                                                                        |
| ----------- | ----------------------------------------------------------- | ------- | ---------------------------------------------------------------------------------- |
| `compat`    | `boolean`                                                   | `false` | If `true`, returns the first signer's raw public key instead of the manifest hash. |
| `version`   | `number`                                                    | —       | Manifest version number (used when building the manifest from a raw key).          |
| `namespace` | [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer) | —       | Namespace buffer to include in the manifest when building from a raw key.          |

ProtocolStreamOptions [#protocolstreamoptions]

Options for Hypercore.createProtocolStream().

| Property         | Type       | Default | Description                                                              |
| ---------------- | ---------- | ------- | ------------------------------------------------------------------------ |
| `stream`         | `object`   | —       | An existing raw stream to wrap; avoids creating a new NoiseSecretStream. |
| `ondiscoverykey` | `function` | —       | Called with a discovery key Buffer when a remote announces a new core.   |
| `keepAlive`      | `boolean`  | `true`  | Send keep-alive pings every 5 s to prevent idle disconnection.           |

DefaultStorageOptions [#defaultstorageoptions]

Options for Hypercore.defaultStorage(). If the first argument is already a storage instance it is returned as-is; otherwise it is treated as a directory and the options are forwarded verbatim to the [`hypercore-storage`](https://github.com/holepunchto/hypercore-storage) constructor. Hypercore itself reads none of them.

SessionOptions [#sessionoptions]

Options for core.session() / core.snapshot().

| Property        | Type             | Default | Description                                                   |
| --------------- | ---------------- | ------- | ------------------------------------------------------------- |
| `valueEncoding` | `string\|object` | —       | Override the value encoding for this session only.            |
| `writable`      | `boolean`        | —       | Override the writable flag for this session.                  |
| `snapshot`      | `boolean`        | `false` | Lock the visible length to the current core length.           |
| `timeout`       | `number`         | —       | Per-session get/seek timeout in ms.                           |
| `wait`          | `boolean`        | —       | Whether to wait for remote blocks by default.                 |
| `weak`          | `boolean`        | —       | Do not keep the core alive when this session is the last one. |
| `exclusive`     | `boolean`        | `false` | Acquire an exclusive write lock on the core.                  |
| `atom`          | `object`         | —       | A storage atom to stage writes against.                       |
| `name`          | `string`         | —       | Named session; writes are staged under this name.             |
| `checkout`      | `number`         | —       | Roll back a named/atom session to this length after opening.  |

SetEncryptionKeyOptions [#setencryptionkeyoptions]

Options for core.setEncryptionKey().

| Property | Type      | Default | Description                                                               |
| -------- | --------- | ------- | ------------------------------------------------------------------------- |
| `block`  | `boolean` | `false` | Treat the supplied key as a raw block-level key rather than deriving one. |

GetOptions [#getoptions]

Options for core.get().

| Property        | Type             | Default | Description                                                                 |
| --------------- | ---------------- | ------- | --------------------------------------------------------------------------- |
| `wait`          | `boolean`        | `true`  | Wait for the block to be downloaded from a peer if not available locally.   |
| `timeout`       | `number`         | `0`     | Max ms to wait for replication (0 = use core default).                      |
| `valueEncoding` | `string\|object` | —       | Decode the block with this encoding instead of the core's default.          |
| `decrypt`       | `boolean`        | `true`  | Decrypt the block when encryption is enabled.                               |
| `raw`           | `boolean`        | `false` | Return the raw Buffer without decoding or decrypting.                       |
| `onwait`        | `function`       | —       | Called if this specific get triggers a network wait: `onwait(index, core)`. |

SeekOptions [#seekoptions]

Options for core.seek().

| Property  | Type      | Default | Description                                             |
| --------- | --------- | ------- | ------------------------------------------------------- |
| `wait`    | `boolean` | `true`  | Wait for the necessary blocks to download if not local. |
| `timeout` | `number`  | `0`     | Max ms to wait (0 = use core default).                  |

ClearOptions [#clearoptions]

Options for core.clear().

| Property | Type      | Default | Description                                                                     |
| -------- | --------- | ------- | ------------------------------------------------------------------------------- |
| `diff`   | `boolean` | `false` | Return a `{ blocks: number }` object counting cleared blocks instead of `null`. |

UpdateOptions [#updateoptions]

Options for core.update().

| Property | Type      | Default | Description                                              |
| -------- | --------- | ------- | -------------------------------------------------------- |
| `wait`   | `boolean` | `true`  | Wait for remote peers to send a new signed length proof. |
| `force`  | `boolean` | `false` | Force an update even when the core is writable.          |

TruncateOptions [#truncateoptions]

Options for core.truncate().

| Property    | Type                                                                                        | Default | Description                                                            |
| ----------- | ------------------------------------------------------------------------------------------- | ------- | ---------------------------------------------------------------------- |
| `fork`      | `number`                                                                                    | —       | The fork ID to assign after truncation (defaults to `state.fork + 1`). |
| `keyPair`   | [`{publicKey: Buffer, secretKey: Buffer}`](https://nodejs.org/api/buffer.html#class-buffer) | —       | Key pair to sign the truncation (defaults to `core.keyPair`).          |
| `signature` | [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer)                                 | —       | Pre-computed signature for the truncation.                             |

AppendOptions [#appendoptions]

Options for core.append().

| Property    | Type                                                                                        | Default | Description                                                       |
| ----------- | ------------------------------------------------------------------------------------------- | ------- | ----------------------------------------------------------------- |
| `keyPair`   | [`{publicKey: Buffer, secretKey: Buffer}`](https://nodejs.org/api/buffer.html#class-buffer) | —       | Key pair to sign the batch (defaults to `core.keyPair`).          |
| `signature` | [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer)                                 | —       | Pre-computed signature.                                           |
| `maxLength` | `number`                                                                                    | —       | Refuse to append if the resulting length would exceed this value. |

InfoOptions [#infooptions]

Options for core.info().

| Property  | Type      | Default | Description                                         |
| --------- | --------- | ------- | --------------------------------------------------- |
| `storage` | `boolean` | `false` | Include per-file storage byte counts in the result. |

ReadStreamOptions [#readstreamoptions]

Options for core.createReadStream().

| Property   | Type      | Default | Description                                                                    |
| ---------- | --------- | ------- | ------------------------------------------------------------------------------ |
| `start`    | `number`  | `0`     | Index of the first block to read.                                              |
| `end`      | `number`  | —       | Index of the block to stop at (exclusive).                                     |
| `live`     | `boolean` | `false` | Keep streaming new blocks as they are appended.                                |
| `snapshot` | `boolean` | `true`  | Snap the end to the current length at open time (ignored when `live` is true). |
| `wait`     | `boolean` | `true`  | Wait for blocks to download.                                                   |
| `timeout`  | `number`  | `0`     | Per-block timeout in ms (0 = use core default).                                |

ByteStreamOptions [#bytestreamoptions]

Options for core.createByteStream().

| Property     | Type     | Default | Description                                       |
| ------------ | -------- | ------- | ------------------------------------------------- |
| `byteOffset` | `number` | `0`     | Start reading from this byte position.            |
| `byteLength` | `number` | —       | Number of bytes to read (-1 = until end of core). |
| `prefetch`   | `number` | `32`    | Number of blocks to prefetch ahead.               |

DownloadRange [#downloadrange]

Download range descriptor for core.download().

| Property | Type      | Default | Description                                                          |
| -------- | --------- | ------- | -------------------------------------------------------------------- |
| `start`  | `number`  | `0`     | First block index to download.                                       |
| `end`    | `number`  | —       | Last block index to download (exclusive; defaults to `core.length`). |
| `linear` | `boolean` | `false` | Download blocks in sequential order.                                 |

ProofOptions [#proofoptions]

Options for core.proof().

| Property   | Type     | Default | Description                                                    |
| ---------- | -------- | ------- | -------------------------------------------------------------- |
| `block`    | `object` | —       | Request a block proof: `{ index: number }`.                    |
| `hash`     | `object` | —       | Request a hash proof: `{ index: number }`.                     |
| `seek`     | `object` | —       | Request a seek proof: `{ bytes: number }`.                     |
| `upgrade`  | `object` | —       | Request an upgrade proof: `{ start: number, length: number }`. |
| `manifest` | `object` | —       | Include a manifest proof.                                      |

CommitOptions [#commitoptions]

Options for core.commit().

| Property  | Type                                                                                        | Default | Description                                 |
| --------- | ------------------------------------------------------------------------------------------- | ------- | ------------------------------------------- |
| `keyPair` | [`{publicKey: Buffer, secretKey: Buffer}`](https://nodejs.org/api/buffer.html#class-buffer) | —       | Key pair used to sign the committed blocks. |

SweepOptions [#sweepoptions]

Options for core.sweep().

| Property    | Type     | Default | Description                                                        |
| ----------- | -------- | ------- | ------------------------------------------------------------------ |
| `batchSize` | `number` | `1000`  | Number of clear operations to run in parallel per sweep iteration. |

CloseOptions [#closeoptions]

Options for core.close().

| Property | Type    | Default | Description                                        |
| -------- | ------- | ------- | -------------------------------------------------- |
| `error`  | `Error` | —       | Error to reject pending replication requests with. |

Errors [#errors]

Coded errors this module can throw — catch them via `err.code`.

| Error                  | Thrown when                                                                                                                                                                                                                                                        |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `ASSERTION`            | if `index` is not a valid block index.; if `bytes` is not a valid byte offset.; if the `start`/`end` range is invalid.; if the provider does not satisfy the `HypercoreEncryption` interface.; if the core is already in gc mode, or is a named or atomic session. |
| `BAD_ARGUMENT`         | if an appended block exceeds the maximum suggested block size.                                                                                                                                                                                                     |
| `INVALID_OPERATION`    | if the append is inconsistent with the manifest prologue.; if the truncation would break the manifest prologue.; if no database batch was passed, or the tree changed during the batch.                                                                            |
| `SESSION_CLOSED`       | if called on a core that is already closing.; if the core has been closed.                                                                                                                                                                                         |
| `SESSION_NOT_WRITABLE` | if the core is not writable.                                                                                                                                                                                                                                       |

See also [#see-also]

* [Replicate and persist with Hypercore](/how-to/store-and-replicate/replicate-and-persist-with-hypercore)—pair a single core with peer discovery and replication.
* [Work with many Hypercores using Corestore](/how-to/store-and-replicate/work-with-many-hypercores-using-corestore)—recommended pattern when one process manages multiple cores.
* [Corestore](/reference/helpers/corestore)—helper reference for creating, naming, and co-replicating groups of Hypercores.
* [Hyperbee](/reference/building-blocks/hyperbee)—sorted key/value B-tree built directly on top of a Hypercore.
* [Hyperdrive](/reference/building-blocks/hyperdrive)—filesystem abstraction whose metadata and blob stores are Hypercore-backed.
* [Compact encoding](/reference/helpers/compact-encoding)—binary encoding toolkit used to structure Hypercore block payloads.


# HyperDHT



<Status level="stable" />

HyperDHT is the lower-level keyed connection layer underneath [Hyperswarm](/reference/building-blocks/hyperswarm). Use it when you want to dial a known public key directly or work with raw DHT discovery and record APIs.

Install [#install]

```sh
npm i hyperdht
```

Quickstart [#quickstart]

```js
import DHT from 'hyperdht'
import { once } from 'node:events'

const serverNode = new DHT()
const clientNode = new DHT()
const keyPair = DHT.keyPair()

const server = serverNode.createServer(socket => {
  socket.end('hello from hyperdht')
})

await server.listen(keyPair)
const socket = clientNode.connect(keyPair.publicKey)

await once(socket, 'open')
socket.write('ping')

for await (const chunk of socket) {
  console.log(chunk.toString())
}

await server.close()
await Promise.all([serverNode.destroy(), clientNode.destroy()])
```

API Reference [#api-reference]

Node setup [#node-setup]

new DHT([options]) [#new-dhtoptions]

[src](https://github.com/holepunchto/hyperdht/blob/v6.33.0/index.js#L26)

Create a new DHT node.

| Parameter | Type                                  | Default |
| --------- | ------------------------------------- | ------- |
| `options` | [`HyperDHTOptions`](#hyperdhtoptions) | `{}`    |

keyPair = DHT.keyPair([seed]) [#keypair--dhtkeypairseed]

Use this method to generate the required keypair for DHT operations.

* Returns: an object with `{publicKey, secretKey}`.

node = DHT.bootstrapper(port, host, [options]) [#node--dhtbootstrapperport-host-options]

If you want to run your own [Hyperswarm](/reference/building-blocks/hyperswarm) network use this method to easily create a bootstrap node.

node.defaultKeyPair [#nodedefaultkeypair]

[src](https://github.com/holepunchto/hyperdht/blob/v6.33.0/index.js#L35)

The default key pair for this node, derived from the `keyPair` or `seed` constructor option. Used by `node.connect()` and `server.listen()` when no key pair is passed explicitly.

Servers [#servers]

node.createServer([options], [onconnection]) [#nodecreateserveroptions-onconnection]

[src](https://github.com/holepunchto/hyperdht/blob/v6.33.0/index.js#L85)

Create a new server for accepting incoming encrypted P2P connections.

| Parameter      | Type                                                                   | Description                                      |
| -------------- | ---------------------------------------------------------------------- | ------------------------------------------------ |
| `options`      | [`CreateServerOptions`](#createserveroptions)                          | —                                                |
| `onconnection` | [`function(NoiseSecretStream): void`](/reference/helpers/secretstream) | Shorthand listener for the `'connection'` event. |

* Returns: `Server` — A server object — call `server.listen(keyPair)` to start accepting connections.

```js
{
  firewall (remotePublicKey, remoteHandshakePayload) {
    // validate if you want a connection from remotePublicKey
    // if you do return false, else return true
    // remoteHandshakePayload contains their ip and some more info
    return true
  }
}
```

await server.listen(keyPair) [#await-serverlistenkeypair]

Make the server listen on a keyPair. To connect to this server use keyPair.publicKey as the connect address.

* Throws:
  * `ALREADY_LISTENING` if the server is already listening.
  * `NODE_DESTROYED` if the DHT node has been destroyed.

server.refresh() [#serverrefresh]

Refresh the server, causing it to reannounce its address. This is automatically called on network changes.

Call this to reannounce the server address. HyperDHT also calls it automatically when the network changes.

server.address() [#serveraddress]

You can also get this info from `node.remoteAddress()` minus the public key.

* Returns: an object containing the address of the server:

```js
{
  ;(host, // external IP of the server,
    port, // external port of the server if predictable,
    publicKey) // public key of the server
}
```

server.on('connection', socket) [#serveronconnection-socket]

Emitted when a new encrypted connection has passed the firewall check.

The socket exposes `socket.remotePublicKey`, and `socket.handshakeHash` is a shared identifier for the encrypted session.

server.on('listening') [#serveronlistening]

Emitted when the server is fully listening on a keyPair.

await server.close() [#await-serverclose]

Stop listening.

server.on('close') [#serveronclose]

Emitted when the server is fully closed.

Clients and sockets [#clients-and-sockets]

node.connect(remotePublicKey, [options]) [#nodeconnectremotepublickey-options]

[src](https://github.com/holepunchto/hyperdht/blob/v6.33.0/index.js#L81)

Connect to a remote server. Similar to `createServer` this performs UDP holepunching for P2P connectivity.

| Parameter         | Type                                                                | Description                                                                      |
| ----------------- | ------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| `remotePublicKey` | [`Buffer\|string`](https://nodejs.org/api/buffer.html#class-buffer) | Public key of the server to connect to (Buffer, hex string, or z-base32 string). |
| `options`         | [`ConnectOptions`](#connectoptions)                                 | —                                                                                |

* Returns: [`NoiseSecretStream`](/reference/helpers/secretstream) — An encrypted duplex stream — use `socket.on('open', ...)` to know when it is ready.

socket.on('open') [#socketonopen]

Emitted when the encrypted connection has been fully established with the server.

socket.remotePublicKey [#socketremotepublickey]

The public key of the remote peer.

socket.publicKey [#socketpublickey]

The public key of the local socket.

Peer discovery [#peer-discovery]

node.lookup(topic, [options]) [#nodelookuptopic-options]

[src](https://github.com/holepunchto/hyperdht/blob/v6.33.0/index.js#L194)

Look for peers in the DHT on the given topic. Topic should be a 32 byte buffer (normally a hash of something).

| Parameter | Type                                                        | Default | Description                     |
| --------- | ----------------------------------------------------------- | ------- | ------------------------------- |
| `topic`   | [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer) | —       | —                               |
| `options` | `object`                                                    | `{}`    | Options forwarded to `dht-rpc`. |

* Returns: `QueryStream` — An async-iterable query stream whose values are `{ from, to, peers }` objects.

node.findPeer(publicKey, [options]) [#nodefindpeerpublickey-options]

[src](https://github.com/holepunchto/hyperdht/blob/v6.33.0/index.js#L188)

Find the addresses of a specific peer, keyed by `hash(publicKey)`—a `lookup` specialized for locating one peer rather than a topic. Pass `{ hash: false }` in `options` to query the raw `publicKey` as the topic instead of its hash.

| Parameter   | Type                                                        | Default | Description                                                                       |
| ----------- | ----------------------------------------------------------- | ------- | --------------------------------------------------------------------------------- |
| `publicKey` | [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer) | —       | The 32-byte public key of the peer to locate.                                     |
| `options`   | `object`                                                    | `{}`    | Forwarded to the underlying query; set `hash: false` to skip hashing `publicKey`. |

* Returns: `QueryStream` — An async-iterable query stream, like `node.lookup()`.

node.announce(topic, keyPair, [relayAddresses], [options]) [#nodeannouncetopic-keypair-relayaddresses-options]

[src](https://github.com/holepunchto/hyperdht/blob/v6.33.0/index.js#L246)

Announce that you are listening on a key-pair to the DHT under a specific topic.

| Parameter        | Type                                                                                                                            | Default | Description                                                      |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------- | ------- | ---------------------------------------------------------------- |
| `topic`          | [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer)                                                                     | —       | 32-byte topic buffer to announce under.                          |
| `keyPair`        | [`{publicKey: Buffer, secretKey: Buffer}`](https://nodejs.org/api/buffer.html#class-buffer)                                     | —       | The Ed25519 key pair to announce with.                           |
| `relayAddresses` | [`Array<{host: string, port: number}>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) | —       | Up to 3 DHT relay node addresses to include in the announcement. |
| `options`        | `object`                                                                                                                        | `{}`    | Options forwarded to `dht-rpc`.                                  |

* Returns: `QueryStream` — An async-iterable query stream (same shape as `lookup()`).

```js
const topic = DHT.hash(Buffer.from('my-topic'))
const stream = node.announce(topic, keyPair)
await stream.finished()
```

Servers created with `node.createServer()` already announce themselves on the key pair they are listening on. Use `node.announce()` when you also want to publish a topic mapping.

await node.unannounce(topic, keyPair, [options]) [#await-nodeunannouncetopic-keypair-options]

[src](https://github.com/holepunchto/hyperdht/blob/v6.33.0/index.js#L242)

Unannounce a key-pair.

| Parameter | Type                                                                                        | Default | Description                                           |
| --------- | ------------------------------------------------------------------------------------------- | ------- | ----------------------------------------------------- |
| `topic`   | [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer)                                 | —       | 32-byte topic buffer previously used in `announce()`. |
| `keyPair` | [`{publicKey: Buffer, secretKey: Buffer}`](https://nodejs.org/api/buffer.html#class-buffer) | —       | The Ed25519 key pair to unannounce.                   |
| `options` | `object`                                                                                    | `{}`    | Options forwarded to `dht-rpc`.                       |

* Returns: [`Promise<void>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) — Resolves when the unannounce query has completed.

```js
const topic = DHT.hash(Buffer.from('my-topic'))
await node.unannounce(topic, keyPair)
```

Mutable and immutable records [#mutable-and-immutable-records]

await node.immutablePut(value, [options]) [#await-nodeimmutableputvalue-options]

[src](https://github.com/holepunchto/hyperdht/blob/v6.33.0/index.js#L283)

Store an immutable value in the DHT. When successful, the hash of the value is returned.

| Parameter | Type                                                        | Default | Description                     |
| --------- | ----------------------------------------------------------- | ------- | ------------------------------- |
| `value`   | [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer) | —       | The value to store (a Buffer).  |
| `options` | `object`                                                    | `{}`    | Options forwarded to `dht-rpc`. |

* Returns: [`Promise<{hash: Buffer, closestNodes: Array<object>}>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) — Object with the 32-byte `hash` and the `closestNodes` that stored the value.

```js
const { hash } = await node.immutablePut(Buffer.from('hello world'))
const result = await node.immutableGet(hash)
console.log(result.value.toString()) // 'hello world'
```

await node.immutableGet(hash, [options]) [#await-nodeimmutablegethash-options]

[src](https://github.com/holepunchto/hyperdht/blob/v6.33.0/index.js#L268)

Fetch an immutable value from the DHT. When successful, it returns the value corresponding to the hash.

| Parameter | Type                                                        | Default | Description                                                        |
| --------- | ----------------------------------------------------------- | ------- | ------------------------------------------------------------------ |
| `hash`    | [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer) | —       | 32-byte hash of the value to fetch (returned by `immutablePut()`). |
| `options` | `object`                                                    | `{}`    | Options forwarded to `dht-rpc`.                                    |

* Returns: [`Promise<{token: Buffer, from: object, to: object, value: Buffer}\|null>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) — The result node or `null` if not found.

```js
const result = await node.immutableGet(hash)
if (result) console.log(result.value.toString())
```

await node.mutablePut(keyPair, value, [options]) [#await-nodemutableputkeypair-value-options]

[src](https://github.com/holepunchto/hyperdht/blob/v6.33.0/index.js#L357)

Store a mutable value in the DHT.

| Parameter | Type                                                                                        | Default | Description                              |
| --------- | ------------------------------------------------------------------------------------------- | ------- | ---------------------------------------- |
| `keyPair` | [`{publicKey: Buffer, secretKey: Buffer}`](https://nodejs.org/api/buffer.html#class-buffer) | —       | Ed25519 key pair used to sign the value. |
| `value`   | [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer)                                 | —       | The value to store (a Buffer).           |
| `options` | [`MutablePutOptions`](#mutableputoptions)                                                   | `{}`    | Put options.                             |

* Returns: [`Promise<{publicKey: Buffer, closestNodes: Array<object>, seq: number, signature: Buffer}>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) — The stored record metadata.

```js
const keyPair = DHT.keyPair()
const { seq } = await node.mutablePut(keyPair, Buffer.from('v1'), { seq: 0 })
console.log('stored at seq', seq)
```

await node.mutableGet(publicKey, [options]) [#await-nodemutablegetpublickey-options]

[src](https://github.com/holepunchto/hyperdht/blob/v6.33.0/index.js#L304)

Fetch a mutable value from the DHT.

| Parameter   | Type                                                        | Default | Description                                                                    |
| ----------- | ----------------------------------------------------------- | ------- | ------------------------------------------------------------------------------ |
| `publicKey` | [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer) | —       | Ed25519 public key of the key pair used to sign the value with `mutablePut()`. |
| `options`   | [`MutableGetOptions`](#mutablegetoptions)                   | `{}`    | Fetch options.                                                                 |

* Returns: [`Promise<{token: Buffer, from: object, to: object, seq: number, value: Buffer, signature: Buffer}\|null>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) — The latest matching result, or `null` if not found.

```js
const result = await node.mutableGet(keyPair.publicKey)
if (result) console.log(result.value.toString(), 'seq:', result.seq)
```

Lifecycle [#lifecycle]

await node.suspend([options]) [#await-nodesuspendoptions]

[src](https://github.com/holepunchto/hyperdht/blob/v6.33.0/index.js#L107)

Suspend the node's network activity—used when the host device is about to sleep or lose connectivity. Suspends every listening server, clears raw streams, and suspends the underlying `dht-rpc` instance; new connections are refused while suspended.

| Parameter | Type     | Default | Description                                                  |
| --------- | -------- | ------- | ------------------------------------------------------------ |
| `options` | `object` | `{}`    | Pass `{ log }` with a function to receive progress messages. |

* Returns: [`Promise<void>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) — Resolves once the node is fully suspended.

await node.resume([options]) [#await-noderesumeoptions]

[src](https://github.com/holepunchto/hyperdht/blob/v6.33.0/index.js#L97)

Resume a suspended node: resumes `dht-rpc` and re-resumes every listening server. Call this after the device wakes or regains connectivity.

| Parameter | Type     | Default | Description                                                  |
| --------- | -------- | ------- | ------------------------------------------------------------ |
| `options` | `object` | `{}`    | Pass `{ log }` with a function to receive progress messages. |

* Returns: [`Promise<void>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) — Resolves once the node is fully resumed.

await node.destroy([options]) [#await-nodedestroyoptions]

[src](https://github.com/holepunchto/hyperdht/blob/v6.33.0/index.js#L123)

Fully destroy this DHT node.

| Parameter | Type     | Default | Description                                                                      |
| --------- | -------- | ------- | -------------------------------------------------------------------------------- |
| `options` | `object` | `{}`    | Pass `{ force: true }` to skip waiting for servers to unannounce before closing. |

* Returns: [`Promise<void>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) — Resolves when the node is fully shut down.

```js
await node.destroy()
// or, to skip graceful unannounce:
await node.destroy({ force: true })
```

HyperDHT inherits additional lower-level RPC APIs from [`dht-rpc`](https://github.com/mafintosh/dht-rpc). Reach for those when you need custom queries beyond the keyed connection and record helpers above.

Types [#types]

HyperDHTOptions [#hyperdhtoptions]

Options for creating a HyperDHT node.

| Property              | Type                                                                                                      | Default | Description                                                                                   |
| --------------------- | --------------------------------------------------------------------------------------------------------- | ------- | --------------------------------------------------------------------------------------------- |
| `bootstrap`           | [`Array<string>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) | —       | Bootstrap server addresses (`'host:port'`). Defaults to the Holepunch public bootstrap nodes. |
| `keyPair`             | [`{publicKey: Buffer, secretKey: Buffer}`](https://nodejs.org/api/buffer.html#class-buffer)               | —       | Default key pair used for `server.listen()` and `connect()`.                                  |
| `connectionKeepAlive` | `number\|false`                                                                                           | `5000`  | Keep-alive interval in ms for all opened sockets. Set `false` to disable.                     |
| `randomPunchInterval` | `number`                                                                                                  | `20000` | Minimum ms between random holepunches.                                                        |

CreateServerOptions [#createserveroptions]

Options for `node.createServer()`.

| Property         | Type                                                                                                                                        | Default | Description                                                                                                                               |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `firewall`       | [`function(Buffer, object): boolean`](https://nodejs.org/api/buffer.html#class-buffer)                                                      | —       | Called with `(remotePublicKey, remoteHandshakePayload)`. Return `true` to block, `false` to allow.                                        |
| `holepunch`      | [`function(number, number, Array, Array): boolean`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) | —       | Called before holepunching begins. Return `false` to abort.                                                                               |
| `relayThrough`   | [`Buffer\|Array<Buffer>\|function(): Buffer\|null`](https://nodejs.org/api/buffer.html#class-buffer)                                        | —       | Optionally relay through a specific peer — pass a public key (Buffer), an array of public keys to pick from, or a function returning one. |
| `relayKeepAlive` | `number`                                                                                                                                    | `5000`  | Keep-alive interval in ms for the relay socket.                                                                                           |

ConnectOptions [#connectoptions]

Options for `node.connect()`.

| Property         | Type                                                                                                                            | Default | Description                                                                                                                               |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `nodes`          | [`Array<{host: string, port: number}>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) | —       | Known DHT nodes close to the remote — speeds up connecting.                                                                               |
| `relayAddresses` | [`Array<{host: string, port: number}>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) | —       | Relay server addresses to hole-punch through when a direct connection cannot be established.                                              |
| `keyPair`        | [`{publicKey: Buffer, secretKey: Buffer}`](https://nodejs.org/api/buffer.html#class-buffer)                                     | —       | Key pair to use for this connection. Defaults to `node.defaultKeyPair`.                                                                   |
| `relayThrough`   | [`Buffer\|Array<Buffer>\|function(): Buffer\|null`](https://nodejs.org/api/buffer.html#class-buffer)                            | —       | Optionally relay through a specific peer — pass a public key (Buffer), an array of public keys to pick from, or a function returning one. |

MutableGetOptions [#mutablegetoptions]

Options for `node.mutableGet()`.

| Property  | Type                        | Default | Description                                                                     |
| --------- | --------------------------- | ------- | ------------------------------------------------------------------------------- |
| `seq`     | `number`                    | `0`     | Only return values whose `seq` is >= this number.                               |
| `latest`  | `boolean`                   | `true`  | If `true`, scan the whole query and return the highest `seq` seen.              |
| `refresh` | `function(object): boolean` | —       | Called with the latest result; return `true` to re-store it, extending its TTL. |

MutablePutOptions [#mutableputoptions]

Options for `node.mutablePut()`.

| Property      | Type                                                                                                   | Default | Description                                                                                 |
| ------------- | ------------------------------------------------------------------------------------------------------ | ------- | ------------------------------------------------------------------------------------------- |
| `seq`         | `number`                                                                                               | `0`     | Sequence number for this value. Must be greater than the current stored `seq` to overwrite. |
| `signMutable` | [`function(number, Buffer, object): Promise<Buffer>`](https://nodejs.org/api/buffer.html#class-buffer) | —       | Custom signing function. Defaults to the built-in Ed25519 signer.                           |

Errors [#errors]

Coded errors this module can throw — catch them via `err.code`.

| Error               | Thrown when                         |
| ------------------- | ----------------------------------- |
| `ALREADY_LISTENING` | if the server is already listening. |
| `NODE_DESTROYED`    | if the DHT node has been destroyed. |

See also [#see-also]

* [Connect two peers by key with HyperDHT](/how-to/connect-to-peers/connect-two-peers-by-key-with-hyperdht)—step-by-step direct peer connection flow.
* [Connect to many peers by topic with Hyperswarm](/how-to/connect-to-peers/connect-to-many-peers-by-topic-with-hyperswarm)—higher-level topic discovery and connection management.
* [Hyperswarm](/reference/building-blocks/hyperswarm)—higher-level swarm abstraction built on HyperDHT.
* [Secretstream](/reference/helpers/secretstream)—the Noise-encrypted stream layer that wraps all HyperDHT connections.
* [Hyperbeam](/reference/tools/hyperbeam)—one-to-one encrypted pipe CLI built on HyperDHT.
* [Hypershell](/reference/tools/hypershell)—encrypted remote shell and file-copy tools built on HyperDHT.
* [Hypertele](/reference/tools/hypertele)—TCP proxy CLI built on HyperDHT.
* [Hyperssh](/reference/tools/hyperssh)—SSH and SSHFS access routed through HyperDHT.


# Hyperdrive



<Status level="stable" />

`Hyperdrive` stores filesystem metadata in a [Hyperbee](/reference/building-blocks/hyperbee) and file contents in a blob store, typically backed by one [Corestore](/reference/helpers/corestore). Use this page for the instance surface; use the linked how-to guides for end-to-end replication flows.

<Callout type="info">
  For when to choose Hyperdrive over Hyperblobs or raw [Hypercore](/reference/building-blocks/hypercore), see [From append-only logs to files](/explanation/from-logs-to-files).
</Callout>

Install [#install]

```sh
npm i hyperdrive
```

Quickstart [#quickstart]

```js
import Corestore from 'corestore'
import Hyperdrive from 'hyperdrive'

const store = new Corestore('./storage')
const drive = new Hyperdrive(store)

await drive.ready()

await drive.put('/hello.txt', Buffer.from('hello world'), {
  metadata: { type: 'text/plain' }
})

const buffer = await drive.get('/hello.txt')
const entry = await drive.entry('/hello.txt')

console.log(buffer.toString())
console.log(entry?.value.metadata)

await drive.close()
```

API Reference [#api-reference]

Constructor and lifecycle [#constructor-and-lifecycle]

new Hyperdrive(store, [key]) [#new-hyperdrivestore-key]

[src](https://github.com/holepunchto/hyperdrive/blob/v13.3.3/index.js#L21)

Creates a new Hyperdrive instance. `store` must be an instance of `Corestore`.

| Parameter   | Type                                                        | Default | Description                                                                           |
| ----------- | ----------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------- |
| `corestore` | [`Corestore`](/reference/helpers/corestore)                 | —       | —                                                                                     |
| `key`       | [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer) | —       | Public key of an existing drive to load. May be omitted, passing `opts` in its place. |
| `opts`      | [`DriveOptions`](#driveoptions)                             | `{}`    | Drive options.                                                                        |

```js
const Corestore = require('corestore')

const store = new Corestore('./storage')
const drive = new Hyperdrive(store)
```

await Hyperdrive.getDriveKey(corestore) [#await-hyperdrivegetdrivekeycorestore]

[src](https://github.com/holepunchto/hyperdrive/blob/v13.3.3/index.js#L52)

Static helper that resolves a drive's public key from a `Corestore` without constructing a `Hyperdrive`. Opens the metadata Hypercore in the store's default namespace, reads its `key`, then closes it again.

| Parameter   | Type                                        | Default | Description                                |
| ----------- | ------------------------------------------- | ------- | ------------------------------------------ |
| `corestore` | [`Corestore`](/reference/helpers/corestore) | —       | The store whose default drive key to read. |

* Returns: [`Promise<Buffer>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) — the 32-byte drive key.

await drive.ready() [#await-driveready]

Waits until internal state is loaded.

await drive.close() [#await-driveclose]

Fully close this drive, including its underlying Hypercore backed datastructures.

await drive.purge() [#await-drivepurge]

[src](https://github.com/holepunchto/hyperdrive/blob/v13.3.3/index.js#L377)

Purge both cores (db and blobs) from your storage, completely removing all the drive's data.

* Returns: [`Promise<void>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) — Resolves once both cores are purged from storage.
* Throws: if called on a non-main session — only the main session can be purged.

```js
await drive.purge()
```

Drive properties [#drive-properties]

drive.corestore [#drivecorestore]

[src](https://github.com/holepunchto/hyperdrive/blob/v13.3.3/index.js#L29)

The Corestore instance used as storage.

* Returns: [`Corestore`](/reference/helpers/corestore)

drive.db [#drivedb]

[src](https://github.com/holepunchto/hyperdrive/blob/v13.3.3/index.js#L30)

The underlying Hyperbee backing the drive file structure.

* Returns: [`Hyperbee`](/reference/building-blocks/hyperbee)

drive.core [#drivecore]

[src](https://github.com/holepunchto/hyperdrive/blob/v13.3.3/index.js#L31)

The Hypercore used for `drive.db`.

* Returns: [`Hypercore`](/reference/building-blocks/hypercore)

drive.blobs [#driveblobs]

[src](https://github.com/holepunchto/hyperdrive/blob/v13.3.3/index.js#L300)

The [Hyperblobs](https://github.com/holepunchto/hyperblobs) instance that stores file contents, keyed by the blob pointers held in `drive.db`. It is `null` until the drive has opened — call `drive.getBlobs()` if you need it resolved.

* Returns: [`Hyperblobs`](https://github.com/holepunchto/hyperblobs) | `null`

drive.id [#driveid]

[src](https://github.com/holepunchto/hyperdrive/blob/v13.3.3/index.js#L83)

String containing the id (z-base-32 of the public key) identifying this drive.

* Returns: `string`

drive.key [#drivekey]

[src](https://github.com/holepunchto/hyperdrive/blob/v13.3.3/index.js#L87)

The public key of the Hypercore backing the drive.

* Returns: [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer)

drive.discoveryKey [#drivediscoverykey]

[src](https://github.com/holepunchto/hyperdrive/blob/v13.3.3/index.js#L91)

The hash of the public key of the Hypercore backing the drive.

* Returns: [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer)

drive.contentKey [#drivecontentkey]

[src](https://github.com/holepunchto/hyperdrive/blob/v13.3.3/index.js#L95)

The public key of the [Hyperblobs](https://github.com/holepunchto/hyperblobs) instance holding blobs associated with entries in the drive.

* Returns: [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer)

drive.writable [#drivewritable]

[src](https://github.com/holepunchto/hyperdrive/blob/v13.3.3/index.js#L103)

Boolean indicating if we can write or delete data in this drive.

* Returns: `boolean`

drive.readable [#drivereadable]

[src](https://github.com/holepunchto/hyperdrive/blob/v13.3.3/index.js#L107)

Boolean indicating if we can read from this drive. After closing the drive this will be `false`.

* Returns: `boolean`

drive.version [#driveversion]

[src](https://github.com/holepunchto/hyperdrive/blob/v13.3.3/index.js#L99)

Number that indicates how many modifications were made, useful as a version identifier.

* Returns: `number`

drive.supportsMetadata [#drivesupportsmetadata]

[src](https://github.com/holepunchto/hyperdrive/blob/v13.3.3/index.js#L33)

Boolean indicating if the drive handles or not metadata. Always `true`.

* Returns: `boolean`

Files [#files]

await drive.put(path, buffer, [options]) [#await-driveputpath-buffer-options]

[src](https://github.com/holepunchto/hyperdrive/blob/v13.3.3/index.js#L330)

Creates a file at `path` in the drive. `options` are the same as in `createWriteStream`.

| Parameter | Type                                                        | Default | Description                |
| --------- | ----------------------------------------------------------- | ------- | -------------------------- |
| `path`    | `string`                                                    | —       | Path to write the file at. |
| `buffer`  | [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer) | —       | Blob contents to store.    |
| `options` | [`WriteOptions`](#writeoptions)                             | `{}`    | —                          |

* Returns: [`Promise<void>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) — Resolves once the file has been written.

```js
await drive.put('/blob.txt', Buffer.from('example'))
```

await drive.get(path, [options]) [#await-drivegetpath-options]

[src](https://github.com/holepunchto/hyperdrive/blob/v13.3.3/index.js#L316)

Reads the blob stored at `path` and resolves with its contents as a `Buffer`. Resolves with `null` when no blob exists at `path`, and also returns `null` for symbolic links.

| Parameter | Type                        | Description               |
| --------- | --------------------------- | ------------------------- |
| `path`    | `string`                    | Path of the file to read. |
| `options` | [`GetOptions`](#getoptions) | —                         |

* Returns: [`Promise<Buffer\|null>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) — The blob at `path`, or `null` if the path does not exist or is a symbolic link.
* Throws: `BLOCK_NOT_AVAILABLE` if a required block is not available.

await drive.entry(path, [options]) [#await-driveentrypath-options]

[src](https://github.com/holepunchto/hyperdrive/blob/v13.3.3/index.js#L396)

Resolves with the entry stored at `path`, or `null` if no entry exists.

| Parameter | Type                            | Description                |
| --------- | ------------------------------- | -------------------------- |
| `path`    | `string`                        | Path of the entry to read. |
| `options` | [`EntryOptions`](#entryoptions) | —                          |

* Returns: [`Promise<object>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) — the entry at `path` in the drive.
* Throws: if a symlink chain is recursive or exceeds 16 hops when `follow` is enabled.

| Property | Type     |
| -------- | -------- |
| `seq`    | `Number` |
| `key`    | `String` |
| `value`  | `Object` |

await drive.exists(path) [#await-driveexistspath]

[src](https://github.com/holepunchto/hyperdrive/blob/v13.3.3/index.js#L415)

Checks whether an entry exists at `path`.

| Parameter | Type     | Description    |
| --------- | -------- | -------------- |
| `path`    | `string` | Path to check. |

* Returns: [`Promise<boolean>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) — `true` if the entry at `path` does exists, otherwise `false`.

```js
const exists = await drive.exists('/blob.txt')
```

await drive.has(path) [#await-drivehaspath]

[src](https://github.com/holepunchto/hyperdrive/blob/v13.3.3/index.js#L483)

Checks if path is saved to local store already.

| Parameter | Type     | Description                     |
| --------- | -------- | ------------------------------- |
| `path`    | `string` | of the file or folder to check. |

* Returns: [`Promise<boolean>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) — `true` if the blob (or every blob under a folder) is stored locally.

```js
const exists = await drive.has('/blob.txt')
```

await drive.del(path) [#await-drivedelpath]

[src](https://github.com/holepunchto/hyperdrive/blob/v13.3.3/index.js#L340)

Deletes the file at `path` from the drive.

| Parameter | Type     | Description                 |
| --------- | -------- | --------------------------- |
| `path`    | `string` | Path of the file to delete. |

* Returns: [`Promise<void>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) — Resolves once the entry has been deleted.

```js
await drive.del('/blob.txt')
```

await drive.clear(path, [options]) [#await-driveclearpath-options]

[src](https://github.com/holepunchto/hyperdrive/blob/v13.3.3/index.js#L349)

Deletes the blob from storage to free up space, but the file structure reference is kept.

| Parameter | Type                            | Description                                    |
| --------- | ------------------------------- | ---------------------------------------------- |
| `path`    | `string`                        | Path of the file whose blob should be cleared. |
| `options` | [`ClearOptions`](#clearoptions) | —                                              |

* Returns: [`Promise<object>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) — A `{ blocks }` object when `diff` is enabled, otherwise `null`.

await drive.clearAll([options]) [#await-driveclearalloptions]

[src](https://github.com/holepunchto/hyperdrive/blob/v13.3.3/index.js#L367)

Deletes all the blobs from storage to free up space, similar to how `drive.clear()` works.

| Parameter | Type                            |
| --------- | ------------------------------- |
| `options` | [`ClearOptions`](#clearoptions) |

* Returns: [`Promise<object>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) — A `{ blocks }` object when `diff` is enabled, otherwise `null`.

await drive.symlink(name, dst, [options]) [#await-drivesymlinkname-dst-options]

[src](https://github.com/holepunchto/hyperdrive/blob/v13.3.3/index.js#L388)

Creates an entry in drive at `name` that points to the entry at `dst`.

| Parameter | Type                                | Default | Description                    |
| --------- | ----------------------------------- | ------- | ------------------------------ |
| `name`    | `string`                            | —       | Path of the symlink to create. |
| `dst`     | `string`                            | —       | Path the symlink points to.    |
| `options` | [`SymlinkOptions`](#symlinkoptions) | `{}`    | Symlink options.               |

* Returns: [`Promise<void>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) — Resolves once the symlink entry has been created.

```js
await drive.symlink('/images/logo.shortcut', '/images/logo.png')
```

drive.createReadStream(path, [options]) [#drivecreatereadstreampath-options]

[src](https://github.com/holepunchto/hyperdrive/blob/v13.3.3/index.js#L525)

Returns a readable stream of the blob stored in the drive at `path`.

| Parameter | Type     | Description               |
| --------- | -------- | ------------------------- |
| `path`    | `string` | Path of the file to read. |
| `options` | `object` | —                         |

* Returns: [`Readable`](https://nodejs.org/api/stream.html#class-streamreadable) — a stream to read out the blob stored in the drive at `path`.

| Option    | Type      | Description                                                        |
| --------- | --------- | ------------------------------------------------------------------ |
| `start`   | `Number`  | `start` and `end` are inclusive                                    |
| `end`     | `Number`  | —                                                                  |
| `length`  | `Number`  | `length` overrides `end`, they're not meant to be used together    |
| `wait`    | `Boolean` | Wait for blocks to be downloaded. Defaults to `true`               |
| `timeout` | `Number`  | Wait at max some milliseconds. Defaults to `0`, meaning no timeout |

drive.createWriteStream(path, [options]) [#drivecreatewritestreampath-options]

[src](https://github.com/holepunchto/hyperdrive/blob/v13.3.3/index.js#L579)

Stream a blob into the drive at `path`.

| Parameter | Type                            | Default | Description                                                           |
| --------- | ------------------------------- | ------- | --------------------------------------------------------------------- |
| `path`    | `string`                        | —       | Path of the file to write.                                            |
| `options` | [`WriteOptions`](#writeoptions) | `{}`    | Write options — the same as for `drive.put(path, buffer, [options])`. |

* Returns: [`Writable`](https://nodejs.org/api/stream.html#class-streamwritable) — A writable stream; data written is stored as the file's blob.

Directories and listings [#directories-and-listings]

drive.list(folder, [options]) [#drivelistfolder-options]

[src](https://github.com/holepunchto/hyperdrive/blob/v13.3.3/index.js#L503)

Returns a stream of all entries in the drive at paths prefixed with `folder`.

| Parameter | Type     | Default | Description                                       |
| --------- | -------- | ------- | ------------------------------------------------- |
| `folder`  | `string` | —       | Path prefix to list. Defaults to the whole drive. |
| `options` | `object` | `{}`    | —                                                 |

* Returns: [`Readable`](https://nodejs.org/api/stream.html#class-streamreadable) — a stream of all entries in the drive at paths prefixed with `folder`.

| Option      | Default | Description                                   |
| ----------- | ------- | --------------------------------------------- |
| `recursive` | —       | Whether to descend into all subfolders or not |
| `ignore`    | —       | Ignore files and folders by name              |
| `wait`      | `true`  | Wait for block to be downloaded.              |

drive.readdir(folder, [options]) [#drivereaddirfolder-options]

[src](https://github.com/holepunchto/hyperdrive/blob/v13.3.3/index.js#L516)

Returns a stream of the immediate subpaths of entries stored at paths prefixed by `folder`.

| Parameter | Type     | Description          |
| --------- | -------- | -------------------- |
| `folder`  | `string` | Path prefix to read. |
| `options` | `object` | —                    |

* Returns: [`Readable`](https://nodejs.org/api/stream.html#class-streamreadable) — a stream of all subpaths of entries in drive stored at paths prefixed by `folder`.

| Option | Default | Description                     |
| ------ | ------- | ------------------------------- |
| `wait` | `true`  | Wait for block to be downloaded |

await drive.entries([range], [options]) [#await-driveentriesrange-options]

[src](https://github.com/holepunchto/hyperdrive/blob/v13.3.3/index.js#L471)

Returns a read stream of the drive entries within the given Hyperbee `range`.

| Parameter | Type     | Description                                                                  |
| --------- | -------- | ---------------------------------------------------------------------------- |
| `range`   | `object` | Hyperbee range bounds (`gt`/`gte`/`lt`/`lte`).                               |
| `options` | `object` | `options` are the same as `Hyperbee().createReadStream([range], [options])`. |

* Returns: [`Readable`](https://nodejs.org/api/stream.html#class-streamreadable) — a read stream of entries in the drive.

```js
for await (const entry of drive.entries()) console.log(entry.key)
```

drive.compare(entryA, entryB) [#drivecompareentrya-entryb]

[src](https://github.com/holepunchto/hyperdrive/blob/v13.3.3/index.js#L344)

Compares two entries by their sequence number.

| Parameter | Type     | Description                                        |
| --------- | -------- | -------------------------------------------------- |
| `entryA`  | `object` | The first entry (as returned by `drive.entry()`).  |
| `entryB`  | `object` | The second entry (as returned by `drive.entry()`). |

* Returns: `number` — `0` if entries are the same, `1` if `entryA` is newer, and `-1` if `entryB` is newer.

```js
const comparison = drive.compare(entryA, entryB)
```

drive.watch([folder]) [#drivewatchfolder]

[src](https://github.com/holepunchto/hyperdrive/blob/v13.3.3/index.js#L419)

Returns an async iterator that watches `folder` (defaults to `/`) and yields `[current, previous]` snapshot pairs whenever the drive changes. The snapshots are auto-closed before the next value, so do not close them yourself.

| Parameter | Type     | Description                |
| --------- | -------- | -------------------------- |
| `folder`  | `string` | to watch. Defaults to `/`. |

* Returns: [`Watcher`](/reference/building-blocks/hyperbee) — an iterator that listens on `folder` to yield changes, by default on `/`.

```js
for await (const [current, previous] of watcher) {
  console.log(current.version)
  console.log(previous.version)
}
```

Versions and batched mutations [#versions-and-batched-mutations]

drive.batch() [#drivebatch]

[src](https://github.com/holepunchto/hyperdrive/blob/v13.3.3/index.js#L169)

Useful for atomically mutate the drive, has the same interface as Hyperdrive.

* Returns: [`Hyperdrive`](/reference/building-blocks/hyperdrive) — A batch with the same interface as Hyperdrive; call `batch.flush()` to commit.

```js
const batch = drive.batch()
await batch.put('/a.txt', Buffer.from('a'))
await batch.flush()
```

await batch.flush() [#await-batchflush]

[src](https://github.com/holepunchto/hyperdrive/blob/v13.3.3/index.js#L187)

Commit a batch of mutations to the underlying drive.

* Returns: [`Promise<void>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) — Resolves once the batch is committed and closed.

```js
await batch.flush()
```

drive.checkout(version) [#drivecheckoutversion]

[src](https://github.com/holepunchto/hyperdrive/blob/v13.3.3/index.js#L165)

Get a read-only snapshot of a previous version.

| Parameter | Type     | Description                |
| --------- | -------- | -------------------------- |
| `version` | `number` | Drive version to snapshot. |

* Returns: [`Hyperdrive`](/reference/building-blocks/hyperdrive) — A read-only Hyperdrive at the requested version.

```js
const snapshot = drive.checkout(4)
```

drive.diff(version, folder, [options]) [#drivediffversion-folder-options]

[src](https://github.com/holepunchto/hyperdrive/blob/v13.3.3/index.js#L428)

Efficiently create a stream of the changes to `folder` between `version` and `drive.version`.

| Parameter | Type     | Description                                                     |
| --------- | -------- | --------------------------------------------------------------- |
| `version` | `number` | Drive version to diff against the current `drive.version`.      |
| `folder`  | `string` | Path prefix to scope the diff to. Omit for the whole drive.     |
| `options` | `object` | Diff options, forwarded to the underlying Hyperbee diff stream. |

* Returns: [`Readable`](https://nodejs.org/api/stream.html#class-streamreadable) — A stream of `{ left, right }` diff entries.

| Property | Type     | Description                                              |
| -------- | -------- | -------------------------------------------------------- |
| `left`   | `Object` | Entry in folder at drive.version for some path           |
| `right`  | `Object` | Entry in folder at drive.checkout(version) for some path |

await drive.truncate(version, [options] }) [#await-drivetruncateversion-options-]

[src](https://github.com/holepunchto/hyperdrive/blob/v13.3.3/index.js#L115)

Truncates the Hyperdrive to a previous version (both the file-structure reference and the blobs).

| Parameter | Type                                  | Default | Description                   |
| --------- | ------------------------------------- | ------- | ----------------------------- |
| `version` | `number`                              | —       | Drive version to truncate to. |
| `options` | [`TruncateOptions`](#truncateoptions) | `{}`    | Truncate options.             |

* Returns: [`Promise<void>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) — Resolves once the drive and its blobs are truncated.
* Throws: `BAD_ARGUMENT` if the truncation length is invalid.

```js
await drive.truncate(drive.version - 1)
```

Replication, downloads, and blob access [#replication-downloads-and-blob-access]

drive.mirror(out, [options]) [#drivemirrorout-options]

[src](https://github.com/holepunchto/hyperdrive/blob/v13.3.3/index.js#L521)

Efficiently mirror this drive into another. Returns a [`MirrorDrive`](https://github.com/holepunchto/mirror-drive#api) instance constructed with `options`.

| Parameter | Type                                                              | Description                                 |
| --------- | ----------------------------------------------------------------- | ------------------------------------------- |
| `out`     | [`Hyperdrive\|Localdrive`](/reference/building-blocks/hyperdrive) | Destination drive to mirror into.           |
| `options` | `object`                                                          | Mirror options, forwarded to `MirrorDrive`. |

* Returns: [`MirrorDrive`](/reference/helpers/mirrordrive) — A `MirrorDrive` instance; await it or `mirror.done()` to finish.

```js
const mirror = drive.mirror(out)
await mirror.done()
```

drive.download(folder, [options]) [#drivedownloadfolder-options]

[src](https://github.com/holepunchto/hyperdrive/blob/v13.3.3/index.js#L477)

Downloads the blobs corresponding to all entries in the drive at paths prefixed with `folder`. Returns a `Download` object that resolves once all data has been downloaded:

| Parameter | Type     | Default | Description                                                          |
| --------- | -------- | ------- | -------------------------------------------------------------------- |
| `folder`  | `string` | `'/'`   | Path prefix to download. Defaults to the whole drive.                |
| `options` | `object` | —       | `options` are the same as those for `drive.list(folder, [options])`. |

* Returns: `Download` — A Download object; await `download.done()` to know when complete.

```js
const download = await drive.download(key)
await download.done()
```

```js
download.destroy()
```

await drive.downloadDiff(version, folder, [options]) [#await-drivedownloaddiffversion-folder-options]

[src](https://github.com/holepunchto/hyperdrive/blob/v13.3.3/index.js#L439)

Downloads all the blobs in `folder` corresponding to entries in `drive.checkout(version)` that are not in `drive.version`. Returns a `Download` object that resolves once all data has been downloaded:

| Parameter | Type     | Description                                                     |
| --------- | -------- | --------------------------------------------------------------- |
| `version` | `number` | Drive version to diff against the current `drive.version`.      |
| `folder`  | `string` | Path prefix to scope the download to. Omit for the whole drive. |
| `options` | `object` | Diff options, forwarded to `drive.diff()`.                      |

* Returns: `Download` — A Download object; await `download.done()` to know when complete.

```js
const download = await drive.downloadDiff(version, folder)
await download.done()
```

```js
download.destroy()
```

await drive.downloadRange(dbRanges, blobRanges) [#await-drivedownloadrangedbranges-blobranges]

[src](https://github.com/holepunchto/hyperdrive/blob/v13.3.3/index.js#L453)

Downloads the entries and blobs stored in the ranges `dbRanges` and `blobRanges`. Returns a `Download` object that resolves once all data has been downloaded:

| Parameter    | Type                                                                                                      | Description                                           |
| ------------ | --------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| `dbRanges`   | [`Array<object>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) | Block ranges to download from the db (metadata) core. |
| `blobRanges` | [`Array<object>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) | Block ranges to download from the blobs core.         |

* Returns: `Download` — A Download object; await `download.done()` to know when complete.

```js
const download = await drive.downloadRange(dbRanges, blobRanges)
await download.done()
```

```js
download.destroy()
```

drive.findingPeers() [#drivefindingpeers]

[src](https://github.com/holepunchto/hyperdrive/blob/v13.3.3/index.js#L111)

Indicate to Hyperdrive that you're finding peers in the background, requests will be on hold until this is done.

* Returns: `Function` — A `done` callback to call once peer discovery has finished.

```js
const done = drive.findingPeers()
swarm.flush().then(done, done)
```

drive.replicate(isInitiator, [opts]) [#drivereplicateisinitiator-opts]

[src](https://github.com/holepunchto/hyperdrive/blob/v13.3.3/index.js#L147)

Creates a replication stream for the drive. Pass `true`/`false` to create a new stream as initiator/responder, or pass an existing stream or socket to replicate over it. See [`corestore.replicate`](https://github.com/holepunchto/corestore#const-stream--storereplicateoptsorstream) for how replication works.

| Parameter     | Type                                                    | Description                                                                             |
| ------------- | ------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| `isInitiator` | [`boolean\|Stream`](https://nodejs.org/api/stream.html) | `true`/`false` to initiate replication, or an existing stream/socket to replicate over. |
| `opts`        | `object`                                                | Replication options, forwarded to `corestore.replicate()`.                              |

* Returns: [`Stream`](https://nodejs.org/api/stream.html) — A replication stream.

```js
const swarm = new Hyperswarm()
const done = drive.findingPeers()
swarm.on('connection', (socket) => drive.replicate(socket))
swarm.join(drive.discoveryKey)
swarm.flush().then(done, done)
```

await drive.update([options]) [#await-driveupdateoptions]

[src](https://github.com/holepunchto/hyperdrive/blob/v13.3.3/index.js#L151)

Waits for initial proof of the new drive version until all `findingPeers` are done.

| Parameter | Type                              |
| --------- | --------------------------------- |
| `options` | [`UpdateOptions`](#updateoptions) |

* Returns: [`Promise<boolean>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) — `true` if the drive advanced to a new version, otherwise `false`.

await drive.getBlobs() [#await-drivegetblobs]

[src](https://github.com/holepunchto/hyperdrive/blob/v13.3.3/index.js#L291)

Returns the [Hyperblobs](https://github.com/holepunchto/hyperblobs)
instance storing the blobs indexed by drive entries.

* Returns: [`Promise<Hyperblobs>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) — the [Hyperblobs](https://github.com/holepunchto/hyperblobs) instance storing the blobs indexed by drive entries.

```js
await drive.put('/file.txt', Buffer.from('hi'))

const buffer1 = await drive.get('/file.txt')

const blobs = await drive.getBlobs()
const entry = await drive.entry('/file.txt')
const buffer2 = await blobs.get(entry.value.blob)

// => buffer1 and buffer2 are equals
```

await drive.getBlobsLength(checkout) [#await-drivegetblobslengthcheckout]

[src](https://github.com/holepunchto/hyperdrive/blob/v13.3.3/index.js#L133)

Returns the length of the Hyperblobs instance at the time of the specified
Hyperdrive version (defaults to the current version).

| Parameter  | Type     | Description                                                |
| ---------- | -------- | ---------------------------------------------------------- |
| `checkout` | `number` | Drive version to measure. Defaults to the current version. |

* Returns: [`Promise<number>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) — the length of the Hyperblobs instance at the time of the specified Hyperdrive version (defaults to the current version).

```js
const blobsLength = await drive.getBlobsLength()
```

drive.monitor(name, [options]) [#drivemonitorname-options]

[src](https://github.com/holepunchto/hyperdrive/blob/v13.3.3/index.js#L304)

Create a `Monitor` that tracks upload and download progress for a single file. The returned monitor reports stats as the blocks of the file's blob move over the wire, and is tracked in `drive.monitors` until closed.

| Parameter | Type     | Default | Description                                            |
| --------- | -------- | ------- | ------------------------------------------------------ |
| `name`    | `string` | —       | Path of the file to monitor, for example `/video.mp4`. |
| `options` | `object` | `{}`    | Monitor options.                                       |

* Returns: `Monitor` — an event emitter reporting the file's transfer stats.

Types [#types]

DriveOptions [#driveoptions]

Options for creating a Hyperdrive.

| Property        | Type                                                        | Default | Description                                                          |
| --------------- | ----------------------------------------------------------- | ------- | -------------------------------------------------------------------- |
| `encryptionKey` | [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer) | —       | Encryption key used to encrypt and decrypt the underlying cores.     |
| `onwait`        | `Function`                                                  | —       | Hook called when a block has to be downloaded before it can be read. |
| `active`        | `boolean`                                                   | `true`  | Whether the drive's cores actively maintain peer connections.        |

TruncateOptions [#truncateoptions]

Options for `drive.truncate()`.

| Property | Type     | Default | Description                                                                        |
| -------- | -------- | ------- | ---------------------------------------------------------------------------------- |
| `blobs`  | `number` | —       | Corresponding blobs length, if known. Recommended to let the method figure it out. |

UpdateOptions [#updateoptions]

Options for `drive.update()`.

| Property | Type      | Default | Description                                                                                                             |
| -------- | --------- | ------- | ----------------------------------------------------------------------------------------------------------------------- |
| `wait`   | `boolean` | `false` | Whether to wait for peers before resolving. Use this or `drive.findingPeers()` to make `await drive.update()` blocking. |

GetOptions [#getoptions]

Options for `drive.get()`.

| Property  | Type      | Default | Description                                    |
| --------- | --------- | ------- | ---------------------------------------------- |
| `wait`    | `boolean` | `true`  | Wait for the block to be downloaded.           |
| `timeout` | `number`  | `0`     | Max milliseconds to wait (0 means no timeout). |

WriteOptions [#writeoptions]

Options for writing a file (`drive.put()` and `drive.createWriteStream()`).

| Property     | Type      | Default | Description                                                                   |
| ------------ | --------- | ------- | ----------------------------------------------------------------------------- |
| `executable` | `boolean` | `false` | Whether the blob at the path is an executable.                                |
| `metadata`   | `*`       | `null`  | Extended file information, that is an arbitrary JSON value.                   |
| `dedup`      | `boolean` | `false` | Reuse the existing blob if the content is unchanged (createWriteStream only). |

ClearOptions [#clearoptions]

Options for clearing blobs (`drive.clear()` and `drive.clearAll()`).

| Property | Type      | Default | Description                                                                                               |
| -------- | --------- | ------- | --------------------------------------------------------------------------------------------------------- |
| `diff`   | `boolean` | `false` | When enabled, returns a `{ blocks }` object reporting the blocks cleared; otherwise the result is `null`. |

SymlinkOptions [#symlinkoptions]

Options for `drive.symlink()`.

| Property   | Type | Default | Description                                                 |
| ---------- | ---- | ------- | ----------------------------------------------------------- |
| `metadata` | `*`  | `null`  | Extended file information, that is an arbitrary JSON value. |

EntryOptions [#entryoptions]

Options for `drive.entry()`.

| Property  | Type      | Default | Description                                           |
| --------- | --------- | ------- | ----------------------------------------------------- |
| `follow`  | `boolean` | `false` | Follow symlinks, up to 16 deep or it throws an error. |
| `wait`    | `boolean` | `true`  | Wait for the block to be downloaded.                  |
| `timeout` | `number`  | `0`     | Max milliseconds to wait (0 means no timeout).        |

Errors [#errors]

Coded errors this module can throw — catch them via `err.code`.

| Error                 | Thrown when                           |
| --------------------- | ------------------------------------- |
| `BAD_ARGUMENT`        | if the truncation length is invalid.  |
| `BLOCK_NOT_AVAILABLE` | if a required block is not available. |

See also [#see-also]

* [Create a full peer-to-peer filesystem with Hyperdrive](/how-to/stream-and-share-media/create-a-full-peer-to-peer-filesystem-with-hyperdrive)—end-to-end filesystem replication walkthrough.
* [Work with many Hypercores using Corestore](/how-to/store-and-replicate/work-with-many-hypercores-using-corestore)—recommended pattern when one app manages multiple drives or related cores.
* [Localdrive](/reference/helpers/localdrive)—map a Hyperdrive-like API onto the local filesystem.
* [Mirrordrive](/reference/helpers/mirrordrive)—sync between Hyperdrive and other drive-like destinations.
* [Corestore](/reference/helpers/corestore)—shared storage and replication manager for drive metadata and content.
* [Hyperbee](/reference/building-blocks/hyperbee)—Hyperdrive uses a Hyperbee internally for metadata indexing.
* [Drives](/reference/tools/drives)—CLI tool for creating, mirroring, and seeding Hyperdrives.


# Hyperswarm



<Status level="stable" />

Hyperswarm is the high-level networking layer for discovering peers by a shared 32-byte topic and opening encrypted connections between them. Prefer one swarm instance per app and join multiple topics on that same instance when possible.

Install [#install]

```sh
npm i hyperswarm
```

Quickstart [#quickstart]

```js
import Hyperswarm from 'hyperswarm'

const server = new Hyperswarm()
const client = new Hyperswarm()

server.on('connection', socket => {
  socket.end('hello from the server')
})

client.on('connection', socket => {
  socket.once('data', async buf => {
    console.log(buf.toString())
    await Promise.all([client.destroy(), server.destroy()])
  })
})

const topic = Buffer.alloc(32).fill('pear-docs-topic')
const discovery = server.join(topic, { server: true, client: false })
await discovery.flushed()

client.join(topic, { server: false, client: true })
await client.flush()
```

API Reference [#api-reference]

Constructor and state [#constructor-and-state]

new Hyperswarm(opts = {}) [#new-hyperswarmopts--]

[API definition on GitHub](https://github.com/holepunchto/hyperswarm/blob/v4.17.0/index.js#L23)

* Signature: `const swarm = new Hyperswarm(opts)`
* Parameters:
  * `opts.keyPair`: Noise key pair to use for DHT listen and connect operations. Defaults to a key pair derived from `opts.seed`, or a random one.
  * `opts.seed`: 32-byte seed used to derive a deterministic key pair.
  * `opts.maxPeers`: Maximum number of peer connections to keep open. Defaults to `64`.
  * `opts.maxClientConnections`: Maximum number of outbound (client) connections. Defaults to `Infinity`.
  * `opts.maxServerConnections`: Maximum number of inbound (server) connections. Defaults to `Infinity`.
  * `opts.maxParallel`: Maximum number of connection attempts running in parallel. Defaults to `3`.
  * `opts.firewall`: Synchronous function `(remotePublicKey, payload) => boolean` that rejects a peer when it returns `true`. Defaults to allowing all peers.
  * `opts.relayThrough`: Public key (or function returning one) of a node to relay connections through when direct hole-punching fails.
  * `opts.dht`: Existing `hyperdht` instance to reuse instead of creating one internally.
* Returns: A new `Hyperswarm` instance.
* Example:

```js
const swarm = new Hyperswarm({ maxPeers: 32 })
await swarm.listen()
```

swarm.connecting [#swarmconnecting]

[API definition on GitHub](https://github.com/holepunchto/hyperswarm/blob/v4.17.0/index.js#L64)

* Signature: `swarm.connecting`
* Returns: `number` count of outbound connections still opening.
* Example:

```js
if (swarm.connecting > 0) console.log('connecting...')
```

swarm.connections [#swarmconnections]

[API definition on GitHub](https://github.com/holepunchto/hyperswarm/blob/v4.17.0/index.js#L65)

* Signature: `swarm.connections`
* Returns: `Set` of active encrypted duplex connections.
* Example:

```js
for (const socket of swarm.connections) socket.write('ping')
```

swarm.peers [#swarmpeers]

[API definition on GitHub](https://github.com/holepunchto/hyperswarm/blob/v4.17.0/index.js#L66)

* Signature: `swarm.peers`
* Returns: `Map<string, PeerInfo>` keyed by the remote Noise public key as a hex string.
* Example:

```js
for (const [key, peer] of swarm.peers) {
  console.log(key, peer.prioritized)
}
```

swarm.dht [#swarmdht]

[API definition on GitHub](https://github.com/holepunchto/hyperswarm/blob/v4.17.0/index.js#L38)

* Signature: `swarm.dht`
* Returns: The underlying `hyperdht` instance used by the swarm.
* Example:

```js
console.log('bootstrap ready:', !!swarm.dht)
```

Topic membership [#topic-membership]

swarm.join(topic, opts = {}) [#swarmjointopic-opts--]

[API definition on GitHub](https://github.com/holepunchto/hyperswarm/blob/v4.17.0/index.js#L501)

* Signature: `const discovery = swarm.join(topic, opts)`
* Parameters:
  * `topic`: 32-byte `Buffer` that identifies the swarm topic.
  * `opts.server`: Announce on the DHT and accept inbound connections for this topic. Defaults to `true`.
  * `opts.client`: Query the DHT and connect to discovered servers for this topic. Defaults to `true`.
  * `opts.limit`: Maximum peers to connect to for this topic. Defaults to `Infinity`.
* Returns: A `PeerDiscovery` object for the topic.
* Example:

```js
const discovery = swarm.join(topic, { server: true, client: false })
await discovery.flushed()
```

Client mode discovers and dials servers for a topic. Server mode announces that topic and accepts inbound connections. Connections opened in client mode update `peerInfo.topics`; inbound server connections are not tied to a single topic.

await swarm.leave(topic) [#await-swarmleavetopic]

[API definition on GitHub](https://github.com/holepunchto/hyperswarm/blob/v4.17.0/index.js#L525)

* Signature: `await swarm.leave(topic)`
* Parameters:
  * `topic`: 32-byte `Buffer` previously joined with `swarm.join(...)`.
* Returns: A promise that resolves after discovery and announcement for that topic stop.
* Example:

```js
await swarm.leave(topic)
```

Leaving a topic stops new discovery work but does not close already-open connections.

swarm.status(topic) [#swarmstatustopic]

[API definition on GitHub](https://github.com/holepunchto/hyperswarm/blob/v4.17.0/index.js#L487)

* Signature: `const discovery = swarm.status(topic)`
* Parameters:
  * `topic`: 32-byte `Buffer` for a joined topic.
* Returns: The current `PeerDiscovery` for that topic, or `null` if the topic is not active.
* Example:

```js
const discovery = swarm.status(topic)
if (discovery) await discovery.refresh()
```

`status(topic)` returns the underlying `PeerDiscovery`, whose `refresh()` takes no arguments and reannounces or re-looks up with the topic's existing client/server configuration. The object returned by `swarm.join(...)` is a session over that discovery and accepts `{ client, server }` on `refresh(...)`.

await swarm.flush() [#await-swarmflush]

[API definition on GitHub](https://github.com/holepunchto/hyperswarm/blob/v4.17.0/index.js#L567)

* Signature: `await swarm.flush()`
* Returns: A promise that resolves after pending DHT announces complete and queued peer connections have been processed.
* Example:

```js
swarm.join(topic, { client: true, server: false })
await swarm.flush()
```

`flush()` is global to the swarm rather than scoped to one topic, so it can be comparatively expensive.

Direct peers and events [#direct-peers-and-events]

swarm.joinPeer(noisePublicKey) [#swarmjoinpeernoisepublickey]

[API definition on GitHub](https://github.com/holepunchto/hyperswarm/blob/v4.17.0/index.js#L543)

* Signature: `swarm.joinPeer(noisePublicKey)`
* Parameters:
  * `noisePublicKey`: 32-byte `Buffer` containing the remote peer's Noise public key.
* Returns: Nothing. Hyperswarm starts and maintains a direct connection attempt to that peer.
* Example:

```js
swarm.joinPeer(remotePublicKey)
```

swarm.leavePeer(noisePublicKey) [#swarmleavepeernoisepublickey]

[API definition on GitHub](https://github.com/holepunchto/hyperswarm/blob/v4.17.0/index.js#L556)

* Signature: `swarm.leavePeer(noisePublicKey)`
* Parameters:
  * `noisePublicKey`: 32-byte `Buffer` for a peer previously targeted with `joinPeer(...)`.
* Returns: Nothing. Future reconnect attempts stop.
* Example:

```js
swarm.leavePeer(remotePublicKey)
```

If the peer is already connected, `leavePeer(...)` does not close that existing socket.

swarm.on('connection', (socket, peerInfo) => {}) [#swarmonconnection-socket-peerinfo--]

[API definition on GitHub](https://github.com/holepunchto/hyperswarm/blob/v4.17.0/index.js#L244)

* Signature: `swarm.on('connection', (socket, peerInfo) => {})`
* Parameters:
  * `socket`: End-to-end encrypted duplex stream for the peer connection.
  * `peerInfo`: `PeerInfo` object describing the connected peer.
* Returns: The swarm emits this event whenever a new peer connection opens.
* Example:

```js
swarm.on('connection', (socket, peerInfo) => {
  console.log(peerInfo.publicKey)
  socket.write('hello')
})
```

swarm.on('update', () => {}) [#swarmonupdate---]

[API definition on GitHub](https://github.com/holepunchto/hyperswarm/blob/v4.17.0/index.js#L104)

* Signature: `swarm.on('update', () => {})`
* Returns: The swarm emits this event whenever internal counters or connection state change.
* Example:

```js
swarm.on('update', () => {
  console.log(swarm.connecting, swarm.connections.size)
})
```

swarm.on('ban', (peerInfo, err) => {}) [#swarmonban-peerinfo-err--]

[API definition on GitHub](https://github.com/holepunchto/hyperswarm/blob/v4.17.0/index.js#L484)

* Signature: `swarm.on('ban', (peerInfo, err) => {})`
* Parameters:
  * `peerInfo`: Banned peer metadata.
  * `err`: Error describing why the peer was banned, such as a firewall rejection.
* Returns: The swarm emits this event after a peer becomes banned.
* Example:

```js
swarm.on('ban', (peerInfo, err) => {
  console.log('banned', peerInfo.publicKey, err?.message)
})
```

Listening and lifecycle [#listening-and-lifecycle]

await swarm.listen() [#await-swarmlisten]

[API definition on GitHub](https://github.com/holepunchto/hyperswarm/blob/v4.17.0/index.js#L491)

* Signature: `await swarm.listen()`
* Returns: A promise that resolves once the swarm is listening for inbound connections.
* Example:

```js
await swarm.listen()
```

`listen()` is usually called for you after the first `join(...)`, but it is available when you want listening to start earlier.

await swarm.suspend({ log } = {}) [#await-swarmsuspend-log---]

[API definition on GitHub](https://github.com/holepunchto/hyperswarm/blob/v4.17.0/index.js#L606)

* Signature: `await swarm.suspend({ log })`
* Parameters:
  * `log`: Optional logging function used while the swarm suspends networking. Defaults to a no-op.
* Returns: A promise that resolves after peer connections, server listening, and discovery are suspended.
* Example:

```js
await swarm.suspend({ log: console.log })
```

await swarm.resume({ log } = {}) [#await-swarmresume-log---]

[API definition on GitHub](https://github.com/holepunchto/hyperswarm/blob/v4.17.0/index.js#L642)

* Signature: `await swarm.resume({ log })`
* Parameters:
  * `log`: Optional logging function used while the swarm resumes networking. Defaults to a no-op.
* Returns: A promise that resolves after the DHT, listening server, and discovery resume.
* Example:

```js
await swarm.resume({ log: console.log })
```

await swarm.destroy({ force } = {}) [#await-swarmdestroy-force---]

[API definition on GitHub](https://github.com/holepunchto/hyperswarm/blob/v4.17.0/index.js#L588)

* Signature: `await swarm.destroy({ force })`
* Parameters:
  * `force`: Optional boolean that skips graceful topic cleanup when `true`.
* Returns: A promise that resolves after the swarm closes its server, discovery work, and underlying DHT instance.
* Example:

```js
await swarm.destroy()
```

PeerDiscovery [#peerdiscovery]

await discovery.flushed() [#await-discoveryflushed]

[API definition on GitHub](https://github.com/holepunchto/hyperswarm/blob/v4.17.0/lib/peer-discovery.js#L191)

* Signature: `await discovery.flushed()`
* Returns: A promise that resolves once a server-mode topic has been fully announced on the DHT.
* Example:

```js
const discovery = swarm.join(topic, { server: true, client: false })
await discovery.flushed()
```

await discovery.refresh({ client, server }) [#await-discoveryrefresh-client-server-]

[API definition on GitHub](https://github.com/holepunchto/hyperswarm/blob/v4.17.0/lib/peer-discovery.js#L310)

* Signature: `await discovery.refresh({ client, server, limit })`
* Parameters:
  * `client`: Optional boolean to enable or disable client lookups. Defaults to the session's current value.
  * `server`: Optional boolean to enable or disable server announcements. Defaults to the session's current value.
  * `limit`: Optional maximum number of peers to connect to for this topic. Defaults to `Infinity`.
* Returns: A promise that resolves after the topic configuration is refreshed. Throws if both `client` and `server` are `false`.
* Example:

```js
await discovery.refresh({ client: true, server: true })
```

Refreshing a server-mode discovery also triggers a new DHT announcement for that topic.

await discovery.destroy() [#await-discoverydestroy]

[API definition on GitHub](https://github.com/holepunchto/hyperswarm/blob/v4.17.0/lib/peer-discovery.js#L333)

* Signature: `await discovery.destroy()`
* Returns: A promise that resolves after discovery and announcements for that topic stop.
* Example:

```js
await discovery.destroy()
```

PeerInfo [#peerinfo]

peerInfo.publicKey [#peerinfopublickey]

[API definition on GitHub](https://github.com/holepunchto/hyperswarm/blob/v4.17.0/lib/peer-info.js#L17)

* Signature: `peerInfo.publicKey`
* Returns: The peer's Noise public key as a `Buffer`.
* Example:

```js
console.log(peerInfo.publicKey)
```

peerInfo.topics [#peerinfotopics]

[API definition on GitHub](https://github.com/holepunchto/hyperswarm/blob/v4.17.0/lib/peer-info.js#L33)

* Signature: `peerInfo.topics`
* Returns: Array of joined topics associated with the peer when the local swarm connected in client mode.
* Example:

```js
for (const topic of peerInfo.topics) console.log(topic)
```

peerInfo.prioritized [#peerinfoprioritized]

[API definition on GitHub](https://github.com/holepunchto/hyperswarm/blob/v4.17.0/lib/peer-info.js#L52)

* Signature: `peerInfo.prioritized`
* Returns: `true` when the peer's connection priority is at or above normal, meaning the swarm still considers it a candidate for connection.
* Example:

```js
if (peerInfo.prioritized) console.log('high-priority peer')
```

peerInfo.ban(banStatus = false) [#peerinfobanbanstatus--false]

[API definition on GitHub](https://github.com/holepunchto/hyperswarm/blob/v4.17.0/lib/peer-info.js#L109)

* Signature: `peerInfo.ban(banStatus = false)`
* Parameters:
  * `banStatus`: `true` to ban the peer or `false` to unban it.
* Returns: Nothing. Updates whether the swarm should avoid future reconnect attempts.
* Example:

```js
peerInfo.ban(true)
```

Banning prevents future reconnection attempts, but it does not close an already-open connection.

See also [#see-also]

* [Connect to many peers by topic with Hyperswarm](/how-to/connect-to-peers/connect-to-many-peers-by-topic-with-hyperswarm)—broader topic-based discovery walkthrough.
* [Connect two peers by key with HyperDHT](/how-to/connect-to-peers/connect-two-peers-by-key-with-hyperdht)—direct one-to-one connections without topic discovery.
* [HyperDHT](/reference/building-blocks/hyperdht)—lower-level DHT and hole-punching layer beneath Hyperswarm.
* [Secretstream](/reference/helpers/secretstream)—the encrypted stream type that Hyperswarm connections expose.
* [Protomux](/reference/helpers/protomux)—multiplex multiple protocols across one Hyperswarm connection.
* [Corestore](/reference/helpers/corestore)—pass swarm connections directly to `store.replicate()` to co-replicate all managed cores.


# Desktop release npm scripts



Pear Electron repositories wrap [`electron-forge`](https://www.electronforge.io/) behind `package.json` scripts so day-to-day work stays predictable. This page lists the script names used by [`hello-pear-electron`](https://github.com/holepunchto/hello-pear-electron#scripts)—the template every snippet in [Ship your app](/getting-started/build-a-peer-to-peer-chat/ship) and [Deploy over-the-air updates](/getting-started/build-a-peer-to-peer-chat/update) is built from. Your project may rename them; read `package.json` locally.

npm start [#npm-start]

Starts the app in development mode with OTA disabled, so a seeded `pear://` link does not replace your working tree while you hack:

```sh
# package.json
"start": "electron-forge start -- --no-updates"
```

To exercise the OTA path locally, drop the flag with an explicit `--updates`:

```sh
npm start -- --updates
```

npm run lint / npm run format [#npm-run-lint--npm-run-format]

Run [Prettier](https://prettier.io/) and the project's linter ([`lunte`](https://www.npmjs.com/package/lunte) in the template):

```sh
# package.json
"lint": "prettier --check . && lunte",
"format": "prettier --write . && lunte --fix"
```

Exact tools vary—inspect `scripts` in your repo.

npm run package [#npm-run-package]

Runs `electron-forge package` to produce a packaged app **without** the per-OS distributables (no `.app`/`.msix`/`.AppImage`). Useful for a quick smoke test:

```sh
# package.json
"package": "electron-forge package"
```

npm run make [#npm-run-make]

Runs `electron-forge make` and produces platform-native installers for the **current host OS**, as defined in [`forge.config.js`](https://github.com/holepunchto/hello-pear-electron/blob/main/forge.config.js):

```sh
# package.json
"make": "electron-forge make"
```

| Host OS | Typical outputs (template makers)                                                                                                                    |
| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| macOS   | `.app` (packager) + `.dmg` (`@electron-forge/maker-dmg`)                                                                                             |
| Windows | `.msix` (`@electron-forge/maker-msix`) under `out/<AppName>-win32-<arch>/`                                                                           |
| Linux   | `.AppImage` (`pear-electron-forge-maker-appimage`), `.flatpak` (`pear-electron-forge-maker-flatpak`), and `.snap` (`pear-electron-forge-maker-snap`) |

Run `npm run make` on each OS (or CI worker) you need before [`pear build`](/how-to/operate-an-app/build-and-package/build-desktop-distributables#build-the-deployment-directory). There are no separate `make:darwin` / `make:linux` / `make:win32` scripts in the current template.

Unsigned local builds are fine on the machine that made them; production paths need vendor signing—see [Build desktop distributables](/how-to/operate-an-app/build-and-package/build-desktop-distributables) for `MAC_CODESIGN_IDENTITY`, `KEYCHAIN_PROFILE`, and `WINDOWS_SIGN_HOOK`.

Where to go next [#where-to-go-next]

* [Build desktop distributables](/how-to/operate-an-app/build-and-package/build-desktop-distributables)—signing, notarization, MSIX publisher, and the `pear build` deployment directory layout.
* [Deploy your application](/how-to/operate-an-app/manual-deployment/deployment)—stage, provision, and multisig once the deployment directory exists.
* [Getting started—part 3 (ship)](/getting-started/build-a-peer-to-peer-chat/ship) and [part 4 (update)](/getting-started/build-a-peer-to-peer-chat/update)—type-along walkthrough of the whole flow.
* [Release pipeline](/explanation/deployment-releasing-apps-p2p)—how the scripts above feed into trust boundaries and release lines.


# Holepunch GitHub Actions



[`holepunchto/actions`](https://github.com/holepunchto/actions) is a collection of reusable composite GitHub Actions for building, signing, publishing, and recovering Pear applications and Holepunch modules. Reference one with:

```yaml
- uses: holepunchto/actions/<name>@v1
```

<Callout type="info">
  There is no project-scaffolding action. To bootstrap a new Pear project, clone the [`hello-pear-electron`](https://github.com/holepunchto/hello-pear-electron) template. The actions below automate CI/CD once a project exists.
</Callout>

Pear app CI/CD [#pear-app-cicd]

| Action                                                                                                      | Purpose                                                                                                                                                                                                                                                                                              | Key inputs / outputs                                                                                                                                                                                                                                                                                                                                                                                                                |
| ----------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a name="make-pear-app" />[`make-pear-app`](https://github.com/holepunchto/actions/tree/main/make-pear-app) | Run `npm run make` for the host OS with code signing and notarization, then upload distributables as artifacts. Handles its own `setup-node` + `npm ci`; precede it with `actions/checkout@v4`. See [Build and sign desktop apps in CI](/how-to/operate-an-app/github-actions/build-and-sign-in-ci). | In: `channel` (required), `upgrade_key`, macOS signing/notarization (`macos_certificate_base64`, `macos_p12_password`, `macos_codesign_identity`, `macos_notarization_method` = `appstore_connect` \| `apple_id_password`, plus the matching API-key or Apple-ID fields), Windows signing (`windows_signing_method` = `windows_cert_sha1` \| `windows_cert_pfx`, plus cert fields), `linux_set_up_snapcraft`. Out: `artifact-links` |
| [`pear-ci`](https://github.com/holepunchto/actions/tree/main/pear-ci)                                       | Stage a directory into a [Hyperdrive](/reference/building-blocks/hyperdrive) on every run, producing a stable `pear://` link. Documented in full at [pear-ci GitHub Action](/reference/ci-and-release/pear-ci-action).                                                                               | `primary-key`, `namespace`, `target`, `dry-run`; out: `pr-url`                                                                                                                                                                                                                                                                                                                                                                      |
| [`pear-provision-recover`](https://github.com/holepunchto/actions/tree/main/pear-provision-recover)         | Recover a provision drive from the network into a new writable drive (runs the `pear-provision-recover` CLI). Used to rebuild write access—see [Recovering from lost write access](/how-to/operate-an-app/manual-deployment/troubleshoot-desktop-releases#recovering-from-lost-write-access).        | `path`, `key`, `length`, `blobs-length`, `primary-key`, `name` (all required)                                                                                                                                                                                                                                                                                                                                                       |

Release [#release]

| Action                                                                              | Purpose                                                                                                                 | Key inputs                                                                          |
| ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| [`publish`](https://github.com/holepunchto/actions/tree/main/publish)               | `npm publish` (honoring dist-tag and workspaces) then create a GitHub release via `create-release`.                     | `tag` (default `latest`), `workspaces`, `include-workspace-root`, `node-auth-token` |
| [`create-release`](https://github.com/holepunchto/actions/tree/main/create-release) | `npm pack` the packages and attach the tarballs to a `gh release create` for the current ref.                           | `workspaces`, `include-workspace-root`                                              |
| [`trigger-canary`](https://github.com/holepunchto/actions/tree/main/trigger-canary) | Dispatch a `release` event to the `holepunchto/canary-tests` repo so downstream canary tests run against a new release. | `repository`, `ref`, `token` (all required)                                         |

Bare native-addon prebuilds [#bare-native-addon-prebuilds]

For authors of native [Bare](/reference/modules/bare-modules) addons who build prebuilt binaries across platforms in CI. The typical shape is a build matrix where each job runs `compile-prebuilds`, then a final job merges the per-platform artifacts.

| Action                                                                                      | Purpose                                                                                                                        | Key inputs                                                                                          |
| ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------- |
| [`compile-prebuilds`](https://github.com/holepunchto/actions/tree/main/compile-prebuilds)   | Install `bare-make`, then `generate` / `build` / `install` a native prebuild for one platform + arch, optionally uploading it. | `platform` (required), `arch` (required), `flags`, `tags`, `prefix` (default `prebuilds`), `upload` |
| [`upload-prebuilds`](https://github.com/holepunchto/actions/tree/main/upload-prebuilds)     | Upload a compiled prebuild as an artifact named `<platform>-<arch><tags>`.                                                     | `platform` (required), `arch` (required), `tags`, `prefix`                                          |
| [`download-prebuilds`](https://github.com/holepunchto/actions/tree/main/download-prebuilds) | Download all prebuild artifacts into one directory (`merge-multiple`).                                                         | `prefix` (default `prebuilds`)                                                                      |
| [`merge-prebuilds`](https://github.com/holepunchto/actions/tree/main/merge-prebuilds)       | Download every per-platform prebuild artifact and re-upload them as a single `prebuilds` artifact.                             | —                                                                                                   |

Project and toolchain setup [#project-and-toolchain-setup]

These are the building blocks the prebuild and release actions compose; you can also use them directly.

| Action                                                                                                                                                                                                                                                                                                               | Purpose                                                                                                                                                                |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`checkout`](https://github.com/holepunchto/actions/tree/main/checkout)                                                                                                                                                                                                                                              | `actions/checkout` with `persist-credentials: false`.                                                                                                                  |
| [`setup-node`](https://github.com/holepunchto/actions/tree/main/setup-node)                                                                                                                                                                                                                                          | Install Node.js LTS and configure the npm registry/scope for auth.                                                                                                     |
| [`node-base`](https://github.com/holepunchto/actions/tree/main/node-base)                                                                                                                                                                                                                                            | `checkout` + `setup-node` + `npm install` (with `allow-git`, `force-install`, registry/scope/auth options).                                                            |
| [`setup-bare`](https://github.com/holepunchto/actions/tree/main/setup-bare)                                                                                                                                                                                                                                          | Install the `bare-runtime` globally.                                                                                                                                   |
| [`bare-base`](https://github.com/holepunchto/actions/tree/main/bare-base)                                                                                                                                                                                                                                            | `node-base` + `setup-bare`: configure a Bare project on a runner.                                                                                                      |
| [`setup-llvm`](https://github.com/holepunchto/actions/tree/main/setup-llvm), [`setup-nasm`](https://github.com/holepunchto/actions/tree/main/setup-nasm), [`setup-swift`](https://github.com/holepunchto/actions/tree/main/setup-swift), [`swift-base`](https://github.com/holepunchto/actions/tree/main/swift-base) | Install the compilers and toolchains (LLVM, NASM, Swift) used when compiling native prebuilds and platform-specific code.                                              |
| [`setup-socket`](https://github.com/holepunchto/actions/tree/main/setup-socket), [`setup-mininet`](https://github.com/holepunchto/actions/tree/main/setup-mininet)                                                                                                                                                   | Install supporting tooling: `setup-socket` configures Socket.dev supply-chain scanning; `setup-mininet` installs Mininet and Open vSwitch for network-emulation tests. |

See also [#see-also]

* [Build and sign desktop apps in CI](/how-to/operate-an-app/github-actions/build-and-sign-in-ci)—the `make-pear-app` walkthrough.
* [Publish with GitHub Actions](/how-to/operate-an-app/github-actions/publish-with-github-actions) and [pear-ci GitHub Action](/reference/ci-and-release/pear-ci-action)—staging with `pear-ci`.
* [Build desktop distributables](/how-to/operate-an-app/build-and-package/build-desktop-distributables)—the manual signing flow `make-pear-app` automates.
* [Bare modules](/reference/modules/bare-modules)—the runtime the prebuild pipeline targets.


# pear-ci GitHub Action



The [`pear-ci` GitHub Action](https://github.com/holepunchto/actions/blob/main/pear-ci/action.yml) stages a directory from your repository into a [Hyperdrive](/reference/building-blocks/hyperdrive) on every run, producing a stable `pear://` link your app can use as its [`upgrade`](/reference/pear/configuration) field. For the task-oriented setup, see [Publish with GitHub Actions](/how-to/operate-an-app/github-actions/publish-with-github-actions).

It is a composite action that installs the [`pear-ci`](https://www.npmjs.com/package/pear-ci) npm tool, fetches the committed snapshot from `main`, stages, and commits the updated snapshot back.

Usage [#usage]

```yaml
- uses: holepunchto/actions/pear-ci@main
  with:
    primary-key: ${{ secrets.PEAR_PRIMARY_KEY }}
    namespace: my-app
    target: dist
    dry-run: false
```

Inputs [#inputs]

| Input          | Required | Default               | Description                                                                                                                                                         |
| -------------- | -------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `primary-key`  | Yes      | —                     | 32-byte (64 hex character) key for the [Corestore](/reference/helpers/corestore) identity. Determines the drive's `pear://` link across runs. Store it as a secret. |
| `namespace`    | Yes      | —                     | Drive namespace name. Combined with `primary-key` to derive the drive. Only letters, numbers, dots, hyphens, and underscores.                                       |
| `target`       | Yes      | —                     | Repo-relative path of the directory to stage. Must not be absolute or contain `..`.                                                                                 |
| `dry-run`      | No       | `false`               | When `true`, computes and logs the diff without writing to the drive or committing the snapshot. Must be `true` or `false`.                                         |
| `github-token` | No       | `${{ github.token }}` | Token used to fetch and commit `ci/snapshot.json`.                                                                                                                  |
| `app-slug`     | No       | —                     | When set, the snapshot commit is attributed to the matching GitHub App bot identity instead of `github-actions[bot]`.                                               |

Outputs [#outputs]

| Output   | Description                                                                               |
| -------- | ----------------------------------------------------------------------------------------- |
| `pr-url` | URL of the PR created if a direct push of the snapshot to `main` failed; empty otherwise. |

Input validation [#input-validation]

The action rejects malformed inputs before staging:

* `primary-key` must match `^[a-fA-F0-9]{64}$`.
* `namespace` must match `^[a-zA-Z0-9._-]+$`.
* `target` must contain only `[a-zA-Z0-9_./-]`, must not be an absolute path, and must not contain `..` (no directory traversal).
* `dry-run` must be exactly `true` or `false`.

Snapshot commits [#snapshot-commits]

The action reads `ci/snapshot.json` from `main` before staging and writes it back afterward. The snapshot records each core's length so subsequent runs sync only what changed. When `dry-run` is `true`, no commit is made. If pushing the snapshot directly to `main` fails, the action pushes a `pear-ci/snapshot-<run-id>` branch and opens a PR, exposing its URL via the `pr-url` output.

Grant the workflow `contents: write` (and `pull-requests: write` if you want the PR fallback) so the snapshot commit can land.

Underlying CLI [#underlying-cli]

Outside of Actions, the same staging runs through the [`pear-ci`](https://www.npmjs.com/package/pear-ci) CLI:

```bash
npm install -g pear-ci
pear-ci \
  --primary-key <64-hex-key> \
  --name my-app \
  --target ./dist \
  --snapshot ci/snapshot.json \
  --storage /tmp/store
```

| Flag            | Description                                                        |
| --------------- | ------------------------------------------------------------------ |
| `--primary-key` | 32-byte hex key for the [Corestore](/reference/helpers/corestore). |
| `--name`        | Namespace name used to derive the drive.                           |
| `--target`      | Local directory to mirror into the drive.                          |
| `--snapshot`    | Path to read/write the JSON snapshot.                              |
| `--storage`     | Corestore storage path.                                            |
| `--dry-run`     | Compute the diff without writing to the drive.                     |

The CLI logs the drive key it stages to (`starting stage for key <drive-key>`)—that key is your `pear://` link. See the [`pear-ci` README](https://github.com/holepunchto/pear-ci#readme) for the programmatic API and snapshot format.

See also [#see-also]

* [Publish with GitHub Actions](/how-to/operate-an-app/github-actions/publish-with-github-actions)—step-by-step setup.
* [Holepunch GitHub Actions](/reference/ci-and-release/github-actions)—the full catalog of shared actions this is part of.
* [Configuration](/reference/pear/configuration)—the `upgrade` field this link feeds.
* [Hyperdrive](/reference/building-blocks/hyperdrive) and [Hyperswarm](/reference/building-blocks/hyperswarm)—the building blocks `pear-ci` stages and replicates over.
* [Deploy your application](/how-to/operate-an-app/manual-deployment/deployment)—the manual staging flow.


# compact-encoding



<Status level="stable" />

`compact-encoding` packages small binary codecs behind a shared encoder interface. It is commonly paired with [Protomux](/reference/helpers/protomux) message schemas and shows up in [Hypercore](/reference/building-blocks/hypercore) and other Holepunch protocol surfaces whenever structured binary payloads matter. For the upstream package and implementation details, see the [compact-encoding repository](https://github.com/holepunchto/compact-encoding).

Module-level encode and decode helpers [#module-level-encode-and-decode-helpers]

const buffer = cenc.encode(enc, value) [#const-buffer--cencencodeenc-value]

Encodes a single `value` using `enc` into a freshly allocated `Buffer` and returns it. Equivalent to manually creating a state, calling `enc.preencode` and `enc.encode`, and slicing the buffer — useful when you just want bytes back in one step.

| Param   | Type     | Description                                                               |
| ------- | -------- | ------------------------------------------------------------------------- |
| `enc`   | `object` | Any compact-encoding encoder (for example `cenc.uint`, a custom encoder). |
| `value` | `*`      | The value to encode.                                                      |

* Returns: `Buffer`

```js
const buf = cenc.encode(cenc.uint, 42)
// <Buffer 2a>
```

const value = cenc.decode(enc, buffer) [#const-value--cencdecodeenc-buffer]

Decodes a single value from `buffer` using `enc`. Equivalent to constructing a state from the buffer and calling `enc.decode`.

| Param    | Type     | Description                   |
| -------- | -------- | ----------------------------- |
| `enc`    | `object` | Any compact-encoding encoder. |
| `buffer` | `Buffer` | The buffer to decode from.    |

* Returns: The decoded value.

```js
const val = cenc.decode(cenc.uint, buf) // 42
```

Install [#install]

```sh
npm i compact-encoding
```

Quickstart [#quickstart]

```js
import cenc from 'compact-encoding'

const state = cenc.state()

cenc.uint.preencode(state, 42)
cenc.string.preencode(state, 'hello')

state.buffer = Buffer.allocUnsafe(state.end)
state.start = 0

cenc.uint.encode(state, 42)
cenc.string.encode(state, 'hello')

state.start = 0

console.log(cenc.uint.decode(state))
console.log(cenc.string.decode(state))
```

API Reference [#api-reference]

Encoder contract [#encoder-contract]

Every bundled encoder follows the same three-method contract. The top-level helpers and exported factories below all return or consume objects with this shape.

enc.preencode(state, val) [#encpreencodestate-val]

Does a fast preencode dry-run that only sets state.end. Use this to figure out how big of a buffer you need.

enc.encode(state, val) [#encencodestate-val]

Writes the encoded form of the value into `state.buffer` at `state.start` (the buffer must have been preallocated via `preencode`), advancing `state.start` past the written bytes.

| Parameter | Type     | Description                                                 |
| --------- | -------- | ----------------------------------------------------------- |
| `state`   | `object` | A compact-encoding state with `start`, `end`, and `buffer`. |
| `val`     | `*`      | The value to encode.                                        |

* Returns: `undefined` — the encoded bytes are written into `state.buffer` in place.

```js
const cenc = require('compact-encoding')
const state = cenc.state()
cenc.uint.preencode(state, 42)
state.buffer = Buffer.allocUnsafe(state.end)
cenc.uint.encode(state, 42)
// state.buffer is a 1-byte Buffer containing the encoded uint
```

val = enc.decode(state) [#val--encdecodestate]

Reads and returns a value from `state.buffer` at `state.start`, advancing `state.start` past the decoded value.

| Parameter | Type     | Description                                                 |
| --------- | -------- | ----------------------------------------------------------- |
| `state`   | `object` | A compact-encoding state with `start`, `end`, and `buffer`. |

* Returns: `*` — The decoded value.

```js
const cenc = require('compact-encoding')
const buf = cenc.encode(cenc.bool, true)
const state = cenc.state(0, buf.byteLength, buf)
const val = cenc.bool.decode(state) // true
```

State and convenience helpers [#state-and-convenience-helpers]

cenc.state(start = 0, end = 0, buffer = null) [#cencstatestart--0-end--0-buffer--null]

[src](https://github.com/holepunchto/compact-encoding/blob/v3.3.0/index.js#L5)

A mutable state object `{ start, end, buffer }` used by all encoders.

| Parameter | Type                                                                          | Default | Description                                                              |
| --------- | ----------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------ |
| `start`   | `number`                                                                      | `0`     | Initial read/write offset.                                               |
| `end`     | `number`                                                                      | `0`     | Initial end offset (set by preencode to determine required buffer size). |
| `buffer`  | [`Buffer\|Uint8Array\|null`](https://nodejs.org/api/buffer.html#class-buffer) | `null`  | Underlying buffer; allocate after preencoding.                           |

* Returns: [`State`](#state) — A new state object `{ start, end, buffer }`.

```js
const cenc = require('compact-encoding')
const state = cenc.state()
cenc.uint.preencode(state, 42)
cenc.string.preencode(state, 'hi')
state.buffer = Buffer.allocUnsafe(state.end)
cenc.uint.encode(state, 42)
cenc.string.encode(state, 'hi')
```

cenc.from(enc) [#cencfromenc]

[src](https://github.com/holepunchto/compact-encoding/blob/v3.3.0/index.js#L966)

Coerces `enc` — an existing compact encoder, a named raw string encoding such as `'utf8'` or `'json'`, a codec with `encode`/`decode`, or an abstract encoding with `encodingLength` — into a compact-encoding-compatible encoder object.

| Parameter | Type             | Description                                                     |
| --------- | ---------------- | --------------------------------------------------------------- |
| `enc`     | `string\|object` | An encoding name, compact encoder, abstract-encoding, or codec. |

* Returns: `object` — A compact-encoding encoder with `preencode`, `encode`, and `decode`.

```js
const cenc = require('compact-encoding')
const enc = cenc.from('utf-8')
const buf = cenc.encode(enc, 'hello')
const val = cenc.decode(enc, buf) // 'hello'
```

Encoder factories [#encoder-factories]

cenc.fixed(n) [#cencfixedn]

[src](https://github.com/holepunchto/compact-encoding/blob/v3.3.0/index.js#L526)

An encoder for fixed-size buffers, where `n` is the exact byte length every encoded value must have.

| Parameter | Type     | Description                             |
| --------- | -------- | --------------------------------------- |
| `n`       | `number` | Exact number of bytes to encode/decode. |

* Returns: `object` — An encoder that reads and writes exactly `n` bytes.

```js
const cenc = require('compact-encoding')
const enc = cenc.fixed(4)
const buf = cenc.encode(enc, Buffer.alloc(4, 0xff))
const val = cenc.decode(enc, buf) // <Buffer ff ff ff ff>
```

cenc.array(enc) [#cencarrayenc]

[src](https://github.com/holepunchto/compact-encoding/blob/v3.3.0/index.js#L546)

An encoder that prefixes arrays with their length and encodes each item in order using `enc`.

| Parameter | Type     | Description                                                  |
| --------- | -------- | ------------------------------------------------------------ |
| `enc`     | `object` | An encoder with `preencode`, `encode`, and `decode` methods. |

* Returns: `object` — An encoder for arrays of values handled by `enc`.

```js
const cenc = require('compact-encoding')
const enc = cenc.array(cenc.uint)
const buf = cenc.encode(enc, [1, 2, 3])
const val = cenc.decode(enc, buf) // [1, 2, 3]
```

cenc.frame(enc) [#cencframeenc]

[src](https://github.com/holepunchto/compact-encoding/blob/v3.3.0/index.js#L566)

An encoder that prefixes one encoded payload with its byte length.

| Parameter | Type     | Description                                                  |
| --------- | -------- | ------------------------------------------------------------ |
| `enc`     | `object` | An encoder with `preencode`, `encode`, and `decode` methods. |

* Returns: `object` — An encoder that wraps each value in a byte-length frame.

```js
const cenc = require('compact-encoding')
const enc = cenc.frame(cenc.string)
const buf = cenc.encode(enc, 'hello')
const val = cenc.decode(enc, buf) // 'hello'
```

cenc.record(keyEncoding, valueEncoding) [#cencrecordkeyencoding-valueencoding]

[src](https://github.com/holepunchto/compact-encoding/blob/v3.3.0/index.js#L919)

An encoder for plain object records, with `keyEncoding` for object keys and `valueEncoding` for object values.

| Parameter       | Type     | Description                         |
| --------------- | -------- | ----------------------------------- |
| `keyEncoding`   | `object` | Encoder used for each object key.   |
| `valueEncoding` | `object` | Encoder used for each object value. |

* Returns: `object` — An encoder that reads/writes plain objects as key-value pairs.

```js
const cenc = require('compact-encoding')
const enc = cenc.record(cenc.string, cenc.uint)
const buf = cenc.encode(enc, { a: 1, b: 2 })
const val = cenc.decode(enc, buf) // [Object: null prototype] { a: 1, b: 2 }
```

cenc.stringRecord [#cencstringrecord]

[src](https://github.com/holepunchto/compact-encoding/blob/v3.3.0/index.js#L948)

A prebuilt `record(cenc.string, cenc.string)` encoder for simple string maps.

* Returns: `object`

```js
const cenc = require('compact-encoding')
const buf = cenc.encode(cenc.stringRecord, { name: 'alice', role: 'admin' })
const val = cenc.decode(cenc.stringRecord, buf) // [Object: null prototype] { name: 'alice', role: 'admin' }
```

Numeric encodings [#numeric-encodings]

cenc.uint64 [#cencuint64]

[src](https://github.com/holepunchto/compact-encoding/blob/v3.3.0/index.js#L180)

Unsigned integer encoders (`cenc.uint`, `cenc.uint8`, `cenc.uint16`, `cenc.uint24`, `cenc.uint32`, `cenc.uint40`, `cenc.uint48`, `cenc.uint56`, `cenc.uint64`). `cenc.uint` chooses a compact size automatically; the fixed-width variants always use the named byte width.

* Returns: `object`

```js
const cenc = require('compact-encoding')
const buf = cenc.encode(cenc.uint64, 2 ** 32)
const val = cenc.decode(cenc.uint64, buf) // 4294967296
```

cenc.int64 [#cencint64]

[src](https://github.com/holepunchto/compact-encoding/blob/v3.3.0/index.js#L224)

Signed integer encoders (`cenc.int`, `cenc.int8` … `cenc.int64`) built on top of the unsigned variants with ZigZag encoding.

* Returns: `object`

```js
const cenc = require('compact-encoding')
const buf = cenc.encode(cenc.int64, -4294967296)
const val = cenc.decode(cenc.int64, buf) // -4294967296
```

cenc.bigint [#cencbigint]

[src](https://github.com/holepunchto/compact-encoding/blob/v3.3.0/index.js#L291)

BigInt-aware integer encoders (`cenc.biguint64`, `cenc.bigint64`, `cenc.biguint`, `cenc.bigint`) for fixed-width or variable-width large integer values.

* Returns: `object`

```js
const cenc = require('compact-encoding')
const buf = cenc.encode(cenc.bigint, -(2n ** 128n))
const val = cenc.decode(cenc.bigint, buf) // -340282366920938463463374607431768211456n
```

cenc.float64 [#cencfloat64]

[src](https://github.com/holepunchto/compact-encoding/blob/v3.3.0/index.js#L321)

Floating-point encoders (`cenc.float32`, `cenc.float64`) using IEEE-754 little-endian layouts.

* Returns: `object`

```js
const cenc = require('compact-encoding')
const buf = cenc.encode(cenc.float64, Math.PI)
const val = cenc.decode(cenc.float64, buf) // 3.141592653589793
```

cenc.lexint [#cenclexint]

[src](https://github.com/holepunchto/compact-encoding/blob/v3.3.0/index.js#L293)

The lexicographic integer encoder exported from the `./lexint` module.

* Returns: `object`

```js
const cenc = require('compact-encoding')
const buf = cenc.encode(cenc.lexint, 1000)
const val = cenc.decode(cenc.lexint, buf) // 1000
```

Binary, buffer, and typed-array encodings [#binary-buffer-and-typed-array-encodings]

cenc.binary [#cencbinary]

[src](https://github.com/holepunchto/compact-encoding/blob/v3.3.0/index.js#L378)

Buffer-oriented encoders. `buffer` length-prefixes a byte sequence, `optionalBuffer` maps zero length to `null`, and `binary` accepts either a string or buffer-like input.

* Returns: `object`

```js
const cenc = require('compact-encoding')
const buf = cenc.encode(cenc.binary, 'hello')
const val = cenc.decode(cenc.binary, buf) // <Buffer 68 65 6c 6c 6f>
```

cenc.arraybuffer [#cencarraybuffer]

[src](https://github.com/holepunchto/compact-encoding/blob/v3.3.0/index.js#L390)

An encoder for `ArrayBuffer` instances.

* Returns: `object`

```js
const cenc = require('compact-encoding')
const ab = new ArrayBuffer(4)
const buf = cenc.encode(cenc.arraybuffer, ab)
const val = cenc.decode(cenc.arraybuffer, buf) // ArrayBuffer { byteLength: 4 }
```

cenc.float64array [#cencfloat64array]

[src](https://github.com/holepunchto/compact-encoding/blob/v3.3.0/index.js#L459)

Length-prefixed typed-array encoders (`cenc.uint8array`, `cenc.uint16array`, `cenc.uint32array`, `cenc.int8array`, `cenc.int16array`, `cenc.int32array`, `cenc.biguint64array`, `cenc.bigint64array`, `cenc.float32array`, `cenc.float64array`) that preserve the underlying element type.

* Returns: `object`

```js
const cenc = require('compact-encoding')
const buf = cenc.encode(cenc.float64array, new Float64Array([Math.PI]))
const val = cenc.decode(cenc.float64array, buf) // Float64Array [3.141592653589793]
```

cenc.fixed64 [#cencfixed64]

[src](https://github.com/holepunchto/compact-encoding/blob/v3.3.0/index.js#L544)

Prebuilt fixed-size buffer encoders (`cenc.fixed32`, `cenc.fixed64`) for 32-byte and 64-byte values.

* Returns: `object`

```js
const cenc = require('compact-encoding')
const sig = Buffer.alloc(64)
const buf = cenc.encode(cenc.fixed64, sig)
const val = cenc.decode(cenc.fixed64, buf) // <Buffer 00 00 ... (64 bytes)>
```

Text encodings [#text-encodings]

cenc.ucs2 [#cencucs2]

[src](https://github.com/holepunchto/compact-encoding/blob/v3.3.0/index.js#L511)

String encoders for the named text encoding (`cenc.string`, `cenc.utf8`, `cenc.ascii`, `cenc.hex`, `cenc.base64`, `cenc.utf16le`, `cenc.ucs2`). Each one also exposes `.fixed(length)` for fixed-size strings.

* Returns: `object`

```js
const cenc = require('compact-encoding')
const buf = cenc.encode(cenc.ucs2, 'hi')
const val = cenc.decode(cenc.ucs2, buf) // 'hi'
```

Boolean, date, and structured-value encodings [#boolean-date-and-structured-value-encodings]

cenc.bool [#cencbool]

[src](https://github.com/holepunchto/compact-encoding/blob/v3.3.0/index.js#L513)

A one-byte boolean encoder.

* Returns: `object`

```js
const cenc = require('compact-encoding')
const buf = cenc.encode(cenc.bool, true)
const val = cenc.decode(cenc.bool, buf) // true
```

cenc.date [#cencdate]

[src](https://github.com/holepunchto/compact-encoding/blob/v3.3.0/index.js#L593)

A `Date` encoder backed by the signed integer timestamp value from `date.getTime()`.

* Returns: `object`

```js
const cenc = require('compact-encoding')
const buf = cenc.encode(cenc.date, new Date('2024-01-01'))
const val = cenc.decode(cenc.date, buf) // Date object for 2024-01-01
```

cenc.ndjson [#cencndjson]

[src](https://github.com/holepunchto/compact-encoding/blob/v3.3.0/index.js#L617)

UTF-8 JSON encoders (`cenc.json`, `cenc.ndjson`). `ndjson` appends a trailing newline before encoding.

* Returns: `object`

```js
const cenc = require('compact-encoding')
const buf = cenc.encode(cenc.ndjson, { a: 1 })
const val = cenc.decode(cenc.ndjson, buf) // { a: 1 }
```

cenc.none [#cencnone]

[src](https://github.com/holepunchto/compact-encoding/blob/v3.3.0/index.js#L630)

A sentinel encoder that always decodes to `null` and writes no payload bytes.

* Returns: `object`

```js
const cenc = require('compact-encoding')
const buf = cenc.encode(cenc.none, null)
const val = cenc.decode(cenc.none, buf) // null
```

cenc.any [#cencany]

[src](https://github.com/holepunchto/compact-encoding/blob/v3.3.0/index.js#L708)

A schemaless tagged-value encoder for JSON-like values, arrays, objects, dates, strings, buffers, booleans, integers, and floats.

* Returns: `object`

```js
const cenc = require('compact-encoding')
const buf = cenc.encode(cenc.any, { n: 42, flag: true })
const val = cenc.decode(cenc.any, buf) // { n: 42, flag: true }
```

Network encodings [#network-encodings]

cenc.port [#cencport]

[src](https://github.com/holepunchto/compact-encoding/blob/v3.3.0/index.js#L726)

The same encoder as `cenc.uint16`, provided for protocol readability when encoding network ports.

* Returns: `object`

```js
const cenc = require('compact-encoding')
const buf = cenc.encode(cenc.port, 8080)
const val = cenc.decode(cenc.port, buf) // 8080
```

cenc.ip [#cencip]

[src](https://github.com/holepunchto/compact-encoding/blob/v3.3.0/index.js#L880)

Encoders for IPv4 addresses, IPv6 addresses, or either family with an embedded family tag (`cenc.ipv4`, `cenc.ipv6`, `cenc.ip`).

* Returns: `object`

```js
const cenc = require('compact-encoding')
const buf4 = cenc.encode(cenc.ip, '1.2.3.4')
cenc.decode(cenc.ip, buf4) // '1.2.3.4'
const buf6 = cenc.encode(cenc.ip, '::1')
cenc.decode(cenc.ip, buf6) // '0:0:0:0:0:0:0:1'
```

cenc.ipAddress [#cencipaddress]

[src](https://github.com/holepunchto/compact-encoding/blob/v3.3.0/index.js#L900)

Address-object encoders (`cenc.ipv4Address`, `cenc.ipv6Address`, `cenc.ipAddress`) for `{ host, family?, port }` shapes.

* Returns: `object`

```js
const cenc = require('compact-encoding')
const buf = cenc.encode(cenc.ipAddress, { host: '1.2.3.4', port: 8080 })
const val = cenc.decode(cenc.ipAddress, buf) // { host: '1.2.3.4', family: 4, port: 8080 }
```

Raw variants [#raw-variants]

cenc.raw [#cencraw]

[src](https://github.com/holepunchto/compact-encoding/blob/v3.3.0/index.js#L9)

A namespace of non-length-prefixed variants for many buffer, string, array, JSON, and typed-array encodings such as `cenc.raw.buffer`, `cenc.raw.utf8`, `cenc.raw.array(enc)`, and `cenc.raw.json`.

* Returns: `object`

```js
const cenc = require('compact-encoding')
// copy raw bytes into state
const buf = Buffer.from([1, 2, 3])
const state = cenc.state()
cenc.raw.preencode(state, buf)
state.buffer = Buffer.allocUnsafe(state.end)
cenc.raw.encode(state, buf)
```

Complete codec reference [#complete-codec-reference]

The sections above detail the contract and the most common encoders. Below is the full catalog of bundled codecs shipped by compact-encoding v3.3.0. Every entry is an object implementing the [encoder contract](#encoder-contract) (`preencode` / `encode` / `decode`), so any of them can be composed with [`cenc.array(enc)`](#cencarrayenc), [`cenc.frame(enc)`](#cencframeenc), or used directly with [`cenc.encode`](#const-buffer--cencencodeenc-value) / [`cenc.decode`](#const-value--cencdecodeenc-buffer). Fixed-size integers are little-endian unless the name ends in `be`.

**Unsigned integers**

| Codec           | Bytes | Notes                                                                                               |
| --------------- | ----- | --------------------------------------------------------------------------------------------------- |
| `cenc.uint`     | 1–9   | Smallest fixed-size encoding with a prefix signalling which; best for values spanning a wide range. |
| `cenc.uint8`    | 1     | Fixed `uint8`.                                                                                      |
| `cenc.uint16`   | 2     | Fixed `uint16`; useful for ports.                                                                   |
| `cenc.uint24`   | 3     | Fixed `uint24`; useful for message framing.                                                         |
| `cenc.uint32`   | 4     | Fixed `uint32`; useful for large message framing.                                                   |
| `cenc.uint32be` | 4     | Big-endian `uint32`.                                                                                |
| `cenc.uint40`   | 5     | Fixed `uint40`.                                                                                     |
| `cenc.uint48`   | 6     | Fixed `uint48`.                                                                                     |
| `cenc.uint56`   | 7     | Fixed `uint56`.                                                                                     |
| `cenc.uint64`   | 8     | Fixed `uint64`.                                                                                     |
| `cenc.uint64be` | 8     | Big-endian `uint64`.                                                                                |

**Signed integers** — each is the matching unsigned codec with [ZigZag](https://en.wikipedia.org/wiki/Variable-length_quantity#Zigzag_encoding) encoding, so small-magnitude negatives stay compact.

| Codec        | Bytes |
| ------------ | ----- |
| `cenc.int`   | 1–9   |
| `cenc.int8`  | 1     |
| `cenc.int16` | 2     |
| `cenc.int24` | 3     |
| `cenc.int32` | 4     |
| `cenc.int40` | 5     |
| `cenc.int48` | 6     |
| `cenc.int56` | 7     |
| `cenc.int64` | 8     |

**Big integers**

| Codec            | Bytes    | Notes                             |
| ---------------- | -------- | --------------------------------- |
| `cenc.biguint64` | 8        | Fixed `biguint64`.                |
| `cenc.bigint64`  | 8        | `biguint64` with ZigZag encoding. |
| `cenc.biguint`   | variable | Word count `uint`-prefixed.       |
| `cenc.bigint`    | variable | `biguint` with ZigZag encoding.   |

**Floating point**

| Codec          | Bytes |
| -------------- | ----- |
| `cenc.float32` | 4     |
| `cenc.float64` | 8     |

**Buffers**

| Codec                 | Notes                                                    |
| --------------------- | -------------------------------------------------------- |
| `cenc.buffer`         | Buffer with a `uint` length prefix.                      |
| `cenc.optionalBuffer` | Like `cenc.buffer` but round-trips `null`/absent values. |
| `cenc.binary`         | Buffer or string, length-prefixed; decodes to a buffer.  |
| `cenc.arraybuffer`    | `ArrayBuffer` with a `uint` length prefix.               |

**Typed arrays** — each is prefixed with its element count as a `uint`.

| Codec                 | Element type     |
| --------------------- | ---------------- |
| `cenc.uint8array`     | `Uint8Array`     |
| `cenc.uint16array`    | `Uint16Array`    |
| `cenc.uint32array`    | `Uint32Array`    |
| `cenc.int8array`      | `Int8Array`      |
| `cenc.int16array`     | `Int16Array`     |
| `cenc.int32array`     | `Int32Array`     |
| `cenc.biguint64array` | `BigUint64Array` |
| `cenc.bigint64array`  | `BigInt64Array`  |
| `cenc.float32array`   | `Float32Array`   |
| `cenc.float64array`   | `Float64Array`   |

**Strings** — each is length-prefixed and also exposes a `.fixed(n)` factory for a fixed-length variant (for example `cenc.hex.fixed(32)`).

| Codec                       | Encoding |
| --------------------------- | -------- |
| `cenc.string`, `cenc.utf8`  | UTF-8    |
| `cenc.ascii`                | ASCII    |
| `cenc.hex`                  | Hex      |
| `cenc.base64`               | Base64   |
| `cenc.utf16le`, `cenc.ucs2` | UTF-16LE |

**Fixed-size buffers**

| Codec           | Notes                                                    |
| --------------- | -------------------------------------------------------- |
| `cenc.fixed(n)` | Factory for an `n`-byte fixed buffer (no length prefix). |
| `cenc.fixed32`  | Fixed 32-byte buffer.                                    |
| `cenc.fixed64`  | Fixed 64-byte buffer.                                    |

**Structured & special values**

| Codec                           | Notes                                                                                                     |
| ------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `cenc.bool`                     | Encodes a boolean as `1` or `0`.                                                                          |
| `cenc.date`                     | Encodes a `Date`.                                                                                         |
| `cenc.json`                     | JSON value serialized as UTF-8.                                                                           |
| `cenc.ndjson`                   | JSON value serialized as newline-delimited UTF-8.                                                         |
| `cenc.any`                      | Any JSON-representable value into a self-describing buffer (compact types); useful for schemaless codecs. |
| `cenc.none`                     | Encodes nothing—placeholder for empty fields.                                                             |
| `cenc.array(enc)`               | Length-prefixed array of `enc` values.                                                                    |
| `cenc.frame(enc)`               | Wraps `enc` with a `uint` byte-length frame prefix.                                                       |
| `cenc.record(keyEnc, valueEnc)` | Length-prefixed map of key/value pairs.                                                                   |
| `cenc.stringRecord`             | `record(utf8, utf8)`—a string-to-string map.                                                              |

**Network addresses**

| Codec              | Notes                                 |
| ------------------ | ------------------------------------- |
| `cenc.port`        | Port number (alias of `cenc.uint16`). |
| `cenc.ipv4`        | IPv4 address.                         |
| `cenc.ipv4Address` | IPv4 address plus port.               |
| `cenc.ipv6`        | IPv6 address.                         |
| `cenc.ipv6Address` | IPv6 address plus port.               |
| `cenc.ip`          | Dual IPv4/IPv6 address.               |
| `cenc.ipAddress`   | Dual IPv4/IPv6 address plus port.     |

**Non-prefixed variants** — [`cenc.raw`](#cencraw) exposes length-prefix-free versions of the buffer, string, typed-array, array, and JSON codecs: `cenc.raw.buffer`, `cenc.raw.arraybuffer`, `cenc.raw.<typedarray>`, `cenc.raw.utf8` / `cenc.raw.ascii` / `cenc.raw.hex` / `cenc.raw.base64` / `cenc.raw.ucs2`, `cenc.raw.array(enc)`, `cenc.raw.json`, and `cenc.raw.ndjson`.

Types [#types]

State [#state]

| Property | Type                                                                          | Default | Description                                                             |
| -------- | ----------------------------------------------------------------------------- | ------- | ----------------------------------------------------------------------- |
| `start`  | `number`                                                                      | —       | Byte offset to read/write from. Advances after each encode/decode call. |
| `end`    | `number`                                                                      | —       | Byte offset marking the end of valid data. Advances during preencode.   |
| `buffer` | [`Buffer\|Uint8Array\|null`](https://nodejs.org/api/buffer.html#class-buffer) | —       | The underlying byte buffer. Set to `null` until allocation.             |

See also [#see-also]

* [Protomux](/reference/helpers/protomux)—the most common higher-level protocol surface built directly on compact-encoding schemas.
* [Hypercore](/reference/building-blocks/hypercore)—accepts compact encodings for structured values and message payloads.
* [Upstream compact-encoding repository](https://github.com/holepunchto/compact-encoding)—source, releases, and implementation details.


# Corestore



<Status level="stable" />

`Corestore` manages many related [Hypercores](/reference/building-blocks/hypercore) behind one storage root and one replication surface. It is the helper you usually share across [Hyperbee](/reference/building-blocks/hyperbee), [Hyperdrive](/reference/building-blocks/hyperdrive), and [Autobase](/reference/building-blocks/autobase) instances. For upstream source and changelog context, see the [Corestore repository](https://github.com/holepunchto/corestore).

Install [#install]

```sh
npm i corestore
```

Quickstart [#quickstart]

```js
import Corestore from 'corestore'

const store = new Corestore('./app-storage')
await store.ready()

const messages = store.get({
  name: 'messages',
  valueEncoding: 'json'
})

await messages.ready()
await messages.append({ text: 'hello from corestore' })

console.log(await messages.get(0))

await store.close()
```

API Reference [#api-reference]

Constructor and lifecycle [#constructor-and-lifecycle]

new Corestore(storage, options = {}) [#new-corestorestorage-options--]

[src](https://github.com/holepunchto/corestore/blob/v7.11.0/index.js#L236)

Create a new Corestore instance.

| Parameter | Type                                    | Default | Description                                               |
| --------- | --------------------------------------- | ------- | --------------------------------------------------------- |
| `storage` | `string\|object`                        | —       | can be either a `hypercore-storage` instance or a string. |
| `options` | [`CorestoreOptions`](#corestoreoptions) | `{}`    | Store options.                                            |

* Throws: `ERR_ASSERTION` if `primaryKey` is set on a root store without `unsafe: true`.

await store.ready() [#await-storeready]

A promise that resolves once the storage seed is loaded and properties such as `store.primaryKey` are available.

await store.close() [#await-storeclose]

Fully close this Corestore instance.

await store.suspend([options]) [#await-storesuspendoptions]

[src](https://github.com/holepunchto/corestore/blob/v7.11.0/index.js#L350)

Suspend the underlying storage for the Corestore.

| Parameter | Type     | Default | Description      |
| --------- | -------- | ------- | ---------------- |
| `options` | `object` | `{}`    | Suspend options. |

* Returns: [`Promise<void>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) — Resolves once the storage is flushed and suspended.

```js
await store.suspend()
```

await store.resume() [#await-storeresume]

[src](https://github.com/holepunchto/corestore/blob/v7.11.0/index.js#L363)

Resume a suspended Corestore.

* Returns: [`Promise<void>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) — Resolves once the storage is resumed.

```js
await store.resume()
```

Store properties [#store-properties]

store.storage [#storestorage]

[src](https://github.com/holepunchto/corestore/blob/v7.11.0/index.js#L240)

The backing storage adapter used for aliases, seeds, and Hypercore data files.

* Returns: `object`

store.primaryKey [#storeprimarykey]

[src](https://github.com/holepunchto/corestore/blob/v7.11.0/index.js#L254)

The 32-byte primary key used to deterministically derive writable named cores and namespaced key pairs.

* Returns: [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer)

store.readOnly [#storereadonly]

[src](https://github.com/holepunchto/corestore/blob/v7.11.0/index.js#L252)

`true` when the store was opened without write access.

* Returns: `boolean`

store.manifestVersion [#storemanifestversion]

[src](https://github.com/holepunchto/corestore/blob/v7.11.0/index.js#L256)

The Hypercore manifest version used when Corestore creates new writable cores.

* Returns: `number`

store.active [#storeactive]

[src](https://github.com/holepunchto/corestore/blob/v7.11.0/index.js#L258)

`true` when the store should automatically attach loaded cores to active replication streams.

* Returns: `boolean`

store.opened / store.closed [#storeopened--storeclosed]

`true` once [`store.ready()`](#await-storeready) has resolved / once [`store.close()`](#await-storeclose) has completed. Useful for guarding access to a store whose lifecycle you don't fully control.

* Returns: `boolean`

Loading cores and scoping sessions [#loading-cores-and-scoping-sessions]

store.get(key | { name: 'a-name', ...hypercoreOpts}) [#storegetkey---name-a-name-hypercoreopts]

[src](https://github.com/holepunchto/corestore/blob/v7.11.0/index.js#L564)

Loads a Hypercore, either by name (if the `name` option is provided), or from the provided key (if the first argument is a Buffer or String with hex/z32 key, or if the `key` options is set).

| Parameter | Type                                                                        | Description                                                                                                       |
| --------- | --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `opts`    | [`Buffer\|string\|object`](https://nodejs.org/api/buffer.html#class-buffer) | A key (Buffer/hex/z32 string), or an options object with `name`, `key`, or `discoveryKey` plus Hypercore options. |

* Returns: [`Hypercore`](/reference/building-blocks/hypercore) — A Hypercore session for the requested core.

```js
const core = store.get({ name: 'my-core' })
```

storeA.session() [#storeasession]

[src](https://github.com/holepunchto/corestore/blob/v7.11.0/index.js#L367)

Create a new Corestore session. Closing a session will close all cores made from this session.

| Parameter | Type     | Description                                       |
| --------- | -------- | ------------------------------------------------- |
| `opts`    | `object` | Session options (forwarded to the new Corestore). |

* Returns: [`Corestore`](/reference/helpers/corestore) — A new Corestore session sharing the same storage.

```js
const session = store.session()
```

store.namespace(name) [#storenamespacename]

[src](https://github.com/holepunchto/corestore/blob/v7.11.0/index.js#L377)

Create a new namespaced Corestore session. Namespacing is useful if you're going to be sharing a single Corestore instance between many applications or components, as it prevents name collisions.

| Parameter | Type                                                                | Description                                                              |
| --------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| `name`    | [`string\|Buffer`](https://nodejs.org/api/buffer.html#class-buffer) | Namespace name; combined with the current namespace to derive a new one. |
| `opts`    | `object`                                                            | Session options (forwarded to the new Corestore).                        |

* Returns: [`Corestore`](/reference/helpers/corestore) — A new namespaced Corestore session.

```js
const ns1 = store.namespace('a')
const ns2 = ns1.namespace('b')
const core1 = ns1.get({ name: 'main' }) // These will load different Hypercores
const core2 = ns2.get({ name: 'main' })
```

Replication and discovery [#replication-and-discovery]

store.replicate(optsOrStream) [#storereplicateoptsorstream]

[src](https://github.com/holepunchto/corestore/blob/v7.11.0/index.js#L481)

Creates a replication stream that's capable of replicating all Hypercores that are managed by the Corestore, assuming the remote peer has the correct capabilities.

| Parameter     | Type                                                    | Description                                                                     |
| ------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------- |
| `isInitiator` | [`boolean\|Stream`](https://nodejs.org/api/stream.html) | `true`/`false` to initiate, or an existing stream/connection to replicate over. |
| `opts`        | `object`                                                | Replication options, forwarded to the protocol stream.                          |

* Returns: [`Stream`](https://nodejs.org/api/stream.html) — The replication stream.

```js
const swarm = new Hyperswarm()

// join the relevant topic
swarm.join(...)

// simply pass the connection stream to corestore
swarm.on('connection', (connection) => store.replicate(connection))
```

store.findingPeers() [#storefindingpeers]

[src](https://github.com/holepunchto/corestore/blob/v7.11.0/index.js#L335)

A completion callback. Call it after the current peer-discovery pass finishes so pending update waits on loaded cores can unblock.

* Returns: `Function` — A `done` function to call once peer discovery has finished.

```js
const done = store.findingPeers()
swarm.flush().then(done, done)
```

store.list(namespace) [#storelistnamespace]

[src](https://github.com/holepunchto/corestore/blob/v7.11.0/index.js#L384)

Creates a discovery key stream of all cores within a namespace or all cores in general if no namespace is provided.

| Parameter   | Type                                                        | Description                          |
| ----------- | ----------------------------------------------------------- | ------------------------------------ |
| `namespace` | [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer) | to scope to; omit to list all cores. |

* Returns: [`Readable`](https://nodejs.org/api/stream.html#class-streamreadable) — A stream of discovery keys.

```js
for await (const discoveryKey of store.list()) console.log(discoveryKey)
```

store.getAuth(discoveryKey) [#storegetauthdiscoverykey]

[src](https://github.com/holepunchto/corestore/blob/v7.11.0/index.js#L388)

The storage-layer auth metadata for that core, including manifest details when available.

| Parameter      | Type                                                        | Description                           |
| -------------- | ----------------------------------------------------------- | ------------------------------------- |
| `discoveryKey` | [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer) | Discovery key of the core to look up. |

* Returns: [`Promise<object\|null>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) — The auth record, or `null` if not stored.

```js
const auth = await store.getAuth(discoveryKey)
```

Key derivation and maintenance [#key-derivation-and-maintenance]

await store.createKeyPair(name, ns = this.ns) [#await-storecreatekeypairname-ns--thisns]

[src](https://github.com/holepunchto/corestore/blob/v7.11.0/index.js#L621)

Generate a key pair seeded with the Corestore's primary key using a `name` and a `ns` aka namespace. `ns` defaults to the current namespace.

| Parameter | Type                                                        | Default   | Description                  |
| --------- | ----------------------------------------------------------- | --------- | ---------------------------- |
| `name`    | `string`                                                    | —         | to derive the key pair from. |
| `ns`      | [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer) | `this.ns` | —                            |

* Returns: [`Promise<{publicKey: Buffer, secretKey: Buffer}>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) — The derived key pair.

```js
const keyPair = await store.createKeyPair('signer')
```

store.audit(opts = {}) [#storeauditopts--]

[src](https://github.com/holepunchto/corestore/blob/v7.11.0/index.js#L346)

An audit report describing the state of the backing store and any detected inconsistencies.

| Parameter | Type     | Default | Description                           |
| --------- | -------- | ------- | ------------------------------------- |
| `opts`    | `object` | `{}`    | Audit options (for example `dryRun`). |

* Returns: `AsyncGenerator<object>` — Yields a result per core as it is audited.

```js
for await (const report of store.audit()) console.log(report)
```

await store.staticify(core, opts) [#await-storestaticifycore-opts]

[src](https://github.com/holepunchto/corestore/blob/v7.11.0/index.js#L520)

A reopened Hypercore whose manifest is converted into a static prologue-based manifest for the current data snapshot.

| Parameter | Type                                                | Description                                          |
| --------- | --------------------------------------------------- | ---------------------------------------------------- |
| `core`    | [`Hypercore`](/reference/building-blocks/hypercore) | The source core to snapshot. Must have data.         |
| `opts`    | `object`                                            | Options forwarded to `store.get()` for the new core. |

* Returns: [`Promise<Hypercore>`](/reference/building-blocks/hypercore) — The new static Hypercore.
* Throws: if the core has no data to staticify.

```js
const staticCore = await store.staticify(core)
```

Watchers [#watchers]

store.watch((core) => {}) [#storewatchcore--]

[src](https://github.com/holepunchto/corestore/blob/v7.11.0/index.js#L277)

Register a callback called when new Hypercores are opened. `core` is the internal core for the opened Hypercore. It can be used to create weak references to a Hypercore like so:

| Parameter | Type       | Description                                                                |
| --------- | ---------- | -------------------------------------------------------------------------- |
| `fn`      | `Function` | Callback invoked with the internal `core` each time a Hypercore is opened. |

* Returns: `void`

```js
store.watch(function (core) {
  const weakCore = new Hypercore({ core, weak: true })
})
```

store.unwatch(callback) [#storeunwatchcallback]

[src](https://github.com/holepunchto/corestore/blob/v7.11.0/index.js#L286)

Unregister a callback used with `store.watch(callback)` so it no longer fires.

| Parameter  | Type       | Description                                        |
| ---------- | ---------- | -------------------------------------------------- |
| `callback` | `Function` | The callback previously passed to `store.watch()`. |

* Returns: `void`

```js
store.unwatch(onCore)
```

Group notifications (experimental) [#group-notifications-experimental]

store.notifyGroup(topic) [#storenotifygrouptopic]

[src](https://github.com/holepunchto/corestore/blob/v7.11.0/index.js#L306)

Get a `handle` for updates from all `hypercore`s with the group `topic` set.

| Parameter | Type                                                        | Description                       |
| --------- | ----------------------------------------------------------- | --------------------------------- |
| `topic`   | [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer) | The 32-byte group topic to watch. |

* Returns: [`GroupNotifyHandle`](/reference/helpers/corestore) — A handle that emits `update` when a core in the group changes.

```js
const handle = store.notifyGroup(topic)
handle.on('update', () => console.log('group changed'))
```

<Callout type="warn">
  Group notifications are experimental. The API is subject to change and may break in any release.
</Callout>

handle.update(opts = {}) [#handleupdateopts--]

Gets updates for the `topic` the handle is for.

| Parameter | Default |
| --------- | ------- |
| `opts`    | `{}`    |

| Option    | Default | Description                                                                          |
| --------- | ------- | ------------------------------------------------------------------------------------ |
| `since`   | `0`     | What timestamp to start returning updates from. Default `0` returns all updates      |
| `reverse` | `true`  | Flag to return updates in reverse order. Defaults to `true` so latest returned first |

```js
for await (const key of handle.updates()) {
  // ...
}
```

handle.destroy() [#handledestroy]

[src](https://github.com/holepunchto/corestore/blob/v7.11.0/index.js#L229)

Destroys and unregisters the `handle` from its `store`.

handle.on('update', callback) [#handleonupdate-callback]

Calls the callback whenever a core with the `topic` for the `handle` updates.

store.on('group-active', (topic) => {}) [#storeongroup-active-topic--]

[src](https://github.com/holepunchto/corestore/blob/v7.11.0/index.js#L298)

The `group-active` event emits whenever an opened Hypercore in the store updates. The `topic` is the group topic the core belongs to.

Types [#types]

CorestoreOptions [#corestoreoptions]

Options for the \{@link Corestore} constructor. Any other options are forwarded
to the underlying `hypercore-storage` instance.

| Property     | Type                                                        | Default | Description                                                                                                                 |
| ------------ | ----------------------------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------- |
| `primaryKey` | [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer) | —       | The 32-byte master key from which all writable named cores are derived. Generated and persisted automatically when omitted. |
| `writable`   | `boolean`                                                   | `true`  | Set to `false` to open the store read-only; loaded cores default to read-only too.                                          |
| `readOnly`   | `boolean`                                                   | `false` | Open the backing storage in read-only mode.                                                                                 |
| `active`     | `boolean`                                                   | `true`  | Whether loaded cores are automatically attached to active replication streams.                                              |
| `unsafe`     | `boolean`                                                   | `false` | Acknowledge that passing `primaryKey` directly is unsafe; required when `primaryKey` is set on a root store.                |

Errors [#errors]

Coded errors this module can throw — catch them via `err.code`.

| Error       | Thrown when                                                    |
| ----------- | -------------------------------------------------------------- |
| `ASSERTION` | if `primaryKey` is set on a root store without `unsafe: true`. |

See also [#see-also]

* [Work with many Hypercores using Corestore](/how-to/store-and-replicate/work-with-many-hypercores-using-corestore)—the task-oriented guide that shows how to share one store across your app.
* [Hypercore](/reference/building-blocks/hypercore)—the append-only log type Corestore opens and co-replicates.
* [Hyperbee](/reference/building-blocks/hyperbee)—commonly layered on top of named Hypercores from one store.
* [Hyperdrive](/reference/building-blocks/hyperdrive)—usually keeps filesystem metadata and content stores inside one shared Corestore.
* [Autobase](/reference/building-blocks/autobase)—multi-writer views often coordinate their input cores through one Corestore.
* [Hyperswarm](/reference/building-blocks/hyperswarm)—pass swarm connections to `store.replicate()` to co-replicate all managed cores over one stream.
* [Upstream Corestore repository](https://github.com/holepunchto/corestore)—source, releases, and implementation details.


# Localdrive



<Status level="stable" />

`Localdrive` exposes a local directory through an API that closely matches [Hyperdrive](/reference/building-blocks/hyperdrive). It is the simplest way to mirror between on-disk files and distributed drives with [Mirrordrive](/reference/helpers/mirrordrive). For upstream implementation details, see the [Localdrive repository](https://github.com/holepunchto/localdrive).

Install [#install]

```sh
npm i localdrive
```

Quickstart [#quickstart]

```js
import Localdrive from 'localdrive'

const drive = new Localdrive('./site')

await drive.put('/index.html', Buffer.from('<h1>Hello</h1>'))
const html = await drive.get('/index.html')

console.log(html?.toString())
console.log(await drive.entry('/index.html'))
```

API Reference [#api-reference]

Constructor and lifecycle [#constructor-and-lifecycle]

new Localdrive(root, [options]) [#new-localdriveroot-options]

[src](https://github.com/holepunchto/localdrive/blob/v2.2.1/index.js#L11)

Creates a drive based on a `root` directory. `root` can be relative or absolute.

| Parameter | Type                                      | Default | Description            |
| --------- | ----------------------------------------- | ------- | ---------------------- |
| `root`    | `string`                                  | —       | —                      |
| `options` | [`LocaldriveOptions`](#localdriveoptions) | `{}`    | Configuration options. |

| Option        | Default | Description                                             |
| ------------- | ------- | ------------------------------------------------------- |
| `followLinks` | `false` | If enabled then `entry(key)` will follow the `linkname` |
| `metadata`    | —       | —                                                       |
| `atomic`      | `false` | Enable atomicity for file writing (tmp file and rename) |

await drive.ready() [#await-driveready]

[src](https://github.com/holepunchto/localdrive/blob/v2.2.1/index.js#L22)

Resolves immediately. It exists for compatibility with drive-like APIs such as [Hyperdrive](/reference/building-blocks/hyperdrive).

* Returns: [`Promise<void>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) — Resolves immediately.

```js
await drive.ready()
```

await drive.close() [#await-driveclose]

[src](https://github.com/holepunchto/localdrive/blob/v2.2.1/index.js#L25)

Resolves immediately. Localdrive does not keep a background storage process open.

* Returns: [`Promise<void>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) — Resolves immediately.

```js
await drive.close()
```

await drive.flush() [#await-driveflush]

[src](https://github.com/holepunchto/localdrive/blob/v2.2.1/index.js#L28)

Resolves immediately. It exists so code written for batched drive APIs can treat Localdrive as a drop-in target.

* Returns: [`Promise<void>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) — Resolves immediately.

```js
await drive.flush()
```

Drive properties [#drive-properties]

drive.root [#driveroot]

[src](https://github.com/holepunchto/localdrive/blob/v2.2.1/index.js#L12)

String with the resolved (absolute) drive path.

* Returns: `string`

drive.supportsMetadata [#drivesupportsmetadata]

[src](https://github.com/holepunchto/localdrive/blob/v2.2.1/index.js#L14)

Boolean that indicates if the drive handles or not metadata. Default `false`.

* Returns: `boolean`

Compatibility helpers [#compatibility-helpers]

drive.batch() [#drivebatch]

[src](https://github.com/holepunchto/localdrive/blob/v2.2.1/index.js#L32)

Returns the same `Localdrive` instance. This lets batch-oriented code reuse a Localdrive target without branching.

* Returns: [`Localdrive`](/reference/helpers/localdrive) — This drive instance.

```js
const batch = drive.batch()
await batch.put('/file.txt', Buffer.from('hello'))
// on Localdrive, batch === drive
```

drive.checkout() [#drivecheckout]

[src](https://github.com/holepunchto/localdrive/blob/v2.2.1/index.js#L36)

Returns the same `Localdrive` instance. Unlike Hyperdrive, Localdrive does not expose historical versions.

* Returns: [`Localdrive`](/reference/helpers/localdrive) — This drive instance.

```js
const snapshot = drive.checkout()
// on Localdrive, snapshot === drive
```

drive.toPath(key) [#drivetopathkey]

[src](https://github.com/holepunchto/localdrive/blob/v2.2.1/index.js#L40)

Resolves a drive path such as `'/images/logo.png'` to its local filesystem path under `drive.root`.

| Parameter | Type     | Description                                            |
| --------- | -------- | ------------------------------------------------------ |
| `key`     | `string` | Drive key to convert (for example `/images/logo.png`). |

* Returns: `string` — Absolute filesystem path for the given key.

```js
const drive = new Localdrive('/srv/data')
drive.toPath('/images/logo.png') // => '/srv/data/images/logo.png'
```

Reading and writing entries [#reading-and-writing-entries]

await drive.entry(name, [options]) [#await-driveentryname-options]

[src](https://github.com/holepunchto/localdrive/blob/v2.2.1/index.js#L46)

Resolves with the entry stored at `key`, or `null` if no entry exists.

| Parameter | Type                            | Description                                     |
| --------- | ------------------------------- | ----------------------------------------------- |
| `name`    | `string`                        | Drive key to look up (for example `/file.txt`). |
| `options` | [`EntryOptions`](#entryoptions) | Entry lookup options.                           |

* Returns: [`Promise<object\|null>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) — the entry at `name` path in the drive.

| Option   | Default | Description                             |
| -------- | ------- | --------------------------------------- |
| `follow` | `false` | Follow symlinks when resolving the key. |

await drive.get(key, [options]) [#await-drivegetkey-options]

[src](https://github.com/holepunchto/localdrive/blob/v2.2.1/index.js#L139)

Reads the file at `key` and resolves with its contents as a `Buffer`, or `null` if no file exists (also `null` for symbolic links).

| Parameter | Type                        | Description                                              |
| --------- | --------------------------- | -------------------------------------------------------- |
| `key`     | `string`                    | Drive key of the file to read (for example `/blob.txt`). |
| `options` | [`GetOptions`](#getoptions) | `options` are the same as in `drive.entry` method.       |

* Returns: [`Promise<Buffer\|null>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) — the blob at `key` path in the drive.

```js
const buffer = await drive.get('/blob.txt')
console.log(buffer.toString()) // => 'example'
```

await drive.put(key, buffer, [options]) [#await-driveputkey-buffer-options]

[src](https://github.com/holepunchto/localdrive/blob/v2.2.1/index.js#L151)

Creates a file at `key` path in the drive. `options` are the same as in `createWriteStream`.

| Parameter | Type                                                                | Description                                                      |
| --------- | ------------------------------------------------------------------- | ---------------------------------------------------------------- |
| `key`     | `string`                                                            | Drive key of the file to write (for example `/images/logo.png`). |
| `buffer`  | [`Buffer\|string`](https://nodejs.org/api/buffer.html#class-buffer) | Data to write.                                                   |
| `options` | [`WriteStreamOptions`](#writestreamoptions)                         | —                                                                |

* Returns: [`Promise<void>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) — Resolves when the file has been fully written and closed.

```js
await drive.put('/blob.txt', Buffer.from('example'))
await drive.put('/images/logo.png', Buffer.from('..'), { executable: false })
```

await drive.del(key) [#await-drivedelkey]

[src](https://github.com/holepunchto/localdrive/blob/v2.2.1/index.js#L166)

Deletes the file at `key` path from the drive.

| Parameter | Type     | Description                                                           |
| --------- | -------- | --------------------------------------------------------------------- |
| `key`     | `string` | Drive key of the file to delete (for example `/images/old-logo.png`). |

* Returns: [`Promise<void>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) — Resolves when the file and any empty parent directories have been removed.

```js
await drive.del('/images/old-logo.png')
```

await drive.symlink(key, linkname) [#await-drivesymlinkkey-linkname]

[src](https://github.com/holepunchto/localdrive/blob/v2.2.1/index.js#L191)

Creates an entry in drive at `key` path that points to the entry at `linkname`.

| Parameter  | Type     | Description                                  |
| ---------- | -------- | -------------------------------------------- |
| `key`      | `string` | Drive key where the symlink will be created. |
| `linkname` | `string` | Target path the symlink should point to.     |

* Returns: [`Promise<void>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) — Resolves when the symlink entry has been created.

```js
await drive.symlink('/images/logo.shortcut', '/images/logo.png')
```

await drive.exists(name) [#await-driveexistsname]

[src](https://github.com/holepunchto/localdrive/blob/v2.2.1/index.js#L291)

Resolves to `true` when `drive.entry(key)` resolves to a non-null entry, otherwise `false`.

| Parameter | Type     | Description                                   |
| --------- | -------- | --------------------------------------------- |
| `name`    | `string` | Drive key to check (for example `/file.txt`). |

* Returns: [`Promise<boolean>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) — Whether an entry exists at the given path.

```js
const found = await drive.exists('/blob.txt')
console.log(found) // => true or false
```

drive.compare(entryA, entryB) [#drivecompareentrya-entryb]

[src](https://github.com/holepunchto/localdrive/blob/v2.2.1/index.js#L214)

Compares two drive entries by modification time.

| Parameter | Type     | Description                                                   |
| --------- | -------- | ------------------------------------------------------------- |
| `entryA`  | `object` | First entry (must have an `mtime` property in milliseconds).  |
| `entryB`  | `object` | Second entry (must have an `mtime` property in milliseconds). |

* Returns: `number` — `1` if `entryA` is newer, `-1` if `entryB` is newer, and `0` if they are equal.

```js
const entryA = await drive.entry('/file-a.txt')
const entryB = await drive.entry('/file-b.txt')
const result = drive.compare(entryA, entryB)
// result: 0 (same), 1 (a is newer), or -1 (b is newer)
```

Listing and mirroring [#listing-and-mirroring]

drive.list([folder], [options]) [#drivelistfolder-options]

[src](https://github.com/holepunchto/localdrive/blob/v2.2.1/index.js#L219)

Returns a stream of entries for files under `folder` (defaults to the whole drive).

| Parameter | Type                          | Default | Description                                             |
| --------- | ----------------------------- | ------- | ------------------------------------------------------- |
| `folder`  | `string`                      | —       | Unix-style path prefix to list (for example `/images`). |
| `options` | [`ListOptions`](#listoptions) | `{}`    | Listing options.                                        |

* Returns: `AsyncIterable<object>` — a stream of all entries in the drive inside of specified `folder`.

drive.readdir([folder]) [#drivereaddirfolder]

[src](https://github.com/holepunchto/localdrive/blob/v2.2.1/index.js#L256)

Returns an async iterator that yields the immediate child names (not
full paths) under `folder`. Only non-empty sub-directories and files with
a valid entry are included.

| Parameter | Type     | Description                                             |
| --------- | -------- | ------------------------------------------------------- |
| `folder`  | `string` | Unix-style path prefix to read (for example `/images`). |

* Returns: `AsyncIterable<string>` — a stream of all subpaths of entries in drive stored at paths prefixed by `folder`.

```js
for await (const name of drive.readdir('/images')) {
  console.log(name) // => 'logo.png', 'banner.jpg', ...
}
```

drive.mirror(out, [options]) [#drivemirrorout-options]

[src](https://github.com/holepunchto/localdrive/blob/v2.2.1/index.js#L295)

Efficiently mirror this drive into another. Returns a [`MirrorDrive`](https://github.com/holepunchto/mirror-drive#api) instance constructed with `options`.

| Parameter | Type                              | Description                                            |
| --------- | --------------------------------- | ------------------------------------------------------ |
| `out`     | `object`                          | Destination drive (must implement the same drive API). |
| `options` | [`MirrorOptions`](#mirroroptions) | Options forwarded to `MirrorDrive`.                    |

* Returns: [`MirrorDrive`](/reference/helpers/mirrordrive) — A MirrorDrive instance that runs the mirror operation.

```js
const src = new Localdrive('./source')
const dst = new Localdrive('./destination')
const mirror = src.mirror(dst)
await mirror.done()
```

Stream APIs [#stream-apis]

drive.createReadStream(key, [options]) [#drivecreatereadstreamkey-options]

[src](https://github.com/holepunchto/localdrive/blob/v2.2.1/index.js#L299)

Returns a readable stream of the file stored at `key`.

| Parameter | Type                                      | Description                                                |
| --------- | ----------------------------------------- | ---------------------------------------------------------- |
| `key`     | `string`                                  | Drive key of the file to stream (for example `/blob.txt`). |
| `options` | [`ReadStreamOptions`](#readstreamoptions) | Range options.                                             |

* Returns: `FileReadStream` — a stream to read out the blob stored in the drive at `key` path.

drive.createWriteStream(key, [options]) [#drivecreatewritestreamkey-options]

[src](https://github.com/holepunchto/localdrive/blob/v2.2.1/index.js#L306)

Stream a blob into the drive at `key` path.

| Parameter | Type                                        | Description                                               |
| --------- | ------------------------------------------- | --------------------------------------------------------- |
| `key`     | `string`                                    | Drive key of the file to write (for example `/blob.txt`). |
| `options` | [`WriteStreamOptions`](#writestreamoptions) | Write options.                                            |

* Returns: `FileWriteStream` — Writable stream targeting the given key.

Types [#types]

LocaldriveOptions [#localdriveoptions]

Options for creating a Localdrive instance.

| Property              | Type                                                                                                  | Default | Description                                                   |
| --------------------- | ----------------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------------------- |
| `followLinks`         | `boolean`                                                                                             | `false` | If enabled, `entry(key)` follows the `linkname` for symlinks. |
| `followExternalLinks` | `boolean`                                                                                             | `false` | If enabled, symlinks pointing outside the root are followed.  |
| `metadata`            | [`object\|Map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) | —       | Hook functions called when metadata is read/written/deleted.  |
| `metadata.get`        | `function`                                                                                            | —       | Called with `(key)` to retrieve metadata for a file.          |
| `metadata.put`        | `function`                                                                                            | —       | Called with `(key, value)` to store metadata for a file.      |
| `metadata.del`        | `function`                                                                                            | —       | Called with `(key)` to delete metadata for a file.            |
| `atomic`              | `boolean`                                                                                             | `false` | Enable atomic file writes (write to a tmp file then rename).  |

EntryOptions [#entryoptions]

Options for `drive.entry()`.

| Property | Type      | Default | Description                                                         |
| -------- | --------- | ------- | ------------------------------------------------------------------- |
| `follow` | `boolean` | `false` | Follow symlinks (up to 15 levels, then throws `Recursive symlink`). |

GetOptions [#getoptions]

Options for `drive.get()`.

| Property | Type      | Default | Description                             |
| -------- | --------- | ------- | --------------------------------------- |
| `follow` | `boolean` | `false` | Follow symlinks when resolving the key. |

WriteStreamOptions [#writestreamoptions]

Options for `drive.put()` and `drive.createWriteStream()`.

| Property     | Type      | Default | Description                                            |
| ------------ | --------- | ------- | ------------------------------------------------------ |
| `executable` | `boolean` | `false` | Mark the written file as executable (chmod 0o755).     |
| `metadata`   | `*`       | —       | Arbitrary metadata value stored via the metadata hook. |

ListOptions [#listoptions]

Options for `drive.list()`.

| Property | Type                                                                                                                        | Default | Description                                                                                                               |
| -------- | --------------------------------------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------- |
| `ignore` | [`string\|Array<string>\|function`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) | —       | File/folder paths to exclude. May be a path string, an array of path strings, or a predicate function `(key) => boolean`. |

ReadStreamOptions [#readstreamoptions]

Options for `drive.createReadStream()`.

| Property | Type     | Default | Description                                                               |
| -------- | -------- | ------- | ------------------------------------------------------------------------- |
| `start`  | `number` | `0`     | Byte offset to start reading from (inclusive).                            |
| `end`    | `number` | —       | Byte offset to stop reading at (inclusive). Ignored when `length` is set. |
| `length` | `number` | —       | Number of bytes to read. Overrides `end`.                                 |

MirrorOptions [#mirroroptions]

Options for `drive.mirror()`.

| Property | Type       | Default | Description                                                                              |
| -------- | ---------- | ------- | ---------------------------------------------------------------------------------------- |
| `dryRun` | `boolean`  | `false` | List differences without writing any changes.                                            |
| `prune`  | `boolean`  | `true`  | Remove files in the destination that are not in the source.                              |
| `filter` | `function` | —       | Predicate `(key) => boolean` to include only matching entries.                           |
| `batch`  | `boolean`  | `false` | Use batched writes on a [Hyperdrive](/reference/building-blocks/hyperdrive) destination. |

See also [#see-also]

* [Create a full peer-to-peer filesystem with Hyperdrive](/how-to/stream-and-share-media/create-a-full-peer-to-peer-filesystem-with-hyperdrive)—shows Localdrive mirroring in a full writer/reader flow.
* [Hyperdrive](/reference/building-blocks/hyperdrive)—the distributed filesystem API Localdrive is designed to interoperate with.
* [Mirrordrive](/reference/helpers/mirrordrive)—the sync engine that copies between Localdrive and Hyperdrive.
* [Drives](/reference/tools/drives)—CLI tool that mirrors between local directories and Hyperdrives using the same drive-like interface.
* [Upstream Localdrive repository](https://github.com/holepunchto/localdrive)—source, releases, and implementation details.


# MirrorDrive



<Status level="stable" />

`Mirrordrive` computes diffs between two drive-like APIs and applies them efficiently. It is the helper that powers sync flows between [Hyperdrive](/reference/building-blocks/hyperdrive) and [Localdrive](/reference/helpers/localdrive), including the `drive.mirror(...)` shortcut on Hyperdrive. A `MirrorDrive` instance is itself an async iterable, so iterating it with `for await (const diff of mirror)` drives the diff/copy pass and yields one diff object per entry. For source and release notes, see the [mirror-drive repository](https://github.com/holepunchto/mirror-drive).

Async iteration [#async-iteration]

for await (const diff of mirror) [#for-await-const-diff-of-mirror]

`MirrorDrive` is itself an async iterable. Iterating it with `for await` drives the entire diff/copy pass; each yield produces one `{ op, key, bytesRemoved, bytesAdded }` object where `op` is `'add'`, `'change'`, or `'remove'`, plus `'equal'` when `includeEquals` is set.

```js
for await (const diff of mirror) {
  console.log(diff.op, diff.key)
}
```

Option patterns [#option-patterns]

transformers [#transformers]

[API definition on GitHub](https://github.com/holepunchto/mirror-drive/blob/v1.14.2/index.js#L88)

* Returns: A copy pipeline hook. Each transformer is a function `(key) => stream | null`; returning `null` skips that transform for the current file.
* Example:

```js
const mirror = new MirrorDrive(src, dst, {
  transformers: [
    (key) => key.endsWith('.txt') ? myTransformStream() : null
  ]
})
```

entries [#entries]

[API definition on GitHub](https://github.com/holepunchto/mirror-drive/blob/v1.14.2/index.js#L87)

* Returns: A fixed list of entries to mirror instead of reading them from `src.list(...)`. When this option is used, `prefix` is ignored.
* Example:

```js
const entries = [{ key: '/index.html' }, { key: '/styles.css' }]
const mirror = new MirrorDrive(src, dst, { entries })
```

metadataEquals [#metadataequals]

[API definition on GitHub](https://github.com/holepunchto/mirror-drive/blob/v1.14.2/index.js#L85)

* Returns: A predicate used to decide whether metadata changes should count as a diff when both drives support metadata.
* Example:

```js
const mirror = new MirrorDrive(src, dst, {
  metadataEquals(left, right) {
    return JSON.stringify(left) === JSON.stringify(right)
  }
})
```

Install [#install]

```sh
npm i mirror-drive
```

Quickstart [#quickstart]

```js
import Corestore from 'corestore'
import Hyperdrive from 'hyperdrive'
import Localdrive from 'localdrive'
import MirrorDrive from 'mirror-drive'

const store = new Corestore('./storage')
const src = new Localdrive('./site')
const dst = new Hyperdrive(store)

await dst.ready()

const mirror = new MirrorDrive(src, dst, { prune: true })

for await (const diff of mirror) {
  console.log(diff)
}
```

API Reference [#api-reference]

Constructor and lifecycle [#constructor-and-lifecycle]

new MirrorDrive(src, dst, [options]) [#new-mirrordrivesrc-dst-options]

[src](https://github.com/holepunchto/mirror-drive/blob/v1.14.2/index.js#L72)

Creates a mirror instance to efficiently move `src` drive into `dst` drive.

| Parameter | Type                                                              | Default | Description                                         |
| --------- | ----------------------------------------------------------------- | ------- | --------------------------------------------------- |
| `src`     | [`Hyperdrive\|Localdrive`](/reference/building-blocks/hyperdrive) | —       | Source drive to read from.                          |
| `dst`     | [`Hyperdrive\|Localdrive`](/reference/building-blocks/hyperdrive) | —       | Destination drive to write into (must be writable). |
| `options` | [`MirrorDriveOptions`](#mirrordriveoptions)                       | `{}`    | Mirror options.                                     |

await mirror.done() [#await-mirrordone]

[src](https://github.com/holepunchto/mirror-drive/blob/v1.14.2/index.js#L131)

It starts processing all the diffing until is done.

* Returns: [`Promise<void>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) — Resolves when all diffs have been processed.

```js
const mirror = new MirrorDrive(src, dst)
await mirror.done()
console.log(mirror.count) // { files: 3, add: 2, remove: 0, change: 1 }
```

Mirror state [#mirror-state]

mirror.count [#mirrorcount]

[src](https://github.com/holepunchto/mirror-drive/blob/v1.14.2/index.js#L90)

It counts the total files proccessed, added, removed, and changed.

* Returns: `{ files: number, add: number, remove: number, change: number }`

mirror.bytesAdded [#mirrorbytesadded]

[src](https://github.com/holepunchto/mirror-drive/blob/v1.14.2/index.js#L92)

The total number of bytes copied into the destination so far.

* Returns: `number`

mirror.bytesRemoved [#mirrorbytesremoved]

[src](https://github.com/holepunchto/mirror-drive/blob/v1.14.2/index.js#L91)

The total number of bytes removed from the destination so far.

* Returns: `number`

mirror.finished [#mirrorfinished]

[src](https://github.com/holepunchto/mirror-drive/blob/v1.14.2/index.js#L94)

`true` once the mirror pass has completed.

* Returns: `boolean`

mirror.preloaded [#mirrorpreloaded]

[src](https://github.com/holepunchto/mirror-drive/blob/v1.14.2/index.js#L81)

`true` once any configured preload phase has fetched the block maps it needs and estimated its download size. The blob ranges themselves may still be downloading.

* Returns: `boolean`

mirror.peers [#mirrorpeers]

[src](https://github.com/holepunchto/mirror-drive/blob/v1.14.2/index.js#L113)

The source drive's current peer list when `src.core` exists, otherwise an empty array.

* Returns: [`Array<object>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)

mirror.downloadProgress [#mirrordownloadprogress]

[src](https://github.com/holepunchto/mirror-drive/blob/v1.14.2/index.js#L117)

A `0..1` estimate of preload/download progress when progress tracking is enabled.

* Returns: `number`

mirror.downloadedBlocks [#mirrordownloadedblocks]

[src](https://github.com/holepunchto/mirror-drive/blob/v1.14.2/index.js#L96)

The number of blob blocks downloaded from the source during the current run.

* Returns: `number`

mirror.downloadedBytes [#mirrordownloadedbytes]

[src](https://github.com/holepunchto/mirror-drive/blob/v1.14.2/index.js#L98)

The number of blob bytes downloaded from the source during the current run.

* Returns: `number`

mirror.uploadedBlocks [#mirroruploadedblocks]

[src](https://github.com/holepunchto/mirror-drive/blob/v1.14.2/index.js#L101)

The number of blob blocks the source drive's blob core has uploaded to its peers during the current run.

* Returns: `number`

mirror.uploadedBytes [#mirroruploadedbytes]

[src](https://github.com/holepunchto/mirror-drive/blob/v1.14.2/index.js#L102)

The number of blob bytes the source drive's blob core has uploaded to its peers during the current run.

* Returns: `number`

Monitoring progress [#monitoring-progress]

mirror.monitor(opts) [#mirrormonitoropts]

[src](https://github.com/holepunchto/mirror-drive/blob/v1.14.2/index.js#L124)

A monitor object that emits progress updates and exposes the latest `stats` snapshot. Requires a source drive that exposes `getBlobs`; iterating the mirror throws otherwise.

| Parameter | Type                                | Description      |
| --------- | ----------------------------------- | ---------------- |
| `opts`    | [`MonitorOptions`](#monitoroptions) | Monitor options. |

* Returns: [`Monitor`](/reference/helpers/mirrordrive) — A new monitor instance attached to this mirror.

```js
const monitor = mirror.monitor({ interval: 500 })
monitor.on('update', (stats) => {
  console.log('downloaded', stats.download.bytes, 'bytes')
})
```

monitor.stats [#monitorstats]

[src](https://github.com/holepunchto/mirror-drive/blob/v1.14.2/index.js#L19)

* Returns: The most recent immutable stats snapshot, shaped like:
  `{
    peers,
    download: { bytes, blocks, speed, progress },
    upload: { bytes, blocks, speed }
  }`

monitor.preloaded [#monitorpreloaded]

[src](https://github.com/holepunchto/mirror-drive/blob/v1.14.2/index.js#L25)

monitor.destroyed [#monitordestroyed]

[src](https://github.com/holepunchto/mirror-drive/blob/v1.14.2/index.js#L29)

* Returns: `true` after the monitor has been torn down.

monitor.destroy() [#monitordestroy]

[src](https://github.com/holepunchto/mirror-drive/blob/v1.14.2/index.js#L55)

Stops update polling and detaches the monitor from the mirror.

monitor.on('update', stats) [#monitoronupdate-stats]

[src](https://github.com/holepunchto/mirror-drive/blob/v1.14.2/index.js#L52)

Emitted every `interval` milliseconds with the latest `monitor.stats` snapshot.

monitor.on('preloaded', listener) [#monitoronpreloaded-listener]

[src](https://github.com/holepunchto/mirror-drive/blob/v1.14.2/index.js#L187)

Emitted once preload has completed.

monitor.on('destroy', listener) [#monitorondestroy-listener]

[src](https://github.com/holepunchto/mirror-drive/blob/v1.14.2/index.js#L67)

Emitted when `monitor.destroy()` runs or when the parent mirror finishes and cleans up remaining monitors.

Types [#types]

MirrorDriveOptions [#mirrordriveoptions]

Options for controlling how `MirrorDrive` synchronises drives.

| Property         | Type                                                                                                                        | Default | Description                                                                                                                    |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `prefix`         | [`string\|Array<string>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)           | `'/'`   | One or more path prefixes to mirror. When an array, each prefix is mirrored in order.                                          |
| `dryRun`         | `boolean`                                                                                                                   | `false` | Walk the diff and emit events without writing any changes to `dst`.                                                            |
| `prune`          | `boolean`                                                                                                                   | `true`  | Remove files from `dst` that no longer exist in `src`.                                                                         |
| `includeEquals`  | `boolean`                                                                                                                   | `false` | Emit `{ op: 'equal' }` events for files that are identical in both drives.                                                     |
| `filter`         | `function(string): boolean`                                                                                                 | —       | Called with each source key; return `false` to skip that entry.                                                                |
| `metadataEquals` | `function(*,*): boolean`                                                                                                    | —       | Custom equality check for file metadata; receives `(srcMetadata, dstMetadata)`.                                                |
| `batch`          | `boolean`                                                                                                                   | `false` | Accumulate destination writes in a single batch and flush at the end.                                                          |
| `entries`        | [`Array<object>\|null`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)             | `null`  | Pre-computed list of source entries to mirror; when provided, `prefix` is ignored.                                             |
| `ignore`         | [`string\|Array<string>\|function`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) | —       | Paths to exclude from both drives' listings; ignored paths in `dst` are therefore never pruned.                                |
| `transformers`   | [`Array<function>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)                 | `[]`    | Array of factory functions `(key) => stream \| null`; each returned stream is piped between source read and destination write. |
| `progress`       | `boolean`                                                                                                                   | `false` | Enable download/upload progress tracking (requires `src.getBlobs`).                                                            |
| `dedup`          | `boolean`                                                                                                                   | `false` | Enable content-addressed deduplication using Rabin chunking on the destination.                                                |

MonitorOptions [#monitoroptions]

Options for the `monitor()` method.

| Property   | Type     | Default | Description                                                                     |
| ---------- | -------- | ------- | ------------------------------------------------------------------------------- |
| `interval` | `number` | `250`   | How often (in milliseconds) the monitor emits `update` events with fresh stats. |

See also [#see-also]

* [Create a full peer-to-peer filesystem with Hyperdrive](/how-to/stream-and-share-media/create-a-full-peer-to-peer-filesystem-with-hyperdrive)—end-to-end workflow that mirrors between Localdrive and Hyperdrive.
* [Hyperdrive](/reference/building-blocks/hyperdrive)—exposes `drive.mirror(...)` and is the canonical distributed destination/source for Mirrordrive.
* [Localdrive](/reference/helpers/localdrive)—the local filesystem companion API most often paired with Mirrordrive.
* [Drives](/reference/tools/drives)—CLI tool whose `drives mirror` command is powered by the same sync logic.
* [Upstream mirror-drive repository](https://github.com/holepunchto/mirror-drive)—source, releases, and implementation details.


# Protomux



<Status level="stable" />

`Protomux` multiplexes multiple message-oriented subprotocols over one framed stream. It is typically layered on top of [Secretstream](/reference/helpers/secretstream) and uses [Compact encoding](/reference/helpers/compact-encoding) for message schemas. For source and releases, see the [Protomux repository](https://github.com/holepunchto/protomux).

Install [#install]

```sh
npm i protomux
```

Quickstart [#quickstart]

```js
import Protomux from 'protomux'
import cenc from 'compact-encoding'

const mux = new Protomux(aFramedEncryptedStream)

const channel = mux.createChannel({
  protocol: 'chat',
  onopen() {
    console.log('chat channel opened')
  }
})

const message = channel.addMessage({
  encoding: cenc.string,
  onmessage(text) {
    console.log(text)
  }
})

channel.open()
message.send('hello')
```

API Reference [#api-reference]

Constructor and mux helpers [#constructor-and-mux-helpers]

mux = new Protomux(stream, [options]) [#mux--new-protomuxstream-options]

[src](https://github.com/holepunchto/protomux/blob/v3.11.0/index.js#L331)

Make a new instance. `stream` should be a framed stream, preserving the messages written.

| Parameter | Type                                  | Default | Description                                                                 |
| --------- | ------------------------------------- | ------- | --------------------------------------------------------------------------- |
| `stream`  | `object`                              | —       | —                                                                           |
| `options` | [`ProtomuxOptions`](#protomuxoptions) | `{}`    | Optional configuration for the instance, such as a custom buffer allocator. |

```js
{
  // Called when the muxer wants to allocate a message that is written.
  // Defaults to the stream's own alloc method when it has one, otherwise Buffer.allocUnsafe.
  alloc (size) {}
}
```

mux = Protomux.from(stream | muxer, [options]) [#mux--protomuxfromstream--muxer-options]

[src](https://github.com/holepunchto/protomux/blob/v3.11.0/index.js#L365)

Helper to accept either an existing muxer instance or a stream (which creates a new one).

| Parameter | Type                                  | Description                                                  |
| --------- | ------------------------------------- | ------------------------------------------------------------ |
| `stream`  | `object`                              | A framed stream or an existing Protomux instance.            |
| `opts`    | [`ProtomuxOptions`](#protomuxoptions) | Muxer options passed through when a new instance is created. |

* Returns: [`Protomux`](/reference/helpers/protomux) — The existing or newly created Protomux instance.

```js
const mux = Protomux.from(someStream)
```

Protomux.isProtomux(mux) [#protomuxisprotomuxmux]

[src](https://github.com/holepunchto/protomux/blob/v3.11.0/index.js#L371)

Returns `true` when `value` looks like a Protomux instance.

| Parameter | Type     | Description    |
| --------- | -------- | -------------- |
| `mux`     | `object` | Value to test. |

* Returns: `boolean` — `true` when `mux` is a Protomux instance.

```js
Protomux.isProtomux(mux) // true
Protomux.isProtomux({})  // false
```

mux.cork() [#muxcork]

[src](https://github.com/holepunchto/protomux/blob/v3.11.0/index.js#L385)

Same as `channel.cork` but on the muxer instance.

* Returns: `void`

```js
mux.cork()
channelA.messages[0].send('hello')
channelB.messages[0].send('world')
mux.uncork() // sends both as one frame
```

mux.uncork() [#muxuncork]

[src](https://github.com/holepunchto/protomux/blob/v3.11.0/index.js#L392)

Same as `channel.uncork` but on the muxer instance.

* Returns: `void`

```js
mux.cork()
msg.send('hello')
mux.uncork()
```

mux.isIdle() [#muxisidle]

[src](https://github.com/holepunchto/protomux/blob/v3.11.0/index.js#L381)

Convenience method that returns true when no channels are open and no closed channel is still awaiting the remote's acknowledgement.

* Returns: `boolean` — `true` when the muxer has no open channels and none awaiting a remote close acknowledgement.

```js
if (mux.isIdle()) console.log('no open channels')
```

for (const channel of muxer) { ... } [#for-const-channel-of-muxer---]

The muxer instance is iterable, so you can iterate over all the channels.

Pairing and channel discovery [#pairing-and-channel-discovery]

mux.pair({ protocol, id }, callback) [#muxpair-protocol-id--callback]

[src](https://github.com/holepunchto/protomux/blob/v3.11.0/index.js#L407)

Register a callback to be called everytime a new channel is requested.

| Parameter | Type                        | Description                                                                              |
| --------- | --------------------------- | ---------------------------------------------------------------------------------------- |
| `options` | [`ChannelKey`](#channelkey) | Protocol name and optional binary id to match.                                           |
| `notify`  | `Function`                  | Async callback called with the channel's binary id when a matching remote channel opens. |

* Returns: `void`

```js
mux.pair({ protocol: 'my-protocol' }, async (id) => {
  const channel = mux.createChannel({ protocol: 'my-protocol' })
  channel.open()
})
```

mux.unpair({ protocol, id }) [#muxunpair-protocol-id-]

[src](https://github.com/holepunchto/protomux/blob/v3.11.0/index.js#L411)

Unregisters the pair callback.

| Parameter | Type                        | Description                                         |
| --------- | --------------------------- | --------------------------------------------------- |
| `options` | [`ChannelKey`](#channelkey) | Protocol name and optional binary id to deregister. |

* Returns: `void`

```js
mux.unpair({ protocol: 'my-protocol' })
```

mux.opened({ protocol, id }) [#muxopened-protocol-id-]

[src](https://github.com/holepunchto/protomux/blob/v3.11.0/index.js#L415)

Boolean that indicates if the channel is opened.

| Parameter | Type                        | Description                                    |
| --------- | --------------------------- | ---------------------------------------------- |
| `options` | [`ChannelKey`](#channelkey) | Protocol name and optional binary id to check. |

* Returns: `boolean` — `true` when one or more matching channels are open.

```js
if (mux.opened({ protocol: 'my-protocol' })) {
  console.log('already open')
}
```

mux.getLastChannel(options) [#muxgetlastchanneloptions]

[src](https://github.com/holepunchto/protomux/blob/v3.11.0/index.js#L400)

Returns the channel that most recently opened. Returns `null` once that channel closes, even if older channels with the same protocol and id are still open.

| Parameter | Type                        | Description                           |
| --------- | --------------------------- | ------------------------------------- |
| `options` | [`ChannelKey`](#channelkey) | Protocol name and optional binary id. |

* Returns: [`Channel\|null`](/reference/helpers/protomux) — The most recently opened matching channel, or `null`.

```js
const ch = mux.getLastChannel({ protocol: 'my-protocol' })
```

Creating channels [#creating-channels]

mux.createChannel(opts) [#muxcreatechannelopts]

[src](https://github.com/holepunchto/protomux/blob/v3.11.0/index.js#L421)

Add a new protocol channel.

| Parameter | Type                                            | Description               |
| --------- | ----------------------------------------------- | ------------------------- |
| `opts`    | [`CreateChannelOptions`](#createchanneloptions) | Channel creation options. |

* Returns: [`Channel\|null`](/reference/helpers/protomux) — The new channel, or `null` if it cannot be opened.

Mux properties [#mux-properties]

mux.stream [#muxstream]

[src](https://github.com/holepunchto/protomux/blob/v3.11.0/index.js#L335)

The framed transport stream backing this mux.

* Returns: `object`

mux.drained [#muxdrained]

[src](https://github.com/holepunchto/protomux/blob/v3.11.0/index.js#L337)

The current writable backpressure state from the underlying stream.

* Returns: `boolean`

Channel lifecycle [#channel-lifecycle]

channel.open([handshake]) [#channelopenhandshake]

[src](https://github.com/holepunchto/protomux/blob/v3.11.0/index.js#L87)

Open the channel.

| Parameter   | Type | Description                                                                               |
| ----------- | ---- | ----------------------------------------------------------------------------------------- |
| `handshake` | `*`  | Optional handshake value encoded with the handshake encoding provided to `createChannel`. |

* Returns: `void`

```js
const channel = mux.createChannel({ protocol: 'my-protocol' })
channel.open()
```

channel.fullyOpened() [#channelfullyopened]

[src](https://github.com/holepunchto/protomux/blob/v3.11.0/index.js#L66)

Resolves to `true` when the channel fully opens or `false` if it closes first.

* Returns: [`Promise<boolean>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)

```js
const opened = await channel.fullyOpened()
if (opened) console.log('channel is open')
```

channel.fullyClosed() [#channelfullyclosed]

[src](https://github.com/holepunchto/protomux/blob/v3.11.0/index.js#L77)

Resolves once the channel has been destroyed and all pending async handlers have finished.

* Returns: [`Promise<void>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)

```js
await channel.fullyClosed()
console.log('channel destroyed')
```

channel.close() [#channelclose]

[src](https://github.com/holepunchto/protomux/blob/v3.11.0/index.js#L242)

Closes the protocol channel.

* Returns: `void`

```js
channel.close()
```

channel.cork() [#channelcork]

[src](https://github.com/holepunchto/protomux/blob/v3.11.0/index.js#L234)

Corking the protocol channel, makes it buffer messages and send them all in a batch when it uncorks.

* Returns: `void`

```js
channel.cork()
one.send('hello')
two.send(true)
channel.uncork() // sends both as a single batch
```

channel.uncork() [#channeluncork]

[src](https://github.com/holepunchto/protomux/blob/v3.11.0/index.js#L238)

Uncork and send the batch.

* Returns: `void`

```js
channel.cork()
one.send('hello')
channel.uncork()
```

Registering and sending messages [#registering-and-sending-messages]

channel.addMessage(opts) [#channeladdmessageopts]

[src](https://github.com/holepunchto/protomux/blob/v3.11.0/index.js#L259)

Add/register a message type for a certain encoding. Options include:

| Parameter | Type                                      | Description                                               |
| --------- | ----------------------------------------- | --------------------------------------------------------- |
| `opts`    | [`AddMessageOptions`](#addmessageoptions) | Message options including encoding and onmessage handler. |

* Returns: `object` — Message object with a `send(data)` method for sending encoded messages.

m.send(data) [#msenddata]

Send a message.

m.encoding [#mencoding]

The encoding for this message.

m.onmessage [#monmessage]

Function that is called when a message arrives.

Channel properties [#channel-properties]

channel.userData [#channeluserdata]

[src](https://github.com/holepunchto/protomux/blob/v3.11.0/index.js#L26)

* Returns: The arbitrary metadata value passed to `mux.createChannel(...)`.

channel.protocol [#channelprotocol]

[src](https://github.com/holepunchto/protomux/blob/v3.11.0/index.js#L27)

* Returns: The channel protocol name.

channel.aliases [#channelaliases]

[src](https://github.com/holepunchto/protomux/blob/v3.11.0/index.js#L28)

* Returns: The list of alternate protocol names registered for this channel family.

channel.id [#channelid]

[src](https://github.com/holepunchto/protomux/blob/v3.11.0/index.js#L29)

* Returns: The optional binary identifier distinguishing this channel family.

channel.handshake [#channelhandshake]

[src](https://github.com/holepunchto/protomux/blob/v3.11.0/index.js#L30)

* Returns: The decoded handshake payload after the channel fully opens, or `null` when no handshake encoder was configured.

channel.messages [#channelmessages]

[src](https://github.com/holepunchto/protomux/blob/v3.11.0/index.js#L31)

* Returns: The array of registered message descriptors in type order.

channel.opened [#channelopened]

[src](https://github.com/holepunchto/protomux/blob/v3.11.0/index.js#L33)

channel.closed [#channelclosed]

[src](https://github.com/holepunchto/protomux/blob/v3.11.0/index.js#L34)

* Returns: `true` after either side closes the channel.

channel.destroyed [#channeldestroyed]

[src](https://github.com/holepunchto/protomux/blob/v3.11.0/index.js#L35)

* Returns: `true` after the close lifecycle and pending handlers have fully drained.

channel.drained [#channeldrained]

[src](https://github.com/holepunchto/protomux/blob/v3.11.0/index.js#L62)

`true` when the underlying stream's write buffer is empty.

* Returns: `boolean`

Lifecycle callbacks [#lifecycle-callbacks]

channel.onopen [#channelonopen]

[src](https://github.com/holepunchto/protomux/blob/v3.11.0/index.js#L37)

* Returns: Called when the channel opens. `handshake` is the decoded open payload or `null`, and `channel` is the channel instance.

channel.onclose [#channelonclose]

[src](https://github.com/holepunchto/protomux/blob/v3.11.0/index.js#L38)

* Returns: Called when the channel closes. `isRemote` is `true` when the remote side initiated the close, and `channel` is the channel instance.

channel.ondestroy [#channelondestroy]

[src](https://github.com/holepunchto/protomux/blob/v3.11.0/index.js#L39)

* Returns: Called when the channel is destroyed. `channel` is the destroyed channel instance.

channel.ondrain [#channelondrain]

[src](https://github.com/holepunchto/protomux/blob/v3.11.0/index.js#L40)

* Returns: Called when the channel's underlying mux becomes writable again. `channel` is that channel instance.

Types [#types]

ProtomuxOptions [#protomuxoptions]

Options for allocating buffers in a Protomux instance.

| Property | Type       | Default | Description                                                                                                                                                     |
| -------- | ---------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `alloc`  | `Function` | —       | Custom allocator; called with `(size)` and must return a `Buffer`. Defaults to the stream's own `alloc` method when it has one, otherwise `Buffer.allocUnsafe`. |

CreateChannelOptions [#createchanneloptions]

Options for creating a protocol channel.

| Property    | Type                                                                                                      | Default | Description                                                                              |
| ----------- | --------------------------------------------------------------------------------------------------------- | ------- | ---------------------------------------------------------------------------------------- |
| `protocol`  | `string`                                                                                                  | —       | Protocol name used to match channels between peers.                                      |
| `id`        | [`Buffer\|null`](https://nodejs.org/api/buffer.html#class-buffer)                                         | `null`  | Optional binary identifier to distinguish multiple channels with the same protocol name. |
| `handshake` | `*`                                                                                                       | `null`  | Compact-encoding codec for encoding/decoding the handshake value exchanged on open.      |
| `messages`  | [`Array<AddMessageOptions>`](#addmessageoptions)                                                          | `[]`    | Array of message descriptors registered when the channel is created.                     |
| `unique`    | `boolean`                                                                                                 | `true`  | When `true`, returns `null` if a channel with this protocol+id is already open.          |
| `aliases`   | [`Array<string>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) | `[]`    | Alternative protocol names that also match this channel.                                 |
| `userData`  | `*`                                                                                                       | `null`  | Arbitrary value stored as `channel.userData`; not transmitted.                           |
| `onopen`    | `Function`                                                                                                | —       | Called with `(handshake, channel)` when the remote side opens this protocol.             |
| `onclose`   | `Function`                                                                                                | —       | Called with `(isRemote, channel)` when either side closes the channel.                   |
| `ondestroy` | `Function`                                                                                                | —       | Called with `(channel)` after `onclose` resolves and all pending promises settle.        |
| `ondrain`   | `Function`                                                                                                | —       | Called with `(channel)` when the underlying stream drains.                               |

AddMessageOptions [#addmessageoptions]

Options for registering a message type on a channel.

| Property    | Type       | Default | Description                                                                    |
| ----------- | ---------- | ------- | ------------------------------------------------------------------------------ |
| `encoding`  | `object`   | —       | A compact-encoding codec. Defaults to raw binary (`c.raw`).                    |
| `autoBatch` | `boolean`  | `true`  | When `true`, batch replies are collected before the next tick.                 |
| `onmessage` | `Function` | —       | Called with `(message, channel)` when the remote sends a message of this type. |

ChannelKey [#channelkey]

Protocol + id selector used by pair/unpair/opened/getLastChannel.

| Property   | Type                                                              | Default | Description                                                                                                                                                                                                   |
| ---------- | ----------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `protocol` | `string`                                                          | —       | Protocol name to match.                                                                                                                                                                                       |
| `id`       | [`Buffer\|null`](https://nodejs.org/api/buffer.html#class-buffer) | `null`  | Optional binary id, combined with `protocol` into an exact key. `opened` and `getLastChannel` only match channels created with the same id; a protocol-only `pair` registration matches channels with any id. |

See also [#see-also]

* [Secretstream](/reference/helpers/secretstream)—the encrypted framed stream most commonly used underneath Protomux.
* [Compact encoding](/reference/helpers/compact-encoding)—the schema toolkit Protomux uses for handshakes and message payloads.
* [Hyperswarm](/reference/building-blocks/hyperswarm)—common peer-transport entry point before you layer on Secretstream and Protomux.
* [Upstream Protomux repository](https://github.com/holepunchto/protomux)—source, releases, and implementation details.


# NoiseSecretStream



<Status level="stable" />

`Secretstream` wraps a transport stream in a Noise handshake plus libsodium `secretstream` encryption. It is the encrypted stream layer used underneath [Hyperswarm](/reference/building-blocks/hyperswarm) and related peer transports. For the upstream package, source, and release notes, see the [@hyperswarm/secret-stream repository](https://github.com/holepunchto/hyperswarm-secret-stream).

Install [#install]

```sh
npm i @hyperswarm/secret-stream
```

Quickstart [#quickstart]

```js
import SecretStream from '@hyperswarm/secret-stream'

const a = new SecretStream(true)
const b = new SecretStream(false)

a.rawStream.pipe(b.rawStream).pipe(a.rawStream)

a.write(Buffer.from('hello encrypted world'))

b.on('data', (data) => {
  console.log(data.toString())
})
```

API Reference [#api-reference]

Constructor and lifecycle [#constructor-and-lifecycle]

new SecretStream(isInitiator, [rawStream], [options]) [#new-secretstreamisinitiator-rawstream-options]

[src](https://github.com/holepunchto/hyperswarm-secret-stream/blob/v6.9.1/index.js#L16)

Make a new stream. `isInitiator` is a boolean indication whether you are the client or the server. `rawStream` can be set to an underlying transport stream you want to run the noise stream over.

| Parameter     | Type                                          | Default |
| ------------- | --------------------------------------------- | ------- |
| `isInitiator` | `boolean`                                     | —       |
| `rawStream`   | `object`                                      | —       |
| `options`     | [`SecretStreamOptions`](#secretstreamoptions) | `{}`    |

* Throws: if `isInitiator` is not a boolean.

s.start(rawStream, [options]) [#sstartrawstream-options]

[src](https://github.com/holepunchto/hyperswarm-secret-stream/blob/v6.9.1/index.js#L123)

Start a SecretStream from a rawStream asynchrously.

| Parameter   | Type                                          | Default | Description                                                                                            |
| ----------- | --------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------ |
| `rawStream` | `object`                                      | —       | The underlying transport stream. If omitted, an internal stream is created and exposed as `rawStream`. |
| `options`   | [`SecretStreamOptions`](#secretstreamoptions) | `{}`    | Stream options (the same shape as the constructor's).                                                  |

* Returns: `void`

```js
const s = new SecretStream(true, null, {
  autoStart: false // call start manually
})

// ... do async stuff or destroy the stream

s.start(rawStream, {
  ... options from above
})
```

await s.flush() [#await-sflush]

[src](https://github.com/holepunchto/hyperswarm-secret-stream/blob/v6.9.1/index.js#L155)

Resolves to `true` when pending encrypted writes and the underlying raw stream have flushed successfully, or `false` if the stream closed before that happened.

* Returns: [`Promise<boolean>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) — `true` once flushed, or `false` if the stream never opened or was destroyed first.

```js
await stream.flush()
```

Stream configuration [#stream-configuration]

s.setTimeout(ms) [#ssettimeoutms]

[src](https://github.com/holepunchto/hyperswarm-secret-stream/blob/v6.9.1/index.js#L93)

Set the stream timeout. If no data is received within a `ms` window, the stream is auto destroyed.

| Parameter | Type     | Description                                       |
| --------- | -------- | ------------------------------------------------- |
| `ms`      | `number` | The idle timeout in milliseconds (0 disables it). |

* Returns: `void`

```js
stream.setTimeout(15000)
```

s.setKeepAlive(ms) [#ssetkeepalivems]

[src](https://github.com/holepunchto/hyperswarm-secret-stream/blob/v6.9.1/index.js#L105)

Send a heartbeat (empty message) every time the socket is idle for `ms` milliseconds. Note: If one side calls `s.setKeepAlive()` and the other does not, then the empty messages will be passed through to the piped stream.

| Parameter | Type     | Description                                              |
| --------- | -------- | -------------------------------------------------------- |
| `ms`      | `number` | The keep-alive interval in milliseconds (0 disables it). |

* Returns: `void`

```js
stream.setKeepAlive(5000)
```

s.sendKeepAlive() [#ssendkeepalive]

[src](https://github.com/holepunchto/hyperswarm-secret-stream/blob/v6.9.1/index.js#L118)

A convenience method that sends an empty message.

* Returns: `void`

```js
stream.sendKeepAlive()
```

Ordered stream I/O [#ordered-stream-io]

s.write(data) [#swritedata]

Writes an ordered payload to be encrypted and sent through the duplex stream, returning the usual writable-stream backpressure boolean.

s.end() [#send]

Ends the stream, optionally writing a final ordered payload, following standard writable-stream behavior.

s.on('data', listener) [#sondata-listener]

Receives ordered decrypted payloads as `Buffer` instances.

Unordered messages [#unordered-messages]

await s.send(buffer) [#await-ssendbuffer]

[src](https://github.com/holepunchto/hyperswarm-secret-stream/blob/v6.9.1/index.js#L564)

Sends an encrypted unordered message, see [udx-native](https://github.com/holepunchto/udx-native/tree/main?tab=readme-ov-file#await-streamsendbuffer) for details. This method silently fails if called before the handshake is complete, or if the underlying `rawStream` is not a UDX stream (not capable of UDP).

| Parameter | Type                                                        | Description                      |
| --------- | ----------------------------------------------------------- | -------------------------------- |
| `buffer`  | [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer) | The message to encrypt and send. |

* Returns: [`Promise<void>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) — Resolves once the message has been sent.

```js
await stream.send(Buffer.from('ping'))
```

s.trySend(buffer) [#strysendbuffer]

[src](https://github.com/holepunchto/hyperswarm-secret-stream/blob/v6.9.1/index.js#L572)

Same as `send(buffer)` but does not return a promise.

| Parameter | Type                                                        | Description                      |
| --------- | ----------------------------------------------------------- | -------------------------------- |
| `buffer`  | [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer) | The message to encrypt and send. |

* Returns: `void`

```js
stream.trySend(Buffer.from('ping'))
```

s.on('message', onmessage) [#sonmessage-onmessage]

[src](https://github.com/holepunchto/hyperswarm-secret-stream/blob/v6.9.1/index.js#L600)

Emmitted when an unordered message is received

Utility methods [#utility-methods]

s.alloc(len) [#salloclen]

[src](https://github.com/holepunchto/hyperswarm-secret-stream/blob/v6.9.1/index.js#L603)

Returns a writable payload slice backed by a preallocated encrypted output buffer. Write into it, then pass it to `stream.write(...)`.

| Parameter | Type     | Description                                |
| --------- | -------- | ------------------------------------------ |
| `len`     | `number` | The number of plaintext bytes to allocate. |

* Returns: [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer) — A writable buffer of `len` bytes to fill and then `write()`.

```js
const buf = stream.alloc(4)
buf.write('ping')
stream.write(buf)
```

s.toJSON() [#stojson]

[src](https://github.com/holepunchto/hyperswarm-secret-stream/blob/v6.9.1/index.js#L610)

Returns a diagnostic object containing connection state, keys, and any serializable raw-stream metadata.

* Returns: `object` — A snapshot with `isInitiator`, `publicKey`, `remotePublicKey`, `connected`, `destroying`, `destroyed`, and `rawStream`.

```js
console.log(JSON.stringify(stream))
```

Static helpers [#static-helpers]

keyPair = SecretStream.keyPair([seed]) [#keypair--secretstreamkeypairseed]

Generate a ed25519 key pair.

NoiseSecretStream.id(handshakeHash, isInitiator, id) [#noisesecretstreamidhandshakehash-isinitiator-id]

[src](https://github.com/holepunchto/hyperswarm-secret-stream/blob/v6.9.1/index.js#L89)

Derives a 32-byte stream identity from the completed handshake hash, choosing the initiator/responder namespace via `isInitiator`.

| Parameter       | Type                                                        | Description                                                                        |
| --------------- | ----------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `handshakeHash` | [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer) | The handshake hash to derive the id from.                                          |
| `isInitiator`   | `boolean`                                                   | Whether to derive the initiator's id (`true`) or the responder's (`false`).        |
| `id`            | [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer) | Optional 32-byte buffer to write the id into; a new one is allocated when omitted. |

* Returns: [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer) — The 32-byte stream id.

```js
const id = SecretStream.id(stream.handshakeHash, stream.isInitiator)
```

Public properties [#public-properties]

s.isInitiator [#sisinitiator]

[src](https://github.com/holepunchto/hyperswarm-secret-stream/blob/v6.9.1/index.js#L24)

`true` on the dialing side and `false` on the accepting side.

* Returns: `boolean`

s.rawStream [#srawstream]

[src](https://github.com/holepunchto/hyperswarm-secret-stream/blob/v6.9.1/index.js#L25)

The wrapped transport stream, or a bridge stream when no raw stream was supplied up front.

* Returns: `object`

s.publicKey [#spublickey]

[src](https://github.com/holepunchto/hyperswarm-secret-stream/blob/v6.9.1/index.js#L27)

Get the local public key.

* Returns: [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer)

s.remotePublicKey [#sremotepublickey]

[src](https://github.com/holepunchto/hyperswarm-secret-stream/blob/v6.9.1/index.js#L28)

Get the remote's public key. Populated after `open` is emitted.

* Returns: [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer)

s.handshakeHash [#shandshakehash]

[src](https://github.com/holepunchto/hyperswarm-secret-stream/blob/v6.9.1/index.js#L29)

Get the unique hash of this handshake. Populated after `open` is emitted.

* Returns: [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer)

s.connected [#sconnected]

[src](https://github.com/holepunchto/hyperswarm-secret-stream/blob/v6.9.1/index.js#L30)

`true` once the handshake is complete and the stream has emitted `connect`.

* Returns: `boolean`

s.keepAlive [#skeepalive]

[src](https://github.com/holepunchto/hyperswarm-secret-stream/blob/v6.9.1/index.js#L31)

Get the interval (in milliseconds) at which keep-alive messages are sent (0 means none are sent).

* Returns: `number`

s.timeout [#stimeout]

[src](https://github.com/holepunchto/hyperswarm-secret-stream/blob/v6.9.1/index.js#L32)

The configured idle-timeout interval in milliseconds.

* Returns: `number`

s.enableSend [#senablesend]

[src](https://github.com/holepunchto/hyperswarm-secret-stream/blob/v6.9.1/index.js#L33)

`true` when unordered `send(...)` and `trySend(...)` support is enabled.

* Returns: `boolean`

s.opened [#sopened]

[src](https://github.com/holepunchto/hyperswarm-secret-stream/blob/v6.9.1/index.js#L39)

A promise that resolves to `true` when the handshake succeeds, or `false` if the stream closes before opening.

* Returns: [`Promise<boolean>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)

s.rawBytesWritten [#srawbyteswritten]

[src](https://github.com/holepunchto/hyperswarm-secret-stream/blob/v6.9.1/index.js#L43)

The number of bytes (measured after encryption) written.

* Returns: `number`

s.rawBytesRead [#srawbytesread]

[src](https://github.com/holepunchto/hyperswarm-secret-stream/blob/v6.9.1/index.js#L44)

The number of bytes (measured before decryption) received.

* Returns: `number`

s.userData [#suserdata]

[src](https://github.com/holepunchto/hyperswarm-secret-stream/blob/v6.9.1/index.js#L36)

An arbitrary user-controlled field that higher-level protocols often use to attach transport metadata.

* Returns: `*`

Events [#events]

s.on('connect', onconnect) [#sonconnect-onconnect]

[src](https://github.com/holepunchto/hyperswarm-secret-stream/blob/v6.9.1/index.js#L517)

Emitted when the handshake is fully done. It is safe to write to the stream immediately though, as data is buffered internally before the handshake has been completed.

s.on('handshake', listener) [#sonhandshake-listener]

[src](https://github.com/holepunchto/hyperswarm-secret-stream/blob/v6.9.1/index.js#L390)

Fires when the Noise handshake keys and hash have been established.

Types [#types]

Handshake [#handshake]

A precomputed Noise handshake to reuse instead of performing one over the
stream. Pass it as `opts.handshake` to adopt the result of a handshake done
elsewhere.

| Property          | Type                                                        | Default | Description                                 |
| ----------------- | ----------------------------------------------------------- | ------- | ------------------------------------------- |
| `tx`              | [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer) | —       | The transmit (encryption) session key.      |
| `rx`              | [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer) | —       | The receive (decryption) session key.       |
| `hash`            | [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer) | —       | The unique hash of the handshake.           |
| `publicKey`       | [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer) | —       | The local public key used in the handshake. |
| `remotePublicKey` | [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer) | —       | The remote peer's public key.               |

KeyPair [#keypair]

An ed25519 key pair, as produced by \{@link NoiseSecretStream.keyPair}.

| Property    | Type                                                        | Default | Description             |
| ----------- | ----------------------------------------------------------- | ------- | ----------------------- |
| `publicKey` | [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer) | —       | The 32-byte public key. |
| `secretKey` | [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer) | —       | The 64-byte secret key. |

SecretStreamOptions [#secretstreamoptions]

Options for creating a `SecretStream` (also accepted by `start()`).

| Property          | Type                                                        | Default | Description                                                                                                 |
| ----------------- | ----------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------- |
| `pattern`         | `string`                                                    | `XX`    | Which Noise handshake pattern to use.                                                                       |
| `remotePublicKey` | [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer) | —       | The remote peer's public key, set if the handshake pattern requires it.                                     |
| `keyPair`         | [`KeyPair\|Promise<KeyPair>`](#keypair)                     | —       | The local key pair, or a promise resolving to one (the stream waits for it and auto-destroys if it errors). |
| `handshake`       | [`Handshake`](#handshake)                                   | —       | A handshake performed elsewhere to adopt instead of handshaking over the stream.                            |
| `keepAlive`       | `number`                                                    | `0`     | Send a keep-alive (empty message) when idle for this many milliseconds (0 disables).                        |
| `autoStart`       | `boolean`                                                   | `true`  | Start the stream automatically; set false to call `start()` manually.                                       |
| `enableSend`      | `boolean`                                                   | `true`  | (advanced) Set false to disable the unordered send API.                                                     |

See also [#see-also]

* [Hyperswarm](/reference/building-blocks/hyperswarm)—the peer-discovery and connection layer that typically hands sockets to Secretstream.
* [HyperDHT](/reference/building-blocks/hyperdht)—lower-level DHT whose direct keyed connections are also wrapped in Secretstream.
* [Protomux](/reference/helpers/protomux)—multiplex higher-level protocols across one framed encrypted stream.
* [Upstream @hyperswarm/secret-stream repository](https://github.com/holepunchto/hyperswarm-secret-stream)—source, releases, and implementation details.


# Bare modules



Bare modules [#bare-modules]

Pear's native runtime is [Bare](/explanation/bare-runtime)—a small, modular JavaScript runtime for desktop and mobile. The [`Bare` global API](/reference/bare/runtime) is minimal and not intended as a standard library; standard runtime functionality is provided via installable modules prefixed with `bare-`. The modules below are grouped by area; within each group they're ordered roughly from foundational to specialized.

To run a script on Bare directly, see the [`bare` CLI](/reference/bare/cli). To embed a Bare core inside a native app, see [Bare Kit](/reference/bare/bare-kit) and [One core, many platforms](/explanation/bare-on-native).

If you author native addons for Bare, the [Bare native-addon prebuild actions](/reference/ci-and-release/github-actions#bare-native-addon-prebuilds) build and collect prebuilt binaries across platforms in CI.

Stability legend [#stability-legend]

Module lists call out a stability indicator. The four levels:

| Stability                       | Description                                                 |
| ------------------------------- | ----------------------------------------------------------- |
| <Status level="stable" />       | Unlikely to change or be removed in the foreseeable future. |
| <Status level="experimental" /> | New, untested, or has known issues.                         |
| <Status level="deprecated" />   | Being removed or replaced in the future.                    |
| <Status level="unstable" />     | May change or be removed without warning.                   |

Modules & packaging [#modules--packaging]

The module system, bundling, and packaging tools.

| Module                                                                | Description                                                                                                                      | Systems                                                                                                                                                                                                                                                                                                                                                                                                                                       | Stability                 |
| --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- |
| [bare-module](https://github.com/holepunchto/bare-module)             | Module support for JavaScript — [reference](/reference/bare/modules/bare-module)                                                 | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /> <img className="dark:[filter:invert(1)]" src="/android-light.svg" alt="Android" /> <img className="dark:[filter:invert(1)]" src="/ios-light.svg" alt="iOS" /></div> | <Status level="stable" /> |
| [bare-module-lexer](https://github.com/holepunchto/bare-module-lexer) | Heuristic lexer for detecting imports and exports in JavaScript modules — [reference](/reference/bare/modules/bare-module-lexer) | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /> <img className="dark:[filter:invert(1)]" src="/android-light.svg" alt="Android" /> <img className="dark:[filter:invert(1)]" src="/ios-light.svg" alt="iOS" /></div> | <Status level="stable" /> |
| [bare-bundle](https://github.com/holepunchto/bare-bundle)             | Application bundle format for JavaScript — [reference](/reference/bare/modules/bare-bundle)                                      | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /> <img className="dark:[filter:invert(1)]" src="/android-light.svg" alt="Android" /> <img className="dark:[filter:invert(1)]" src="/ios-light.svg" alt="iOS" /></div> | <Status level="stable" /> |
| [bare-bundle-id](https://github.com/holepunchto/bare-bundle-id)       | Construct a unique ID for a bundle — [reference](/reference/bare/modules/bare-bundle-id)                                         | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /> <img className="dark:[filter:invert(1)]" src="/android-light.svg" alt="Android" /> <img className="dark:[filter:invert(1)]" src="/ios-light.svg" alt="iOS" /></div> | <Status level="stable" /> |
| [bare-pack](https://github.com/holepunchto/bare-pack)                 | Bundle packing for Bare—traverse a module graph into an embeddable bundle — [reference](/reference/bare/modules/bare-pack)       | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /> <img className="dark:[filter:invert(1)]" src="/android-light.svg" alt="Android" /> <img className="dark:[filter:invert(1)]" src="/ios-light.svg" alt="iOS" /></div> | <Status level="stable" /> |
| [bare-unpack](https://github.com/holepunchto/bare-unpack)             | Bundle unpacking for Bare                                                                                                        | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /> <img className="dark:[filter:invert(1)]" src="/android-light.svg" alt="Android" /> <img className="dark:[filter:invert(1)]" src="/ios-light.svg" alt="iOS" /></div> | <Status level="stable" /> |
| [bare-make](https://github.com/holepunchto/bare-make)                 | Opinionated CMake-based build system generator for native addons — [reference](/reference/bare/modules/bare-make)                | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /></div>                                                                                                                                                               | <Status level="stable" /> |
| [bare-build](https://github.com/holepunchto/bare-build)               | Package a Bare app as native bundles or standalone executables                                                                   | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /> <img className="dark:[filter:invert(1)]" src="/android-light.svg" alt="Android" /> <img className="dark:[filter:invert(1)]" src="/ios-light.svg" alt="iOS" /></div> | <Status level="stable" /> |
| [bare-runtime](https://github.com/holepunchto/bare-runtime)           | Prebuilt Bare binaries for macOS, iOS, Linux, Android, and Windows                                                               | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /> <img className="dark:[filter:invert(1)]" src="/android-light.svg" alt="Android" /> <img className="dark:[filter:invert(1)]" src="/ios-light.svg" alt="iOS" /></div> | <Status level="stable" /> |
| [bare-semver](https://github.com/holepunchto/bare-semver)             | Minimal semantic versioning library for Bare — [reference](/reference/bare/modules/bare-semver)                                  | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /> <img className="dark:[filter:invert(1)]" src="/android-light.svg" alt="Android" /> <img className="dark:[filter:invert(1)]" src="/ios-light.svg" alt="iOS" /></div> | <Status level="stable" /> |
| [bare-realm](https://github.com/holepunchto/bare-realm)               | Realm support for Bare — [reference](/reference/bare/modules/bare-realm)                                                         | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /> <img className="dark:[filter:invert(1)]" src="/android-light.svg" alt="Android" /> <img className="dark:[filter:invert(1)]" src="/ios-light.svg" alt="iOS" /></div> | <Status level="stable" /> |
| [bare-type](https://github.com/holepunchto/bare-type)                 | Cross-realm type predicates for Bare — [reference](/reference/bare/modules/bare-type)                                            | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /> <img className="dark:[filter:invert(1)]" src="/android-light.svg" alt="Android" /> <img className="dark:[filter:invert(1)]" src="/ios-light.svg" alt="iOS" /></div> | <Status level="stable" /> |

Threads, events & processes [#threads-events--processes]

Concurrency primitives, the event system, and process control.

| Module                                                                      | Description                                                                                          | Systems                                                                                                                                                                                                                                                                                                                                                                                                                                       | Stability                 |
| --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- |
| [bare-worker](https://github.com/holepunchto/bare-worker)                   | Higher-level worker threads for JavaScript                                                           | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /> <img className="dark:[filter:invert(1)]" src="/android-light.svg" alt="Android" /> <img className="dark:[filter:invert(1)]" src="/ios-light.svg" alt="iOS" /></div> | <Status level="stable" /> |
| [bare-channel](https://github.com/holepunchto/bare-channel)                 | Inter-thread messaging for JavaScript — [reference](/reference/bare/modules/bare-channel)            | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /> <img className="dark:[filter:invert(1)]" src="/android-light.svg" alt="Android" /> <img className="dark:[filter:invert(1)]" src="/ios-light.svg" alt="iOS" /></div> | <Status level="stable" /> |
| [bare-atomics](https://github.com/holepunchto/bare-atomics)                 | Native synchronization primitives for JavaScript — [reference](/reference/bare/modules/bare-atomics) | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /> <img className="dark:[filter:invert(1)]" src="/android-light.svg" alt="Android" /> <img className="dark:[filter:invert(1)]" src="/ios-light.svg" alt="iOS" /></div> | <Status level="stable" /> |
| [bare-events](https://github.com/holepunchto/bare-events)                   | Event emitters for JavaScript — [reference](/reference/bare/modules/bare-events)                     | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /> <img className="dark:[filter:invert(1)]" src="/android-light.svg" alt="Android" /> <img className="dark:[filter:invert(1)]" src="/ios-light.svg" alt="iOS" /></div> | <Status level="stable" /> |
| [bare-queue-microtask](https://github.com/holepunchto/bare-queue-microtask) | Microtask queuing for Bare                                                                           | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /> <img className="dark:[filter:invert(1)]" src="/android-light.svg" alt="Android" /> <img className="dark:[filter:invert(1)]" src="/ios-light.svg" alt="iOS" /></div> | <Status level="stable" /> |
| [bare-timers](https://github.com/holepunchto/bare-timers)                   | Native timers for JavaScript — [reference](/reference/bare/modules/bare-timers)                      | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /> <img className="dark:[filter:invert(1)]" src="/android-light.svg" alt="Android" /> <img className="dark:[filter:invert(1)]" src="/ios-light.svg" alt="iOS" /></div> | <Status level="stable" /> |
| [bare-hrtime](https://github.com/holepunchto/bare-hrtime)                   | High-resolution timers for JavaScript — [reference](/reference/bare/modules/bare-hrtime)             | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /> <img className="dark:[filter:invert(1)]" src="/android-light.svg" alt="Android" /> <img className="dark:[filter:invert(1)]" src="/ios-light.svg" alt="iOS" /></div> | <Status level="stable" /> |
| [bare-signals](https://github.com/holepunchto/bare-signals)                 | Native signal handling for JavaScript — [reference](/reference/bare/modules/bare-signals)            | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /> <img className="dark:[filter:invert(1)]" src="/android-light.svg" alt="Android" /> <img className="dark:[filter:invert(1)]" src="/ios-light.svg" alt="iOS" /></div> | <Status level="stable" /> |
| [bare-daemon](https://github.com/holepunchto/bare-daemon)                   | Create and manage daemon processes in JavaScript                                                     | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /></div>                                                                                                                                                               | <Status level="stable" /> |
| [bare-subprocess](https://github.com/holepunchto/bare-subprocess)           | Native process spawning for JavaScript — [reference](/reference/bare/modules/bare-subprocess)        | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /></div>                                                                                                                                                               | <Status level="stable" /> |
| [bare-process](https://github.com/holepunchto/bare-process)                 | Node.js-compatible process control for Bare — [reference](/reference/bare/modules/bare-process)      | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /> <img className="dark:[filter:invert(1)]" src="/android-light.svg" alt="Android" /> <img className="dark:[filter:invert(1)]" src="/ios-light.svg" alt="iOS" /></div> | <Status level="stable" /> |
| [bare-thread](https://github.com/holepunchto/bare-thread)                   | Thread support for Bare                                                                              | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /> <img className="dark:[filter:invert(1)]" src="/android-light.svg" alt="Android" /> <img className="dark:[filter:invert(1)]" src="/ios-light.svg" alt="iOS" /></div> | <Status level="stable" /> |

File system & OS [#file-system--os]

Filesystem access, paths, environment, and terminal I/O.

| Module                                                                | Description                                                                                                 | Systems                                                                                                                                                                                                                                                                                                                                                                                                                                       | Stability                 |
| --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- |
| [bare-fs](https://github.com/holepunchto/bare-fs)                     | Native file system for JavaScript — [reference](/reference/bare/modules/bare-fs)                            | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /> <img className="dark:[filter:invert(1)]" src="/android-light.svg" alt="Android" /> <img className="dark:[filter:invert(1)]" src="/ios-light.svg" alt="iOS" /></div> | <Status level="stable" /> |
| [bare-path](https://github.com/holepunchto/bare-path)                 | Path manipulation library for JavaScript — [reference](/reference/bare/modules/bare-path)                   | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /> <img className="dark:[filter:invert(1)]" src="/android-light.svg" alt="Android" /> <img className="dark:[filter:invert(1)]" src="/ios-light.svg" alt="iOS" /></div> | <Status level="stable" /> |
| [bare-os](https://github.com/holepunchto/bare-os)                     | Operating system utilities for JavaScript — [reference](/reference/bare/modules/bare-os)                    | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /> <img className="dark:[filter:invert(1)]" src="/android-light.svg" alt="Android" /> <img className="dark:[filter:invert(1)]" src="/ios-light.svg" alt="iOS" /></div> | <Status level="stable" /> |
| [bare-env](https://github.com/holepunchto/bare-env)                   | Environment variable support for JavaScript — [reference](/reference/bare/modules/bare-env)                 | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /> <img className="dark:[filter:invert(1)]" src="/android-light.svg" alt="Android" /> <img className="dark:[filter:invert(1)]" src="/ios-light.svg" alt="iOS" /></div> | <Status level="stable" /> |
| [bare-pipe](https://github.com/holepunchto/bare-pipe)                 | Native I/O pipes for JavaScript — [reference](/reference/bare/modules/bare-pipe)                            | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /> <img className="dark:[filter:invert(1)]" src="/android-light.svg" alt="Android" /> <img className="dark:[filter:invert(1)]" src="/ios-light.svg" alt="iOS" /></div> | <Status level="stable" /> |
| [bare-tty](https://github.com/holepunchto/bare-tty)                   | Native TTY streams for JavaScript — [reference](/reference/bare/modules/bare-tty)                           | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /> <img className="dark:[filter:invert(1)]" src="/android-light.svg" alt="Android" /> <img className="dark:[filter:invert(1)]" src="/ios-light.svg" alt="iOS" /></div> | <Status level="stable" /> |
| [bare-tui](https://github.com/holepunchto/bare-tui)                   | A little TUI framework for Bare, based on bubbletea                                                         | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /> <img className="dark:[filter:invert(1)]" src="/android-light.svg" alt="Android" /> <img className="dark:[filter:invert(1)]" src="/ios-light.svg" alt="iOS" /></div> | <Status level="stable" /> |
| [bare-readline](https://github.com/holepunchto/bare-readline)         | Line editing for interactive CLIs with command history — [reference](/reference/bare/modules/bare-readline) | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /> <img className="dark:[filter:invert(1)]" src="/android-light.svg" alt="Android" /> <img className="dark:[filter:invert(1)]" src="/ios-light.svg" alt="iOS" /></div> | <Status level="stable" /> |
| [bare-ansi-escapes](https://github.com/holepunchto/bare-ansi-escapes) | Parse and produce ANSI escape sequences — [reference](/reference/bare/modules/bare-ansi-escapes)            | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /> <img className="dark:[filter:invert(1)]" src="/android-light.svg" alt="Android" /> <img className="dark:[filter:invert(1)]" src="/ios-light.svg" alt="iOS" /></div> | <Status level="stable" /> |

Networking [#networking]

Sockets, transport security, HTTP, and RPC.

| Module                                                          | Description                                                                                                                 | Systems                                                                                                                                                                                                                                                                                                                                                                                                                                       | Stability                 |
| --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- |
| [bare-tcp](https://github.com/holepunchto/bare-tcp)             | Native TCP sockets for JavaScript — [reference](/reference/bare/modules/bare-tcp)                                           | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /> <img className="dark:[filter:invert(1)]" src="/android-light.svg" alt="Android" /> <img className="dark:[filter:invert(1)]" src="/ios-light.svg" alt="iOS" /></div> | <Status level="stable" /> |
| [bare-dgram](https://github.com/holepunchto/bare-dgram)         | Native UDP for JavaScript                                                                                                   | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /> <img className="dark:[filter:invert(1)]" src="/android-light.svg" alt="Android" /> <img className="dark:[filter:invert(1)]" src="/ios-light.svg" alt="iOS" /></div> | <Status level="stable" /> |
| [bare-dns](https://github.com/holepunchto/bare-dns)             | Domain name resolution for JavaScript — [reference](/reference/bare/modules/bare-dns)                                       | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /> <img className="dark:[filter:invert(1)]" src="/android-light.svg" alt="Android" /> <img className="dark:[filter:invert(1)]" src="/ios-light.svg" alt="iOS" /></div> | <Status level="stable" /> |
| [bare-http1](https://github.com/holepunchto/bare-http1)         | HTTP/1 library for JavaScript — [reference](/reference/bare/modules/bare-http1)                                             | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /> <img className="dark:[filter:invert(1)]" src="/android-light.svg" alt="Android" /> <img className="dark:[filter:invert(1)]" src="/ios-light.svg" alt="iOS" /></div> | <Status level="stable" /> |
| [bare-https](https://github.com/holepunchto/bare-https)         | HTTPS library for JavaScript — [reference](/reference/bare/modules/bare-https)                                              | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /> <img className="dark:[filter:invert(1)]" src="/android-light.svg" alt="Android" /> <img className="dark:[filter:invert(1)]" src="/ios-light.svg" alt="iOS" /></div> | <Status level="stable" /> |
| [bare-tls](https://github.com/holepunchto/bare-tls)             | Transport Layer Security (TLS) streams for JavaScript — [reference](/reference/bare/modules/bare-tls)                       | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /> <img className="dark:[filter:invert(1)]" src="/android-light.svg" alt="Android" /> <img className="dark:[filter:invert(1)]" src="/ios-light.svg" alt="iOS" /></div> | <Status level="stable" /> |
| [bare-ws](https://github.com/holepunchto/bare-ws)               | WebSocket library for JavaScript — [reference](/reference/bare/modules/bare-ws)                                             | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /> <img className="dark:[filter:invert(1)]" src="/android-light.svg" alt="Android" /> <img className="dark:[filter:invert(1)]" src="/ios-light.svg" alt="iOS" /></div> | <Status level="stable" /> |
| [bare-fetch](https://github.com/holepunchto/bare-fetch)         | WHATWG Fetch implementation for Bare — [reference](/reference/bare/modules/bare-fetch)                                      | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /> <img className="dark:[filter:invert(1)]" src="/android-light.svg" alt="Android" /> <img className="dark:[filter:invert(1)]" src="/ios-light.svg" alt="iOS" /></div> | <Status level="stable" /> |
| [bare-form-data](https://github.com/holepunchto/bare-form-data) | Form data support for Bare — [reference](/reference/bare/modules/bare-form-data)                                            | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /> <img className="dark:[filter:invert(1)]" src="/android-light.svg" alt="Android" /> <img className="dark:[filter:invert(1)]" src="/ios-light.svg" alt="iOS" /></div> | <Status level="stable" /> |
| [bare-url](https://github.com/holepunchto/bare-url)             | WHATWG URL implementation for JavaScript — [reference](/reference/bare/modules/bare-url)                                    | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /> <img className="dark:[filter:invert(1)]" src="/android-light.svg" alt="Android" /> <img className="dark:[filter:invert(1)]" src="/ios-light.svg" alt="iOS" /></div> | <Status level="stable" /> |
| [bare-rpc](https://github.com/holepunchto/bare-rpc)             | [librpc](https://github.com/holepunchto/librpc) ABI compatible RPC for Bare — [reference](/reference/bare/modules/bare-rpc) | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /> <img className="dark:[filter:invert(1)]" src="/android-light.svg" alt="Android" /> <img className="dark:[filter:invert(1)]" src="/ios-light.svg" alt="iOS" /></div> | <Status level="stable" /> |
| [bare-net](https://github.com/holepunchto/bare-net)             | TCP and IPC servers and clients for JavaScript — [reference](/reference/bare/modules/bare-net)                              | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /> <img className="dark:[filter:invert(1)]" src="/android-light.svg" alt="Android" /> <img className="dark:[filter:invert(1)]" src="/ios-light.svg" alt="iOS" /></div> | <Status level="stable" /> |
| [bare-ipc](https://github.com/holepunchto/bare-ipc)             | Lightweight pipe-based IPC for Bare — [reference](/reference/bare/modules/bare-ipc)                                         | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /> <img className="dark:[filter:invert(1)]" src="/android-light.svg" alt="Android" /> <img className="dark:[filter:invert(1)]" src="/ios-light.svg" alt="iOS" /></div> | <Status level="stable" /> |
| [bare-zmq](https://github.com/holepunchto/bare-zmq)             | Low-level ZeroMQ bindings for JavaScript                                                                                    | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /> <img className="dark:[filter:invert(1)]" src="/android-light.svg" alt="Android" /> <img className="dark:[filter:invert(1)]" src="/ios-light.svg" alt="iOS" /></div> | <Status level="stable" /> |

Data, streams & encoding [#data-streams--encoding]

Buffers, streaming, cryptography, and serialization.

| Module                                                                        | Description                                                                                              | Systems                                                                                                                                                                                                                                                                                                                                                                                                                                       | Stability                 |
| ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- |
| [bare-buffer](https://github.com/holepunchto/bare-buffer)                     | Native buffers for JavaScript — [reference](/reference/bare/modules/bare-buffer)                         | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /> <img className="dark:[filter:invert(1)]" src="/android-light.svg" alt="Android" /> <img className="dark:[filter:invert(1)]" src="/ios-light.svg" alt="iOS" /></div> | <Status level="stable" /> |
| [bare-stream](https://github.com/holepunchto/bare-stream)                     | Streaming data for JavaScript — [reference](/reference/bare/modules/bare-stream)                         | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /> <img className="dark:[filter:invert(1)]" src="/android-light.svg" alt="Android" /> <img className="dark:[filter:invert(1)]" src="/ios-light.svg" alt="iOS" /></div> | <Status level="stable" /> |
| [bare-crypto](https://github.com/holepunchto/bare-crypto)                     | Cryptographic primitives for JavaScript — [reference](/reference/bare/modules/bare-crypto)               | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /> <img className="dark:[filter:invert(1)]" src="/android-light.svg" alt="Android" /> <img className="dark:[filter:invert(1)]" src="/ios-light.svg" alt="iOS" /></div> | <Status level="stable" /> |
| [bare-encoding](https://github.com/holepunchto/bare-encoding)                 | WHATWG text encoding interfaces for JavaScript — [reference](/reference/bare/modules/bare-encoding)      | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /> <img className="dark:[filter:invert(1)]" src="/android-light.svg" alt="Android" /> <img className="dark:[filter:invert(1)]" src="/ios-light.svg" alt="iOS" /></div> | <Status level="stable" /> |
| [bare-structured-clone](https://github.com/holepunchto/bare-structured-clone) | Structured cloning algorithm for JavaScript — [reference](/reference/bare/modules/bare-structured-clone) | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /> <img className="dark:[filter:invert(1)]" src="/android-light.svg" alt="Android" /> <img className="dark:[filter:invert(1)]" src="/ios-light.svg" alt="iOS" /></div> | <Status level="stable" /> |
| [bare-zlib](https://github.com/holepunchto/bare-zlib)                         | Stream-based zlib bindings for JavaScript — [reference](/reference/bare/modules/bare-zlib)               | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /> <img className="dark:[filter:invert(1)]" src="/android-light.svg" alt="Android" /> <img className="dark:[filter:invert(1)]" src="/ios-light.svg" alt="iOS" /></div> | <Status level="stable" /> |

Diagnostics & console [#diagnostics--console]

Logging, inspection, assertions, and the REPL.

| Module                                                              | Description                                                                                                      | Systems                                                                                                                                                                                                                                                                                                                                                                                                                                       | Stability                 |
| ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- |
| [bare-console](https://github.com/holepunchto/bare-console)         | WHATWG debugging console for JavaScript — [reference](/reference/bare/modules/bare-console)                      | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /> <img className="dark:[filter:invert(1)]" src="/android-light.svg" alt="Android" /> <img className="dark:[filter:invert(1)]" src="/ios-light.svg" alt="iOS" /></div> | <Status level="stable" /> |
| [bare-inspect](https://github.com/holepunchto/bare-inspect)         | Inspect objects as strings for debugging — [reference](/reference/bare/modules/bare-inspect)                     | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /> <img className="dark:[filter:invert(1)]" src="/android-light.svg" alt="Android" /> <img className="dark:[filter:invert(1)]" src="/ios-light.svg" alt="iOS" /></div> | <Status level="stable" /> |
| [bare-inspector](https://github.com/holepunchto/bare-inspector)     | V8 inspector support for Bare — [reference](/reference/bare/modules/bare-inspector)                              | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /> <img className="dark:[filter:invert(1)]" src="/android-light.svg" alt="Android" /> <img className="dark:[filter:invert(1)]" src="/ios-light.svg" alt="iOS" /></div> | <Status level="stable" /> |
| [bare-logger](https://github.com/holepunchto/bare-logger)           | Low-level logger for Bare with system log integration — [reference](/reference/bare/modules/bare-logger)         | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /> <img className="dark:[filter:invert(1)]" src="/android-light.svg" alt="Android" /> <img className="dark:[filter:invert(1)]" src="/ios-light.svg" alt="iOS" /></div> | <Status level="stable" /> |
| [bare-performance](https://github.com/holepunchto/bare-performance) | Performance monitoring for Bare                                                                                  | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /> <img className="dark:[filter:invert(1)]" src="/android-light.svg" alt="Android" /> <img className="dark:[filter:invert(1)]" src="/ios-light.svg" alt="iOS" /></div> | <Status level="stable" /> |
| [bare-assert](https://github.com/holepunchto/bare-assert)           | Assertion library for JavaScript — [reference](/reference/bare/modules/bare-assert)                              | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /> <img className="dark:[filter:invert(1)]" src="/android-light.svg" alt="Android" /> <img className="dark:[filter:invert(1)]" src="/ios-light.svg" alt="iOS" /></div> | <Status level="stable" /> |
| [bare-abort](https://github.com/holepunchto/bare-abort)             | Cause abnormal program termination and generate a crash report — [reference](/reference/bare/modules/bare-abort) | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /> <img className="dark:[filter:invert(1)]" src="/android-light.svg" alt="Android" /> <img className="dark:[filter:invert(1)]" src="/ios-light.svg" alt="iOS" /></div> | <Status level="stable" /> |
| [bare-format](https://github.com/holepunchto/bare-format)           | String formatting for JavaScript — [reference](/reference/bare/modules/bare-format)                              | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /> <img className="dark:[filter:invert(1)]" src="/android-light.svg" alt="Android" /> <img className="dark:[filter:invert(1)]" src="/ios-light.svg" alt="iOS" /></div> | <Status level="stable" /> |
| [bare-repl](https://github.com/holepunchto/bare-repl)               | Read-Evaluate-Print-Loop environment for JavaScript                                                              | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /> <img className="dark:[filter:invert(1)]" src="/android-light.svg" alt="Android" /> <img className="dark:[filter:invert(1)]" src="/ios-light.svg" alt="iOS" /></div> | <Status level="stable" /> |

Media [#media]

Audio, video, and image formats for Bare apps.

| Module                                                                    | Description                        |
| ------------------------------------------------------------------------- | ---------------------------------- |
| [bare-ffmpeg](https://github.com/holepunchto/bare-ffmpeg)                 | Low-level FFmpeg bindings for Bare |
| [bare-media](https://github.com/holepunchto/bare-media)                   | A set of media APIs for Bare       |
| [bare-png](https://github.com/holepunchto/bare-png)                       | PNG support for Bare               |
| [bare-jpeg](https://github.com/holepunchto/bare-jpeg)                     | JPEG support for Bare              |
| [bare-gif](https://github.com/holepunchto/bare-gif)                       | GIF support for Bare               |
| [bare-webp](https://github.com/holepunchto/bare-webp)                     | WebP support for Bare              |
| [bare-heif](https://github.com/holepunchto/bare-heif)                     | HEIF support for Bare              |
| [bare-tiff](https://github.com/holepunchto/bare-tiff)                     | TIFF support for Bare              |
| [bare-bmp](https://github.com/holepunchto/bare-bmp)                       | Native BMP codec for Bare          |
| [bare-ico](https://github.com/holepunchto/bare-ico)                       | ICO support for Bare               |
| [bare-svg](https://github.com/holepunchto/bare-svg)                       | SVG support for Bare               |
| [bare-exif](https://github.com/holepunchto/bare-exif)                     | EXIF metadata support for Bare     |
| [bare-image-resample](https://github.com/holepunchto/bare-image-resample) | Image resampling support for Bare  |

Native development kits [#native-development-kits]

For embedding a Bare core inside a native application rather than running it standalone, use the toolkits below. They're documented in the [Bare Kit reference](/reference/bare/bare-kit) and the [One core, many platforms](/explanation/bare-on-native) explanation.

| Project                                                                       | Description                                                                  |
| ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| [bare-kit](https://github.com/holepunchto/bare-kit)                           | Bare for native application development—worklets and IPC for iOS and Android |
| [react-native-bare-kit](https://github.com/holepunchto/react-native-bare-kit) | `bare-kit` for React Native                                                  |
| [bare-expo](https://github.com/holepunchto/bare-expo)                         | Example of embedding Bare in an Expo application                             |
| [bare-ios](https://github.com/holepunchto/bare-ios)                           | Example of embedding Bare in an iOS application                              |
| [bare-native](https://github.com/holepunchto/bare-native)                     | Native application development framework for Bare                            |

The sections below catalog the rest of the published `bare-*` modules. They're listed by area without the platform/stability matrix above—per-module platform support and stability are tracked in each repository (and in the project's module research dossier).

Node.js compatibility [#nodejs-compatibility]

Coming from Node.js, the surface looks familiar, but Bare's standard library is opt-in rather than built in (see [Inside Bare](/explanation/bare-runtime)). Porting is mostly a matter of installing the right modules:

Builtin replacements [#builtin-replacements]

For each Node.js builtin your code uses, install the matching `bare-*` module. The mapping table below covers the common ones; each is documented in its functional section above.

Shims, globals & polyfills [#shims-globals--polyfills]

[`bare-node`](https://github.com/holepunchto/bare-node) is the umbrella entry point that maps Node.js builtins and globals onto their Bare equivalents. The remaining modules below fill specific gaps.

Native addons [#native-addons]

Addons written against Node-API don't load directly; rebuild them against Bare's addon API, or use [`bare-compat-napi`](https://github.com/holepunchto/bare-compat-napi) for Node-API compatibility headers.

Web-standard APIs [#web-standard-apis]

Several web-standard APIs a Node.js developer expects — [`bare-url`](https://github.com/holepunchto/bare-url) (WHATWG URL), [`bare-fetch`](https://github.com/holepunchto/bare-fetch) (WHATWG Fetch), [`bare-encoding`](https://github.com/holepunchto/bare-encoding) (text encoding), and [`bare-console`](https://github.com/holepunchto/bare-console) — are WHATWG implementations and live in the functional sections above rather than here.

| Node.js builtin  | Bare module                                                                                               |
| ---------------- | --------------------------------------------------------------------------------------------------------- |
| `assert`         | [bare-assert](https://github.com/holepunchto/bare-assert)                                                 |
| `async_hooks`    | [bare-async-hooks](https://github.com/holepunchto/bare-async-hooks)                                       |
| `buffer`         | [bare-buffer](https://github.com/holepunchto/bare-buffer)                                                 |
| `child_process`  | [bare-subprocess](https://github.com/holepunchto/bare-subprocess)                                         |
| `console`        | [bare-console](https://github.com/holepunchto/bare-console)                                               |
| `crypto`         | [bare-crypto](https://github.com/holepunchto/bare-crypto)                                                 |
| `dgram`          | [bare-dgram](https://github.com/holepunchto/bare-dgram)                                                   |
| `dns`            | [bare-dns](https://github.com/holepunchto/bare-dns)                                                       |
| `events`         | [bare-events](https://github.com/holepunchto/bare-events)                                                 |
| `fs`             | [bare-fs](https://github.com/holepunchto/bare-fs)                                                         |
| `http`           | [bare-http1](https://github.com/holepunchto/bare-http1)                                                   |
| `https`          | [bare-https](https://github.com/holepunchto/bare-https)                                                   |
| `net`            | [bare-net](https://github.com/holepunchto/bare-net) / [bare-tcp](https://github.com/holepunchto/bare-tcp) |
| `os`             | [bare-os](https://github.com/holepunchto/bare-os)                                                         |
| `path`           | [bare-path](https://github.com/holepunchto/bare-path)                                                     |
| `process`        | [bare-process](https://github.com/holepunchto/bare-process)                                               |
| `querystring`    | [bare-querystring](https://github.com/holepunchto/bare-querystring)                                       |
| `readline`       | [bare-readline](https://github.com/holepunchto/bare-readline)                                             |
| `stream`         | [bare-stream](https://github.com/holepunchto/bare-stream)                                                 |
| `string_decoder` | [bare-string-decoder](https://github.com/holepunchto/bare-string-decoder)                                 |
| `timers`         | [bare-timers](https://github.com/holepunchto/bare-timers)                                                 |
| `tls`            | [bare-tls](https://github.com/holepunchto/bare-tls)                                                       |
| `tty`            | [bare-tty](https://github.com/holepunchto/bare-tty)                                                       |
| `url`            | [bare-url](https://github.com/holepunchto/bare-url)                                                       |
| `vm`             | [bare-vm](https://github.com/holepunchto/bare-vm)                                                         |
| `worker_threads` | [bare-worker](https://github.com/holepunchto/bare-worker)                                                 |
| `zlib`           | [bare-zlib](https://github.com/holepunchto/bare-zlib)                                                     |

Shims & compatibility layers [#shims--compatibility-layers]

Shims and compatibility layers that map Node.js APIs and globals onto Bare. See also [`bare-node`](https://github.com/holepunchto/bare-node) as the umbrella entry point.

| Module                                                                        | Description                                                                                    |
| ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| [bare-node](https://github.com/holepunchto/bare-node)                         | Compatibility modules for Node.js builtins in Bare                                             |
| [bare-node-runtime](https://github.com/holepunchto/bare-node-runtime)         | Compatibility layer for Node.js builtins and globals in Bare                                   |
| [bare-vm](https://github.com/holepunchto/bare-vm)                             | Isolated JavaScript contexts for Bare — [reference](/reference/bare/modules/bare-vm)           |
| [bare-async-hooks](https://github.com/holepunchto/bare-async-hooks)           | `async_hooks` shim for Bare                                                                    |
| [bare-abort-controller](https://github.com/holepunchto/bare-abort-controller) | Abort controller support for Bare — [reference](/reference/bare/modules/bare-abort-controller) |
| [bare-querystring](https://github.com/holepunchto/bare-querystring)           | URL query-string utilities — [reference](/reference/bare/modules/bare-querystring)             |
| [bare-http-parser](https://github.com/holepunchto/bare-http-parser)           | Streaming HTTP request and response parser for Bare                                            |
| [bare-utils](https://github.com/holepunchto/bare-utils)                       | Node.js-compatible utility functions for Bare                                                  |
| [bare-intl](https://github.com/holepunchto/bare-intl)                         | ECMAScript Internationalization API for Bare                                                   |
| [bare-compat-napi](https://github.com/holepunchto/bare-compat-napi)           | Bare compatibility headers for Node-API                                                        |
| [bare-string-decoder](https://github.com/holepunchto/bare-string-decoder)     | `string_decoder` shim for Bare — [reference](/reference/bare/modules/bare-string-decoder)      |
| [bare-punycode](https://github.com/holepunchto/bare-punycode)                 | Punycode support for Bare                                                                      |

Module system, build & packaging [#module-system-build--packaging]

Module resolution and traversal, addon linking and prebuilding, and bundle/app packaging.

| Module                                                                      | Description                                                                                               |
| --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| [bare-module-resolve](https://github.com/holepunchto/bare-module-resolve)   | Low-level module resolution algorithm for Bare — [reference](/reference/bare/modules/bare-module-resolve) |
| [bare-module-traverse](https://github.com/holepunchto/bare-module-traverse) | Low-level module graph traversal for Bare — [reference](/reference/bare/modules/bare-module-traverse)     |
| [bare-addon-resolve](https://github.com/holepunchto/bare-addon-resolve)     | Low-level addon resolution algorithm for Bare — [reference](/reference/bare/modules/bare-addon-resolve)   |
| [bare-addon](https://github.com/holepunchto/bare-addon)                     | Native addon template for Bare                                                                            |
| [bare-link](https://github.com/holepunchto/bare-link)                       | Native addon linker for Bare                                                                              |
| [bare-prebuild](https://github.com/holepunchto/bare-prebuild)               | Recursively prebuild installed native addons from source                                                  |
| [bare-boot](https://github.com/holepunchto/bare-boot)                       | Boot drives in Bare                                                                                       |
| [bare-run](https://github.com/holepunchto/bare-run)                         | Cross-platform script runner for Bare                                                                     |
| [bare-which](https://github.com/holepunchto/bare-which)                     | Find a program in `$PATH`                                                                                 |
| [bare-open](https://github.com/holepunchto/bare-open)                       | Cross-platform application launcher for Bare                                                              |
| [bare-storage](https://github.com/holepunchto/bare-storage)                 | Minimal, cross-platform directory locator for Bare                                                        |
| [bare-pack-drive](https://github.com/holepunchto/bare-pack-drive)           | Pack drives to Bare bundles                                                                               |
| [bare-bundle-compile](https://github.com/holepunchto/bare-bundle-compile)   | Compile a bundle of CommonJS modules to a single module                                                   |
| [bare-union-bundle](https://github.com/holepunchto/bare-union-bundle)       | Combine multiple bundles into a union bundle — [reference](/reference/bare/modules/bare-union-bundle)     |
| [bare-stow](https://github.com/holepunchto/bare-stow)                       | Module bundling and harness generation for Bare — [reference](/reference/bare/modules/bare-stow)          |
| [bare-distributable](https://github.com/holepunchto/bare-distributable)     | Template for creating custom Bare distributables                                                          |
| [bare-apk](https://github.com/holepunchto/bare-apk)                         | APK packaging tools for Bare — [reference](/reference/bare/modules/bare-apk)                              |
| [bare-app-image](https://github.com/holepunchto/bare-app-image)             | AppImage packaging tools for Bare                                                                         |

Native bindings [#native-bindings]

Bindings to native libraries and platform capabilities. Several are platform-specific (the name indicates the target).

| Module                                                                          | Description                                                                                       |
| ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| [bare-sqlite](https://github.com/holepunchto/bare-sqlite)                       | SQLite bindings for Bare — [reference](/reference/bare/modules/bare-sqlite)                       |
| [bare-sqlite-vector](https://github.com/holepunchto/bare-sqlite-vector)         | SQLite vector-search bindings for Bare — [reference](/reference/bare/modules/bare-sqlite-vector)  |
| [bare-sdl](https://github.com/holepunchto/bare-sdl)                             | SDL bindings for Bare — [reference](/reference/bare/modules/bare-sdl)                             |
| [bare-bluetooth-android](https://github.com/holepunchto/bare-bluetooth-android) | Android Bluetooth bindings for Bare — [reference](/reference/bare/modules/bare-bluetooth-android) |
| [bare-bluetooth-apple](https://github.com/holepunchto/bare-bluetooth-apple)     | Apple CoreBluetooth bindings for Bare — [reference](/reference/bare/modules/bare-bluetooth-apple) |
| [bare-posix](https://github.com/holepunchto/bare-posix)                         | POSIX-specific bindings for Bare — [reference](/reference/bare/modules/bare-posix)                |
| [bare-stdio](https://github.com/holepunchto/bare-stdio)                         | Standard input/output streams for Bare — [reference](/reference/bare/modules/bare-stdio)          |
| [bare-xdiff](https://github.com/holepunchto/bare-xdiff)                         | libxdiff bindings for Bare                                                                        |
| [bare-delta](https://github.com/holepunchto/bare-delta)                         | Binary patch handling for Bare                                                                    |
| [bare-md4c](https://github.com/holepunchto/bare-md4c)                           | MD4C markdown push-parser bindings                                                                |
| [bare-system-logger](https://github.com/holepunchto/bare-system-logger)         | System logger for Bare — [reference](/reference/bare/modules/bare-system-logger)                  |

Logging, metrics & testing [#logging-metrics--testing]

| Module                                                                              | Description                                                                         |
| ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| [bare-prom-client](https://github.com/holepunchto/bare-prom-client)                 | Prometheus metrics client — [reference](/reference/bare/modules/bare-prom-client)   |
| [bare-diagnostics-channel](https://github.com/holepunchto/bare-diagnostics-channel) | Publish data to named diagnostics channels                                          |
| [bare-debug-log](https://github.com/holepunchto/bare-debug-log)                     | Simple debug log for JavaScript                                                     |
| [bare-file-logger](https://github.com/holepunchto/bare-file-logger)                 | File-system logger for Bare — [reference](/reference/bare/modules/bare-file-logger) |
| [bare-cov](https://github.com/holepunchto/bare-cov)                                 | Generate coverage reports using Bare and Node.js                                    |
| [bare-tap](https://github.com/holepunchto/bare-tap)                                 | Minimal TAP test library for Bare                                                   |

Terminal UI [#terminal-ui]

Extensions for [`bare-tui`](https://github.com/holepunchto/bare-tui), the terminal-UI framework.

| Module                                                                | Description                              |
| --------------------------------------------------------------------- | ---------------------------------------- |
| [bare-tui-form](https://github.com/holepunchto/bare-tui-form)         | Declarative form builder for `bare-tui`  |
| [bare-tui-paparam](https://github.com/holepunchto/bare-tui-paparam)   | Menu/form helper for `paparam` CLIs      |
| [bare-tui-markdown](https://github.com/holepunchto/bare-tui-markdown) | Limited markdown renderer for `bare-tui` |

Other utilities [#other-utilities]

| Module                                                                          | Description                                                                                                                   |
| ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| [bare-sidecar](https://github.com/holepunchto/bare-sidecar)                     | Start and manage Bare sidecar processes from Node.js and Electron — [reference](/reference/bare/modules/bare-sidecar)         |
| [bare-broadcast-channel](https://github.com/holepunchto/bare-broadcast-channel) | Multi-producer, multi-consumer inter-thread broadcast messaging — [reference](/reference/bare/modules/bare-broadcast-channel) |
| [bare-type-stripper](https://github.com/holepunchto/bare-type-stripper)         | Strip TypeScript type syntax to produce plain JavaScript — [reference](/reference/bare/modules/bare-type-stripper)            |
| [bare-node-fetch](https://github.com/holepunchto/bare-node-fetch)               | Cross-runtime `fetch` module                                                                                                  |
| [bare-mdns-discovery](https://github.com/holepunchto/bare-mdns-discovery)       | Multicast DNS (mDNS) service discovery for Bare — [reference](/reference/bare/modules/bare-mdns-discovery)                    |
| [bare-mime](https://github.com/holepunchto/bare-mime)                           | MIME-type parsing for Bare — [reference](/reference/bare/modules/bare-mime)                                                   |
| [bare-collabora](https://github.com/holepunchto/bare-collabora)                 | Collabora bindings for Bare — [reference](/reference/bare/modules/bare-collabora)                                             |

See also [#see-also]

* [Inside Bare](/explanation/bare-runtime)—what the runtime is and why its standard library is opt-in.
* [Bare runtime API](/reference/bare/runtime)—the `Bare` global these modules build on.
* [`bare` CLI](/reference/bare/cli)—run a script or REPL on Bare.
* [Bare Kit](/reference/bare/bare-kit)—embed a Bare worklet in a native app.
* [Modules](/reference/modules/pear-modules)—higher-level `pear-*` modules built on Bare.
* [`pear-runtime` reference](/reference/pear/runtime)—JavaScript API exposed inside a running Pear app.
* [Runtime and languages](/explanation/runtime-and-languages)—the language-and-runtime story behind both.


# Modules



Modules [#modules]

The `Pear` global API is minimal and not intended as a standard library. Application and integration libraries are supplied via installable modules prefixed with `pear-`.

Stability legend [#stability-legend]

Module lists call out a stability indicator. The four levels:

| Stability                       | Description                                                 |
| ------------------------------- | ----------------------------------------------------------- |
| <Status level="stable" />       | Unlikely to change or be removed in the foreseeable future. |
| <Status level="experimental" /> | New, untested, or has known issues.                         |
| <Status level="deprecated" />   | Being removed or replaced in the future.                    |
| <Status level="unstable" />     | May change or be removed without warning.                   |

Application libraries [#application-libraries]

Pear modules related directly to the application environment.

| Module                                                          | Description                                                  | Systems                                                                                                                                                                                                                                                                         | Stability                 |
| --------------------------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- |
| [pear-crasher](https://github.com/holepunchto/pear-crasher)     | Uncaught exceptions & uncaught rejections crash logger       | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /></div> | <Status level="stable" /> |
| [pear-message](https://github.com/holepunchto/pear-message)     | Send inter-app pattern-matched object messages               | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /></div> | <Status level="stable" /> |
| [pear-messages](https://github.com/holepunchto/pear-messages)   | Receive object messages that match a given object pattern    | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /></div> | <Status level="stable" /> |
| [pear-pipe](https://github.com/holepunchto/pear-pipe)           | Parent-app-connected pipe, the other end of pear-run pipe    | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /></div> | <Status level="stable" /> |
| [pear-run](https://github.com/holepunchto/pear-run)             | Run Pear child app by link. Returns a pipe to the child pipe | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /></div> | <Status level="stable" /> |
| [pear-updates](https://github.com/holepunchto/pear-updates)     | Receive platform and application update notifications        | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /></div> | <Status level="stable" /> |
| [pear-user-dirs](https://github.com/holepunchto/pear-user-dirs) | Get the path of user-specific directories                    | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /></div> | <Status level="stable" /> |
| [pear-wakeups](https://github.com/holepunchto/pear-wakeups)     | Receive wakeup events, including link clicks external to app | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /></div> | <Status level="stable" /> |

User interface libraries [#user-interface-libraries]

Pear modules that supply User Interface runtime capabilities.

| Module                                                        | Description                                      | Systems                                                                                                                                                                                                                                                                         | Stability                 |
| ------------------------------------------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- |
| [pear-electron](https://github.com/holepunchto/pear-electron) | Pear User-Interface Library for Electron         | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /></div> | <Status level="stable" /> |
| [pear-bridge](https://github.com/holepunchto/pear-bridge)     | Local HTTP bridge for pear-electron applications | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /></div> | <Status level="stable" /> |

Common libraries [#common-libraries]

Pear modules for general usage, including applications per case.

| Module                                                          | Description                                                      | Systems                                                                                                                                                                                                                                                                                                                                                                                                                                       | Stability                 |
| --------------------------------------------------------------- | ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- |
| [pear-drop](https://github.com/holepunchto/pear-drop)           | Drop data, including application reset                           | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /></div>                                                                                                                                                               | <Status level="stable" /> |
| [pear-dump](https://github.com/holepunchto/pear-dump)           | Synchronize files from link to dir peer-to-peer or from-disk     | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /></div>                                                                                                                                                               | <Status level="stable" /> |
| [pear-gracedown](https://github.com/holepunchto/pear-gracedown) | Pear graceful closer. For use with `pipe.autoexit = false`       | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /></div>                                                                                                                                                               | <Status level="stable" /> |
| [pear-info](https://github.com/holepunchto/pear-info)           | Read Pear project information by link                            | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /></div>                                                                                                                                                               | <Status level="stable" /> |
| [pear-link](https://github.com/holepunchto/pear-link)           | Parser-Serializer for `pear://` links. Includes alias resolution | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /> <img className="dark:[filter:invert(1)]" src="/android-light.svg" alt="Android" /> <img className="dark:[filter:invert(1)]" src="/ios-light.svg" alt="iOS" /></div> | <Status level="stable" /> |
| [pear-opwait](https://github.com/holepunchto/pear-opwait)       | Pear operation stream promise wrapper                            | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /></div>                                                                                                                                                               | <Status level="stable" /> |
| [pear-release](https://github.com/holepunchto/pear-release)     | Set application production release version length                | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /></div>                                                                                                                                                               | <Status level="stable" /> |
| [pear-seed](https://github.com/holepunchto/pear-seed)           | Seed or reseed a Pear app drive by link                          | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /></div>                                                                                                                                                               | <Status level="stable" /> |
| [pear-stage](https://github.com/holepunchto/pear-stage)         | Synchronize from-disk to app drive peer-to-peer                  | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /></div>                                                                                                                                                               | <Status level="stable" /> |
| [pear-stamp](https://github.com/holepunchto/pear-stamp)         | Interleave locals into a template, sync and stream               | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /></div>                                                                                                                                                               | <Status level="stable" /> |

Developer libraries [#developer-libraries]

Pear modules to assist with developing & debugging

| Module                                                      | Description                                                                                        | Systems                                                                                                                                                                                                                                                                                                                                                                                                                                       | Stability                 |
| ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- |
| [pear-inspect](https://github.com/holepunchto/pear-inspect) | Securely enable remote debugging protocol over [Hyperswarm](/reference/building-blocks/hyperswarm) | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /> <img className="dark:[filter:invert(1)]" src="/android-light.svg" alt="Android" /> <img className="dark:[filter:invert(1)]" src="/ios-light.svg" alt="iOS" /></div> | <Status level="stable" /> |
| [pear-hotmods](https://github.com/holepunchto/pear-hotmods) | For `pear-electron` UI apps. Frontend framework-agnostic live-reload                               | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /></div>                                                                                                                                                               | <Status level="stable" /> |

Integration libraries [#integration-libraries]

Pear modules for runtime integrations. Such as [pear-electron](https://github.com/holepunchto/pear-electron).

| Module                                                          | Description                                                                                                                                                                                | Systems                                                                                                                                                                                                                                                                                                                                                                                                                                       | Stability                   |
| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- |
| [pear-appdrive](https://github.com/holepunchto/pear-appdrive)   | Read-only [Hyperdrive](/reference/building-blocks/hyperdrive) API subset interface for application drives                                                                                  | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /></div>                                                                                                                                                               | <Status level="stable" />   |
| [pear-aliases](https://github.com/holepunchto/pear-aliases)     | List of aliases for `pear://<alias>` links                                                                                                                                                 | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /> <img className="dark:[filter:invert(1)]" src="/android-light.svg" alt="Android" /> <img className="dark:[filter:invert(1)]" src="/ios-light.svg" alt="iOS" /></div> | <Status level="stable" />   |
| [pear-api](https://github.com/holepunchto/pear-api)             | global.Pear API class—[removed as of Pear v3](/reference/pear/api), use [Pear OTA](/reference/pear/runtime)                                                                                | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /> <img className="dark:[filter:invert(1)]" src="/android-light.svg" alt="Android" /> <img className="dark:[filter:invert(1)]" src="/ios-light.svg" alt="iOS" /></div> | <Status level="removed" />  |
| [pear-changelog](https://github.com/holepunchto/pear-changelog) | Changelog parsing and diffing—the parser behind [`pear changelog`](/reference/pear/cli#pear-changelog); see [Publish a changelog for your app](/how-to/operate-an-app/publish-a-changelog) | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /> <img className="dark:[filter:invert(1)]" src="/android-light.svg" alt="Android" /> <img className="dark:[filter:invert(1)]" src="/ios-light.svg" alt="iOS" /></div> | <Status level="stable" />   |
| [pear-constants](https://github.com/holepunchto/pear-constants) | Shared Pear constants                                                                                                                                                                      | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /> <img className="dark:[filter:invert(1)]" src="/android-light.svg" alt="Android" /> <img className="dark:[filter:invert(1)]" src="/ios-light.svg" alt="iOS" /></div> | <Status level="stable" />   |
| [pear-cmd](https://github.com/holepunchto/pear-cmd)             | Command parser & definitions                                                                                                                                                               | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /></div>                                                                                                                                                               | <Status level="stable" />   |
| [pear-errors](https://github.com/holepunchto/pear-errors)       | Shared Pear error types                                                                                                                                                                    | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /> <img className="dark:[filter:invert(1)]" src="/android-light.svg" alt="Android" /> <img className="dark:[filter:invert(1)]" src="/ios-light.svg" alt="iOS" /></div> | <Status level="stable" />   |
| [pear-gunk](https://github.com/holepunchto/pear-gunk)           | Shared builtins, overrides & linker mappings                                                                                                                                               | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /></div>                                                                                                                                                               | <Status level="unstable" /> |
| [pear-ipc](https://github.com/holepunchto/pear-ipc)             | Interprocess Communication library                                                                                                                                                         | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /></div>                                                                                                                                                               | <Status level="stable" />   |
| [pear-ref](https://github.com/holepunchto/pear-ref)             | IO handle reference counter & tracker                                                                                                                                                      | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /> <img className="dark:[filter:invert(1)]" src="/android-light.svg" alt="Android" /> <img className="dark:[filter:invert(1)]" src="/ios-light.svg" alt="iOS" /></div> | <Status level="stable" />   |
| [pear-rti](https://github.com/holepunchto/pear-rti)             | Runtime Information state bootstrap for API building                                                                                                                                       | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /> <img className="dark:[filter:invert(1)]" src="/android-light.svg" alt="Android" /> <img className="dark:[filter:invert(1)]" src="/ios-light.svg" alt="iOS" /></div> | <Status level="stable" />   |
| [pear-state](https://github.com/holepunchto/pear-state)         | Shared state structure & capabilities                                                                                                                                                      | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /> <img className="dark:[filter:invert(1)]" src="/android-light.svg" alt="Android" /> <img className="dark:[filter:invert(1)]" src="/ios-light.svg" alt="iOS" /></div> | <Status level="stable" />   |
| [pear-terminal](https://github.com/holepunchto/pear-terminal)   | Terminal User Interface library                                                                                                                                                            | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /></div>                                                                                                                                                               | <Status level="stable" />   |
| [pear-tryboot](https://github.com/holepunchto/pear-tryboot)     | Used with `pear-ipc`, tries to boot sidecar on connect failure                                                                                                                             | <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}><img className="dark:[filter:invert(1)]" src="/windows-light.svg" alt="Windows" /> <img className="dark:[filter:invert(1)]" src="/macos-light.svg" alt="macOS" /> <img src="/linux.svg" alt="Linux" /></div>                                                                                                                                                               | <Status level="stable" />   |

See also [#see-also]

* [Bare modules](/reference/modules/bare-modules)—the lower-level `bare-*` runtime modules.
* Building blocks—peer-to-peer primitives:
  * [Hypercore](/reference/building-blocks/hypercore)
  * [Hyperbee](/reference/building-blocks/hyperbee)
  * [Hyperdrive](/reference/building-blocks/hyperdrive)
  * [Autobase](/reference/building-blocks/autobase)
  * [HyperDHT](/reference/building-blocks/hyperdht)
  * [Hyperswarm](/reference/building-blocks/hyperswarm)
* Helpers—utilities that complement the building blocks:
  * [Corestore](/reference/helpers/corestore)
  * [Localdrive](/reference/helpers/localdrive)
  * [Mirrordrive](/reference/helpers/mirrordrive)
  * [Secretstream](/reference/helpers/secretstream)
  * [Compact encoding](/reference/helpers/compact-encoding)
  * [Protomux](/reference/helpers/protomux)
* Tools—standalone CLI utilities:
  * [Hypershell](/reference/tools/hypershell)
  * [Hypertele](/reference/tools/hypertele)
  * [Hyperbeam](/reference/tools/hyperbeam)
  * [Hyperssh](/reference/tools/hyperssh)
  * [Drives](/reference/tools/drives)


# Application Programming Interface (API)



<Callout type="warning">
  **Deprecated in Pear v2.6.5, removed as of Pear v3.** The `global.Pear` direct-access API documented here was injected by the removed `pear run` command and is superseded by **[Pear OTA](/reference/pear/runtime)** (the `pear-runtime` module)—instantiate `Pear` and use its API instead. This page is retained for reference and for the still-current [`global.Bare`](#globalbare) APIs.
</Callout>

Pear is built on [Bare](/reference/modules/bare-modules). Pear applications have a `global.Pear` object and a`global.Bare` object. For background on the runtime split, see [Runtime and languages](/explanation/runtime-and-languages); for the surrounding `pear-*` library catalog, see [Modules](/reference/modules/pear-modules).

* [global.Pear](#globalpear)
* [global.Bare](#globalbare)

global.Pear [#globalpear]

<a name="globalpear" />

The Pear Platform API is made available globally as `Pear`.

The `Pear` API is designed to be as minimal as possible.

The majority of capabilities are supplied via [Pear Modules](/reference/modules/pear-modules).

Pear.app <Object> [#pearapp-object]

<a name="pear-app" />

**REMOVED**—superseded by the [Pear OTA](/reference/pear/runtime) (`pear-runtime`) API (instantiate `Pear` and use its instance instead). Applies to all `Pear.app.*` properties below.

Contains application information. Supersedes `Pear.config`.

Pear.app.key <Buffer|null> [#pearappkey-buffernull]

<a name="pear-app-key" />

**REMOVED**

A buffer of the application key. If running from disk, `Pear.app.key` is null.

Pear.app.length <Integer> [#pearapplength-integer]

<a name="pear-app-length" />

**REMOVED**

The application drive length. The application version consists of `Pear.app.key`, `Pear.app.length` and `Pear.app.fork`.

Pear.app.fork <Integer> [#pearappfork-integer]

<a name="pear-app-fork" />

**REMOVED**

The application drive fork count. A fork is where the append-only log of the drive is truncated.

The application version consists of `Pear.app.key`, `Pear.app.length` and `Pear.app.fork`.

Pear.app.alias <String|null> [#pearappalias-stringnull]

<a name="pear-app-alias" />

**REMOVED**

Given an application that is run from a pear:// link with an alias it, contains that alias.
For example the `Pear.app.alias` for `pear run pear://myapp` would be `myapp`.

Pear.app.dev <Boolean> [#pearappdev-boolean]

<a name="pear-app-dev" />

**REMOVED**

Whether the application is in development mode.

Note that development mode means, the application has been run with the `--dev` flag.

Development mode is not the same as development environment. Development environment equates to running from disk.

For example, to detect both development mode & environment:

```js
const fromDisk = Pear.app.key === null
const isDev = fromDisk && Pear.app.dev
```

Pear.app.name <String> [#pearappname-string]

<a name="pear-app-name" />

**REMOVED**

Application name.

Pear.app.main <String> [#pearappmain-string]

<a name="pear-app-main" />

**REMOVED**

Application entry file.

Pear.app.channel <String|null> [#pearappchannel-stringnull]

<a name="pear-app-channel" />

**REMOVED**

Application release/staging channel.

Pear.app.storage <String> [#pearappstorage-string]

<a name="pear-app-storage" />

**REMOVED**

Application storage path

Pear.app.options <Object> [#pearappoptions-object]

<a name="pear-app-options" />

**REMOVED**

Configuration options.
The `pear` configuration object as supplied via an applications `package.json` file.

**References**

* [Configuration](/reference/pear/configuration)

Pear.app.env <Object> [#pearappenv-object]

<a name="pear-app-env" />

**REMOVED**

The environment variables that an application was started with, as key-value pairs in an object.

Pear.app.flags <Object> [#pearappflags-object]

<a name="pear-app-flags" />

**REMOVED**

Parsed command-line flag values as supplied when an application was started.

Pear.app.checkout <String> [#pearappcheckout-string]

<a name="pear-app-checkout" />

**REMOVED**

The value of the [`pear run --checkout`](/reference/pear/cli#pear-run-flags-linkdir-app-args) flag. Same as [`Pear.app.flags.checkout`](#pear-app-checkout).

**References**

* [`pear run`](/reference/pear/cli#pear-run-flags-linkdir-app-args)
* [`Pear.app.flags`](#pear-app-flags)

Pear.app.storage <String> [#pearappstorage-string-1]

<a name="pear-app-storage-dir" />

**REMOVED**

Application storage path.

Pear.app.args <Array> [#pearappargs-array]

<a name="pear-app-args" />

**REMOVED**

Command-line application arguments passed like `pear run --dev . --some arg`.

Pear.app.release <Number> [#pearapprelease-number]

<a name="pear-app-release" />

**REMOVED**

The current release length as marked by the `pear release` command.

**References**

* [`pear release`](/reference/pear/cli#pear-release-link-dir)

Pear.app.link <String> [#pearapplink-string]

<a name="pear-app-link" />

**REMOVED**

The link that was passed to `pear run` with alias resolved to key.

Includes any potential pathname, query or fragment.

**References**

* [`pear run`](/reference/pear/cli#pear-run-flags-linkdir-app-args)

Pear.app.links <Object|Array> [#pearapplinks-objectarray]

<a name="pear-app-links" />

**REMOVED**

Holds trusted Pear application links and domains as specified in the `links` field inside `package.json`.

**References**

* [`pear.links`](/reference/pear/configuration#pearlinks-objectarray)
* [`pear run`](/reference/pear/cli#pear-run-flags-linkdir-app-args)

Pear.app.routes <String> [#pearapproutes-string]

<a name="pear-app-routes" />

**REMOVED**

The configuration provided [`pear.routes`](/reference/pear/configuration#pearroutes-objectstring) mapping object.

Pear.app.entrypoint <String> [#pearappentrypoint-string]

<a name="pear-app-entrypoint" />

**REMOVED**

The link pathname (`pear://<key>/<pathname>`), after any route mappings have been applied per [`pear.routes`](/reference/pear/configuration#pearroutes-objectstring).

Includes the leading `/`, e.g given `pear://foo/bar/baz`, `Pear.app.entrypoint` would be `/bar/baz`.

Only `Pear.app.entrypoint` supports route-mapping via the [`pear.routes`](/reference/pear/configuration#pearroutes-objectstring) mapping object. `Pear.app.route` is provides access the raw pathname, including the leading slash (`/`), while `Pear.app.linkData` is legacy, excludes the slash, but is still supported.

* [`Pear.app.route`](#pear-app-route)
* [`Pear.app.routes`](#pear-app-routes)
* [`pear.routes`](/reference/pear/configuration#pearroutes-objectstring)

Pear.app.fragment <String> [#pearappfragment-string]

<a name="pear-app-fragment" />

**REMOVED**

The link hash, without the leading `#`.

Given `pear://<key>/<pathname>#frag` `Pear.app.fragment` would be `frag`.

Pear.app.query <String> [#pearappquery-string]

<a name="pear-app-query" />

**REMOVED**

The link query string, without the leading `?`.

Given `pear://<key>/<pathname>?qs` `Pear.app.query` would be `qs`.

Pear.app.route <String> [#pearapproute-string]

<a name="pear-app-route" />

**REMOVED**

The link pathname (`pear://<key>/<pathname>`), prior to any route mappings being applied.

Includes the leading `/`, e.g given `pear://foo/bar/baz`, `Pear.app.route` would be `/bar/baz`.

**References**

* [`Pear.app.entrypoint`](#pear-app-entrypoint)
* [`Pear.app.routes`](#pear-app-routes)
* [`pear.routes`](/reference/pear/configuration#pearroutes-objectstring)

Pear.app.linkData <String> [#pearapplinkdata-string]

<a name="pear-app-linkData" />

**REMOVED**

Holds just the data portion of a Pear link.

The Pear link of an application. Takes the form `pear://<key>/<data>`.

In development, `pear://dev/<data>`.

Unlike `Pear.app.route` and `Pear.app.entrypoint` *does not* include the leading slash (`/`).

Legacy but still supported. Prefer `Pear.app.entrypoint` or `Pear.app.route`.

**References**

* [`Pear.app.entrypoint`](#pear-app-entrypoint)
* [`Pear.app.route`](#pear-app-route)
* [`Pear.app.link`](#pear-app-link)
* [`pear run`](/reference/pear/cli#pear-run-flags-linkdir-app-args)

Pear.app.checkpoint <Any> [#pearappcheckpoint-any]

<a name="pear-app-checkpoint" />

**REMOVED**

Holds state as set by `Pear.checkpoint()`. When an application restarts it will hold the most recent value passed to `Pear.checkpoint()`.

Stores state that will be available as `Pear.app.checkpoint` next time the application starts.

The `Pear.app.checkpoint` property immediately reflects the latest checkpoint.

The returned `Promise` will resolve once the checkpoint has been successfully stored.

**References**

* [Pear.checkpoint()](#pear-checkpoint)

Pear.app.release <Integer> [#pearapprelease-integer]

<a name="pear-app-release-sequence" />

**REMOVED**

Application release sequence integer.

Pear.app.flags <Object> [#pearappflags-object-1]

<a name="pear-app-run-flags" />

**REMOVED**

Parsed `pear run` flags.

Pear.app.applink <String> [#pearappapplink-string]

<a name="pear-app-applink" />

**REMOVED**

Pear application link. May be a `pear://` link or a local directory.

Pear.app.dir <String> [#pearappdir-string]

<a name="pear-app-dir" />

**REMOVED**

The current working directory of `pear run` when the application was started.

Pear.app.dht.nodes <Array<Object>> [#pearappdhtnodes-arrayobject]

<a name="pear-app-dht-nodes" />

**REMOVED**

A list of known [DHT](https://github.com/holepunchto/hyperdht) nodes of the form `{ host: <String>, port: <Number> }`. The nodes are set when the Pear application is started.

Unless started with a custom set of bootstrap nodes, Pear caches known nodes to speed up connecting to the swarm and to make it more resilient.

Pear.app.dht.bootstrap <Array<Object>> [#pearappdhtbootstrap-arrayobject]

<a name="pear-app-dht-bootstrap" />

**REMOVED**

A list of custom bootstrap nodes Pear is started with of the form `{ host: <String>, port: <Number> }`.

Pear.app.assets  <String> [#pearappassets--string]

<a name="pear-app-assets" />

**REMOVED**

Advanced / integration purposes.

Per [`pear-assets`](/reference/pear/configuration#pear-assets) configuration assets are fetched and stored to disk. Use `Pear.app.assets[namespace].path` to get the path that given asset is stored to.

Takes the form `{ [namespace]: { link <String>, ns <String>, path <String>, name <String>, only <Array<String>>, bytes <Integer> } }`. `namespace` is per the property name on the assets object. By convention, should be describe the asset type, for example: `ui`.

* `link` - Configuration supplied `pear://<fork>.<length>.<key>`
* `ns` - Namespace - same as the property name
* `path` - The path that Pear stored the asset to on-disk
* `name` - Configuration supplied name
* `only` - Configuration supplied only array
* `bytes` - The total bytes used by asset on-disk

Example:

```js
{
  "ui": {
    "link": "pear://0.940.cktxzetiwt6un3ado5kgqedge6ya4nfazjckzq76zcapefwxakdy",
    "ns": "ui",
    "path": "/Users/xxx/Library/Application Support/pear/assets/0c82035d08c00ae4da2f307eb5d2c1fd",
    "name": "Pear Runtime",
    "only": [
      "/boot.bundle",
      "/by-arch/%HOST%",
      "/prebuilds/%HOST%"
    ],
    "bytes": 259158801
  }
}
```

Pear.app.prerunning <Boolean> [#pearappprerunning-boolean]

<a name="pear-app-prerunning" />

**REMOVED**

Whether the current application is a [`pre`](/reference/pear/configuration#pear-pre) script.

Pear.app.startId <String> [#pearappstartid-string]

<a name="pear-app-startid" />

**REMOVED**

Advanced. Integration purposes.

The application start identifier. Can be used to register a [`pear-ipc`](https://github.com/holepunchto/pear-ipc) client to an applicaiton, with
`ipc.identify()`

Pear.app.swapDir <String> [#pearappswapdir-string]

<a name="pear-app-swapdir" />

**REMOVED**

Advanced. Integration purposes.

The active swap directory with Pear platform directory.

Pear.app.pearDir <String> [#pearapppeardir-string]

<a name="pear-app-peardir" />

**REMOVED**

Advanced. Integration purposes.

Pear platform directory.

Pear.checkpoint(<Any>) => Promise [#pearcheckpointany--promise]

<a name="pear-checkpoint" />

**REMOVED**

Stores state that will be available as `Pear.app.checkpoint` next time the application starts.

The `Pear.app.checkpoint` property immediately reflects the latest checkpoint.

The returned `Promise` will resolve once the checkpoint has been successfully stored.

**References**

* [`Pear.app.checkpoint`](#pear-app-checkpoint)

Pear.teardown(fn <Async Function|Function>) [#pearteardownfn-async-functionfunction]

<a name="pear-teardown" />

**REMOVED**

Register application clean-up handlers to be called when an application begins to unload.

May be called multiple times to register multiple teardown handlers.

Functions supplied to teardown will be executed in order of registration when
an application begins to unload. Any promise returned from each supplied function
will be waited upon until resolution before calling the next teardown handler.

Pear.argv [#pearargv]

<a name="pear-argv" />

**REMOVED**—use [`Bare.argv`](#bare-argv).

The command line arguments passed to the process when launched.

Pear.pid [#pearpid]

<a name="pear-pid" />

**REMOVED**—use [`Bare.pid`](#bare-pid).

The ID of the current process.

Pear.exitCode [#pearexitcode]

<a name="pear-exitcode" />

**REMOVED**—use [`Bare.exitCode`](#bare-exitcode).

The code that will be returned once the process exits. If the process is exited using `Bare.exit()` without specifying a code, `Bare.exitCode` is used.

Pear.exit(code) [#pearexitcode-1]

<a name="pear-exit" />

**REMOVED**—use [`Bare.exit()`](#bare-exit).

Exits the process with the provided exit code. Follows Pear teardown flow, whereas [`Bare.exit()`](#bare-exit) does not.

Pear.constructor.CUTOVER (Integration) [#pearconstructorcutover-integration]

<a name="pear-constructor-cutover" />

**REMOVED**

{/*
  Shared snippet (content/_snippets/) included via Fumadocs <include> by each Integration
  API section in reference/pear/api.mdx to flag that these APIs may change.
  See: https://www.fumadocs.dev/docs/markdown#include
  */}

<Callout type="warn">
  Integration APIs may change.
</Callout>

For auto-cutover opt-out do `Pear.constructor.CUTOVER = false` in the first-tick.

Cutover signals the end of the application init phase and instructs sidecar to stop buffering critical streams, such as updates.

This stops an internal `ipc.cutover` call to the sidecar, indicating that a manual call will be made later which in turn allows child processes to listen to critical streams without any data loss but the onus is then on child process to call cutover in order free resources in the sidecar.

Pear.constructor.COMPAT (Integration) [#pearconstructorcompat-integration]

<a name="pear-constructor-compat" />

**REMOVED**

{/*
  Shared snippet (content/_snippets/) included via Fumadocs <include> by each Integration
  API section in reference/pear/api.mdx to flag that these APIs may change.
  See: https://www.fumadocs.dev/docs/markdown#include
  */}

<Callout type="warn">
  Integration APIs may change.
</Callout>

Compat-mode opt-in for legacy applications. For JavaScript projects, use the [`pear-runtime` reference](/reference/pear/runtime).

Pear.constructor.RTI (Integration) [#pearconstructorrti-integration]

<a name="pear-constructor-rit" />

**REMOVED**

{/*
  Shared snippet (content/_snippets/) included via Fumadocs <include> by each Integration
  API section in reference/pear/api.mdx to flag that these APIs may change.
  See: https://www.fumadocs.dev/docs/markdown#include
  */}

<Callout type="warn">
  Integration APIs may change.
</Callout>

Runtime Information. Used by additional runtimes to bootstrap runtime state at boot. Used by [`pear-run`](https://github.com/holepunchto/pear-run).

Pear.constructor.IPC (Integration) [#pearconstructoripc-integration]

<a name="pear-constructor-ipc" />

**REMOVED**

{/*
  Shared snippet (content/_snippets/) included via Fumadocs <include> by each Integration
  API section in reference/pear/api.mdx to flag that these APIs may change.
  See: https://www.fumadocs.dev/docs/markdown#include
  */}

<Callout type="warn">
  Integration APIs may change.
</Callout>

Symbol for accessing built-in IPC client. Used by libraries and other integrations.

```js
const ipc = Pear[Pear.constructor.IPC]
```

Pear.constructor.RUNTIME (Integration) [#pearconstructorruntime-integration]

<a name="pear-constructor-runtime" />

**REMOVED**

{/*
  Shared snippet (content/_snippets/) included via Fumadocs <include> by each Integration
  API section in reference/pear/api.mdx to flag that these APIs may change.
  See: https://www.fumadocs.dev/docs/markdown#include
  */}

<Callout type="warn">
  Integration APIs may change.
</Callout>

The runtime binary to spawn when running. Used by [`pear-run`](https://github.com/holepunchto/pear-run). Useful for certain testing scenarios.

Pear.constructor.RUNTIME_ARGV (Integration) [#pearconstructorruntime_argv-integration]

<a name="pear-constructor-runtime_argv" />

**REMOVED**

{/*
  Shared snippet (content/_snippets/) included via Fumadocs <include> by each Integration
  API section in reference/pear/api.mdx to flag that these APIs may change.
  See: https://www.fumadocs.dev/docs/markdown#include
  */}

<Callout type="warn">
  Integration APIs may change.
</Callout>

Used to modify argv passed spawn when running. Used by [`pear-run`](https://github.com/holepunchto/pear-run). Useful for certain testing scenarios.

Pear.restart() [#pearrestart]

<a name="pear-restart" />

**REMOVED**

**REMOVED** Use [`pear-restart`](https://github.com/holepunchto/pear-restart).

Pear.config <Object> [#pearconfig-object]

<a name="pear-config" />

**REMOVED**

**REMOVED** Use [`Pear.app`](#pear-app).

Pear.messages([ pattern ], [ listener ]) -> Iterable [#pearmessages-pattern---listener----iterable]

<a name="pear-messages" />

**REMOVED**

**REMOVED** Use [`pear-messages`](https://github.com/holepunchto/pear-messages).

await Pear.message(<Object>) [#await-pearmessageobject]

<a name="pear-message" />

**REMOVED**

**REMOVED** Use [`pear-message`](https://github.com/holepunchto/pear-message).

Pear.worker <Object> [#pearworker-object]

<a name="pear-worker" />

**REMOVED**

**REMOVED** Use [`pear-run`](https://github.com/holepunchto/pear-run) & [`pear-pipe`](https://github.com/holepunchto/pear-pipe).

Pear.media <Object> [#pearmedia-object]

<a name="pear-media" />

**REMOVED**

**REMOVED** Use [`pear-electron ui.media`](https://github.com/holepunchto/pear-electron#uimedia-object-).

Pear.versions <Async Function> [#pearversions-async-function]

<a name="pear-versions" />

**REMOVED**

Outputs version information.

Example:

```js
{
  platform: {
    key: 'pzcjqmpoo6szkoc4bpkw65ib9ctnrq7b6mneeinbhbheihaq6p6o',
    length: 5949,
    fork: 0
  },
  app: { key: null, length: 0, fork: 0 },
  runtimes: { bare: '1.24.3', pear: '2.2.6' }
}
```

Pear.reload() [#pearreload]

<a name="pear-reload" />

**REMOVED**

**REMOVED** Use `location.reload()` in Desktop apps. No reload in terminal apps.

Pear.updates(listener <Async Function|Function>) =>streamx.Readable [#pearupdateslistener-async-functionfunction-streamxreadable]

<a name="pear-updates" />

**REMOVED**

**REMOVED** Use [`pear-updates`](https://github.com/holepunchto/pear-updates).

const update = await Pear.updated() [#const-update--await-pearupdated]

<a name="pear-updated" />

**REMOVED**

**REMOVED** No option. Do not use.

Pear.wakeups(listener <Async Function|Function>) =>streamx.Readable [#pearwakeupslistener-async-functionfunction-streamxreadable]

<a name="pear-wakeups" />

**REMOVED**

**REMOVED** Use [`pear-wakeups`](https://github.com/holepunchto/pear-wakeups).

Pear.badge(count <Integer|null>) =>Promise<Boolean> [#pearbadgecount-integernull-promiseboolean]

<a name="pear-badge" />

**REMOVED**

**REMOVED** Use [`pear-electron ui.app.badge()`](https://github.com/holepunchto/pear-electron#const-success--await-uiappbadgecount-integernull-).

Pear.tray(options <Object>, listener <AsyncFunction|Function>) => Promise<untray()> [#peartrayoptions-object-listener-asyncfunctionfunction--promiseuntray]

<a name="pear-tray" />

**REMOVED**

**REMOVED** Use [`pear-electron ui.app.tray()`](https://github.com/holepunchto/pear-electron#const-untray--await-uiapptrayoptions-object-listener-function-).

const win = new Pear.Window(entry <String>, options<Object>) [#const-win--new-pearwindowentry-string-optionsobject]

<a name="pear-window" />

**REMOVED**

**REMOVED** Use [`pear-electron ui.Window`](https://github.com/holepunchto/pear-electron#const-win--new-uiwindowentry-string-options-object-).

const view = new Pear.View(options <Object>) [#const-view--new-pearviewoptions-object]

<a name="pear-view" />

**REMOVED**

**REMOVED** Use [`pear-electron ui.View`](https://github.com/holepunchto/pear-electron#const-view--new-uiviewoptions-object-).

global.Bare [#globalbare]

<a name="globalbare" />

<Status level="stable" />

The core JavaScript API of Bare is available through the global `Bare` namespace.

The `Bare` API is designed to be as minimal as possible.

The majority of capabilities are supplied via [Bare modules](/reference/modules/bare-modules).

Bare.platform [#bareplatform]

<a name="bare-platform" />

The identifier of the operating system for which Bare was compiled. The possible values are `android`, `darwin`, `ios`, `linux`, and `win32`.

Bare.arch [#barearch]

<a name="bare-arch" />

The identifier of the processor architecture for which Bare was compiled. The possible values are `arm`, `arm64`, `ia32`, `mips`, `mipsel`, `riscv64`, and `x64`.

Bare.simulator [#baresimulator]

<a name="bare-simulator" />

Whether or not Bare was compiled for a simulator.

Bare.argv [#bareargv]

<a name="bare-argv" />

The command line arguments passed to the process when launched.

Bare.pid [#barepid]

<a name="bare-pid" />

The ID of the current process.

Bare.exitCode [#bareexitcode]

<a name="bare-exitcode" />

The code that will be returned once the process exits. If the process is exited using `Bare.exit()` without specifying a code, `Bare.exitCode` is used.

Bare.version [#bareversion]

<a name="bare-version" />

The Bare version string.

Bare.versions [#bareversions]

<a name="bare-versions" />

An object containing the version strings of Bare and its dependencies.

Bare.exit([code]) [#bareexitcode-1]

<a name="bare-exit" />

Immediately terminate the process or current thread with an exit status of `code` which defaults to `Bare.exitCode`.

Bare.suspend([linger]) [#baresuspendlinger]

<a name="bare-suspend" />

Suspend the process and all threads. This will emit a `suspend` event signalling that all work should stop immediately. When all work has stopped and the process would otherwise exit, an `idle` event will be emitted. If the process is not resumed from an `idle` event listener, the loop will block until the process is resumed.

Bare.wakeup([deadline]) [#barewakeupdeadline]

<a name="bare-wakeup" />

Wake the process and all threads during suspension. This will emit a `wakeup` event signalling that work may be performed until `deadline` is reached.

Bare.idle() [#bareidle]

<a name="bare-idle" />

Immediately suspend the event loop and trigger the `idle` event.

Bare.resume() [#bareresume]

<a name="bare-resume" />

Resume the process and all threads after suspension. This can be used to cancel suspension after the `suspend` event has been emitted and up until all `idle` event listeners have run.

Bare.on('uncaughtException', err) [#bareonuncaughtexception-err]

<a name="bare-on-uncaught-exception" />

Emitted when a JavaScript exception is thrown within an execution context without being caught by any exception handlers within that execution context. By default, uncaught exceptions are printed to `stderr` and the processes aborted. Adding an event listener for the `uncaughtException` event overrides the default behavior.

Bare.on('unhandledRejection', reason, promise) [#bareonunhandledrejection-reason-promise]

<a name="bare-on-unhandled-rejection" />

Emitted when a JavaScript promise is rejected within an execution context without that rejection being handled within that execution context. By default, unhandled rejections are printed to `stderr` and the process aborted. Adding an event listener for the `unhandledRejection` event overrides the default behavior.

Bare.on('beforeExit', code) [#bareonbeforeexit-code]

<a name="bare-on-beforeexit" />

Emitted when the loop runs out of work and before the process or current thread exits. This provides a chance to schedule additional work and keep the process from exiting. If additional work is scheduled, `beforeExit` will be emitted again once the loop runs out of work.

If the process is exited explicitly, such as by calling `Bare.exit()` or as the result of an uncaught exception, the `beforeExit` event will not be emitted.

Bare.on('exit', code) [#bareonexit-code]

<a name="bare-on-exit" />

Emitted when the process or current thread exits. If the process is forcefully terminated from an `exit` event listener, the remaining listeners will not run.

<Callout type="warn">
  Additional work **MUST NOT** be scheduled from an `exit` event listener.
</Callout>

Bare.on('suspend', linger) [#bareonsuspend-linger]

<a name="bare-on-suspend" />

Emitted when the process or current thread is suspended. Any in-progress or outstanding work, such as network activity or file system access, should be deferred, cancelled, or paused when the `suspend` event is emitted and no additional work should be scheduled. A `suspend` event listener may call `Bare.resume()` to cancel the suspension.

Bare.on('wakeup', deadline) [#bareonwakeup-deadline]

<a name="bare-on-wakeup" />

Emitted when the process or current thread wakes up during suspension. Once the process becomes idle, or if the process is not idle by the time `deadline` has passed, the process will suspend itself again and an `idle` event be emitted. A `wakeup` event listener may call `Bare.resume()` to resume the process.

Bare.on('idle') [#bareonidle]

<a name="bare-on-idle" />

Emitted when the process or current thread becomes idle after suspension. After all handlers have run, the event loop will block and no additional work be performed until the process is resumed. An `idle` event listener may call `Bare.resume()` to cancel the suspension.

Bare.on('resume') [#bareonresume]

<a name="bare-on-resume" />

Emitted when the process or current thread resumes after suspension. Deferred and paused work should be continued when the `resume` event is emitted and new work may again be scheduled.

Bare.Addon [#bareaddon]

<a name="bare-addon" />

The `Bare.Addon` namespace provides support for loading native addons, which are typically written in C/C++ and distributed as shared libraries.

Addon.cache [#addoncache]

<a name="bare-addon-cache" />

The global cache of loaded addons.

Addon.host [#addonhost]

<a name="bare-addon-host" />

The target triplet identifying the current addon host.

const url = Addon.resolve(specifier, parentURL[, options]) [#const-url--addonresolvespecifier-parenturl-options]

<a name="bare-addon-resolve" />

Resolve a native addon specifier by searching for a static native addon or dynamic object library matching `specifier` imported from `parentURL`.

Options are reserved.

const addon = Addon.load(url[, options]) [#const-addon--addonloadurl-options]

<a name="bare-addon-load" />

Load a static or dynamic native addon identified by `url`. If `url` is not a static native addon, Bare will instead look for a matching dynamic object library.

Options are reserved.

addon.url [#addonurl]

<a name="bare-addon-url" />

The WHATWG `URL` identifier of the addon.

addon.exports [#addonexports]

<a name="bare-addon-exports" />

The exports of the addon.

Bare.Thread [#barethread]

<a name="bare-thread" />

The `Bare.Thread` provides support for lightweight threads. Threads are similar to workers in Node.js, but provide only minimal API surface for creating and joining threads.

Thread.isMainThread [#threadismainthread]

<a name="bare-thread-ismainthread" />

`true` if the current thread is the main thread.

Thread.self [#threadself]

<a name="bare-thread-self" />

A reference to the current thread as a `ThreadProxy` object. Will be `null` on the main thread.

Thread.self.data [#threadselfdata]

<a name="bare-self-data" />

A copy of or, if shared, reference to the `data` buffer that was passed to the current thread on creation. Will be `null` if no buffer was passed.

const thread = new Thread([filename][, options][, callback]) [#const-thread--new-threadfilename-options-callback]

<a name="bare-new-thread" />

Start a new thread that will run the contents of `filename`. If `callback` is provided, its function body will be treated as the contents of `filename` and invoked on the new thread with `Thread.self.data` passed as an argument.

Options include:

```js
{
  // Optional data to pass to the thread
  data: null,
  // Optional file source, will be read from `filename` if neither `source` nor `callback` are provided
  source: string | Buffer,
  // Optional source encoding if `source` is a string
  encoding: 'utf8',
  // Optional stack size in bytes, pass 0 for default
  stackSize: 0
}
```

const thread = Thread.create([filename][, options][, callback]) [#const-thread--threadcreatefilename-options-callback]

<a name="bare-thread-create" />

Convenience method for the `new Thread()` constructor.

thread.joined [#threadjoined]

<a name="bare-new-thread-joined" />

Whether or not the thread has been joined with the current thread.

thread.join() [#threadjoin]

<a name="bare-new-thread-join" />

Block and wait for the thread to exit.

thread.suspend([linger]) [#threadsuspendlinger]

<a name="bare-new-thread-suspend" />

Suspend the thread. Equivalent to calling `Bare.suspend()` from within the thread.

thread.wakeup([deadline]) [#threadwakeupdeadline]

<a name="bare-new-thread-wakeup" />

Wake the thread. Equivalent to calling `Bare.wakeup()` from within the thread.

thread.resume() [#threadresume]

<a name="bare-new-thread-resume" />

Resume the thread. Equivalent to calling `Bare.resume()` from within the thread.

thread.terminate() [#threadterminate]

<a name="bare-new-thread-terminate" />

Terminate the thread. Equivalent to calling `Bare.exit()` from within the thread.

Bare.IPC [#bareipc]

<a name="bare-ipc" />

Optional streaming communication between an embedder and JavaScript code. By default, `Bare.IPC` is `null`, indicating streaming communication isn't supported. If set by the embedder, `Bare.IPC` is a [`bare-stream`](https://github.com/holepunchto/bare-stream) `Duplex`.

This is how [Pear OTA](/reference/pear/runtime) wires up worker communication: [`PearRuntime.run()`](/reference/pear/runtime#running-workers) returns the embedder-side `IPC` duplex stream, and the spawned worker reads and writes the other end as `Bare.IPC`.

See also [#see-also]

* [`pear-runtime` reference](/reference/pear/runtime)—the supported, non-deprecated way to access these capabilities from a Pear app.
* [Configuration](/reference/pear/configuration)—the `package.json` fields read at the values surfaced in `Pear.config` and `Pear.app.*`.
* [Pear CLI](/reference/pear/cli)—commands that drive the lifecycle these APIs reflect (`pear stage`, `pear seed`, `pear build`).
* [Modules](/reference/modules/pear-modules)—the `pear-*` libraries that supply most application capabilities.
* [Bare modules](/reference/modules/bare-modules)—runtime primitives the API builds on.


# Command Line Interface (CLI)



import { Tabs, Tab } from 'fumadocs-ui/components/tabs'

{/* Maintainer note: "Command source on GitHub" links are pinned to v3.1.0, the release this page documents. Re-pin them when a newer release ships. To find flag-level drift, diff the command definitions between tags:
  gh api "repos/holepunchto/pear/contents/cmd/index.js?ref=<tag>" -H "Accept: application/vnd.github.raw"
  That diff is the complete CLI surface change. Mark anything that differs from a previous release rather than describing it in prose (src/components/version). `Since` = added in that release, `Until` = removed in it; pass `label` to override the badge text. Four tools, by the size of what changed:
  <Since v="x.y.z" />                  inline badge on a sentence. Never hidden — it is the warning.
  <VersionSection since="x.y.z" />     one line directly under a heading; gates that whole section.
  <VersionGate since="x.y.z">…</…>     gates a block that is not a whole section, for example a single <Callout>.
  --flag  Description  [!version since=x.y.z]    gates one row inside a fenced help block.
  Add the release to DOCS_VERSIONS in src/lib/docs-versions.ts when it changes the documented surface, or it will not appear in the dropdown.

  Commands are grouped by task (Building and staging, Production releases, ...) rather than listed in cmd/index.js order — see the `##` headings below. Keep new commands in the group that matches their role, and keep the four "no direct replacement" removals (presets/shift/drop/init) together at the end rather than scattered near unrelated commands. */}

<Status level="stable" />

The Command Line Interface is the primary interface for Pear Development.

<Callout type="info">
  This page tracks **Pear 3.1.0**. Several commands were removed in v3—most notably `pear run`, which is replaced by embedding the **[Pear OTA](/reference/pear/runtime)** (`pear-runtime`) library. Removed commands are kept below with a badge and migration guidance.

  Anything a release adds or removes carries an inline badge—<Since v="3.1.0" /> or <Until v="3.1.0" />—so you can tell whether your build has it. Run `pear versions` to check what you are on, and see the [Release Overview](/release-overview) for the full history.
</Callout>

Install & upgrade [#install--upgrade]

<a name="install" />

The fastest way to install Pear is the installer at **[install.pears.com](https://install.pears.com)**—it also works via `npx` if you'd rather go through npm:

<Tabs items={['curl (macOS / Linux)', 'irm (Windows)', 'npx', 'docker']}>
  <Tab value="curl (macOS / Linux)">
    ```sh
    curl https://install.pears.com/pear.sh | sh
    ```
  </Tab>

  <Tab value="irm (Windows)">
    ```powershell
    irm https://install.pears.com/pear.ps1 | iex
    ```
  </Tab>

  <Tab value="npx">
    ```sh
    npx pear
    ```
  </Tab>

  <Tab value="docker">
    ```sh
    docker run -it --rm tetherto/pear
    ```
  </Tab>
</Tabs>

This bootstraps Pear onto the system. Complete the setup by following the `PATH` instructions the installer prints, then run `pear` directly. To install it globally through npm instead, use `npm i -g pear`—and every `pear <cmd>` also works as `npx pear <cmd>`, which is handy for running commands from a directory other than the one you installed into. npm and Node.js are only the delivery mechanism: after install, `pear` runs on [Bare](/reference/bare/runtime), not Node.

The [`tetherto/pear`](https://hub.docker.com/r/tetherto/pear) Docker image runs Pear inside Ubuntu 24.04 with `pear` and `pear-install` ready to go—a low-risk way to try out Pear apps without installing anything on the host.

Moving from Pear v2 to v3 [#moving-from-pear-v2-to-v3]

Run `npx pear` to move onto the v3 platform. From v3 on, the CLI is a standalone binary that keeps itself up to date over the air through [Pear OTA](/reference/pear/runtime)—so you no longer reinstall from npm for platform updates. Several commands were removed in v3 (see the <Status level="removed" /> badges below); if your application relied on the removed `pear run` runtime or the global `Pear` API, follow [Migrate from pear run to Pear OTA](/how-to/operate-an-app/migration) and review the [Release Overview](/release-overview).

Scripting with --json [#scripting-with---json]

<a name="json-output" />

Most commands accept `--json`—use it for anything that parses a command's result. The default, human-readable output is meant for a person at a terminal and can change wording or formatting between releases; the JSON shape is the stable contract to script against.

`--json` output is newline-delimited JSON (NDJSON): one object per line, each shaped `{"cmd", "tag", "data"}`. Intermediate tags are command-specific—[`pear changelog --json`](#pear-changelog) tags each release `"changelog"`, for example—so filter on `tag` rather than assuming a fixed number of lines.

Most commands close the stream with a `tag: "final"` object whose `data` carries `success` alongside any result fields, as `pear touch --json` does with `{"success": true, "key": "…", "link": "pear://…"}`. Two exceptions to code defensively around: some commands emit **no** `final` object at all—`pear versions --json` emits only its `platform`, `runtimes`, `libraries`, and `modules` tags—and some emit a bare `final` with no `data`, as `pear multisig keys list --json` does. Treat a missing `success` as "no status reported" rather than as failure.

<Callout type="info">
  [`pear touch`](#pear-touch-flags) is the practical exception: its default output is already nothing but the bare `pear://<key>` link on its own line, so it's safe to consume directly without `--json`—for example `LINK=$(pear touch)`.
</Callout>

For commands that take a subcommand, **where you put `--json` matters—and it is not the same for all of them**, because each command declares the flag at a different level of its tree:

| Command                                          | Position                  | Works                            | Rejected                         |
| ------------------------------------------------ | ------------------------- | -------------------------------- | -------------------------------- |
| [`pear data`](#pear-data), [`pear gc`](#pear-gc) | **before** the subcommand | `pear data --json dht`           | `pear data dht --json`           |
| [`pear multisig`](#pear-multisig)                | **after** the subcommand  | `pear multisig keys list --json` | `pear multisig --json keys list` |

The wrong position is rejected with `✖ Unrecognized Flag: --json`, so a script that guesses will fail loudly rather than silently emit human-readable text.

Building and staging [#building-and-staging]

Generate a link, assemble a deployment folder, and sync it to the network—in that order, since `build` and `stage` both need a link to work with.

pear touch [flags] [#pear-touch-flags]

[Command source on GitHub](https://github.com/holepunchto/pear/blob/v3.1.0/cmd/touch.js)

<a name="pear-touch" />

Creates a Pear link. Pear links hold a key, this is the basis for application discovery.

Default output is just the `pear://<key>` link on its own line—safe to capture directly in a script (`LINK=$(pear touch)`) without needing [`--json`](#json-output).

```text version-lines="2:since:3.1.0"
  --json              Newline delimited JSON output
  --vanity <vanity>   Generate a vanity link with this prefix
  --help|-h           Show help
```

<VersionGate since="3.1.0">
  `--vanity` mines for a key whose z32-encoded form starts with the given prefix. The value must contain only z32 characters—anything else is rejected with `Vanity key must contain only z32 characters`—and generation slows sharply as the prefix grows. Prefixes longer than four characters print a warning, and because it goes to **stderr** rather than stdout, `LINK=$(pear touch --vanity pear)` still captures just the link. <Since v="3.1.0" /> Not available on 3.0.1 or earlier.
</VersionGate>

pear build [flags] [#pear-build-flags]

[Command source on GitHub](https://github.com/holepunchto/pear-build)

<a name="pear-build" />

Create a project deployment folder.

Assembles per-OS [`electron-forge`](https://www.electronforge.io/) makes—one per target architecture—into the multi-architecture **deployment directory** that [`pear stage`](#pear-stage) reads from disk: a `package.json` plus a `by-arch/<platform-arch>/app/` tree.

Each make runs on its own OS, so transfer the per-platform outputs to one machine first, then pass each via its `--<platform-arch>-app` flag. Run `pear build` from **outside** the application source tree (or point `--target` at a sibling folder) so the deployment output is never re-staged into itself—see [stage size increases](/how-to/operate-an-app/manual-deployment/troubleshoot-desktop-releases#pear-stage-shows-huge-size-growth). If you omit `--target`, the directory is auto-named `<name>-<version>` from `package.json`.

<Callout type="info">
  As of Pear v3, `pear build` is provided by the standalone [`pear-build`](https://github.com/holepunchto/pear-build) module and integrated into the CLI.
</Callout>

```
  --package [path]               Path to project package.json
  --target [path]                Target build dir
  --darwin-arm64-app [path]      Path to Mac ARM64 app
  --darwin-x64-app [path]        Path to Mac x64 app
  --linux-arm64-app [path]       Path to Linux ARM64 app
  --linux-x64-app [path]         Path to Linux x64 app
  --win32-x64-app [path]         Path to Windows x64 app
  --win32-arm64-app [path]       Path to Windows ARM64 app
  --ios-arm64 [path]             Path to iOS ARM64 folder (ota bundle and assets)
  --ios-arm64-simulator [path]   Path to iOS ARM64-Simulator folder (ota bundle and assets)
  --ios-x64-simulator [path]     Path to iOS x64-Simulator folder (ota bundle and assets)
  --android-arm64 [path]         Path to Android ARM64 folder (ota bundle and assets)
  --json                         Newline delimited JSON output
  --help|-h                      Show help
```

For the full release walkthrough, see [Deploy a Pear desktop app](/how-to/operate-an-app/manual-deployment/deployment) and [Build desktop distributables](/how-to/operate-an-app/build-and-package/build-desktop-distributables).

pear stage <link> [dir] [#pear-stage-link-dir]

[Command source on GitHub](https://github.com/holepunchto/pear/blob/v3.1.0/cmd/stage.js)

<a name="pear-stage" />

Synchronize local changes to pear hypercores.

To generate a link, see [`pear touch`](#pear-touch-flags).

Pear links hold a key, this is the basis for application discovery.

Outputs diff information and project link.

Each time new changes are staged, the length will increase. This change can be replicated to any peer who know the link and is connected. If they run `pear info <link>`, they will see the `length` update even if the application is not being seeded. Connections can potentially linger after seeding an application but will eventually close.

```
  --dry-run|-d       Execute a stage without writing
  --ignore <paths>   Comma-separated path ignore list
  --purge            Remove ignored files if present in previous stage
  --only <paths>     Filter by paths. Comma-separated
  --truncate <n>     Advanced. Truncate to version length n
  --json             Newline delimited JSON output
  --help|-h          Show help
```

Production releases [#production-releases]

Advance a staged build to a quorum-signed production release, replacing the single-key `pear release` command removed in v3.

pear provision <source-verlink> <target-link> <production-verlink> [#pear-provision-source-verlink-target-link-production-verlink]

[Command source on GitHub](https://github.com/holepunchto/pear/blob/v3.1.0/cmd/provision.js)

<a name="pear-provision" />

Pre-production block sync

Synchronize blocks to a pre-production target link

The target can then be multi-signed against a production link

Use [pear touch](#pear-touch-flags) to generate target link

```
Arguments:
  <source-verlink>       Versioned source link
  <target-link>          Target link to sync to
  <production-verlink>   Versioned link to sync against

Flags:
  --dry-run|-d           Execute provision without writing
  --json                 Newline delimited JSON output
  --help|-h              Show help
```

pear multisig [command] [#pear-multisig-command]

[Command source on GitHub](https://github.com/holepunchto/pear/blob/v3.1.0/cmd/multisig.js)

<a name="pear-multisig" />

Production signing coordination. Gate production releases behind a quorum of signing keys instead of a single machine's key. Since Pear v3 removed the single-key `pear release` command, quorum multisig (together with [`pear provision`](#pear-provision)) is the path to production. See [Set up multisig](/how-to/operate-an-app/multisig/set-up-multisig) and [Sign with multisig](/how-to/operate-an-app/multisig/sign-with-multisig) for the end-to-end flow.

| Command                                         | Description                                                                           |
| ----------------------------------------------- | ------------------------------------------------------------------------------------- |
| `keys get [name=default]`                       | Get a signing key, initializing it if needed (`--secret` also prints the private key) |
| `keys paths [name=default]`                     | Print paths to the public & private key files                                         |
| `keys list`                                     | List signing keys                                                                     |
| `keys add <name> <public-key> [private-key]`    | Import a signing keypair or add a known public key                                    |
| `keys remove <name>`                            | Remove a signing key                                                                  |
| `link`                                          | Print the project multisig link (derived from the `multisig` field in `pear.json`)    |
| `request <verlink>`                             | Create a multisig request from a versioned source link                                |
| `sign <request> [name=default]`                 | Sign a multisig request with a local signing key                                      |
| `verify <source-link> <request> [...responses]` | Verify the request and responses (commit dry-run)                                     |
| `commit <source-link> <request> [...responses]` | Apply signatures to sync the source drive to the multisig drive (go live)             |

```text version-lines="4:since:3.1.0"
  --config [./pear.json]        Config file path
  --peer-update-timeout <ms>    Peer update timeout in ms (request, verify, commit)
  --force                       Skip sanity checks (request)
  --vanity <vanity>             Vanity link prefix (link)
  --json                        Newline delimited JSON output
  --help|-h                     Show help
```

<VersionGate since="3.1.0">
  `--vanity` applies to the `link` subcommand only, deriving a multisig link whose key starts with the given prefix. <Since v="3.1.0" /> Not available on 3.0.1 or earlier.
</VersionGate>

pear release <link> [dir] [#pear-release-link-dir]

<a name="pear-release" />

{/* Shared badge + status line for CLI commands removed in Pear v3.
    Single source for the version pair — update it here, not per page. */}

<mark style={{ backgroundColor: '#ff4242', padding: '2px 8px', borderRadius: '4px', fontSize: '0.85em', fontWeight: 500 }}>
  removed
</mark>

Deprecated in Pear v2.6.5, **removed as of Pear v3**.

The single-key release pointer has been replaced by quorum-based production releases. Use [`pear provision`](#pear-provision) to block-sync a pre-production target and [`pear multisig`](#pear-multisig) to cosign it onto a production link.

Distributing and running apps [#distributing-and-running-apps]

Seed a link so peers can fetch it, then install the app it points to. `pear run` launched an app directly from a link in v2; apps now embed [Pear OTA](/reference/pear/runtime) instead.

pear seed <link> [#pear-seed-link]

[Command source on GitHub](https://github.com/holepunchto/pear/blob/v3.1.0/cmd/seed.js)

<a name="pear-seed" />

Seed project or reseed key.

Specify link to seed a project or a remote link to reseed.

Seeding will sparsely replicate the application. This means the entire history of the link is available, but most likely only the most recent version will be replicated.

```
  --no-tty                  Disable tty features
  --stats-interval <ms>     Stats refresh interval in milliseconds
  --json                    Newline delimited JSON output
  --help|-h                 Show help
```

pear install <link> [#pear-install-link]

<a name="pear-install" />

[Command source on GitHub](https://github.com/holepunchto/pear-install)

Install a Pear application—or the Pear platform itself—from a `pear://` link.

`pear install pear://<key>` installs any application built with [`pear build`](#pear-build), pulling it from the swarm and wiring it up locally so it can be launched and kept up to date over the air. It works for both applications and binaries. Installs go directly into the OS application folder.

```
  --only <paths>          Advanced. Filter by app filenames
  --timeout <seconds>     Advanced. Override network timeout (30s)
  --to <dir>              Advanced. Override install target directory
  --dht-bootstrap <nodes> Advanced. Custom DHT bootstrap
  --json                  Newline delimited JSON output
  --help|-h               Show help
```

<Callout type="info">
  As of Pear v3, `pear install` is part of the Pear CLI, provided by the standalone [`pear-install`](https://www.npmjs.com/package/pear-install) module. For example, install an application peer-to-peer with:

  ```
  pear install pear://<key>
  ```

  See [Storage and distribution](/explanation/storage-and-distribution#installing-applications) for the install model and the direction described in [Pear Evolution](https://pears.com/news/pear-evolution/).
</Callout>

pear run [flags] <link|dir> [...app-args] [#pear-run-flags-linkdir-app-args]

<a name="pear-run" />

{/* Shared badge + status line for CLI commands removed in Pear v3.
    Single source for the version pair — update it here, not per page. */}

<mark style={{ backgroundColor: '#ff4242', padding: '2px 8px', borderRadius: '4px', fontSize: '0.85em', fontWeight: 500 }}>
  removed
</mark>

Deprecated in Pear v2.6.5, **removed as of Pear v3**.

Running `pear run` now exits with:

```
pear run has been removed.
Use the pear-runtime module instead: https://www.npmjs.com/package/pear-runtime
```

Applications are now launched by embedding the **[Pear OTA](/reference/pear/runtime)** (`pear-runtime`) library, which provides over-the-air peer-to-peer updates, application storage, and Bare workers. See [Migrate from `pear run` to Pear OTA](/how-to/operate-an-app/migration) for the move.

Inspecting apps and links [#inspecting-apps-and-links]

Read-only lookups against a project, an installed app, or the local platform state—none of these write anything.

pear changelog [link] [#pear-changelog-link]

[Command source on GitHub](https://github.com/holepunchto/pear/blob/v3.1.0/cmd/changelog.js)

<a name="pear-changelog" />

View project changelog

Supply a link to view an application's changelog, read from the `CHANGELOG.md` at its drive root. Any Pear app can ship one—see [Publish a changelog for your app](/how-to/operate-an-app/publish-a-changelog) for the file format and how to stage it.

Shows the Pear platform changelog by default (no link).

```
  --max|-m <n=10>    Maximum entries to show
  --of <semver=^*>   SemVer filter - default: latest major
  --full             Show entire changelog
  --json             Newline delimited JSON output
  --help|-h          Show help
```

`CHANGELOG.md` must open with a header line (typically a `# Title`) followed by one release per `## <version>` heading, newest first, where the first space-separated token of each heading is a SemVer version (a leading `v` is stripped). `--of` filters by that version, defaulting to the latest major; `--full` shows every entry. The parser is the [`pear-changelog`](https://github.com/holepunchto/pear-changelog) module. To fetch the raw file instead, use [`pear dump pear://<key>/CHANGELOG.md`](#pear-dump).

pear info [link] [dir] [#pear-info-link-dir]

[Command source on GitHub](https://github.com/holepunchto/pear/blob/v3.1.0/cmd/info.js)

<a name="pear-info" />

Read project information. `[dir]` is the project directory path (defaults to the current directory).

Supply a link to view application information.

Supply no argument to view platform information.

```
  --metadata       View metadata only
  --manifest       View app manifest only
  --multisig       View multisig info only
  --key            View key only
  --json           Newline delimited JSON output
  --help|-h        Show help
```

With [`--json`](#json-output), output arrives as three tagged objects before the closing `final`:

| Tag          | `data`                                                         |
| ------------ | -------------------------------------------------------------- |
| `retrieving` | `z32`, `onlyShowKey`                                           |
| `keys`       | `project`, `content`, `discovery`                              |
| `info`       | `link`, `verlink`, `name`, `version`, `productName`, `upgrade` |

Filter on `"tag": "info"` for the manifest values and `"tag": "keys"` for the key triplet, rather than relying on ordering. `verlink` is the versioned `pear://<fork>.<length>.<key>` form and was added in 3.1.0.

<Callout type="info">
  <Until v="3.1.0" label="Fixed in 3.1.0" /> On 3.0.1 and earlier, `pear info` and [`pear changelog`](#pear-changelog) can fail outright with `✖ Cannot read properties of undefined (reading 'key')`.
</Callout>

pear dump [flags] <link> <dir> [#pear-dump-flags-link-dir]

[Command source on GitHub](https://github.com/holepunchto/pear/blob/v3.1.0/cmd/dump.js)

<a name="pear-dump" />

Synchronize files from link to dir.

<Callout type="info">
  To dump to stdout, use `-` in place of `<dir>`.
</Callout>

`<link>` can contain a path portion to dump a subset of the files for the Pear application. For example, to dump only the `CHANGELOG.md` from an application into a `dump-dir` directory run:

```
pear dump pear://<key>/CHANGELOG.md dump-dir/
```

```
  --dry-run|-d     Execute a dump without writing
  --checkout <n>   Dump from specified checkout, n is version length
  --only <paths>   Filter by paths. Implies --no-prune. Comma-seperated
  --force|-f       Force overwrite existing files
  --list           List paths at link. Sets <dir> to -
  --no-prune       Prevent removal of existing paths
  --json           Newline delimited JSON output
  --help|-h        Show help
```

<VersionGate since="3.1.0">
  pear cores [#pear-cores]

  <a name="pear-cores" />

  [Command source on GitHub](https://github.com/holepunchto/pear/blob/v3.1.0/cmd/cores.js)

  List platform corestore cores.

  <Callout type="info">
    <Since v="3.1.0" /> On 3.0.1 and earlier, `pear cores` fails with `✖ Unrecognized Argument at index 0 with value cores`.
  </Callout>

  Prints one line per core—the core's `pear://` link, suffixed `(writable)` when this device holds its key pair—followed by a `Total cores: <n> | Writable: <n>` summary, or `No cores` when the store is empty.

  ```
    --json        Newline delimited JSON output
    --help|-h     Show help
  ```

  With [`--json`](#json-output), each core is emitted as a `"tag": "core"` object carrying `{ link, writable }`, and the closing `"tag": "final"` object carries `{ count, writable }`.

  Distinct from [`pear gc cores`](#pear-gc), which *clears* corestore cores rather than listing them.
</VersionGate>

pear data [flags] [command] [#pear-data-flags-command]

[Command source on GitHub](https://github.com/holepunchto/pear/blob/v3.1.0/cmd/data.js)

<a name="pear-data" />

Explore the platform database.

The database contains metadata stored on this device used by the Pear runtime.

| Commands | Description           |
| -------- | --------------------- |
| dht      | DHT known-nodes cache |
| multisig | Multisig records      |

```
--json      Newline delimited JSON output
--help|-h   Show help
```

Platform maintenance and diagnostics [#platform-maintenance-and-diagnostics]

Manage the background sidecar process, reclaim disk space, and check what's installed.

pear sidecar [command] [#pear-sidecar-command]

[Command source on GitHub](https://github.com/holepunchto/pear/blob/v3.1.0/cmd/sidecar.js)

<a name="pear-sidecar" />

The Pear Sidecar is a local-running IPC server for corestore access.

This command instructs any existing sidecar process to shutdown
and then becomes the sidecar.

| Command    | Description                          |
| ---------- | ------------------------------------ |
| `shutdown` | Shut down the running sidecar        |
| `inspect`  | Enable the running sidecar inspector |

```
  --log-level <level>   Level to log at. 0,1,2,3 (OFF,ERR,INF,TRC)
  --help|-h             Show help
```

<VersionGate until="3.1.0">
  <Callout type="info">
    <Until v="3.1.0" /> `--log-labels`, `--log-fields`, and `--log-stacks` were removed in 3.1.0; only `--log-level` remains. All three still work on 3.0.1 and earlier.
  </Callout>
</VersionGate>

`--log-level` accepts either a number (`0`–`3`) or a name (`OFF`, `ERR`, `INF`, `TRC`); it defaults to `INF`.

<VersionGate since="3.1.0">
  Persisted logs [#persisted-logs]

  <a name="sidecar-logs" />

  <Since v="3.1.0" /> Log output is written to a file as well as the terminal, so sidecar errors and stack traces survive the process exiting—previously they were lost once it died.

  * **Location:** `pear.log` in the Pear platform directory.
  * **Rotation:** at 10 MB the current file is moved to `pear.old.log`, replacing any previous `pear.old.log`. Only those two files are ever kept.
  * **Line format:** the level padded to five characters, an ISO-8601 timestamp, the label in brackets, then the message:

    ```
    INF   2026-07-28T18:29:43.869Z [ sidecar ] - Sidecar Booted
    ```

    The terminal prints the same entry with the **timestamp first** (`2026-07-28T18:29:43.869Z INF [ sidecar ] …`), so parse the file rather than captured console output.

  Entries above the active `--log-level` are dropped from both the file and the terminal, so raise the level before reproducing a fault you want captured.
</VersionGate>

pear gc [flags] [command] [#pear-gc-flags-command]

[Command source on GitHub](https://github.com/holepunchto/pear/blob/v3.1.0/cmd/gc.js)

<a name="pear-gc" />

Perform garbage collection and remove unused resources.

| Commands       | Description                                |
| -------------- | ------------------------------------------ |
| sidecars       | Clear running sidecars                     |
| cores `[link]` | Clear corestore cores (optionally by link) |

```
  --json        Newline delimited JSON output
  --help|-h     Show help
```

pear versions [#pear-versions]

[Command source on GitHub](https://github.com/holepunchto/pear/blob/v3.1.0/cmd/versions.js)

<a name="pear-versions" />

Output version information.

```
--modules|-m   Include module versions
--json         Newline delimited JSON output
--help|-h      Show help
```

pear help [command] [#pear-help-command]

[Command source on GitHub](https://github.com/holepunchto/pear/blob/v3.1.0/cmd/index.js)

<a name="pear-help" />

View help for a command. With no argument, prints the full command overview.

Relatedly, running `pear -v` (no command) prints platform version information: the platform key as a versioned `pear://<fork>.<length>.<key>` link where available, plus the SemVer—or the dev root path on development installs. `pear -v` does not itself accept `--json`; for the machine-readable equivalent use [`pear versions --json`](#pear-versions) instead.

Removed without a direct replacement [#removed-without-a-direct-replacement]

These four have no successor command—each is now rejected as an unrecognized command or argument rather than printing removal guidance.

pear presets [flags] [command] [#pear-presets-flags-command]

<a name="pear-presets" />

{/* Shared badge + status line for CLI commands removed in Pear v3.
    Single source for the version pair — update it here, not per page. */}

<mark style={{ backgroundColor: '#ff4242', padding: '2px 8px', borderRadius: '4px', fontSize: '0.85em', fontWeight: 500 }}>
  removed
</mark>

Deprecated in Pear v2.6.5, **removed as of Pear v3**.

Per-command default flags are no longer configurable through the CLI.

pear shift [flags] <source> <destination> [#pear-shift-flags-source-destination]

<a name="pear-shift" />

{/* Shared badge + status line for CLI commands removed in Pear v3.
    Single source for the version pair — update it here, not per page. */}

<mark style={{ backgroundColor: '#ff4242', padding: '2px 8px', borderRadius: '4px', fontSize: '0.85em', fontWeight: 500 }}>
  removed
</mark>

Deprecated in Pear v2.6.5, **removed as of Pear v3**.

Moving user application storage between applications is no longer supported from the CLI.

pear drop [flags] [command] [#pear-drop-flags-command]

<a name="pear-drop" />

{/* Shared badge + status line for CLI commands removed in Pear v3.
    Single source for the version pair — update it here, not per page. */}

<mark style={{ backgroundColor: '#ff4242', padding: '2px 8px', borderRadius: '4px', fontSize: '0.85em', fontWeight: 500 }}>
  removed
</mark>

Deprecated in Pear v2.6.5, **removed as of Pear v3**.

`pear drop` was tied to the removed `pear run` model. See [Manage installed applications](/how-to/manage-installed-applications) for resetting application storage.

pear init [#pear-init]

<a name="pear-init" />

<Status level="removed" />

`pear init` has been removed from the Pear CLI. Unlike `pear run` (which prints a dedicated removal message), `init` is no longer a recognized command, so it is rejected as an unknown argument—`✖ Unrecognized Argument at index 0 with value init`, followed by the top-level usage.

<Callout type="info">
  To scaffold a project, clone the official template instead—[`holepunchto/hello-pear-electron`](https://github.com/holepunchto/hello-pear-electron)—and follow [Start from the hello-pear-electron template](/getting-started/from-a-template/start-from-hello-pear-electron).
</Callout>

See also [#see-also]

* [Release Overview](/release-overview)—the curated record of the v3 command removals and other module changes.
* [Manage installed applications](/how-to/manage-installed-applications)—resetting and inspecting installed apps.
* [Distribute as a binary](/how-to/operate-an-app/build-and-package/distribute-as-binary)—packaging a release built from these commands.
* [Pear OTA reference](/reference/pear/runtime)—the `pear-runtime` library that replaces `pear run`.


# Configuration



<Status level="stable" />

package.json [#packagejson]

<a name="package-json" />

The `package.json` is used by `pear` and [`pear-runtime`](/reference/pear/runtime) for application builds, delivery and updates.

version [#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 [#upgrade]

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

Example:

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

package.json pear field [#packagejson-pear-field]

<a name="pear" />

[Field source on GitHub](https://github.com/holepunchto/pear-state/blob/v1.1.0/index.js#L66)

pear.stage <Object> [#pearstage-object]

<a name="pear-stage" />

Staging configuration options.

pear.stage.entrypoints <Array> [#pearstageentrypoints-array]

<a name="pear-stage-entrypoints" />

[Field source on GitHub](https://github.com/holepunchto/pear-state/blob/v1.1.0/index.js#L83)

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

pear.stage.ignore <Array> [#pearstageignore-array]

<a name="pear-stage-ignore" />

[Field source on GitHub](https://github.com/holepunchto/pear/blob/v2.6.5/subsystems/sidecar/ops/stage.js#L71)

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

pear.stage.only <Array> [#pearstageonly-array]

<a name="pear-stage-only" />

[Field source on GitHub](https://github.com/holepunchto/pear/blob/v3.1.0/subsystems/sidecar/ops/stage.js)

Restrict staging to the given path prefixes—only entries under these paths are staged. Merged with any [`pear stage --only`](/reference/pear/cli#pear-stage) values. Accepts an array (a comma-separated string is also accepted).

pear.stage.purge <Boolean> [#pearstagepurge-boolean]

<a name="pear-stage-purge" />

[Field source on GitHub](https://github.com/holepunchto/pear/blob/v3.1.0/subsystems/sidecar/ops/stage.js)

When `true`, removes entries from a previous stage that are now ignored—the config equivalent of [`pear stage --purge`](/reference/pear/cli#pear-stage). Defaults to `false`.

pear.stage.include <Array> [#pearstageinclude-array]

<a name="pear-stage-include" />

**REMOVED**

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`](#pear-stage-ignore) (or the [`pear.stage.only`](#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> [#pearstagedefer-array]

<a name="pear-stage-defer" />

**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 [#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](/reference/pear/runtime)** (the `pear-runtime` module) instead.

pear.name <String> [#pearname-string]

<a name="pear-name" />

[Field source on GitHub](https://github.com/holepunchto/pear-state/blob/v1.1.0/index.js#L53)

**DEPRECATED**

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

pear.pre <String> [#pearpre-string]

<a name="pear-pre" />

**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`](https://github.com/holepunchto/pear-pipe). The `pipe` carries values encoded with [`compact-encoding`](https://github.com/holepunchto/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> [#pearroutes-objectstring]

<a name="pear-routes" />

[Field source on GitHub](https://github.com/holepunchto/pear-state/blob/v1.1.0/index.js#L86)

**DEPRECATED**

By default, [`pear run`](/reference/pear/cli#pear-run-flags-linkdir-app-args) 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`](/reference/pear/api#pearapproute-string) would contain `/some/path.js` and [`Pear.app.entrypoint`](/reference/pear/api#pearappentrypoint-string) 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):

```json
{
  "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`](/reference/pear/api#pearapproutes-string) would contain `/some/path.js` while [`Pear.app.entrypoint`](/reference/pear/api#pearappentrypoint-string) 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:

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

When `routes: "."` is used in conjunction with [`pear-electron`](https://github.com/holepunchto/pear-electron) and [`pear-bridge`](https://github.com/holepunchto/pear-bridge) [`waypoint`](https://github.com/holepunchto/pear-bridge/#options) option this enables in-app single-page-application routing.

pear.unrouted <Array> [#pearunrouted-array]

<a name="pear-unrouted" />

[Field source on GitHub](https://github.com/holepunchto/pear-state/blob/v1.1.0/index.js#L87)

**DEPRECATED**

Array of paths to exclude from any routing rules in [`pear.routes`](#pearroutes-objectstring).

pear.assets <Object> [#pearassets-object]

<a name="pear-assets" />

[Field source on GitHub](https://github.com/holepunchto/pear/blob/v2.6.5/subsystems/sidecar/lib/pod.js#L650)

**REMOVED**

{/* Maintainer note: re-check once pear-electron ships a Pear v3-compatible release (still on 1.7.x/pear-state@^1.0.2 as of this writing)—if it wires pear.assets through pear-runtime this section should be revisited. */}

Not read as of Pear v3: `pear-state` still carries an `assets` property through to `Pear.config`/`Pear.app`, but nothing populates it from `package.json` any more—it stays the empty default. The `pear gc assets` cleanup command is also gone, and the runtime-side [`Pear.app.assets`](/reference/pear/api#pear-app-assets) property is itself REMOVED. [Pear OTA](/reference/pear/runtime), the v3 embeddable runtime, has no replacement asset-fetching mechanism, and [`pear-electron`](https://github.com/holepunchto/pear-electron)—previously the only consumer of this field—has not been updated for Pear v3.

Historically (Pear ≤ v2), this declared assets to fetch and store on disk on behalf of the application.

By convention namespaces (the object keys) described the asset type.

In particular, Desktop applications used the `ui` namespace to declare UI assets.

Asset objects took 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`](https://github.com/holepunchto/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:

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

The `pear.assets` config wasn't only for User Interface runtimes, such as [`pear-electron`](https://github.com/holepunchto/pear-electron). It applied to any assets that needed to be placed on disk, such as large language model (LLM) assets, prebuilds, and other runtimes or binaries.

Declared assets were updated onto user machines passively while the application was running. Initial assets were fetched on first run by the (pre-v3) embedded Pear runtime; application installers and distributables prefetched them so they were in place before first run.

Assets could be declared directly on `pear.assets` as described, but when used in combination with [`pear.pre`](#pear-pre), installable modules such as [`pear-electron`](https://github.com/holepunchto/pear-electron) could also automatically define assets (and other configuration) on behalf of the application.

Assets were stored in the platform folder, retrieved via `Pear.app.assets[namespace].path`—see [`Pear.app.assets`](/reference/pear/api#pear-app-assets) for the shape this took.

pear.links <Object|Array> [#pearlinks-objectarray]

<a name="pear-links" />

[Field source on GitHub](https://github.com/holepunchto/pear-state/blob/v1.1.0/index.js#L80)

**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`](/reference/pear/api#pearconfig-object)

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.

```json
{
  // ...
  "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> [#peargui-object]

<a name="pear-gui" />

**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](https://github.com/holepunchto/pear-electron#graphical-user-interface-options-)

pear.stage.prefetch <Array> [#pearstageprefetch-array]

**REMOVED**

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

pear.userAgent <string> [#pearuseragent-string]

<a name="pear-useragent" />

**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](https://github.com/holepunchto/pear-electron#graphical-user-interface-options-)

See also [#see-also]

* [Pear CLI](/reference/pear/cli)—the commands that read these fields (`pear stage`, `pear seed`, `pear build`).
* [Pear API](/reference/pear/api)—how `Pear.config` and `Pear.app.*` surface configuration values at runtime.
* [`pear-runtime` reference](/reference/pear/runtime)—embedding the runtime that consumes `package.json` and these fields.
* [Distribute as a binary](/how-to/operate-an-app/build-and-package/distribute-as-binary)—how `pear.stage` and `pear.assets` interact with binary releases.


# Pear OTA



Pear OTA [#pear-ota]

**Pear OTA** is the embeddable over-the-air update library for Pear, provided by the [`pear-runtime`](https://github.com/holepunchto/pear-runtime) module. It enables applications to be deployed peer-to-peer with the [`pear cli`](/reference/pear/cli).

Embedding the `pear-runtime` library into an application provides the following capabilities:

* Over-the-Air Peer-to-peer (OTA P2P) updates
* Application P2P storage management
* Embedded [Bare](/reference/modules/bare-modules) workers

For background on why Pear runs on Bare instead of Node, see [Runtime and languages](/explanation/runtime-and-languages).

Install the [`pear-runtime`](https://github.com/holepunchto/pear-runtime) module into any JS-capable application:

```sh
npm install pear-runtime
```

Package.json Configuration [#packagejson-configuration]

Add an `upgrade` field with a `pear://...` link.

Use `pear touch` to create a link.

Example:

```json
{
  "version": "1.0.0",
  "upgrade": "pear://qxenz5wmspmryjc13m9yzsqj1conqotn8fb4ocbufwtz9mtbqq5o",
  ...
}
```

Instantiate [#instantiate]

In an applications entrypoint create an instance of [`PearRuntime`](https://github.com/holepunchto/pear-runtime/blob/v1.3.1/index.js#L8):

```js
const path = require('path')
const { version, upgrade, name } = require('./package.json')
const PearRuntime = require('pear-runtime')
const dir = path.join('path', 'to', 'app', 'storage') // eg ~/.config/{name}
const app = path.join('application', 'path') // eg process.execPath, may also be null
const pear = new PearRuntime({ dir, version, upgrade, name, app })
pear.on('error', console.error) // network errors etc.
```

Options [#options]

* `dir` `<String>` - Required. Directory to store runtime data (for example the app data dir).
* `upgrade` `<String>` - Required. Pear upgrade link, typically from the `package.json` `upgrade` field.
* `name` `<String>` - Required. The application's product name.
* `version` `<String>` - Current app version; used to decide whether an update should be stored. Defaults to `0.0.0-0`.
* `app` `<String>` - Path to the app bundle (`.app`, `.AppImage`, and so on); used by `applyUpdate()` for bundled apps.
* `updates` `<Boolean>` - Set to `false` to opt out of updates. Defaults to `true`.
* `storage` `<String>` - Override the peer-to-peer application storage path. Defaults to `<dir>/app-storage`.
* `store` `<Corestore>` & `swarm` `<Hyperswarm>` - Supply an existing [Corestore](/reference/helpers/corestore) and [Hyperswarm](/reference/building-blocks/hyperswarm) for update replication. Both must be passed together; when omitted, `pear-runtime` creates and swarms its own.
* `bundled` `<Boolean>` - Whether the application is bundled. Defaults to `!!app`.
* `delay` `<Integer>` - Maximum random delay in milliseconds before a detected update is fetched. Defaults to one hour—see [Tune `delay` for live OTA visibility](/how-to/operate-an-app/manual-deployment/troubleshoot-desktop-releases#tune-pearruntime-delay-for-live-ota-visibility).

Updates [#updates]

An update occurs when a seeded application drive is written to - see [Deployment](/how-to/operate-an-app/manual-deployment/deployment).

Update events are emitted by the instance's `updater`. When an update occurs it emits `updating`, then `updated` once the new version is staged. Apply the staged update with `pear.updater.applyUpdate()`.

```js
pear.updater.on('updating', () => {
  // update view to indicate updating in progress
})
```

```js
pear.updater.on('updated', () => {
  // update view to indicate application updated, then apply it
  pear.updater.applyUpdate()
})
```

Disabling Updates [#disabling-updates]

To opt-out of updates set the `updates` option to `false`:

```js
const pear = new PearRuntime({ dir, version, upgrade, name, app, updates: false })
```

Perhaps support a `--no-updates` flag:

```js
const pear = new PearRuntime({ dir, version, upgrade, name, app, updates: !NO_UPDATES_FLAG })
```

Storage [#storage]

The `dir` option defines where peer-to-peer storage should be kept.

The [`pear.storage`](https://github.com/holepunchto/pear-runtime/blob/v1.3.1/index.js#L24) property holds a path to application storage, this value should be passed as [`Corestore`](/reference/helpers/corestore) storage argument.

For local development, specifying different `dir` values for different running instances allows for local end-to-end flow.

For example, an application could support `--storage|-s` flag:

```js
const pear = new PearRuntime({ dir: STORAGE_FLAG, version, upgrade, name, app })
```

Then pass `-s /tmp/storage-a` to one instance and `-s /tmp/storage-b` to another.

The separate application instances can then interact without conflicting.

Lifecycle [#lifecycle]

Instantiation is eager—`pear-runtime` starts opening its store and swarm as soon as `new PearRuntime(opts)` returns. Await `pear.ready()` to know when that initialization has completed.

```js
await pear.ready()
```

Await `pear.close()` during application teardown to shut down the embedded runtime, including OTA updates:

```js
goodbye(() => pear.close()) // e.g. via graceful-goodbye
```

Running Workers [#running-workers]

To run a Bare worker, [`PearRuntime.run`](https://github.com/holepunchto/pear-runtime/blob/v1.3.1/index.js#L9) takes its entrypoint with any args. It is a **static** method (so it can be called directly, for example from an Electron main process); the instance exposes [`pear.run`](https://github.com/holepunchto/pear-runtime/blob/v1.3.1/index.js#L50) as an alias for it:

```js
const IPC = PearRuntime.run('./path/to/js/file.js', ['some', 'args'])
```

`IPC` is a duplex stream for Inter-Process Communication. Use this to communicate with the worker.

The idea is to put all application peer-to-peer code into a main worker that then acts as a local backend for the application view layer.

```js
const IPC = pear.run('./workers/main.js', [pear.storage])
IPC.on('data', (data) => { 
  console.log('data from worker', data)
})
IPC.write('hello')
```

The `workers/main.js` would then be executed with an embedded Bare runtime.

The other side of the IPC stream can be accessed inside the worker as `Bare.IPC`.

Note how `pear.storage` is passed in as a the first arguments, this can be accessed via `Bare.argv[2]`.

```js
const Corestore = require('corestore')
const storage = Bare.argv[2]

Bare.IPC.on('data', (data) => console.log(data.toString()))

Bare.IPC.write('Hello from worker')

const corestore = new Corestore(storage)
//.. do more with corestore..
```

See also [#see-also]

* [Pear CLI](/reference/pear/cli)—the command-line counterpart to embedding `pear-runtime` in an app.
* [Configuration](/reference/pear/configuration)—the `package.json` fields that govern stage, seed, and update behaviour.
* [Bare modules](/reference/modules/bare-modules)—the runtime workers above are Bare workers.
* [Corestore](/reference/helpers/corestore)—what `pear.storage` plugs into.
* [Deploy your application](/how-to/operate-an-app/manual-deployment/deployment)—production build flow that pairs with this runtime.
* [Runtime and languages](/explanation/runtime-and-languages)—design rationale for running on Bare.


# Drives



Drives is a CLI for creating and synchronizing Hyperdrives. This page documents the public commands installed by [`drives`](https://github.com/holepunchto/drives).

System support [#system-support]

Desktop only: macOS, Linux, and Windows are supported. Drives is not available on Android or iOS.

Install [#install]

```sh
npm i -g drives
```

drives touch [#drives-touch]

[Command source on GitHub](https://github.com/holepunchto/drives/blob/v3.1.0/bin.js)

Create a writable [Hyperdrive](/reference/building-blocks/hyperdrive) and print its public key.

```sh
drives touch [options]
```

Flags:

* `--storage [path]`: storage directory for the local corestore.
  Default: the upstream docs describe `~/.drives`; current CLI code stores the corestore beneath that directory
* `--help`: show help.

Example:

```sh
drives touch
```

drives mirror <src> <dst> [#drives-mirror-src-dst]

[Command source on GitHub](https://github.com/holepunchto/drives/blob/v3.1.0/bin.js)

Mirror a local directory into a [Hyperdrive](/reference/building-blocks/hyperdrive), mirror a Hyperdrive into a local directory, or mirror between two local targets.

```sh
drives mirror <src> <dst> [options]
```

Arguments:

* `<src>`: source drive key or local folder path.
* `<dst>`: destination drive key or local folder path.

Flags:

* `--live`: keep mirroring as changes arrive.
  Default: off
* `--version [v]`: mirror a specific drive version instead of the latest version.
  Default: latest version
* `--storage [path]`: storage directory for the local corestore.
  Default: the upstream docs describe `~/.drives`; current CLI code stores the corestore beneath that directory
* `--help`: show help.

Notes:

* `.DS_Store` is ignored automatically.
* If the source root contains `/.drivesignore`, the ignore patterns are applied during the mirror. The ignore file is read once at startup, so changing it during a `--live` mirror has no effect until you restart the command.
* `drives mirror` makes the destination match the source in either direction, so entries on the destination that do not exist on the source can be deleted—whether the destination is a Hyperdrive or a local folder.

Example:

```sh
drives mirror ./site <drive-key>
```

drives seed [key] [#drives-seed-key]

[Command source on GitHub](https://github.com/holepunchto/drives/blob/v3.1.0/bin.js)

Announce a [Hyperdrive](/reference/building-blocks/hyperdrive) so other peers can download it.

```sh
drives seed [key] [options]
```

Arguments:

* `[key]`: drive public key to seed.
  Default: if omitted, the CLI uses the drive already present in the selected storage namespace

Flags:

* `--storage [path]`: storage directory for the local corestore.
  Default: the upstream docs describe `~/.drives`; current CLI code stores the corestore beneath that directory
* `--help`: show help.

Notes:

* `drives seed` is a long-running command.
* The status output includes the drive key, replication status, and connected peers.

Example:

```sh
drives seed <drive-key>
```

Common workflows [#common-workflows]

Create a drive, mirror a directory into it, and seed it [#create-a-drive-mirror-a-directory-into-it-and-seed-it]

Create a new drive and keep the printed key:

```sh
drives touch
```

Mirror a local directory into that drive:

```sh
drives mirror ./site <drive-key>
```

Seed it so another peer can download it:

```sh
drives seed <drive-key>
```

Mirror a drive back into a local directory [#mirror-a-drive-back-into-a-local-directory]

On another machine, pull the drive into a folder:

```sh
drives mirror <drive-key> ./site-copy
```

Keep a destination up to date with live mirroring [#keep-a-destination-up-to-date-with-live-mirroring]

Push local changes continuously:

```sh
drives mirror --live ./site <drive-key>
```

Or follow a live drive into a local folder:

```sh
drives mirror --live <drive-key> ./site-copy
```

Pull a fixed snapshot by version [#pull-a-fixed-snapshot-by-version]

Mirror a specific version instead of the latest head:

```sh
drives mirror --version 3 <drive-key> ./snapshot
```

Use .drivesignore to skip generated files [#use-drivesignore-to-skip-generated-files]

Create `./site/.drivesignore` in the source directory:

```txt
node_modules/
dist/
*.log
```

Then mirror as usual:

```sh
drives mirror ./site <drive-key>
```

See also [#see-also]

* [Hyperdrive](/reference/building-blocks/hyperdrive)
* [Localdrive](/reference/helpers/localdrive)
* [Mirrordrive](/reference/helpers/mirrordrive)—the sync engine powering `drives mirror`.
* [Hypershell—`hypershell-copy`](/reference/tools/hypershell#hypershell-copy)
* [Hyperbeam—one-to-one pipe for ad-hoc transfers](/reference/tools/hyperbeam#hyperbeam)
* [Pear CLI](/reference/pear/cli)


# Hyperbeam



Hyperbeam creates a one-to-one encrypted pipe between two peers. This page documents the public CLI installed by [`hyperbeam`](https://github.com/holepunchto/hyperbeam).

System support [#system-support]

Desktop only: macOS, Linux, and Windows are supported. Hyperbeam is not available on Android or iOS.

Install [#install]

```sh
npm i -g hyperbeam
```

hyperbeam [#hyperbeam]

[Command source on GitHub](https://github.com/holepunchto/hyperbeam/blob/v3.1.0/bin.js)

Create a new encrypted pipe, or connect to an existing one by passphrase.

```sh
hyperbeam [passphrase] [options]
```

Flags:

* `-r`: restart the listening side with an existing passphrase instead of joining as the second peer.
  Default: off
* `-h, --help`: show help.

Defaults and behavior:

* If you omit `passphrase`, Hyperbeam generates a new passphrase, starts listening, and prints the connect command for the second peer.
* If you provide `passphrase`, Hyperbeam connects to the existing pipe for that passphrase.
* If you provide `passphrase` together with `-r`, Hyperbeam starts listening again with that same passphrase.
* Status messages are written to standard error, while piped data flows through standard input and standard output.

Example:

```sh
hyperbeam
```

Common workflows [#common-workflows]

Create a fresh pipe and connect from a second terminal [#create-a-fresh-pipe-and-connect-from-a-second-terminal]

In the first terminal, start a new Hyperbeam session:

```sh
hyperbeam
```

The command prints a generated passphrase. In the second terminal, join that same pipe:

```sh
hyperbeam <passphrase>
```

Anything written to one side is now available on the other.

Pipe standard input and output through the encrypted tunnel [#pipe-standard-input-and-output-through-the-encrypted-tunnel]

Send data into a new pipe:

```sh
echo "hello world" | hyperbeam
```

Connect from another terminal or machine and read the data:

```sh
hyperbeam <passphrase>
```

Restart the original listening side with the same passphrase [#restart-the-original-listening-side-with-the-same-passphrase]

If the announcing side stops and you want to resume it with the same passphrase, start it again with `-r`:

```sh
hyperbeam <passphrase> -r
```

Use Hyperbeam as a temporary one-to-one transport [#use-hyperbeam-as-a-temporary-one-to-one-transport]

Because the CLI uses a single passphrase per connection pair, Hyperbeam is well suited to short-lived point-to-point transfers where one side creates the session and the other joins it with the printed passphrase.

See also [#see-also]

* [HyperDHT](/reference/building-blocks/hyperdht)
* [Hypershell—`hypershell`](/reference/tools/hypershell#hypershell)
* [Hypertele—persistent TCP proxy](/reference/tools/hypertele#expose-a-local-tcp-service-to-a-client-side-local-port)
* [Hyperssh—`hyperssh`](/reference/tools/hyperssh#hyperssh)
* [Pear CLI](/reference/pear/cli)


# Hypershell



Hypershell is a set of CLI tools for encrypted shell access, file transfer, and local port forwarding over [HyperDHT](/reference/building-blocks/hyperdht). This page documents the public binaries installed by [`hypershell`](https://github.com/holepunchto/hypershell).

System support [#system-support]

Desktop only: macOS, Linux, and Windows are supported. Hypershell is not available on Android or iOS.

Install [#install]

```sh
npm i -g hypershell
```

Installing the package adds four binaries:

* `hypershell-keygen`
* `hypershell-server`
* `hypershell`
* `hypershell-copy`

hypershell-keygen [#hypershell-keygen]

[Command source on GitHub](https://github.com/holepunchto/hypershell/blob/v0.0.15/bin/keygen.js)

Create an Ed25519 seed file for Hypershell and other [HyperDHT](/reference/building-blocks/hyperdht)-based tools.

```sh
hypershell-keygen [-f <filename>] [-c <comment>]
```

Flags:

* `-f <filename>`: write the seed to a specific file.
  Default: if omitted, the CLI prompts and suggests `~/.hypershell/peer`.
* `-c <comment>`: append `# <comment>` to the saved seed line.
* `-h, --help`: show help.

Notes:

* The generated file is written with owner-only permissions on non-Windows systems.
* The command prints the derived public key after creating the seed file.

Example:

```sh
hypershell-keygen -f ~/.hypershell/work-laptop -c "work laptop"
```

hypershell-server [#hypershell-server]

[Command source on GitHub](https://github.com/holepunchto/hypershell/blob/v0.0.15/bin/server.js)

Start a Hypershell server that can expose remote shell access, upload, download, and TCP tunneling.

```sh
hypershell-server [options]
```

Flags:

* `-f <filename>`: server seed key file.
  Default: `~/.hypershell/peer`
* `--firewall <filename>`: file containing allowed public keys, one per line.
  Default: `~/.hypershell/authorized_peers`
* `--disable-firewall`: allow any peer to connect.
  Default: off
* `--protocol <name...>`: restrict the enabled protocols to one or more of `shell`, `upload`, `download`, or `tunnel`.
  Default: all four protocols are enabled
* `--tunnel-host <address...>`: allowlist tunneled destination hosts.
  Default: any host
* `--tunnel-port <port...>`: allowlist tunneled destination ports.
  Default: any port
* `--testnet`: use the local testnet bootstrap node.
  Default: off
* `-h, --help`: show help.

Notes:

* If the key file does not exist, the server creates it automatically.
* If the firewall file does not exist, the server creates it and starts with no authorized peers until you add them.
* The firewall file is watched live, so adding or removing keys takes effect without restarting the server.

Example:

```sh
hypershell-server --protocol tunnel --tunnel-host 127.0.0.1 --tunnel-port 3000
```

hypershell [#hypershell]

[Command source on GitHub](https://github.com/holepunchto/hypershell/blob/v0.0.15/bin/client.js)

Connect to a Hypershell server by raw public key or by a name stored in `~/.hypershell/known_peers`.

```sh
hypershell <server-public-key-or-name> [options]
```

Flags:

* `-f <filename>`: client seed key file.
  Default: `~/.hypershell/peer`
* `-L <[address:]port:host:hostport...>`: open one or more local forwarding tunnels.
  Default: no tunnels
* `--testnet`: use the local testnet bootstrap node.
  Default: off
* `-h, --help`: show help.

Notes:

* If the client key file does not exist, the CLI creates it automatically.
* When the `address:` prefix is omitted from `-L`, the local listener binds to all interfaces.
* A `known_peers` entry lets you use a short alias instead of a raw public key.

Example:

```sh
hypershell home -L 127.0.0.1:2020:127.0.0.1:3000
```

hypershell-copy [#hypershell-copy]

[Command source on GitHub](https://github.com/holepunchto/hypershell/blob/v0.0.15/bin/copy.js)

Upload files or directories to a remote peer, or download them back to the local machine.

```sh
hypershell-copy <source> <target> [options]
```

Remote paths use one of these forms:

* `@name:/path`
* `<public-key>:/path`

Flags:

* `-f <filename>`: client seed key file.
  Default: `~/.hypershell/peer`
* `--testnet`: use the local testnet bootstrap node.
  Default: off
* `-h, --help`: show help.

Notes:

* If the source is remote, the command downloads.
* If the target is remote, the command uploads.
* Directories are copied recursively.

Example:

```sh
hypershell-copy ./backup @home-server:/srv/backups/backup
```

Common workflows [#common-workflows]

Provision a server key and authorize a client [#provision-a-server-key-and-authorize-a-client]

Create a server identity, start the server, then add the client's public key to the firewall file:

```sh
hypershell-keygen -f ~/.hypershell/server
hypershell-server -f ~/.hypershell/server --firewall ~/.hypershell/authorized_peers
```

On the server, add the allowed client public key to `~/.hypershell/authorized_peers`. The running server reloads that file automatically.

Save a peer alias and connect by name [#save-a-peer-alias-and-connect-by-name]

Store a server key in `~/.hypershell/known_peers`, one entry per line in `<name> <public-key>` form. The public key is the value printed by `hypershell-keygen` (or by `hypershell-server` on start)—a 64-character hex string, for example:

```txt
home 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
```

Then connect with the alias:

```sh
hypershell home
```

Upload, download, and tunnel in one toolchain [#upload-download-and-tunnel-in-one-toolchain]

Upload a local directory:

```sh
hypershell-copy ./site @home:/srv/site
```

Download it back later:

```sh
hypershell-copy @home:/srv/site ./site-copy
```

Forward a remote web service to a local port:

```sh
hypershell home -L 127.0.0.1:2020:127.0.0.1:3000
```

See also [#see-also]

* [HyperDHT](/reference/building-blocks/hyperdht)
* [Hyperssh—`hyperssh`](/reference/tools/hyperssh#hyperssh)
* [Hypertele—expose a local TCP service](/reference/tools/hypertele#expose-a-local-tcp-service-to-a-client-side-local-port)
* [Hyperbeam—one-to-one encrypted pipe](/reference/tools/hyperbeam#hyperbeam)
* [Drives—`drives mirror`](/reference/tools/drives#drives-mirror-src-dst)
* [Pear CLI](/reference/pear/cli)


# Hyperssh



Hyperssh routes SSH-style access through [HyperDHT](/reference/building-blocks/hyperdht). This page documents the public binaries installed by [`hyperssh`](https://github.com/holepunchto/hyperssh): `hyperssh` and `hyperssh-fuse`.

System support [#system-support]

Desktop only: macOS, Linux, and Windows are supported. Hyperssh is not available on Android or iOS.

Install [#install]

```sh
npm i -g hyperssh
```

For end-to-end setups, the remote side also needs [Hypertele](/reference/tools/hypertele) so it can expose SSH, SSHFS-backed traffic, or RDP over [HyperDHT](/reference/building-blocks/hyperdht):

```sh
npm i -g hypertele
```

Prerequisites [#prerequisites]

Hyperssh does not generate its own keys. The workflows below need a server seed (for [`hypertele-server`](/reference/tools/hypertele#hypertele-server) on the remote) and, optionally, a client `identity.json`. Generate them with [`hyper-cmd-utils`](https://github.com/holepunchto/hyper-cmd-utils):

```sh
npm i -g hyper-cmd-utils

# Server seed (used as --seed for hypertele-server)
hyper-cmd-util-keygen --gen_seed

# Optional: client identity file (used as -i for hyperssh / hyperssh-fuse)
hyper-cmd-util-keygen --gen_keypair identity.json
```

[`hypertele-server`](/reference/tools/hypertele#hypertele-server) prints the server public key on start; use that as `-s` for `hyperssh` and `hyperssh-fuse`.

hyperssh [#hyperssh]

[Command source on GitHub](https://github.com/holepunchto/hyperssh/blob/v5.0.4/client.js)

Open an SSH session through a peer exposed over [HyperDHT](/reference/building-blocks/hyperdht).

```sh
hyperssh -s <peer-key-or-alias> [options]
```

Flags:

* `-s <peer-key-or-alias>`: peer key or resolved host alias to connect to.
  Default: required
* `-u <username>`: remote username.
  Default: the current local OS username
* `-i <identity.json>`: identity file to use for the client.
  Default: off
* `-e <ssh-command>`: remote command to run instead of opening an interactive shell.
  Default: interactive SSH session
* `--rdp`: open a local RDP proxy instead of spawning `ssh`.
  Default: off
* `--help`: show help.

Notes:

* In normal mode, Hyperssh binds an ephemeral local port and runs `ssh -p <port> <user>@localhost`.
* In `--rdp` mode, Hyperssh exposes a local proxy on port `3389` for an RDP client.

Example:

```sh
hyperssh -s <peer-key> -u alice
```

hyperssh-fuse [#hyperssh-fuse]

[Command source on GitHub](https://github.com/holepunchto/hyperssh/blob/v5.0.4/fuse.js)

Mount a remote filesystem locally through SSHFS over [HyperDHT](/reference/building-blocks/hyperdht).

```sh
hyperssh-fuse -s <peer-key-or-alias> -m <mountpoint> [options]
```

Flags:

* `-s <peer-key-or-alias>`: peer key or resolved host alias to connect to.
  Default: required
* `-u <username>`: remote username.
  Default: the current local OS username
* `-i <identity.json>`: identity file to use for the client.
  Default: off
* `-m <mountpoint>`: local mountpoint for the remote filesystem.
  Default: required
* `--help`: show help.

Notes:

* `hyperssh-fuse` shells out to `sshfs`, so the local machine must already have SSHFS installed.
* As with `hyperssh`, the CLI creates a local ephemeral port and tunnels SSH traffic through it.

Example:

```sh
hyperssh-fuse -s <peer-key> -u alice -m ~/mnt/remote
```

Common workflows [#common-workflows]

SSH into a peer by key or alias [#ssh-into-a-peer-by-key-or-alias]

On the remote machine, expose the local SSH service first:

```sh
hypertele-server --seed <server-seed> -l 22
```

If you already know the peer key, connect directly:

```sh
hyperssh -s <peer-key> -u alice
```

If you manage host aliases in your [HyperDHT](/reference/building-blocks/hyperdht) tooling, use the alias instead:

```sh
hyperssh -s work-server -u alice
```

Run one remote command without opening an interactive shell [#run-one-remote-command-without-opening-an-interactive-shell]

Use `-e` to pass a single command through the SSH session:

```sh
hyperssh -s <peer-key> -u alice -e "uname -a"
```

Mount a remote filesystem locally [#mount-a-remote-filesystem-locally]

Expose the remote SSH service first if it is not already running:

```sh
hypertele-server --seed <server-seed> -l 22
```

Create a mountpoint and then use `hyperssh-fuse`:

```sh
mkdir -p ~/mnt/remote
hyperssh-fuse -s <peer-key> -u alice -m ~/mnt/remote
```

Reach a remote desktop through HyperDHT [#reach-a-remote-desktop-through-hyperdht]

Expose the remote machine's RDP service with [`hypertele-server`](/reference/tools/hypertele#hypertele-server):

```sh
hypertele-server --seed <server-seed> -l 3389
```

Then open the local RDP proxy:

```sh
hyperssh --rdp -s <peer-key>
```

Connect your RDP client to `localhost:3389`.

See also [#see-also]

* [Hypertele—`hypertele-server`](/reference/tools/hypertele#hypertele-server)
* [Hypershell—`hypershell`](/reference/tools/hypershell#hypershell)
* [Hyperbeam—one-to-one encrypted pipe](/reference/tools/hyperbeam#hyperbeam)
* [HyperDHT](/reference/building-blocks/hyperdht)
* [Pear CLI](/reference/pear/cli)


# Hypertele



Hypertele is a [HyperDHT](/reference/building-blocks/hyperdht)-based proxy tool. This page documents the public binaries installed by [`hypertele`](https://github.com/bitfinexcom/hypertele): `hypertele` and `hypertele-server`.

System support [#system-support]

Desktop only: macOS, Linux, and Windows are supported. Hypertele is not available on Android or iOS.

Install [#install]

```sh
npm i -g hypertele
```

Prerequisites [#prerequisites]

The Hypertele workflows below need a server seed, and the identity-backed flows also need a client `identity.json`. Hypertele itself does not generate either; the upstream README pairs Hypertele with [`hyper-cmd-utils`](https://github.com/holepunchto/hyper-cmd-utils), which provides `hyper-cmd-util-keygen`:

```sh
npm i -g hyper-cmd-utils

# Generate a server seed (printed once; keep it secret)
hyper-cmd-util-keygen --gen_seed

# Optional: generate a client identity file
hyper-cmd-util-keygen --gen_keypair identity.json
```

Use the printed seed as `--seed` on the server, and use the server's public key (also printed at server start) as `-s` on the client.

hypertele [#hypertele]

[Command source on GitHub](https://github.com/bitfinexcom/hypertele/blob/0432686b43623706b0345f34b434d324b8b7f587/client.js)

Start a local TCP listener or Unix socket and forward incoming traffic to a remote Hypertele server.

```sh
hypertele (-s <server-peer-key> | -c <conf.json>) (-p <port> | -u <unix-socket>) [options]
```

Flags:

* `-s <server-peer-key>`: remote Hypertele server key.
  Default: required unless supplied by `-c <conf.json>`
* `-p <port>`: local TCP port to listen on.
  Default: required unless `-u` is used
* `-u <unix-socket>`: local Unix socket path to listen on.
  Default: required unless `-p` is used
* `--address <host>`: local bind address.
  Default: `127.0.0.1`
* `-c <conf.json>`: load client settings from a JSON config file.
  Default: off
* `-i <identity.json>`: use a specific identity file for the client.
  Default: off
* `--private`: connect to a private server using its seed instead of its public key.
  Default: off
* `--compress`: enable stream compression.
  Default: off
* `--help`: show help.

Notes:

* Exactly one of `-p` or `-u` must be supplied.
* In normal mode, `-s` is the server public key.
* In `--private` mode, `-s` is the server seed and cannot be combined with `-i`.

Example:

```sh
hypertele -s <server-public-key> -p 8080
```

hypertele-server [#hypertele-server]

[Command source on GitHub](https://github.com/bitfinexcom/hypertele/blob/0432686b43623706b0345f34b434d324b8b7f587/server.js)

Expose a local TCP service or Unix socket to Hypertele clients over [HyperDHT](/reference/building-blocks/hyperdht).

```sh
hypertele-server (--seed <seed> | -c <conf.json>) (-l <service-port> | -u <unix-socket>) [options]
```

Flags:

* `-l <service-port>`: local TCP service port to expose.
  Default: required unless `-u` is used
* `-u <unix-socket>`: local Unix socket path to expose.
  Default: required unless `-l` is used
* `--address <host>`: upstream service host.
  Default: `127.0.0.1`
* `-c <conf.json>`: load server settings from a JSON config file.
  Default: off
* `--seed <seed>`: server seed.
  Default: required unless supplied by config
* `--cert-skip`: disable TLS certificate verification for the proxied upstream connection.
  Default: off
* `--compress`: enable stream compression.
  Default: off
* `--private`: make the server private.
  Default: off
* `--help`: show help.

Notes:

* Exactly one of `-l` or `-u` must be supplied.
* In public mode, the server can use an allowlist from its config file.
* In private mode, clients connect with the seed rather than the public key.

Example:

```sh
hypertele-server --seed <server-seed> -l 3000
```

Common workflows [#common-workflows]

Expose a local TCP service to a client-side local port [#expose-a-local-tcp-service-to-a-client-side-local-port]

Start the server next to the service you want to expose:

```sh
hypertele-server --seed <server-seed> -l 3000
```

Copy the public key from the server output, then consume it on another machine:

```sh
hypertele -s <server-public-key> -p 8080
```

Clients can now connect to `127.0.0.1:8080`, and Hypertele forwards that traffic to the server's local port `3000`.

Run in private mode [#run-in-private-mode]

Use the same seed on both sides:

```sh
hypertele-server --seed <server-seed> -l 3000 --private
hypertele -s <server-seed> -p 8080 --private
```

Private mode avoids publishing a reusable public endpoint.

Drive the proxy from config files [#drive-the-proxy-from-config-files]

Server config:

```json
{
  "seed": "<server-seed>",
  "allow": ["<client-public-key>"]
}
```

Client config:

```json
{
  "peer": "<server-public-key>"
}
```

Then run the two commands with `-c`:

```sh
hypertele-server -c server.json -l 3000
hypertele -c client.json -p 8080
```

See also [#see-also]

* [HyperDHT](/reference/building-blocks/hyperdht)
* [Hyperssh—SSH into a peer](/reference/tools/hyperssh#ssh-into-a-peer-by-key-or-alias)
* [Hypershell—local port forwarding with `-L`](/reference/tools/hypershell#hypershell)
* [Hyperbeam—temporary one-to-one pipe](/reference/tools/hyperbeam#hyperbeam)
* [Pear CLI](/reference/pear/cli)


# Build desktop distributables



This guide shows you how to **produce per-OS distributables** and assemble a **deployment directory** that `pear stage` can consume. It assumes you already ship with Electron tooling (for example Electron Forge) and a Pear release line; for the overall pipeline, read [Release pipeline](/explanation/deployment-releasing-apps-p2p) and [Deploy your application](/how-to/operate-an-app/manual-deployment/deployment).

<Callout type="info">
  To run all of this on hosted runners instead of by hand on each OS, see [Build and sign desktop apps in CI](/how-to/operate-an-app/github-actions/build-and-sign-in-ci)—the [`make-pear-app`](/reference/ci-and-release/github-actions#make-pear-app) action automates the signing and notarization steps below.
</Callout>

Before you begin [#before-you-begin]

* [Node.js](https://nodejs.org/) and npm on each build host (or CI runners) for the target OS.
* [`pear` CLI](/reference/pear/cli) available (`npx pear`) for later `pear build` / `pear stage` steps.
* Branding fields filled in `package.json` (`name`, `productName`, `description`, `author`, `license`) and icons under `build/` where your template expects them.

Checklist (all platforms) [#checklist-all-platforms]

Complete these before you cut binaries you will ship to others:

* Application metadata and icons are **final for the brand** you are releasing under.
* You know which **release line** link (development, staging, rc, etc.) this build will track—see [Release pipeline](/explanation/deployment-releasing-apps-p2p).
* For **macOS** and **Windows** production paths, plan **vendor signing** up front (same certificate across builds for MSIX updates).

macOS [#macos]

1. On a Mac, run `npm run make` (runs `electron-forge make` with darwin makers from [`forge.config.js`](https://github.com/holepunchto/hello-pear-electron/blob/main/forge.config.js)).

2. Unsigned local `.app` bundles are fine for **your machine**; **other Macs** will quarantine unsigned builds. For OTA installs on other machines you need **code signing and notarization** with Apple credentials.

3. Set the environment variables your [`forge.config.js`](https://github.com/holepunchto/hello-pear-electron/blob/main/forge.config.js) reads:

   ```sh
   MAC_CODESIGN_IDENTITY=identity KEYCHAIN_PROFILE=notary-profile npm run make
   ```

   `KEYCHAIN_PROFILE` is the [notarytool keychain profile](https://www.electronforge.io/guides/code-signing/code-signing-macos) name configured on the build host.

4. Maintain `build/entitlements.mac.plist` for Hardened Runtime. Notarized apps require it; the defaults cover Bare native-addon compatibility:

   * `cs.allow-jit`—required for V8/Bare JIT compilation.
   * `cs.allow-unsigned-executable-memory`—required for the Bare runtime.

   Add or remove entitlements here as needed (`com.apple.security.device.camera`, `com.apple.security.device.microphone`, etc.). To load third-party native addons that dynamically link shared libraries built by a different developer, also add `cs.disable-library-validation`.

5. If you are using `pear` ≤ v2.2.15, add a `pear.stage.include` entry that keeps `.github` folders so notarization does not break on stripped resources:

   ```json
   { "pear": { "stage": { "include": [".github"] } } }
   ```

Follow the [Electron Forge macOS code signing guide](https://www.electronforge.io/guides/code-signing/code-signing-macos) for credential setup.

Windows [#windows]

1. Install [Windows SDK](https://developer.microsoft.com/en-us/windows/downloads/windows-sdk/) and [PowerShell 7+](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-windows) on the build host.
2. On Windows, run `npm run make`.
3. Without signing credentials, [`@electron-forge/maker-msix`](https://www.npmjs.com/package/@electron-forge/maker-msix) generates a **self-signed** development certificate matching the `Publisher` field in `build/AppxManifest.xml`. The certificate is cached locally and reused across builds on the same machine, but is **not portable**—building on a different machine or clearing the cert store generates a new one.
4. Edit `build/AppxManifest.xml` so `Name`, `Publisher`, `DisplayName`, and the executable path are correct for your brand. Several of these are declared in multiple locations.
5. Install with `Add-AppxPackage .\out\<AppName>-win32-x64\<AppName>.msix`; uninstall with `Get-AppxPackage -Name <AppName> | Remove-AppxPackage`.
6. For production MSIX, point `WINDOWS_SIGN_HOOK` at a signing hook module that loads your persistent certificate (see [`forge.config.js`](https://github.com/holepunchto/hello-pear-electron/blob/main/forge.config.js)):

   ```sh
   WINDOWS_SIGN_HOOK=path/to/sign-hook.js npm run make
   ```

   Keep the **`Publisher`** field in `AppxManifest.xml` exactly equal to the certificate's `CN`—Windows rejects MSIX updates when the publisher string drifts, breaking OTA. Use the same certificate across every release for the lifetime of the install base.

See [Microsoft's MSIX signing documentation](https://learn.microsoft.com/en-us/windows/msix/package/create-certificate-package-signing).

Linux [#linux]

1. On Linux (or a Linux CI runner), run `npm run make`. The template [`forge.config.js`](https://github.com/holepunchto/hello-pear-electron/blob/main/forge.config.js) also configures Flatpak and Snap makers via `pear-electron-forge-maker-flatpak` and `pear-electron-forge-maker-snap`.
2. Verify the produced AppImage (or your chosen format) launches on a clean VM before you fold it into the deployment directory.

Build the deployment directory [#build-the-deployment-directory]

After you have one build **per target architecture** (darwin arm64/x64, linux arm64/x64, win32 x64, etc.), run `pear build` to merge them into a **single deployment directory** (typically `package.json` + `by-arch/.../app`).

* Run `pear build` **outside** the application source tree, or pass `--target` to a sibling folder—never nest the deployment folder inside a tree that will itself be staged, or sizes will balloon on every stage. See [Troubleshoot desktop releases](/how-to/operate-an-app/manual-deployment/troubleshoot-desktop-releases).

Example shape (paths illustrative only):

```bash skip="signed-build"
pear build --package=./my-app/package.json \
  --darwin-arm64-app ./out/MyApp-darwin-arm64/MyApp.app \
  --darwin-x64-app ./out/MyApp-darwin-x64/MyApp.app \
  --linux-arm64-app ./out/MyApp-linux-arm64/MyApp.AppImage \
  --linux-x64-app ./out/MyApp-linux-x64/MyApp.AppImage \
  --win32-x64-app ./out/MyApp-win32-x64/MyApp.msix \
  --target my-app-1.2.3
```

Then continue with **dry-run** and real **`pear stage`** as described in [Deploy your application](/how-to/operate-an-app/manual-deployment/deployment).

Where to go next [#where-to-go-next]

* [Submit to app stores](/how-to/operate-an-app/build-and-package/submit-to-app-stores)—package the Linux artifacts above for Flathub and the Snap Store.
* [Build and sign desktop apps in CI](/how-to/operate-an-app/github-actions/build-and-sign-in-ci)—automate this whole flow with the `make-pear-app` GitHub Action.
* [Desktop release npm scripts](/reference/ci-and-release/desktop-release-npm-scripts)—common `npm` entry points in sample repos.
* [Troubleshoot desktop releases](/how-to/operate-an-app/manual-deployment/troubleshoot-desktop-releases)—OTA did not land, `pear stage` sizes exploded, or keys were lost.
* [Release pipeline glossary](/explanation/deployment-releasing-apps-p2p#glossary)—terminology for links, lines, and multisig.

<Callout type="info">
  **Related documentation**

  **Getting Started:** [Part 1: Chat](/getting-started/build-a-peer-to-peer-chat/build-a-peer-to-peer-chat) · [Part 2: Production-shaped](/getting-started/build-a-peer-to-peer-chat/reshape-into-a-production-app) · [Part 3: Ship](/getting-started/build-a-peer-to-peer-chat/ship) · [Part 4: Update](/getting-started/build-a-peer-to-peer-chat/update)

  **Operating an app**

  * [Deploy your application](/how-to/operate-an-app/manual-deployment/deployment)
  * [Distribute as a binary](/how-to/operate-an-app/build-and-package/distribute-as-binary)
  * [Manage installed applications](/how-to/manage-installed-applications)
  * [Troubleshoot common issues](/how-to/troubleshooting)
</Callout>


# Distribute as a binary



The default Pear distribution model assumes users already have the `pear` runtime installed; they open `pear://<your-link>` to launch your application. For users who don't—or for app stores that want a self-contained download—Pear supports compiling a small bootstrap binary that pulls the platform and the application from the swarm at first launch. For why this stays small, see [Storage and distribution](/explanation/storage-and-distribution).

The binary is bootstrap-only: it doesn't ship the application's code or assets, only the references needed to fetch them. Once a user has run any version, future releases reach them via the swarm without recompilation—the same delivery channel covered in [Deploy your application](/how-to/operate-an-app/manual-deployment/deployment).

Steps [#steps]

1. **Clone the [`pear-appling`](https://github.com/holepunchto/pear-appling/) template repository.** It's a CMake-based project that produces native binaries for macOS, Linux, and Windows from one source tree. (The repository is archived/read-only upstream, but remains usable as a template.)

2. **Edit `CMakeLists.txt` with your application metadata.** The `add_pear_appling()` call holds the application name (`NAME`), `pear://` link (`ID`), version (`VERSION`), author and description, plus the platform-specific identifiers and signing inputs (`MACOS_IDENTIFIER`, `MACOS_SIGNING_IDENTITY`, `WINDOWS_SIGNING_SUBJECT`, `WINDOWS_SIGNING_THUMBPRINT`, and so on). Replace each placeholder with your own value.

3. **Build the binary** with [`bare-make`](https://github.com/holepunchto/bare-make):

   ```sh
   npm i -g bare-make
   npm i
   bare-make generate
   bare-make build
   ```

   The output is one small binary—typically a few MB—that bootstraps Pear when launched. Run the same steps on each target OS to produce that platform's binary.

4. **Distribute the binary** via your channel of choice (GitHub Releases, an MSI/dmg, an app store, a download link). End users run it; on first launch it replicates the Pear platform and your application, then runs it. On subsequent launches, the swarm delivers any new version of the application—usually no recompile or redistribution is needed.

When this is the wrong tool [#when-this-is-the-wrong-tool]

* **For users who already run Pear**, `pear://<your-link>` is the lighter path: zero compilation, instant updates.
* **For installing apps or binaries from a link**, the [`pear install`](/reference/pear/cli#pear-install) command (or `npx pear-install pear://<key>` on machines without Pear) pulls a build from the swarm without compiling a bootstrap binary yourself. See [Installing applications](/explanation/storage-and-distribution#installing-applications).
* **For mobile distribution**, see the platform-specific paths under [Bare modules](/reference/modules/bare-modules) (Bare iOS / Bare Android)—`pear-appling` targets desktop OSes.


# Build & package



import { Cards, Card } from 'fumadocs-ui/components/card'

Recipes for turning a Pear project into artifacts you can hand to users.

<Cards>
  <Card href="/how-to/operate-an-app/build-and-package/build-desktop-distributables" title="Build desktop distributables" description="Produce signed macOS, Windows, and Linux artifacts for a Pear Electron app." />

  <Card href="/how-to/operate-an-app/build-and-package/distribute-as-binary" title="Distribute as a binary" description="Ship a small bootstrap binary that pulls the latest version from the swarm." />

  <Card href="/how-to/operate-an-app/build-and-package/submit-to-app-stores" title="Submit to app stores" description="Package a desktop app for Flathub and the Snap Store." />
</Cards>


# Submit to app stores



Applications built from the [`hello-pear-electron`](https://github.com/holepunchto/hello-pear-electron#store-submissions) template can also be distributed through platform-specific application stores. This guide covers the two Linux store flows the template supports: **Flathub** (Flatpak) and the **Snap Store**.

Both flows start from the Linux distributables produced by `npm run make`—see [Build desktop distributables](/how-to/operate-an-app/build-and-package/build-desktop-distributables#linux) first. Store distribution complements, rather than replaces, peer-to-peer distribution: apps installed from a store still update over the air through [Pear OTA](/reference/pear/runtime).

Flathub [#flathub]

Flathub packages applications as Flatpaks. This section covers preparing a Flatpak manifest and submitting releases for review.

Prepare the submission [#prepare-the-submission]

Fork the [flathub repository](https://github.com/flathub/flathub) in your GitHub organization, clone it, and create a branch targeting the repository's `new-pr` branch:

```sh skip="store-tooling"
git clone git@github.com:<org>/flathub.git
cd flathub
git checkout -b my-app-submission -t new-pr
```

Create these files in the flathub directory:

* a metainfo file generated with the [AppStream web form](https://www.freedesktop.org/software/appstream/metainfocreator/#/), like [`com.pears.HelloPear.metainfo.xml`](https://github.com/holepunchto/hello-pear-electron/blob/main/flatpak/com.pears.HelloPear.metainfo.xml)
* a Flatpak YAML manifest, like [`com.pears.HelloPear.yml`](https://github.com/holepunchto/hello-pear-electron/blob/main/flatpak/com.pears.HelloPear.yml)

Test the Flatpak locally [#test-the-flatpak-locally]

Install the Flatpak tools:

```sh skip="store-tooling"
sudo apt install flatpak
flatpak remote-add --if-not-exists --user flathub https://dl.flathub.org/repo/flathub.flatpakrepo
flatpak install flathub org.flatpak.Builder
```

In the project directory, build the app for Linux and serve the generated Flatpak artifacts over HTTP:

```sh skip="store-tooling"
python3 -m http.server --directory out/make/
```

In the `flatpak` directory, build and install the Flatpak:

```sh skip="store-tooling"
flatpak run --command=flathub-build org.flatpak.Builder --disable-rofiles-fuse com.pears.HelloPear.yml
flatpak install --user ./repo com.pears.HelloPear
```

Repeat the build command after making any changes to the manifest.

Launch the application from your desktop environment or run it from the CLI:

```sh skip="store-tooling"
flatpak run com.pears.HelloPear
```

Uninstall using:

```sh skip="store-tooling"
flatpak uninstall com.pears.HelloPear
rm -rf ~/.var/app/com.pears.HelloPear
```

If the builds take up too much disk space, clear the build files from the `flatpak` directory:

```sh skip="store-tooling"
rm -rf builddir repo .flatpak-builder
```

Submit for review [#submit-for-review]

After confirming that the Flatpak works:

1. Upload the Flatpak artifacts to a publicly accessible location with versioned URLs, like [this site](https://static.keet.io/downloads/), and update the artifact links in the Flatpak YAML.
2. For verification, upload an empty file to your app website at `https://<app-website>/.well-known/org.flathub.VerifiedApps.txt`.
3. Open a PR on the [flathub repository](https://github.com/flathub/flathub) from your branch, like [this PR](https://github.com/flathub/flathub/pull/8716), and address the review comments.
4. Comment `bot, build` to test building the Flatpak on the Flathub CI.
5. Once the submission is accepted, the Flathub maintainers create a repository in the flathub organization from your submission branch, like [this repository](https://github.com/flathub/io.keet.Keet).
6. Log in to the [Flathub Developer Portal](https://flathub.org/en/developer-portal) to manage the app, and complete verification by copying the token from that page to `https://<app-website>/.well-known/org.flathub.VerifiedApps.txt`.
7. In a few hours the app should be available on Flathub, like [this app](https://flathub.org/en/apps/io.keet.Keet).

If the app doesn't show up on Flathub:

* If the Flathub bot opens an issue on the repository containing build errors, address it.
* If it's unrelated, comment `bot, retry` or open an issue in [Flathub](https://github.com/flathub/flathub/issues) for assistance from the maintainers.
* Follow the build status at [builds.flathub.org](https://builds.flathub.org); app-specific status is at `https://builds.flathub.org/status/<app-id>`.

Automate new releases [#automate-new-releases]

To have the Flathub bot open PRs when new versions of the app are available on your website, follow the [external data checker guide](https://github.com/flathub-infra/flatpak-external-data-checker/#changes-to-flatpak-manifests) and configure it on the `type: archive` source, matching the format of your download site:

```yml skip="manifest-config"
x-checker-data:
  type: html
  url: https://static.keet.io/downloads/
  version-pattern: href="((?:\d+\.)+\d+)/"
  url-template: https://static.keet.io/downloads/$version/Keet-arm64-flatpak.tar.gz
```

Snap [#snap]

Snap packages applications for Linux and distributes them through the Snap Store. This section covers preparing a Snap package, testing it locally, and publishing releases.

Build and test the Snap [#build-and-test-the-snap]

Install the Snap tools:

```sh skip="store-tooling"
snap install snapcraft --classic
snap install lxd
sudo usermod -a -G lxd $USER
sudo lxd init --auto
```

In the project directory, build the app for Linux—this creates a `.snap` package in the `out/make` directory. Install it:

```sh skip="store-tooling"
snap install out/make/hellopear_1.0.0_arm64.snap --devmode
```

After making changes to the Snap configuration, rebuild the application and reinstall the generated Snap.

Launch the application from your desktop environment or run it from the CLI:

```sh skip="store-tooling"
hellopear
```

Uninstall using:

```sh skip="store-tooling"
snap remove hellopear
```

If the builds take up too much disk space, clean the build container:

```sh skip="store-tooling"
cd out
snapcraft clean
```

Refer to the [Electron Forge Snap Maker documentation](https://github.com/holepunchto/electron-forge-maker-snap) to configure the Snap.

Publish to the Snap Store [#publish-to-the-snap-store]

After confirming that the Snap works:

1. Create your developer account at [login.ubuntu.com](https://login.ubuntu.com/) and log in.
2. Log in from your terminal with `snapcraft login`.
3. Register your Snap using [the name](https://documentation.ubuntu.com/snapcraft/9.0/how-to/publishing/register-a-snap/#name-your-snap) with `snapcraft register <snap-name>`, or `snapcraft register --private <snap-name>` for a private Snap.
4. Publish with `snapcraft upload --release=stable <my-snap>.snap`.
5. Check the release status with `snapcraft status <snap-name>`.

Snapcraft will guide you with the next steps if a release fails. Once released, the Snap is available on the Snap Store at `https://snapcraft.io/<snap-name>`:

```sh skip="store-tooling"
snap install <snap-name>
<snap-name>
```

Automate Snap releases [#automate-snap-releases]

To publish from CI, first create a credentials file:

```sh skip="store-tooling"
snapcraft export-login <credentials-filename>
```

Set the contents of the file as a secret in your automation pipeline and authenticate Snap with:

```sh skip="store-tooling"
export SNAPCRAFT_STORE_CREDENTIALS=$(cat <credentials-filename>)
```

Upload a new Snap release to the desired channel (for example, `stable`):

```sh skip="store-tooling"
snapcraft upload <snap-name>.snap --release stable
```

See also [#see-also]

* [Build desktop distributables](/how-to/operate-an-app/build-and-package/build-desktop-distributables)—produce the Linux artifacts these store flows package.
* [Deploy your application](/how-to/operate-an-app/manual-deployment/deployment)—the peer-to-peer release flow that store installs update through.
* [Distribute as a binary](/how-to/operate-an-app/build-and-package/distribute-as-binary)—direct binary distribution without a store.
* [Pear OTA](/reference/pear/runtime)—how store-installed apps keep updating over the air.


# Build and sign desktop apps with GitHub Actions



This is the CI automation of [Build desktop distributables](/how-to/operate-an-app/build-and-package/build-desktop-distributables). Instead of running `npm run make` by hand on a Mac, a Windows box, and a Linux box and wiring signing credentials into each, you run one matrix job that uses the [`make-pear-app`](/reference/ci-and-release/github-actions#make-pear-app) action on hosted runners for every OS at once.

`make-pear-app` runs your `npm run make` script—the same [`forge.config.js`](https://github.com/holepunchto/hello-pear-electron/blob/main/forge.config.js) the manual guide uses—and sets the signing environment variables that file reads. It imports the Apple certificate and stores notarytool credentials on macOS, installs the certificate on Windows, sets up Snapcraft on Linux, then uploads each platform's output as a build artifact.

{/*
  Shared snippet (content/_snippets/) included via Fumadocs <include> by guides that
  run `pear` CLI commands, so readers can install the CLI before following the steps.
  See: https://www.fumadocs.dev/docs/markdown#include
  */}

<Callout type="info">
  **Need the `pear` CLI?** Install it from **[install.pears.com](https://install.pears.com)**, or prefix any command below with `npx`. See [Install & upgrade](/reference/pear/cli#install) for details.
</Callout>

Before you begin [#before-you-begin]

You need:

1. A [`hello-pear-electron`](https://github.com/holepunchto/hello-pear-electron)-shaped repository whose `npm run make` produces distributables (see [Desktop release npm scripts](/reference/ci-and-release/desktop-release-npm-scripts)).
2. Signing credentials stored as [repository secrets](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions):
   * **macOS**: base64-encoded distribution certificate (`.p12`) and its password, the code-signing identity, and notarization credentials—either App Store Connect API key (`appstore_connect`) or Apple ID + app-specific password (`apple_id_password`).
   * **Windows**: either a certificate SHA-1 thumbprint (`windows_cert_sha1`) or a base64-encoded `.pfx` and its password (`windows_cert_pfx`).
3. The `pear://` link this build should track as its `channel`/`upgrade_key` (see [Set the upgrade link](/how-to/operate-an-app/manual-deployment/deployment#1-set-the-upgrade-link)).

Add the workflow [#add-the-workflow]

Create `.github/workflows/build.yml`. Check out the repository, then run [`make-pear-app`](/reference/ci-and-release/github-actions#make-pear-app) per OS (it handles `setup-node` and `npm ci` internally):

```yaml skip="ci-config"
name: Build desktop app

on:
  workflow_dispatch:
  push:
    tags: ['v*']

jobs:
  build:
    strategy:
      fail-fast: false
      matrix:
        os: [macos-latest, windows-latest, ubuntu-latest]
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/checkout@v4
      - id: make
        uses: holepunchto/actions/make-pear-app@v1
        with:
          channel: production
          upgrade_key: ${{ vars.PEAR_UPGRADE_KEY }}

          # macOS signing + notarization
          macos_certificate_base64: ${{ secrets.MACOS_CERTIFICATE_BASE64 }}
          macos_p12_password: ${{ secrets.MACOS_P12_PASSWORD }}
          macos_codesign_identity: ${{ secrets.MACOS_CODESIGN_IDENTITY }}
          macos_notarization_method: appstore_connect
          macos_api_key_base64: ${{ secrets.MACOS_API_KEY_BASE64 }}
          macos_api_key_id: ${{ secrets.MACOS_API_KEY_ID }}
          macos_api_issuer: ${{ secrets.MACOS_API_ISSUER }}

          # Windows signing
          windows_signing_method: windows_cert_pfx
          windows_cert_pfx_base64: ${{ secrets.WINDOWS_CERT_PFX_BASE64 }}
          windows_cert_password: ${{ secrets.WINDOWS_CERT_PASSWORD }}
```

The action validates its inputs per OS and fails fast if a required signing field is missing, so the macOS leg only needs the macOS inputs, the Windows leg only the Windows ones, and the Linux leg needs neither.

Choose the signing methods [#choose-the-signing-methods]

`make-pear-app` branches on two method inputs that mirror the manual environment variables in [Build desktop distributables](/how-to/operate-an-app/build-and-package/build-desktop-distributables):

* **`macos_notarization_method`**

  * `appstore_connect`—requires `macos_api_key_base64`, `macos_api_key_id`, `macos_api_issuer`.
  * `apple_id_password`—requires `macos_apple_id`, `macos_apple_password`, `macos_apple_team_id`.

  Either way you also pass `macos_certificate_base64`, `macos_p12_password`, and `macos_codesign_identity`. The action imports the cert into a temporary keychain and stores notarytool credentials—the CI equivalent of setting `MAC_CODESIGN_IDENTITY` and `KEYCHAIN_PROFILE`.
* **`windows_signing_method`**

  * `windows_cert_sha1`—requires `windows_cert_sha1` (a thumbprint already on the runner).
  * `windows_cert_pfx`—requires `windows_cert_pfx_base64` and `windows_cert_password`; the action imports the `.pfx` and derives the thumbprint.

  This drives `WINDOWS_CERT_SHA1` and points `WINDOWS_SIGN_HOOK` at the action's bundled hook. Keep the `Publisher` in `build/AppxManifest.xml` equal to the certificate `CN` or MSIX OTA updates break—see [the Windows section](/how-to/operate-an-app/build-and-package/build-desktop-distributables#windows).

On Linux, set `linux_set_up_snapcraft: false` if you do not build a Snap and want to skip the Snapcraft/LXD setup.

Use the artifacts [#use-the-artifacts]

`make-pear-app` exposes an `artifact-links` output and uploads each OS's build as a workflow artifact. Collect them in a follow-up job, run [`pear build`](/how-to/operate-an-app/build-and-package/build-desktop-distributables#build-the-deployment-directory) to assemble the multi-architecture deployment directory, then `pear stage` it as in [Deploy your application](/how-to/operate-an-app/manual-deployment/deployment).

To make publishing fully hands-off, hand the deployment directory to [`pear-ci`](/how-to/operate-an-app/github-actions/publish-with-github-actions): `make-pear-app` produces the signed build, and `pear-ci` stages it to a stable `pear://` link on every push.

See also [#see-also]

* [Build desktop distributables](/how-to/operate-an-app/build-and-package/build-desktop-distributables)—the manual per-OS make, signing, and notarization this automates.
* [Publish with GitHub Actions](/how-to/operate-an-app/github-actions/publish-with-github-actions)—stage the resulting build with `pear-ci`.
* [Holepunch GitHub Actions](/reference/ci-and-release/github-actions)—every shared action, inputs, and outputs.
* [Deploy your application](/how-to/operate-an-app/manual-deployment/deployment)—covers `pear build`, `pear stage`, and release lines.
* [Desktop release npm scripts](/reference/ci-and-release/desktop-release-npm-scripts)—the `npm run make` entry point the action calls.


# CI/CD with GitHub Actions



import { Cards, Card } from 'fumadocs-ui/components/card'

Recipes for automating the release flow in CI.

<Cards>
  <Card href="/how-to/operate-an-app/github-actions/publish-with-github-actions" title="Publish with GitHub Actions" description="Auto-publish and update a Pear app from CI with the pear-ci GitHub Action." />

  <Card href="/how-to/operate-an-app/github-actions/build-and-sign-in-ci" title="Build and sign desktop apps with GitHub Actions" description="Build, code-sign, and notarize a Pear Electron app on macOS, Windows, and Linux runners." />
</Cards>


# Publish with GitHub Actions



The simplest way to publish and update a Pear app is to let CI do it. The [`pear-ci` GitHub Action](https://github.com/holepunchto/actions/blob/main/pear-ci/action.yml) stages a directory from your repository into a [Hyperdrive](/reference/building-blocks/hyperdrive) on every push, so shipping a new version is just a `git push`. There is no local `pear touch`, `pear seed`, or `pear stage` to run by hand, and nothing to keep online between releases.

This is the goal-oriented recipe. If you need the full-control flow—release lines, provision, and multisig—use [Deploy your application](/how-to/operate-an-app/manual-deployment/deployment) instead. The two are not mutually exclusive: CI is the fast path for development and staging links, while the manual flow gives you production gating.

{/*
  Shared snippet (content/_snippets/) included via Fumadocs <include> by guides that
  run `pear` CLI commands, so readers can install the CLI before following the steps.
  See: https://www.fumadocs.dev/docs/markdown#include
  */}

<Callout type="info">
  **Need the `pear` CLI?** Install it from **[install.pears.com](https://install.pears.com)**, or prefix any command below with `npx`. See [Install & upgrade](/reference/pear/cli#install) for details.
</Callout>

How it works [#how-it-works]

The action wraps the [`pear-ci`](https://www.npmjs.com/package/pear-ci) tool. On each run it:

1. Installs `pear-ci` and fetches the committed `ci/snapshot.json` from `main`.
2. Mirrors your `target` directory into a [Hyperdrive](/reference/building-blocks/hyperdrive) whose key is **derived deterministically from `primary-key` + `namespace`**, then replicates over [Hyperswarm](/reference/building-blocks/hyperswarm) until connected peers have synced.
3. Commits the updated `ci/snapshot.json` back to `main` (or opens a PR if the push is rejected).

Two properties make this work well in CI:

* **The `pear://` link is stable.** Because the drive key comes from the secret primary key plus the namespace, every run stages to the same link. You set that link once as your app's `upgrade` field and every push updates it.
* **The snapshot replaces persistent storage.** `ci/snapshot.json` records each core's length, so the next run only syncs what changed instead of re-uploading the whole drive or persisting a full [Corestore](/reference/helpers/corestore) between jobs.

<Mermaid
  chart="flowchart LR
  push[&#x22;git push to main&#x22;] --> action[&#x22;pear-ci action&#x22;]
  action --> snap[&#x22;fetch ci/snapshot.json&#x22;]
  snap --> stage[&#x22;stage target into Hyperdrive&#x22;]
  stage --> sync[&#x22;replicate over Hyperswarm&#x22;]
  sync --> commit[&#x22;commit updated snapshot.json&#x22;]
  stage --> link[&#x22;stable pear:// link&#x22;]"
/>

Before you begin [#before-you-begin]

You need:

1. A GitHub repository for your app.
2. The directory you want to publish committed to that repo—typically the [`pear build`](/how-to/operate-an-app/build-and-package/build-desktop-distributables#build-the-deployment-directory) deployment directory, or your app source if you stage the runnable project directly.
3. A 32-byte hex **primary key** (created below) stored as a repository secret.
4. A **namespace** name (any string of letters, numbers, dots, hyphens, or underscores) that identifies this drive.

Generate and store the primary key [#generate-and-store-the-primary-key]

Generate a random 32-byte key:

```bash skip="manual-walkthrough"
openssl rand -hex 32
# 9f2c... (64 hex characters)
```

Add it to your repository as a secret named `PEAR_PRIMARY_KEY` (**Settings → Secrets and variables → Actions → New repository secret**).

<Callout type="warning">
  The primary key is the **write key** for your drive—anyone who has it can publish updates that your users will receive over the air. Keep it in a repository (or organization) secret, never commit it, and rotate it if it leaks. Rotating the key changes the derived `pear://` link, so you would need to update the `upgrade` field and re-onboard users.
</Callout>

Add the workflow [#add-the-workflow]

Create `.github/workflows/pear-ci.yml`:

```yaml skip="ci-config"
name: Publish with pear-ci

on:
  push:
    branches: [main]

# pear-ci commits the updated snapshot back to main
permissions:
  contents: write
  pull-requests: write

concurrency:
  group: pear-ci
  cancel-in-progress: false

jobs:
  stage:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: holepunchto/actions/pear-ci@main
        with:
          primary-key: ${{ secrets.PEAR_PRIMARY_KEY }}
          namespace: my-app
          target: dist
          dry-run: false
```

Set `namespace` to your chosen name and `target` to the repo-relative path of the directory you want to publish. The `concurrency` group prevents two runs from racing to commit `ci/snapshot.json` at the same time.

For the full list of inputs and outputs, see the [`pear-ci` GitHub Action reference](/reference/ci-and-release/pear-ci-action).

Wire up the pear:// link [#wire-up-the-pear-link]

The first run prints the drive key it stages to:

```text skip="sample-output"
starting stage for key <drive-key>
```

That key is your app's `pear://` link. Set it as the [`upgrade`](/reference/pear/configuration) field so installed builds poll it for updates:

```bash skip="manual-walkthrough"
npm pkg set upgrade=pear://<drive-key>
```

This is the same `upgrade` link that the [manual deploy flow](/how-to/operate-an-app/manual-deployment/deployment#1-set-the-upgrade-link) sets—the only difference is that CI now stages to it for you. Because the key is deterministic, you only do this once.

Dry-run first [#dry-run-first]

Before publishing for real, set `dry-run: true` in the workflow. The action computes and logs the file-by-file diff without writing anything to the drive—the same safety check as `pear stage --dry-run`:

```yaml skip="ci-config"
        with:
          primary-key: ${{ secrets.PEAR_PRIMARY_KEY }}
          namespace: my-app
          target: dist
          dry-run: true
```

Read the diff in the Actions log. Look for the files you expect, no surprise additions (`.DS_Store`, editor swap files, secrets), and sensible byte counts. When it looks right, set `dry-run: false` and push. Every subsequent push to `main` then stages and publishes automatically.

Producing the build to stage [#producing-the-build-to-stage]

`pear-ci` stages whatever is in `target`. To build and sign that directory on CI first, pair it with [`make-pear-app`](/reference/ci-and-release/github-actions#make-pear-app): one job produces signed, notarized distributables (see [Build and sign desktop apps in CI](/how-to/operate-an-app/github-actions/build-and-sign-in-ci)), and `pear-ci` stages the assembled deployment directory to your stable `pear://` link.

See also [#see-also]

* [`pear-ci` GitHub Action reference](/reference/ci-and-release/pear-ci-action)—every input, output, and the underlying CLI.
* [Holepunch GitHub Actions](/reference/ci-and-release/github-actions)—the other shared actions, including `make-pear-app`.
* [Build and sign desktop apps in CI](/how-to/operate-an-app/github-actions/build-and-sign-in-ci)—build and sign the artifacts `pear-ci` stages.
* [Deploy your application](/how-to/operate-an-app/manual-deployment/deployment)—the full manual flow with release lines, provision, and multisig.
* [Ship your app](/getting-started/build-a-peer-to-peer-chat/ship)—the type-along walkthrough of staging by hand.
* [Configuration](/reference/pear/configuration)—the `upgrade` field and other `package.json` settings.
* [Release pipeline](/explanation/deployment-releasing-apps-p2p)—the conceptual picture of staging and OTA updates.
* [Troubleshoot desktop releases](/how-to/operate-an-app/manual-deployment/troubleshoot-desktop-releases)—when an update does not reach peers.


# Deploy your application



This is the operator reference for the desktop release flow. The conceptual picture lives in [Release pipeline](/explanation/deployment-releasing-apps-p2p); the type-along path is in [Ship your app](/getting-started/build-a-peer-to-peer-chat/ship) and [Deploy over-the-air updates](/getting-started/build-a-peer-to-peer-chat/update). Use this page when you need exact commands for the eight **Foundational Steps** documented in [`hello-pear-electron`'s Foundational Steps](https://github.com/holepunchto/hello-pear-electron#foundational-steps).

{/*
  Shared snippet (content/_snippets/) included via Fumadocs <include> by the full-control
  release pages, pointing readers at the CI shortcut for the simple publish/update path.
  See: https://www.fumadocs.dev/docs/markdown#include
  */}

<Callout type="info">
  For the simplest publish/update workflow, let CI stage for you. [Publish with GitHub Actions](/how-to/operate-an-app/github-actions/publish-with-github-actions) turns shipping a new version into a `git push`. This page is the full-control path when you need release lines, provision, and multisig.
</Callout>

Each step is independent—you can stop at any point if your project is still in proof-of-concept. The first three (`touch`, `upgrade link`, `version`) are setup; the next four (`make`, `pear build`, `stage`, `provision`) are the **release cycle** you repeat for every shipment; the final step (`multisig`) gates production.

0. Touch and seed [#0-touch-and-seed]

Mint a new `pear://` link backed by a fresh [Hypercore](/reference/building-blocks/hypercore):

```sh skip="release-flow"
pear touch
# pear://qxenz5wmspmryjc13m9yzsqj1conqotn8fb4ocbufwtz9mtbqq5o
```

Announce the link on the swarm:

```sh skip="release-flow"
pear seed pear://qxenz5wmspmryjc13m9yzsqj1conqotn8fb4ocbufwtz9mtbqq5o
```

Run `pear seed` on at least one always-online machine so peers can fetch updates while developer laptops are asleep. On every other machine that should reseed, run the same command—additional seeders raise availability and shorten the [first-connection latency](/how-to/operate-an-app/manual-deployment/troubleshoot-desktop-releases#seeder-came-online-after-the-client).

1. Set the upgrade link [#1-set-the-upgrade-link]

Every shipped build polls a `pear://` link from its `package.json` `upgrade` field. Set it once per [release line](/explanation/deployment-releasing-apps-p2p#release-lines):

```sh skip="release-flow"
npm pkg set upgrade=pear://qxenz5wmspmryjc13m9yzsqj1conqotn8fb4ocbufwtz9mtbqq5o
```

Or edit `package.json` directly:

```json skip="release-flow"
{
  "version": "1.0.0",
  "upgrade": "pear://qxenz5wmspmryjc13m9yzsqj1conqotn8fb4ocbufwtz9mtbqq5o"
}
```

For production, set `upgrade` to the **multisig** link (see [Set up multisig](/how-to/operate-an-app/multisig/set-up-multisig)). For internal preview, set it to the **provision** link ([step 6](#6-provision)). For developer-team builds, set it to a **stage** link ([step 5](#5-stage)). The link decides which release line a binary follows.

2. Version [#2-version]

[`pear-runtime`](/reference/pear/runtime) only swaps the application drive if the new build advertises a higher version:

```sh skip="release-flow"
npm version [<newversion> | major | minor | patch | premajor | preminor | prepatch | prerelease]
```

`npm version` rewrites `package.json` and creates a `vX.Y.Z` git tag. If this is the first release, leave `version` at `1.0.0` and skip to step 3.

3. Make distributables [#3-make-distributables]

Run `npm run make` on each OS you ship (macOS, Linux, Windows, or CI workers per platform):

```sh skip="release-flow"
npm run make   # .app + .dmg on macOS; .AppImage on Linux; .msix on Windows
```

The full coverage—entitlements, code signing, notarization, MSIX publisher matching, signing certificates—is in [Build desktop distributables](/how-to/operate-an-app/build-and-package/build-desktop-distributables).

The `package.json` checklist before a make:

* `author` populated
* `license` populated
* `description` populated
* `name` set per brand
* `productName` set per brand
* `build/icon.icns` (macOS), `build/icon.ico` (Windows), `build/icon.png` (Linux) are per brand

4. Build the deployment directory [#4-build-the-deployment-directory]

`pear build` assembles per-OS makes into the multi-architecture **deployment directory** layout `pear stage` expects. It is part of the `pear` CLI, so there is nothing extra to install—run it as `pear build` (or `npx pear build`).

The expected layout:

```text skip="layout-illustration"
pear-chat-1.0.1/
├─ package.json
└─ by-arch/
   └─ <platform-arch>/
      └─ app/
```

Run `pear build` from **outside** the application folder (see [stage size increases](/how-to/operate-an-app/manual-deployment/troubleshoot-desktop-releases#pear-stage-shows-huge-size-growth)). Pass each make's output via `--<platform-arch>-app` and pick a `--target` name:

```sh skip="release-flow"
pear build \
  --package=./pear-chat/package.json \
  --darwin-arm64-app ./pear-chat/out/PearChat-darwin-arm64/PearChat.app \
  --darwin-x64-app   ./pear-chat/out/PearChat-darwin-x64/PearChat.app \
  --linux-arm64-app  ./pear-chat/out/PearChat-linux-arm64/PearChat.AppImage \
  --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
```

If you omit `--target`, the deployment directory is named `<name>-<version>` from `package.json`. Each make produces a single platform-arch on its own machine—transfer the build outputs to the build machine first, then assemble.

5. Stage [#5-stage]

`pear stage <upgrade-link> <deployment-directory>` syncs the directory into the [Hypercore](/reference/building-blocks/hypercore) behind the link.

Always dry-run first and read the file-by-file diff:

```sh skip="release-flow"
pear stage --dry-run pear://qxenz5wmspmryjc13m9yzsqj1conqotn8fb4ocbufwtz9mtbqq5o ./pear-chat-1.0.1
```

Look for:

* Files you expect to ship
* No surprise additions (`.DS_Store`, editor swap files, secrets, deployment directories nested inside the app)
* Sensible byte counts

Run the real stage:

```sh skip="release-flow"
pear stage pear://qxenz5wmspmryjc13m9yzsqj1conqotn8fb4ocbufwtz9mtbqq5o ./pear-chat-1.0.1
```

The output should match the dry-run diff line for line. If anything differs, abort and investigate before continuing.

Stage checklist [#stage-checklist]

* Always dry-run first.
* Check the dry-run output diff.
* Compare the live stage output to the dry-run output diff.

Confirm stage updates [#confirm-stage-updates]

Open the app on a second machine. The seeding process from step 0 should show peers joining as instances connect. To verify the update flow:

1. Change a file.
2. `npm version patch`.
3. `npm run make`.
4. `pear build`.
5. `pear stage`.

If `upgrade` points to the stage link, every connected instance should fire the `updated` event from [`pear.updater`](/reference/pear/runtime) (and, in the template, surface an "Update ready" button).

6. Provision [#6-provision]

`pear stage` is append-only—every file you ever staged stays in the core history. `pear provision` resyncs from a stage link onto a target link while compacting deletions, producing a leaner drive for prerelease distribution.

The signature is:

```sh skip="release-flow"
pear provision <versioned-source-link> <target-link> <versioned-production-link>
```

A **versioned link** has the form `pear://<fork>.<length>.<key>`. Copy it from the most recent `pear stage` output—the link printed under the `^Latest:` line at the end (the versioned link at the top of the output shows the drive *before* that stage).

The target link is a fresh `pear://` from step 0. While bootstrapping, set the third argument (the versioned production link) to `pear://0.0.<target-key>`; after a multisig drive exists, use `pear://<fork>.<length>.<multisig-key>` instead.

Dry-run first:

```sh skip="release-flow"
pear provision --dry-run \
  pear://0.1079.qxenz5wmspmryjc13m9yzsqj1conqotn8fb4ocbufwtz9mtbqq5o \
  pear://q9sopzoqgas9usoiq7uzkkwngm5pzj4zo3n4esjwwbmw6offis8o \
  pear://0.0.q9sopzoqgas9usoiq7uzkkwngm5pzj4zo3n4esjwwbmw6offis8o
```

Read the diff and run for real:

```sh skip="release-flow"
pear provision \
  pear://0.1079.qxenz5wmspmryjc13m9yzsqj1conqotn8fb4ocbufwtz9mtbqq5o \
  pear://q9sopzoqgas9usoiq7uzkkwngm5pzj4zo3n4esjwwbmw6offis8o \
  pear://0.0.q9sopzoqgas9usoiq7uzkkwngm5pzj4zo3n4esjwwbmw6offis8o
```

Switching builds to provision [#switching-builds-to-provision]

Update `package.json`:

* `upgrade` → the provision link (step 1)
* `version` → bumped (step 2)

Make, `pear build`, and stage again. Then provision a second time so the source link points at the provision target:

```sh skip="release-flow"
pear provision pear://0.1080.qxenz5wmspmryjc13m9yzsqj1conqotn8fb4ocbufwtz9mtbqq5o pear://q9sopzoqgas9usoiq7uzkkwngm5pzj4zo3n4esjwwbmw6offis8o pear://0.0.q9sopzoqgas9usoiq7uzkkwngm5pzj4zo3n4esjwwbmw6offis8o
```

Provision checklist [#provision-checklist]

* Always dry-run first.
* Check the dry-run output diff before provisioning.

7. Multisig [#7-multisig]

Production releases are gated by a **multisig** drive—a [Hypercore](/reference/building-blocks/hypercore) whose write access is controlled by a quorum of signing keys instead of one machine's private key. This is what removes the single point of failure from a typical desktop release flow, and unlike stage and provision drives, a multisig drive is **not** machine-bound.

Multisig has a one-time setup and a repeatable per-release flow, each covered in its own guide:

* [Set up multisig](/how-to/operate-an-app/multisig/set-up-multisig)—generate signing keys, configure `pear.json`, compute the multisig link, and point `upgrade` at it. Do this once.
* [Sign with multisig](/how-to/operate-an-app/multisig/sign-with-multisig)—prepare a request, collect a quorum of signatures, verify, and commit the production drive. Repeat for every release.
* [Troubleshoot multisig](/how-to/operate-an-app/multisig/troubleshoot-multisig)—refused requests, interrupted commits, `INCOMPATIBLE_SOURCE_AND_TARGET`, and recovering lost write access.

8. Store submissions (optional) [#8-store-submissions-optional]

Beyond peer-to-peer distribution, the Linux distributables from [step 3](#3-make-distributables) can also be packaged for platform application stores—**Flathub** (Flatpak) and the **Snap Store**. Store installs complement the flow above: an app installed from a store still updates over the air through the same staged and multisig-gated releases.

See [Submit to app stores](/how-to/operate-an-app/build-and-package/submit-to-app-stores) for the manifest preparation, local testing, submission, and release-automation steps of both flows.

Disabling updates [#disabling-updates]

Pass `--no-updates` per run to skip the OTA check (matches `hello-pear-electron`'s default `npm start` script):

```sh skip="release-flow"
npm start -- --no-updates
```

To disable updates for every run of a build, construct the runtime with `updates: false` (see [`pear-runtime`](/reference/pear/runtime#disabling-updates)):

```js skip="snippet-illustration"
const PearRuntime = require('pear-runtime')
const { version, upgrade, name } = require('../package.json')
const pear = new PearRuntime({
  dir,
  version,
  upgrade,
  name,
  updates: false
  // ... other options
})
```

This is useful for kiosk binaries or air-gapped distributions where OTA must be off.

Release lines and multiple stage drives [#release-lines-and-multiple-stage-drives]

A typical project keeps several stage drives in parallel—`development`, `staging`, `rc`, plus any number of custom lines for experiments or hotfixes. Each line has its own `pear://` link from step 0 and its own seeded reseeders.

Production has exactly one chain: `rc` → provision (`prerelease`) → multisig (`production`). The `rc` build's `upgrade` field points at the multisig link, so `rc` builds do not receive OTA updates—every `rc` iteration requires a new installer. The [Release pipeline](/explanation/deployment-releasing-apps-p2p#release-lines) explanation has the conceptual picture.

To bootstrap a new release line:

1. Run step 0 to mint and seed a new link.
2. Run step 1 in a build dedicated to that line.
3. Skip step 2—the line starts at the current `version`.
4. Run steps 3 and 4 to produce a build.
5. The build is now pointed at the new line; share it with whoever should follow that line.

See also [#see-also]

* [Set up multisig](/how-to/operate-an-app/multisig/set-up-multisig)—one-time signing-key, config, and link setup for the production gate.
* [Sign with multisig](/how-to/operate-an-app/multisig/sign-with-multisig)—the per-release prepare → sign → verify → commit flow.
* [Troubleshoot multisig](/how-to/operate-an-app/multisig/troubleshoot-multisig)—refused requests, interrupted commits, and recovering lost write access.
* [Publish with GitHub Actions](/how-to/operate-an-app/github-actions/publish-with-github-actions)—the simplest publish/update workflow, staging from CI on every push.
* [Release pipeline](/explanation/deployment-releasing-apps-p2p)—conceptual diagrams for stage, provision, multisig, and release lines.
* [Build desktop distributables](/how-to/operate-an-app/build-and-package/build-desktop-distributables)—per-OS makes, signing, notarization, and MSIX publisher details.
* [Submit to app stores](/how-to/operate-an-app/build-and-package/submit-to-app-stores)—Flathub and Snap Store packaging on top of the Linux distributables.
* [Desktop release npm scripts](/reference/ci-and-release/desktop-release-npm-scripts)—the `package.json` scripts that drive this flow.
* [Publish a changelog for your app](/how-to/operate-an-app/publish-a-changelog)—ship a `CHANGELOG.md` so users read release notes with `pear changelog`.
* [Troubleshoot desktop releases](/how-to/operate-an-app/manual-deployment/troubleshoot-desktop-releases)—OTA, seeding, deployment-folder, and lost write-access pitfalls.
* [Release pipeline glossary](/explanation/deployment-releasing-apps-p2p#glossary)—terminology.
* [`pear-ci` GitHub Action reference](/reference/ci-and-release/pear-ci-action)—inputs, outputs, and the CLI behind CI publishing.
* [`pear-runtime` reference](/reference/pear/runtime)—the runtime that drives OTA on the client.
* [Storage and distribution](/explanation/storage-and-distribution)—how releases reach users.


# Manual deployment



import { Cards, Card } from 'fumadocs-ui/components/card'

The hands-on release flow when you need release lines, provision, and full control. For the concepts, see [Release pipeline](/explanation/deployment-releasing-apps-p2p).

<Cards>
  <Card href="/how-to/operate-an-app/manual-deployment/deployment" title="Deploy your application" description="The eight Foundational Steps: touch, upgrade link, version, make, pear build, stage, provision, and multisig." />

  <Card href="/how-to/operate-an-app/manual-deployment/troubleshoot-desktop-releases" title="Troubleshoot desktop releases" description="Fix common OTA and staging problems in desktop releases." />
</Cards>


# Troubleshoot desktop releases



Use this guide when **desktop OTA** or **`pear stage`** behaves unexpectedly after you have a [deployment directory](/explanation/deployment-releasing-apps-p2p#deployment-directory-and-release-lines) and a release line. For general Pear and Bare development issues, see [Troubleshoot common issues](/how-to/troubleshooting).

{/*
  Shared snippet (content/_snippets/) included via Fumadocs <include> by guides that
  run `pear` CLI commands, so readers can install the CLI before following the steps.
  See: https://www.fumadocs.dev/docs/markdown#include
  */}

<Callout type="info">
  **Need the `pear` CLI?** Install it from **[install.pears.com](https://install.pears.com)**, or prefix any command below with `npx`. See [Install & upgrade](/reference/pear/cli#install) for details.
</Callout>

App did not update [#app-did-not-update]

Bump version [#bump-version]

An update will not apply unless `package.json` **`version`** changes. Use `npm version patch` (or the level you intend) before rebuilding and staging.

Advance the release pointer after pear stage [#advance-the-release-pointer-after-pear-stage]

`pear stage` writes new content into the [Hypercore](/reference/building-blocks/hypercore) but does **not** move the `release` pointer that peers poll. Staging ends by printing the new **`Latest`** length and the post-stage versioned link:

```text skip="sample-output"
Staging complete!

^Latest: 1191

pear://0.1191.<stage-key>
[  pear://<stage-link>  ]
```

The stage output does not show a release pointer, so a clean stage on its own never changes what peers already tracking the link fetch—they keep the previous release until the pointer advances. The single-key `pear release` command was **removed in Pear v3**—advance the pointer for a production release with [`pear provision`](/how-to/operate-an-app/manual-deployment/deployment#6-provision) followed by [`pear multisig`](/reference/pear/cli#pear-multisig) quorum cosigning, which manage the release pointer.

Tune PearRuntime delay for live OTA visibility [#tune-pearruntime-delay-for-live-ota-visibility]

`pear-runtime-updater` polls aggressively only during the first **60 seconds** after launch (the boot grace period). After that, every detected change is scheduled with a random delay of up to **one hour** by default. The delay is sampled **once at construction**, so each new `append` event reschedules against the same offset. If you stage frequently, the timer can reset forever—you may not see the **Update ready** button until the app restarts.

`PearRuntime` forwards its constructor options straight to the updater, so you can shorten or remove the delay:

```js skip="snippet-illustration"
pear = new PearRuntime({
  dir,
  app: appPath,
  updates,
  version,
  upgrade,
  name: productName + extension,
  store,
  swarm,
  delay: 0 // detect every append immediately; default is up to 1 hour
})
```

**Trade-off:** the long random delay exists on purpose for production. It spreads update checks across many clients so seeders do not get a thundering-herd when a new release goes out. Use `delay: 0` (or a few seconds) for development and tutorials; keep the default—or set a value in the **tens of minutes**—for production builds with many users.

Restarting the running app is a quick workaround without recompiling: a restart resets the boot grace period, and the next poll happens within seconds. This is also why an OTA can appear to "only work after a restart"—detection waits for the next scheduled poll, and a restart triggers one immediately.

Worker did not exit cleanly [#worker-did-not-exit-cleanly]

Bare workers spawned through [`pear-runtime`](https://github.com/holepunchto/pear-runtime) (`PearRuntime.run(...)`, as in the `hello-pear-electron`-shaped `getWorker(...)` helper) are plain OS child processes. Electron does **not** signal them on exit, so any code path that quits without tearing the worker down leaves it running. The worker keeps an exclusive lock on its [Corestore](/reference/helpers/corestore) directory, and the next launch hangs forever on [`await store.ready()`](/reference/helpers/corestore#await-storeready).

Look for the symptom in `ps`:

```bash skip="diagnostic-command"
ps -A -o pid,command | grep bare-sidecar
```

If a row points at your old `.app` (or a now-deleted deployment directory), kill it:

```bash skip="diagnostic-command"
kill <pid>
```

Then fix the host so it can't recur:

1. Register a `before-quit` listener per worker that destroys its IPC pipe (`pipe.destroy()`), so any quit tears every worker down. Remove the listener when the worker emits `exit`.
2. Relaunch through `app.quit()`, not `app.exit()`. `app.quit()` runs `before-quit` and lets each worker shut down; `app.exit()` skips Electron's clean-shutdown path entirely, so the `before-quit` listeners never fire and the workers leak.

The reference wiring lives in [Read the Electron main process](/getting-started/build-a-peer-to-peer-chat/reshape-into-a-production-app#read-the-electron-main-process) (the per-worker `before-quit` listeners and the `app:afterUpdate` handler that calls `app.relaunch()` then `app.quit()`).

Apply finishes the swap before relaunch [#apply-finishes-the-swap-before-relaunch]

`pear.updater.applyUpdate()` is **async**—it atomically swaps the new app bundle on disk and removes the staging copy. The renderer's **Update ready** button must wait for the swap to finish before triggering the relaunch. In the example, the updater worker awaits `applyUpdate()` and only then writes `pear:updateApplied` back over the IPC pipe; the main process resolves the `pear:applyUpdate` handler on that message, and the renderer calls `app:afterUpdate` afterwards:

```js skip="snippet-illustration"
// updater worker (workers/main.js)
pipe.on('data', async (data) => {
  if (data.toString() === 'pear:applyUpdate') {
    await pear.updater.applyUpdate()
    pipe.write('pear:updateApplied')
  }
})
```

If the relaunch fires before the swap completes, it may load the previous bundle. The symptom is that clicking **Update ready** appears to do nothing, but quitting the app manually and reopening it shows the new version.

Confirm the upgrade link [#confirm-the-upgrade-link]

The `upgrade` field must point at the **`pear://` link** you actually staged to. If it points at an old line, clients will track the wrong drive.

Seed the link [#seed-the-link]

The upgrade target must be **seeded** so peers can find it:

```bash skip="release-flow"
pear seed pear://your-link-here
```

Keep **always-on seeders** for production links; user laptops alone are a fragile source.

Seeder came online after the client [#seeder-came-online-after-the-client]

Discovery is asynchronous. If the seeder was offline when the client first looked up the key, the client may retry on a **roughly fifteen-minute** cadence. Wait, or add more seeders, then restart the client once the key is announced.

Seeder unreachable [#seeder-unreachable]

Add the key to **multiple** reachable seeders so OTA does not depend on one network path.

Recovering from lost write access [#recovering-from-lost-write-access]

* **Staged** and **provisioned** drives are **machine-bound** in normal setups—if you lose the data that holds write capability to those keys, you cannot "undelete" the same keys from thin air.
* **Multisig** production drives are **not** machine-bound. Write access is determined by signing capability, so a quorum of signers can keep producing releases even if every other key is lost.

**If a stage link is lost:** create a new link with `pear touch`, seed it, stage to it, and repoint **stage-line** builds' `upgrade` fields as needed.

**If a provision key is lost** and you already have a multisig production drive, you can rebuild a clean provision drive from production. Mint a fresh target key with `pear touch`, then run two `pear provision` commands in order:

```sh skip="release-flow"
# 1. Seed the new target with the production drive's current contents
pear provision <versioned-production-key> <target-key> <versioned-production-key>

# 2. Sync from the most recent stage onto the new target, anchored on production
pear provision <versioned-stage-key> <target-key> <versioned-production-key>
```

The multisig config does not reference the provision link, so there is nothing to update in `pear.json` (see [Create the multisig config](/how-to/operate-an-app/multisig/set-up-multisig#create-the-multisig-config)). Instead, pass the new provision link as the `<source-link>` to [`pear multisig verify` and `pear multisig commit`](/how-to/operate-an-app/multisig/sign-with-multisig) on the next release. For multisig-specific recovery—interrupted commits and `INCOMPATIBLE_SOURCE_AND_TARGET`—see [Troubleshoot multisig](/how-to/operate-an-app/multisig/troubleshoot-multisig).

To automate this in CI, the [`pear-provision-recover`](/reference/ci-and-release/github-actions#pear-app-cicd) action rebuilds a writable provision drive from a remote key—pass the lost drive's `key`, target `length`/`blobs-length`, and a fresh `primary-key` and `name`.

Node ABI mismatch during make [#node-abi-mismatch-during-make]

If `npm run make` fails with a `NODE_MODULE_VERSION` mismatch like:

```text skip="sample-error"
The module '.../node_modules/macos-alias/build/Release/volume.node'
was compiled against a different Node.js version using
NODE_MODULE_VERSION 127. This version of Node.js requires
NODE_MODULE_VERSION 141.
```

the native add-ons in `node_modules` were compiled for a different Node ABI than the Node version that runs `electron-forge make`. This usually happens after `nvm use`, a Node upgrade, or installing dependencies under one Node version and running the make under another.

Rebuild against the current Node:

```bash skip="machine-state"
npm rebuild
```

If you have multiple Node versions installed, pin one for the project—for example with an [`.nvmrc`](https://github.com/nvm-sh/nvm#nvmrc) file and an `engines.node` field in `package.json`—so installs and builds always use the same ABI.

`NODE_MODULE_VERSION` to Node version mapping is in the [Node.js release schedule](https://nodejs.org/en/about/previous-releases) (for example, `127` is Node 22, `141` is Node 25).

pear stage shows huge size growth [#pear-stage-shows-huge-size-growth]

Deployment folder nested inside the app [#deployment-folder-nested-inside-the-app]

If the **deployment directory** (output of `pear build`) lives **inside** the application tree that gets staged, each stage can **re-include the previous deployment blob**, so diffs grow without bound.

**Fix:** always pass `--target` pointing to a sibling directory **beside** the app root. Note that omitting `--target` does **not** protect you: `pear build` then writes a `<name>-<version>` folder into the directory you run it *from*, so run it from a parent directory outside the app tree if you leave `--target` off. Never run:

```bash skip="signed-build"
# Bad: target inside the app you are about to stage
pear build ... --package ./my-app/package.json --target ./my-app/deploy-out
```

**Do** run from a parent directory:

```bash skip="signed-build"
# Good: target next to the app
pear build ... --package ./my-app/package.json --target ./deploy-out/my-app-1.2.3
```

Keeping one folder per version also makes **rollback** easier: you can re-stage or re-provision from an older deployment directory.

Where to go next [#where-to-go-next]

* [Deploy your application](/how-to/operate-an-app/manual-deployment/deployment)—dry-run staging and provision commands.
* [Build desktop distributables](/how-to/operate-an-app/build-and-package/build-desktop-distributables)—correct `pear build` invocation before staging.
* [Release pipeline](/explanation/deployment-releasing-apps-p2p)—which link each build should follow.

<Callout type="info">
  **Related documentation**

  **Getting Started:** [Part 1: Chat](/getting-started/build-a-peer-to-peer-chat/build-a-peer-to-peer-chat) · [Part 2: Production-shaped](/getting-started/build-a-peer-to-peer-chat/reshape-into-a-production-app) · [Part 3: Ship](/getting-started/build-a-peer-to-peer-chat/ship) · [Part 4: Update](/getting-started/build-a-peer-to-peer-chat/update)

  **Operating an app**

  * [Desktop release npm scripts](/reference/ci-and-release/desktop-release-npm-scripts)
  * [Distribute as a binary](/how-to/operate-an-app/build-and-package/distribute-as-binary)
  * [Manage installed applications](/how-to/manage-installed-applications)
  * [Troubleshoot common issues](/how-to/troubleshooting)
</Callout>


# Multisig



import { Cards, Card } from 'fumadocs-ui/components/card'

Recipes for gating production releases behind a quorum of signers.

<Cards>
  <Card href="/how-to/operate-an-app/multisig/set-up-multisig" title="Set up multisig" description="One-time setup: generate signing keys, configure pear.json, and point upgrade at the multisig link." />

  <Card href="/how-to/operate-an-app/multisig/sign-with-multisig" title="Sign with multisig" description="The repeatable release flow: request, collect a quorum, verify, and commit." />

  <Card href="/how-to/operate-an-app/multisig/troubleshoot-multisig" title="Troubleshoot multisig" description="Fix seeding, commit, and source/target errors in the multisig flow." />
</Cards>


# Set up multisig



Production releases are gated by a **multisig** drive—a [Hypercore](/reference/building-blocks/hypercore) whose write access is controlled by a quorum of signing keys instead of one machine's private key. This is what removes the single point of failure from a typical desktop release flow, and it is why a multisig drive is **not** machine-bound: a quorum of signers can keep producing releases even if every other key is lost.

This guide is the **one-time setup**. Once it is done, every release uses the repeatable signing flow in [Sign with multisig](/how-to/operate-an-app/multisig/sign-with-multisig).

<Callout type="info">
  This is the production gate of the desktop release flow. You need a working [provision link](/how-to/operate-an-app/manual-deployment/deployment#6-provision) before you set up multisig—provision is the source drive that signing requests are prepared and committed against.
</Callout>

{/*
  Shared snippet (content/_snippets/) included via Fumadocs <include> by guides that
  run `pear` CLI commands, so readers can install the CLI before following the steps.
  See: https://www.fumadocs.dev/docs/markdown#include
  */}

<Callout type="info">
  **Need the `pear` CLI?** Install it from **[install.pears.com](https://install.pears.com)**, or prefix any command below with `npx`. See [Install & upgrade](/reference/pear/cli#install) for details.
</Callout>

Create signing keys [#create-signing-keys]

Every signer generates a signing key with Pear:

```sh skip="release-flow"
pear multisig keys get
```

On first run this prompts for a password to encrypt the new private key (it errors if none is supplied), then prints the key name and its public key; the keypair is stored under `~/.pear`. `pear multisig keys get` is idempotent—running it again just reprints the existing public key. Each signer takes note of the printed public key and shares it with whoever is assembling the multisig config. The same key can sign many builds.

Create the multisig config [#create-the-multisig-config]

In your project—the same directory as `package.json`—create or edit `pear.json` and set the `multisig` property to an object with every signer's public key, a `quorum` count, and an arbitrary `namespace` string:

```json skip="release-flow"
{
  "multisig": {
    "publicKeys": ["pubkey-signer-1", "pubkey-signer-2", "pubkey-signer-3"],
    "namespace": "pear-chat",
    "quorum": 2
  }
}
```

This example needs two of three signers to release. The `quorum` is the minimum number of signers whose responses must agree before a release can be committed. The multisig link is derived from the `namespace`, `publicKeys`, and `quorum` alone—the provision (source) link is not part of the config; it is supplied later, when you prepare and commit each signing request.

Set upgrade to the multisig link [#set-upgrade-to-the-multisig-link]

From the same directory, compute the multisig link:

```sh skip="release-flow"
pear multisig link
# pear://69qwbihxj4c8te15wt3skj4j1g3ufmbo3mperedjqr1hb55mspoo
```

Then finish the release cycle:

1. [Set the upgrade link](/how-to/operate-an-app/manual-deployment/deployment#1-set-the-upgrade-link) in `package.json` to the multisig link from above.
2. [Bump `version`](/how-to/operate-an-app/manual-deployment/deployment#2-version).
3. Run [`npm run make`](/how-to/operate-an-app/manual-deployment/deployment#3-make-distributables), [`pear build`](/how-to/operate-an-app/manual-deployment/deployment#4-build-the-deployment-directory), and [`pear stage`](/how-to/operate-an-app/manual-deployment/deployment#5-stage).
4. [Provision](/how-to/operate-an-app/manual-deployment/deployment#6-provision) again with the multisig link as the third argument:

```sh skip="release-flow"
pear provision pear://0.1082.qxenz5wmspmryjc13m9yzsqj1conqotn8fb4ocbufwtz9mtbqq5o pear://q9sopzoqgas9usoiq7uzkkwngm5pzj4zo3n4esjwwbmw6offis8o pear://0.0.69qwbihxj4c8te15wt3skj4j1g3ufmbo3mperedjqr1hb55mspoo
```

The provision drive's `upgrade` field now points at the multisig drive. Setup is complete—releases now go through the signing flow.

See also [#see-also]

* [Sign with multisig](/how-to/operate-an-app/multisig/sign-with-multisig)—the repeatable prepare → sign → verify → commit flow for every release.
* [Troubleshoot multisig](/how-to/operate-an-app/multisig/troubleshoot-multisig)—interrupted commits, `INCOMPATIBLE_SOURCE_AND_TARGET`, and recovering lost write access.
* [Deploy your application](/how-to/operate-an-app/manual-deployment/deployment)—the full eight-step release flow this gates.
* [Release pipeline](/explanation/deployment-releasing-apps-p2p)—conceptual diagrams for stage, provision, and multisig.


# Sign with multisig



Once [multisig is set up](/how-to/operate-an-app/multisig/set-up-multisig), every production release runs the same four steps:

1. [Prepare the request](#prepare-the-request)
2. [Sign](#sign) it with a quorum of signers
3. [Verify](#verify) the responses
4. [Commit](#commit) the production drive

The request and responses are portable—the commit does not have to run on the machine that prepared the request.

<Callout type="info">
  This assumes the multisig drive already exists. If you have not generated signing keys, configured `pear.json`, and pointed `upgrade` at the multisig link yet, do [Set up multisig](/how-to/operate-an-app/multisig/set-up-multisig) first.
</Callout>

{/*
  Shared snippet (content/_snippets/) included via Fumadocs <include> by guides that
  run `pear` CLI commands, so readers can install the CLI before following the steps.
  See: https://www.fumadocs.dev/docs/markdown#include
  */}

<Callout type="info">
  **Need the `pear` CLI?** Install it from **[install.pears.com](https://install.pears.com)**, or prefix any command below with `npx`. See [Install & upgrade](/reference/pear/cli#install) for details.
</Callout>

Prepare the request [#prepare-the-request]

```sh skip="release-flow"
pear multisig request <versioned-provision-link>
```

`<versioned-provision-link>` is the seeded provision link in `pear://<fork>.<length>.<key>` form—the link from your most recent `pear provision`. For example:

```sh skip="release-flow"
pear multisig request pear://0.856.q9sopzoqgas9usoiq7uzkkwngm5pzj4zo3n4esjwwbmw6offis8o
```

`pear multisig request` runs safety checks before issuing the request. One of them ensures the source drive is healthily seeded; if it is not, the request is refused—see [Troubleshoot multisig](/how-to/operate-an-app/multisig/troubleshoot-multisig#request-refused-source-not-healthily-seeded). It returns a signing request.

Sign [#sign]

Each signer confirms the build is the one they intend to release, then signs the request:

```sh skip="release-flow"
pear multisig sign <signing request>
```

and shares the response. `pear multisig` guards against formal mistakes, but it is up to each signer to verify they are signing the correct build. Once a [quorum](/how-to/operate-an-app/multisig/set-up-multisig#create-the-multisig-config) of responses exists, the build is ready to verify.

Verify [#verify]

Check for formal mistakes before committing. Run `verify` first on the request alone, then again with the collected responses appended:

```sh skip="release-flow"
pear multisig verify <source-link> <signing request> [...responses]
```

`<source-link>` is the provisioned link (a staged link also works). **Never** sign or commit a request that fails `verify`.

Commit [#commit]

Only commit after verifying the request and all responses:

```sh skip="release-flow"
pear multisig commit <source-link> <signing request> [...responses]
```

As with `verify`, `<source-link>` is the provisioned (or staged) link. The committer does not have to be a signer—the request and responses are enough to generate the build, which is why `pear multisig` insists the source drive is well seeded, and why the commit can run on a different machine than the one that prepared the request.

The commit is not safely finished until the new multisig drive's key is seeded by peers. Make sure it is seeding:

```sh skip="release-flow"
pear seed <multisig-link>
```

`pear seed` shows replication activity rather than a completion signal: peer events (`o-o peer join`) and the upload totals in the `Network` row confirm other peers are pulling the drive. The commit itself prints `Waiting for remote seeders to pick up the changes...` and continues on its own once the drive is seeded. Keep seeding until peers have replicated, then stop it with `Ctrl+C`.

<Callout type="warning">
  **Do not abort a running commit.** An interrupted commit leaves the production build in an intermediate state. See [Recover from an interrupted commit](/how-to/operate-an-app/multisig/troubleshoot-multisig#interrupted-or-aborted-commit) before retrying.
</Callout>

To inspect which signing keys and quorum a multisig link enforces:

```sh skip="release-flow"
pear info --multisig <multisig-link>
```

See also [#see-also]

* [Set up multisig](/how-to/operate-an-app/multisig/set-up-multisig)—the one-time setup this flow depends on.
* [Troubleshoot multisig](/how-to/operate-an-app/multisig/troubleshoot-multisig)—request refused, interrupted commits, and `INCOMPATIBLE_SOURCE_AND_TARGET`.
* [Deploy your application](/how-to/operate-an-app/manual-deployment/deployment)—the full eight-step release flow.
* [Release pipeline](/explanation/deployment-releasing-apps-p2p)—conceptual diagrams for stage, provision, and multisig.


# Troubleshoot multisig



Use this guide when the [multisig signing flow](/how-to/operate-an-app/multisig/sign-with-multisig) fails or a production drive ends up in a bad state. For general desktop OTA and staging problems, see [Troubleshoot desktop releases](/how-to/operate-an-app/manual-deployment/troubleshoot-desktop-releases).

{/*
  Shared snippet (content/_snippets/) included via Fumadocs <include> by guides that
  run `pear` CLI commands, so readers can install the CLI before following the steps.
  See: https://www.fumadocs.dev/docs/markdown#include
  */}

<Callout type="info">
  **Need the `pear` CLI?** Install it from **[install.pears.com](https://install.pears.com)**, or prefix any command below with `npx`. See [Install & upgrade](/reference/pear/cli#install) for details.
</Callout>

Request refused: source not healthily seeded [#request-refused-source-not-healthily-seeded]

`pear multisig request` refuses to issue a signing request if the source provision drive is not healthily seeded. Reseed the provision drive on more peers, then retry:

```sh skip="release-flow"
pear seed <provision-link>
```

Keep always-on seeders for the provision link so requests do not depend on a single network path.

Interrupted or aborted commit [#interrupted-or-aborted-commit]

**Never abort a commit while it is running.** If a commit gets interrupted (crash, power loss, premature `Ctrl+C`), the production build is stuck in an intermediate state.

The request and responses are enough to finish the commit, and the commit does not have to run on the same machine that prepared the request. Run the commit again as soon as possible:

```sh skip="release-flow"
pear multisig commit <source-link> <signing request> [...responses]
```

From the second commit onwards, a misuse can corrupt the production build. If `pear multisig commit` errors with `INCOMPATIBLE_SOURCE_AND_TARGET`, do not work around it—see below.

INCOMPATIBLE_SOURCE_AND_TARGET [#incompatible_source_and_target]

From the second commit onwards it is technically possible to corrupt the production build—for example after an accidental interruption. If `pear multisig commit` errors with `INCOMPATIBLE_SOURCE_AND_TARGET`, **never try to work around it.** The only safe way to proceed is to create a fresh source link with `pear provision` and commit against that.

Mint a new target key, provision a clean source onto it from the original source, then recommit:

```sh skip="release-flow"
pear touch
```

```sh skip="release-flow"
pear provision <source-verlink> <touched-link> <production-multisig-link>
```

`<source-verlink>` is the versioned link originally used as the source of the provisioned drive. Then commit against the new link:

```sh skip="release-flow"
pear multisig commit <touched-link> <signing request> [...responses]
```

Recovering lost write access [#recovering-lost-write-access]

* **Staged** and **provisioned** drives are **machine-bound** in normal setups—if you lose the data that holds write capability to those keys, you cannot "undelete" the same keys from thin air.
* **Multisig** production drives are **not** machine-bound. Write access is determined by signing capability, so a quorum of signers can keep producing releases even if every other key is lost.

**If a stage link is lost**, just create a new stage link, stage to it, and update the stage builds.

**If a provision key is lost** and you already have a multisig production drive, you can rebuild a clean provision drive from production. Mint a fresh target key with `pear touch`, then run two `pear provision` commands in order:

```sh skip="release-flow"
# 1. Seed the new target with the production drive's current contents
pear provision <versioned-production-key> <target-key> <versioned-production-key>

# 2. Sync from the most recent stage onto the new target, anchored on production
pear provision <versioned-stage-key> <target-key> <versioned-production-key>
```

The multisig config does not reference the provision link, so there is nothing to update in `pear.json`. Instead, pass the new provision link as the `<source-link>` to `pear multisig verify` and `pear multisig commit` on the next release.

To automate this in CI, the [`pear-provision-recover`](/reference/ci-and-release/github-actions#pear-app-cicd) action rebuilds a writable provision drive from a remote key—pass the lost drive's `key`, target `length`/`blobs-length`, and a fresh `primary-key` and `name`.

See also [#see-also]

* [Set up multisig](/how-to/operate-an-app/multisig/set-up-multisig)—generate keys, configure `pear.json`, and point `upgrade` at the multisig link.
* [Sign with multisig](/how-to/operate-an-app/multisig/sign-with-multisig)—the prepare → sign → verify → commit flow.
* [Troubleshoot desktop releases](/how-to/operate-an-app/manual-deployment/troubleshoot-desktop-releases)—OTA, seeding, and staging problems.
* [Release pipeline](/explanation/deployment-releasing-apps-p2p)—conceptual diagrams for stage, provision, and multisig.


# bare-abort-controller



<mark style={{ backgroundColor: '#7dde9a', padding: '2px 8px', borderRadius: '4px', fontSize: '0.85em', fontWeight: 500 }}>
  stable
</mark>

[`bare-abort-controller`](https://github.com/holepunchto/bare-abort-controller) — Abort controller support for Bare.

```sh
npm i bare-abort-controller
```

Usage [#usage]

```js
const controller = new AbortController()

const signal = controller.signal

signal.addEventListener('abort', (event) => {
  console.log(event)
})

controller.abort(new Error('Operation aborted'))
```

API [#api]

AbortController [#abortcontroller]

new AbortController() [#new-abortcontroller]

Create a new `AbortController` with a fresh, unaborted `AbortSignal`.

abort(reason: any): void [#abortreason-any-void]

Abort the controller's signal, notifying every listener with the given `reason`.

**Parameters**

| Parameter | Type  | Default | Description                                                                                                                                  |
| --------- | ----- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `reason`  | `any` | —       | The reason to abort with; passed to every `'abort'` listener and exposed as the signal's `reason`. Defaults to an `AbortError` when omitted. |

signal: AbortSignal [#signal-abortsignal]

The `AbortSignal` linked to this controller.

AbortSignal [#abortsignal]

aborted: boolean [#aborted-boolean]

Whether the signal has been aborted.

AbortSignal.abort(reason: any): AbortSignal [#abortsignalabortreason-any-abortsignal]

Return a new `AbortSignal` that is already aborted with the given `reason`.

**Parameters**

| Parameter | Type  | Default | Description                                                                               |
| --------- | ----- | ------- | ----------------------------------------------------------------------------------------- |
| `reason`  | `any` | —       | The reason the returned signal is aborted with. Defaults to an `AbortError` when omitted. |

AbortSignal.any(signals: AbortSignal[]): AbortSignal [#abortsignalanysignals-abortsignal-abortsignal]

Return a new `AbortSignal` that aborts as soon as any of the given `signals` abort, with the same reason.

**Parameters**

| Parameter | Type            | Default | Description                                                                                                                             |
| --------- | --------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `signals` | `AbortSignal[]` | —       | The signals to observe; the returned signal aborts with the reason of whichever aborts first, or immediately if one is already aborted. |

AbortSignal.timeout(ms: number): AbortSignal [#abortsignaltimeoutms-number-abortsignal]

Return a new `AbortSignal` that aborts with a `TimeoutError` after `ms` milliseconds.

**Parameters**

| Parameter | Type     | Default | Description                                                                                 |
| --------- | -------- | ------- | ------------------------------------------------------------------------------------------- |
| `ms`      | `number` | —       | The number of milliseconds to wait before the returned signal aborts with a `TimeoutError`. |

reason: any [#reason-any]

The reason the signal was aborted, or `undefined` if it hasn't been.

throwIfAborted(): void [#throwifaborted-void]

Throw the signal's abort reason if the signal has been aborted, otherwise do nothing.

toJSON(): { aborted: boolean; reason: any } [#tojson--aborted-boolean-reason-any-]

Return a plain object with the signal's `aborted` and `reason` values.

bare-abort-controller/global [#bare-abort-controllerglobal]

Types [#types]

AbortControllerConstructor [#abortcontrollerconstructor]

```ts
type AbortControllerConstructor = typeof abort.AbortController
```

AbortSignalConstructor [#abortsignalconstructor]

```ts
type AbortSignalConstructor = typeof abort.AbortSignal
```

See also [#see-also]

* Builds on `bare-events`.
* [Bare modules](/reference/modules/bare-modules) — the full `bare-*` catalog.
* [Bare runtime API](/reference/bare/runtime) — the runtime these modules extend.


# bare-abort



<mark style={{ backgroundColor: '#7dde9a', padding: '2px 8px', borderRadius: '4px', fontSize: '0.85em', fontWeight: 500 }}>
  stable
</mark>

[`bare-abort`](https://github.com/holepunchto/bare-abort) — Cause abnormal program termination and generate a crash report. It is a native addon.

```sh
npm i bare-abort
```

Usage [#usage]

```js
const abort = require('bare-abort')

abort()
```

API [#api]

Functions [#functions]

abort(): never [#abort-never]

Cause abnormal program termination and generate a crash report.

See also [#see-also]

* [Bare modules](/reference/modules/bare-modules) — the full `bare-*` catalog.
* [Bare runtime API](/reference/bare/runtime) — the runtime these modules extend.


# bare-addon-resolve



<mark style={{ backgroundColor: '#7dde9a', padding: '2px 8px', borderRadius: '4px', fontSize: '0.85em', fontWeight: 500 }}>
  stable
</mark>

[`bare-addon-resolve`](https://github.com/holepunchto/bare-addon-resolve) — Low-level addon resolution algorithm for Bare.

```sh
npm i bare-addon-resolve
```

Usage [#usage]

For synchronous resolution:

```js
const resolve = require('bare-addon-resolve')

function readPackage(url) {
  // Read and parse `url` if it exists, otherwise `null`
}

for (const resolution of resolve('./addon', new URL('file:///directory/'), readPackage)) {
  console.log(resolution)
}
```

For asynchronous resolution:

```js
const resolve = require('bare-addon-resolve')

async function readPackage(url) {
  // Read and parse `url` if it exists, otherwise `null`
}

for await (const resolution of resolve('./addon', new URL('file:///directory/'), readPackage)) {
  console.log(resolution)
}
```

API [#api]

Functions [#functions]

resolve [#resolve]

```ts
resolve(specifier: string, parentURL: URL, readPackage?: (url: URL) => JSON | null): Iterable<URL>
```

Resolve `specifier` relative to `parentURL`, which must be a WHATWG `URL` instance. `readPackage` is called with a `URL` instance for every package manifest to be read and must either return the parsed JSON package manifest, if it exists, or `null`. If `readPackage` returns a promise, synchronous iteration is not supported.

**Parameters**

| Parameter      | Type                         | Default | Description                                                                                                                                              |
| -------------- | ---------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `specifier`    | `string`                     | —       | The module specifier to resolve.                                                                                                                         |
| `parentURL`    | `URL`                        | —       | The URL to resolve `specifier` relative to.                                                                                                              |
| `readPackage?` | `(url: URL) => JSON \| null` | —       | Called with the URL of each package manifest encountered; must return the parsed manifest or `null`. Returning a promise disables synchronous iteration. |

**Returns** `Iterable<URL>` — Yields candidate resolution `URL`s for the caller to test, in the order the algorithm tries them.

**Throws**

* `INVALID_ADDON_SPECIFIER` — the addon specifier is not a valid package name or contains an invalid escape sequence.
* `INVALID_PACKAGE_NAME` — a package manifest's `name` field is invalid (for example contains `__`).

resolve.addon(specifier: string, parentURL: URL, opts?: ResolveOptions): Resolver [#resolveaddonspecifier-string-parenturl-url-opts-resolveoptions-resolver]

One step of the resolution algorithm, exposed for fine-grained use: resolve `specifier` as an addon — a relative or absolute specifier resolves via `resolve.file`/`resolve.directory`, otherwise via `resolve.package`.

**Parameters**

| Parameter   | Type                                | Default | Description                                       |
| ----------- | ----------------------------------- | ------- | ------------------------------------------------- |
| `specifier` | `string`                            | —       | The addon specifier to resolve.                   |
| `parentURL` | `URL`                               | —       | The URL to resolve `specifier` relative to.       |
| `opts?`     | [`ResolveOptions`](#resolveoptions) | —       | Options; see [`ResolveOptions`](#resolveoptions). |

**Returns** `Resolver` — A `Resolver` yielding the candidate resolutions.

resolve.directory [#resolvedirectory]

```ts
resolve.directory(dirname: string, version: string, parentURL: URL, opts?: ResolveOptions): Resolver
```

Resolve `dirname` as a prebuilds directory addon candidate relative to `parentURL`.

**Parameters**

| Parameter   | Type                                | Default | Description                                                     |
| ----------- | ----------------------------------- | ------- | --------------------------------------------------------------- |
| `dirname`   | `string`                            | —       | The prebuilds directory addon candidate.                        |
| `version`   | `string`                            | —       | The package version, if the specifier carried one, else `null`. |
| `parentURL` | `URL`                               | —       | The URL to resolve `dirname` relative to.                       |
| `opts?`     | [`ResolveOptions`](#resolveoptions) | —       | Options; see [`ResolveOptions`](#resolveoptions).               |

**Returns** `Resolver` — A `Resolver` yielding the candidate resolutions.

resolve.file(filename: string, parentURL: URL, opts?: ResolveOptions): Resolver [#resolvefilefilename-string-parenturl-url-opts-resolveoptions-resolver]

Resolve `filename` as a file addon candidate relative to `parentURL`, trying each of `opts.extensions` in turn.

**Parameters**

| Parameter   | Type                                | Default | Description                                                            |
| ----------- | ----------------------------------- | ------- | ---------------------------------------------------------------------- |
| `filename`  | `string`                            | —       | The file addon candidate, without an extension.                        |
| `parentURL` | `URL`                               | —       | The URL to resolve `filename` relative to.                             |
| `opts?`     | [`ResolveOptions`](#resolveoptions) | —       | Options; `extensions` lists the candidate extensions to try, in order. |

**Returns** `Resolver` — A `Resolver` yielding the candidate resolutions.

resolve.linked(name: string, version?: string, opts?: ResolveOptions): Resolver [#resolvelinkedname-string-version-string-opts-resolveoptions-resolver]

Resolve `name` to a `linked:` specifier, for runtimes that link addons ahead of time by platform (for example iOS or Android) rather than resolving a prebuild at runtime.

**Parameters**

| Parameter  | Type                                | Default | Description                                                                                                                                             |
| ---------- | ----------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`     | `string`                            | —       | The addon name to resolve to a `linked:` specifier.                                                                                                     |
| `version?` | `string`                            | —       | The addon version, if any.                                                                                                                              |
| `opts?`    | [`ResolveOptions`](#resolveoptions) | —       | Options; `linked` must not be `false` and `hosts` (or `host`) must be set, or resolution is skipped. `linkedProtocol` overrides the `'linked:'` prefix. |

**Returns** `Resolver` — A `Resolver` yielding the candidate `linked:` resolutions.

resolve.package [#resolvepackage]

```ts
resolve.package(packageSpecifier: string, packageVersion: string, parentURL: URL, opts?: ResolveOptions): Resolver
```

Resolve `packageSpecifier` (optionally `@packageVersion`) as a package name, locating the addon within it.

**Parameters**

| Parameter          | Type                                | Default | Description                                                     |
| ------------------ | ----------------------------------- | ------- | --------------------------------------------------------------- |
| `packageSpecifier` | `string`                            | —       | The package name to resolve the addon within.                   |
| `packageVersion`   | `string`                            | —       | The package version, if the specifier carried one, else `null`. |
| `parentURL`        | `URL`                               | —       | The URL to resolve the package from.                            |
| `opts?`            | [`ResolveOptions`](#resolveoptions) | —       | Options; see [`ResolveOptions`](#resolveoptions).               |

**Returns** `Resolver` — A `Resolver` yielding the candidate resolutions.

resolve.packageSelf [#resolvepackageself]

```ts
resolve.packageSelf(packageName: string, packageSubpath: string, packageVersion: string, parentURL: URL, opts?: ResolveOptions): Resolver
```

Resolve `packageSubpath` against the package named `packageName`, for when `parentURL` lies within that package's own scope — a package requiring its own addon by name.

**Parameters**

| Parameter        | Type                                | Default | Description                                                              |
| ---------------- | ----------------------------------- | ------- | ------------------------------------------------------------------------ |
| `packageName`    | `string`                            | —       | The package's own name, matched against each candidate scope's manifest. |
| `packageSubpath` | `string`                            | —       | The addon subpath to resolve within the matching package.                |
| `packageVersion` | `string`                            | —       | The package version, if the specifier carried one, else `null`.          |
| `parentURL`      | `URL`                               | —       | A URL within the package's own scope to search upward from.              |
| `opts?`          | [`ResolveOptions`](#resolveoptions) | —       | Options; see [`ResolveOptions`](#resolveoptions).                        |

**Returns** `Resolver` — A `Resolver` yielding the candidate resolutions.

resolve.url(specifier: string, parentURL: URL, opts?: ResolveOptions): Resolver [#resolveurlspecifier-string-parenturl-url-opts-resolveoptions-resolver]

Resolve `specifier` as an absolute URL, yielding it as a single candidate.

**Parameters**

| Parameter   | Type                                | Default | Description                                                |
| ----------- | ----------------------------------- | ------- | ---------------------------------------------------------- |
| `specifier` | `string`                            | —       | An absolute URL specifier.                                 |
| `parentURL` | `URL`                               | —       | Unused; accepted for a consistent step-function signature. |
| `opts?`     | [`ResolveOptions`](#resolveoptions) | —       | Options; see [`ResolveOptions`](#resolveoptions).          |

**Returns** `Resolver` — A `Resolver` yielding the candidate resolution.

Constants and variables [#constants-and-variables]

resolve.constants [#resolveconstants]

```ts
resolve.constants: {
    UNRESOLVED: number
    YIELDED: number
    RESOLVED: number
  }
```

The generator status codes yielded by each resolution step: `UNRESOLVED`, `YIELDED`, and `RESOLVED`.

Types [#types]

resolve.Resolver [#resolveresolver]

```ts
type Resolver = Generator<
    { resolution: URL } | { package: URL },
    number,
    void | boolean | JSON | null
  >
```

The shared generator type every `resolve.*` step function returns.

ResolveOptions [#resolveoptions]

```ts
interface ResolveOptions {
  builtinProtocol?: string
  builtins?: Builtins
  conditions?: Conditions
  extensions?: string[]
  host?: string
  hosts?: string[]
  linked?: boolean
  linkedProtocol?: string
  matchedConditions?: string[]
  resolutions?: ResolutionsMap
}
```

bare-addon-resolve/errors [#bare-addon-resolveerrors]

AddonResolveError [#addonresolveerror]

AddonResolveError.INVALID_ADDON_SPECIFIER(msg: string): AddonResolveError [#addonresolveerrorinvalid_addon_specifiermsg-string-addonresolveerror]

**Parameters**

| Parameter | Type     | Default | Description        |
| --------- | -------- | ------- | ------------------ |
| `msg`     | `string` | —       | The error message. |

**Returns** `AddonResolveError` — A new `AddonResolveError` with code `INVALID_ADDON_SPECIFIER`.

AddonResolveError.INVALID_PACKAGE_NAME(msg: string): AddonResolveError [#addonresolveerrorinvalid_package_namemsg-string-addonresolveerror]

**Parameters**

| Parameter | Type     | Default | Description        |
| --------- | -------- | ------- | ------------------ |
| `msg`     | `string` | —       | The error message. |

**Returns** `AddonResolveError` — A new `AddonResolveError` with code `INVALID_PACKAGE_NAME`.

code: string [#code-string]

See also [#see-also]

* Builds on `bare-module-resolve` and `bare-semver`.
* The resolved addon is the first candidate `resolve` yields that exists as a file on the file system.
* The `resolve.*` step functions are subject to change between minor releases; if using them directly, specify a tilde range (for example `~1.10.0`) when declaring the module dependency.
* Addons normally resolve through the [runtime](/reference/bare/runtime) or are bundled by [`bare-pack`](/reference/modules/bare-modules); reach for this module directly only when building tooling on the resolution algorithm itself, such as [`bare-module-traverse`](/reference/bare/modules/bare-module-traverse).
* [Bare modules](/reference/modules/bare-modules) — the full `bare-*` catalog.
* [Bare runtime API](/reference/bare/runtime) — the runtime these modules extend.


# bare-ansi-escapes



<mark style={{ backgroundColor: '#7dde9a', padding: '2px 8px', borderRadius: '4px', fontSize: '0.85em', fontWeight: 500 }}>
  stable
</mark>

[`bare-ansi-escapes`](https://github.com/holepunchto/bare-ansi-escapes) — Parse and produce ANSI escape sequences.

```sh
npm i bare-ansi-escapes
```

Usage [#usage]

```js
const KeyDecoder = require('bare-ansi-escapes/key-decoder')

readableStream.pipe(new KeyDecoder()).on('data', (key) => console.log(key))
```

API [#api]

Functions [#functions]

cursorUp(n?: number): string [#cursorupn-number-string]

Return the ANSI escape sequence that moves the cursor up `n` lines.

**Parameters**

| Parameter | Type     | Default | Description                                  |
| --------- | -------- | ------- | -------------------------------------------- |
| `n?`      | `number` | —       | Number of lines to move up; defaults to `1`. |

cursorDown(n?: number): string [#cursordownn-number-string]

Return the ANSI escape sequence that moves the cursor down `n` lines.

**Parameters**

| Parameter | Type     | Default | Description                                    |
| --------- | -------- | ------- | ---------------------------------------------- |
| `n?`      | `number` | —       | Number of lines to move down; defaults to `1`. |

cursorForward(n?: number): string [#cursorforwardn-number-string]

Return the ANSI escape sequence that moves the cursor forward `n` columns.

**Parameters**

| Parameter | Type     | Default | Description                                         |
| --------- | -------- | ------- | --------------------------------------------------- |
| `n?`      | `number` | —       | Number of columns to move forward; defaults to `1`. |

cursorBack(n?: number): string [#cursorbackn-number-string]

Return the ANSI escape sequence that moves the cursor back `n` columns.

**Parameters**

| Parameter | Type     | Default | Description                                      |
| --------- | -------- | ------- | ------------------------------------------------ |
| `n?`      | `number` | —       | Number of columns to move back; defaults to `1`. |

cursorNextLine(n?: number): string [#cursornextlinen-number-string]

Return the ANSI escape sequence that moves the cursor to the start of the line `n` lines down.

**Parameters**

| Parameter | Type     | Default | Description                                    |
| --------- | -------- | ------- | ---------------------------------------------- |
| `n?`      | `number` | —       | Number of lines down to move; defaults to `1`. |

cursorPreviousLine(n?: number): string [#cursorpreviouslinen-number-string]

Return the ANSI escape sequence that moves the cursor to the start of the line `n` lines up.

**Parameters**

| Parameter | Type     | Default | Description                                  |
| --------- | -------- | ------- | -------------------------------------------- |
| `n?`      | `number` | —       | Number of lines up to move; defaults to `1`. |

cursorPosition(column: number, row?: number): string [#cursorpositioncolumn-number-row-number-string]

Return the ANSI escape sequence that moves the cursor to `column` and, if given, `row`.

**Parameters**

| Parameter | Type     | Default | Description                                                              |
| --------- | -------- | ------- | ------------------------------------------------------------------------ |
| `column`  | `number` | —       | Zero-based column to move the cursor to.                                 |
| `row?`    | `number` | —       | Zero-based row to move the cursor to; defaults to `0` (the current row). |

scrollUp(n?: number): string [#scrollupn-number-string]

Return the ANSI escape sequence that scrolls the display up `n` lines.

**Parameters**

| Parameter | Type     | Default | Description                                                |
| --------- | -------- | ------- | ---------------------------------------------------------- |
| `n?`      | `number` | —       | Number of lines to scroll the display up; defaults to `1`. |

scrollDown(n?: number): string [#scrolldownn-number-string]

Return the ANSI escape sequence that scrolls the display down `n` lines.

**Parameters**

| Parameter | Type     | Default | Description                                                  |
| --------- | -------- | ------- | ------------------------------------------------------------ |
| `n?`      | `number` | —       | Number of lines to scroll the display down; defaults to `1`. |

Constants and variables [#constants-and-variables]

constants: { ESC: string; CSI: string; SGR: (n: number) => string } [#constants--esc-string-csi-string-sgr-n-number--string-]

The raw escape sequence building blocks: `ESC`, `CSI`, and the `SGR` (Select Graphic Rendition) sequence builder.

cursorHide: string [#cursorhide-string]

ANSI escape sequence that hides the cursor.

cursorShow: string [#cursorshow-string]

ANSI escape sequence that shows the cursor.

eraseDisplayEnd: string [#erasedisplayend-string]

ANSI escape sequence that erases the display from the cursor to the end.

eraseDisplayStart: string [#erasedisplaystart-string]

ANSI escape sequence that erases the display from the start to the cursor.

eraseDisplay: string [#erasedisplay-string]

ANSI escape sequence that erases the entire display.

eraseLineEnd: string [#eraselineend-string]

ANSI escape sequence that erases the line from the cursor to the end.

eraseLineStart: string [#eraselinestart-string]

ANSI escape sequence that erases the line from the start to the cursor.

eraseLine: string [#eraseline-string]

ANSI escape sequence that erases the entire line.

modifierReset: string [#modifierreset-string]

SGR escape sequence that resets all modifiers.

modifierBold: string [#modifierbold-string]

SGR escape sequence that enables bold text.

modifierDim: string [#modifierdim-string]

SGR escape sequence that enables dim text.

modifierItalic: string [#modifieritalic-string]

SGR escape sequence that enables italic text.

modifierUnderline: string [#modifierunderline-string]

SGR escape sequence that enables underlined text.

modifierNormal: string [#modifiernormal-string]

SGR escape sequence that resets bold/dim to normal intensity.

modifierNotItalic: string [#modifiernotitalic-string]

SGR escape sequence that disables italic text.

modifierNotUnderline: string [#modifiernotunderline-string]

SGR escape sequence that disables underlined text.

colorBlack: string [#colorblack-string]

SGR escape sequence that sets the foreground color to black.

colorRed: string [#colorred-string]

SGR escape sequence that sets the foreground color to red.

colorGreen: string [#colorgreen-string]

SGR escape sequence that sets the foreground color to green.

colorYellow: string [#coloryellow-string]

SGR escape sequence that sets the foreground color to yellow.

colorBlue: string [#colorblue-string]

SGR escape sequence that sets the foreground color to blue.

colorMagenta: string [#colormagenta-string]

SGR escape sequence that sets the foreground color to magenta.

colorCyan: string [#colorcyan-string]

SGR escape sequence that sets the foreground color to cyan.

colorWhite: string [#colorwhite-string]

SGR escape sequence that sets the foreground color to white.

colorDefault: string [#colordefault-string]

SGR escape sequence that resets the foreground color to the default.

colorBrightBlack: string [#colorbrightblack-string]

SGR escape sequence that sets the foreground color to bright black.

colorBrightRed: string [#colorbrightred-string]

SGR escape sequence that sets the foreground color to bright red.

colorBrightGreen: string [#colorbrightgreen-string]

SGR escape sequence that sets the foreground color to bright green.

colorBrightYellow: string [#colorbrightyellow-string]

SGR escape sequence that sets the foreground color to bright yellow.

colorBrightBlue: string [#colorbrightblue-string]

SGR escape sequence that sets the foreground color to bright blue.

colorBrightMagenta: string [#colorbrightmagenta-string]

SGR escape sequence that sets the foreground color to bright magenta.

colorBrightCyan: string [#colorbrightcyan-string]

SGR escape sequence that sets the foreground color to bright cyan.

colorBrightWhite: string [#colorbrightwhite-string]

SGR escape sequence that sets the foreground color to bright white.

bare-ansi-escapes/key-decoder [#bare-ansi-escapeskey-decoder]

KeyDecoder [#keydecoder]

new KeyDecoder(opts?: KeyDecoderOptions) [#new-keydecoderopts-keydecoderoptions]

Create a `KeyDecoder`, optionally configuring the input `encoding` and `escapeCodeTimeout`.

**Parameters**

| Parameter | Type                | Default | Description                                                                                               |
| --------- | ------------------- | ------- | --------------------------------------------------------------------------------------------------------- |
| `opts?`   | `KeyDecoderOptions` | —       | Options controlling the `encoding` and `escapeCodeTimeout` used to decode input; see `KeyDecoderOptions`. |

encoding: BufferEncoding [#encoding-bufferencoding]

The encoding used to decode incoming byte data into characters.

Key [#key]

new Key(name: string | number, sequence: string, ctrl: boolean, meta: boolean, shift: boolean) [#new-keyname-string--number-sequence-string-ctrl-boolean-meta-boolean-shift-boolean]

Create a `Key` with the given `name`, raw `sequence`, and modifier flags.

**Parameters**

| Parameter  | Type                 | Default | Description                                                                  |
| ---------- | -------------------- | ------- | ---------------------------------------------------------------------------- |
| `name`     | `string` \| `number` | —       | The decoded key name, for example `'up'`, `'return'`, or a single character. |
| `sequence` | `string`             | —       | The raw input sequence the key was decoded from.                             |
| `ctrl`     | `boolean`            | —       | Whether the Ctrl modifier was held.                                          |
| `meta`     | `boolean`            | —       | Whether the Meta (Alt) modifier was held.                                    |
| `shift`    | `boolean`            | —       | Whether the Shift modifier was held.                                         |

ctrl: boolean [#ctrl-boolean]

Whether the Ctrl modifier was held.

meta: boolean [#meta-boolean]

Whether the Meta (Alt) modifier was held.

name: string [#name-string]

The decoded key name, for example `'up'`, `'return'`, or a single character.

sequence: string [#sequence-string]

The raw input sequence the key was decoded from.

shift: boolean [#shift-boolean]

Whether the Shift modifier was held.

Types [#types]

KeyDecoderOptions [#keydecoderoptions]

```ts
interface KeyDecoderOptions {
  encoding?: BufferEncoding
  escapeCodeTimeout?: number
}
```

KeyDecoderEvents [#keydecoderevents]

```ts
interface KeyDecoderEvents {
  data: [key: Key]
  end: []
  readable: []
  piping: [dest: Writable]
  close: []
  error: [err: Error]
  drain: []
  finish: []
  pipe: [src: Readable]
}
```

See also [#see-also]

* Builds on `bare-stream`.
* [Bare modules](/reference/modules/bare-modules) — the full `bare-*` catalog.
* [Bare runtime API](/reference/bare/runtime) — the runtime these modules extend.


# bare-apk



[`bare-apk`](https://github.com/holepunchto/bare-apk) provides Android packaging tools for [Bare](/reference/bare/runtime): build an Android App Bundle (`.aab`) from a manifest, derive an APK set, and produce an installable `.apk`. It's pure JavaScript (it shells out to the Android build tools) and is used in the Android packaging path of [`bare-build`](https://github.com/holepunchto/bare-build).

```sh
npm i bare-apk
```

Usage [#usage]

```js
const { createAppBundle, createAPK } = require('bare-apk')

await createAppBundle('./path/to/AndroidManifest.xml', './app.aab')
await createAPK('./app.aab', './app.apk')
```

API [#api]

await createAppBundle(manifest, out[, options]) [#await-createappbundlemanifest-out-options]

Build an Android App Bundle (`.aab`) from an `AndroidManifest.xml`.

Options include:

```js
options = {
  targetSDK: DEFAULT_TARGET_SDK,
  // Additional files and directories to include in uncompressed format
  include: [],
  // Resource directory to compile and compress
  resources
}
```

await createAPKSet(bundle, out[, options]) [#await-createapksetbundle-out-options]

Produce an APK set from an app bundle.

Options include:

```js
options = {
  universal: false,
  archive: true,
  sign: false,
  keystore,
  keystoreKey,
  keystorePassword
}
```

await createAPK(bundle, out[, options]) [#await-createapkbundle-out-options]

Produce an installable `.apk`.

Options include:

```js
options = {
  sign: false,
  keystore,
  keystoreKey,
  keystorePassword
}
```

constants [#constants]

| Constant              | Description                                |
| :-------------------- | :----------------------------------------- |
| `ANDROID_HOME`        | The Android SDK root directory.            |
| `DEFAULT_MINIMUM_SDK` | The default minimum Android SDK API level. |
| `DEFAULT_TARGET_SDK`  | The default target Android SDK API level.  |

See also [#see-also]

* [Bundle a Bare app](/how-to/run-on-native/bundle-a-bare-app)—where app packaging fits in the build flow.
* [Bare modules](/reference/modules/bare-modules)—the full `bare-*` catalog.
* [Bare runtime API](/reference/bare/runtime)—the runtime this targets.


# bare-assert



<mark style={{ backgroundColor: '#7dde9a', padding: '2px 8px', borderRadius: '4px', fontSize: '0.85em', fontWeight: 500 }}>
  stable
</mark>

[`bare-assert`](https://github.com/holepunchto/bare-assert) — Assertion library for JavaScript.

Mirrors the Node.js [`assert`](https://nodejs.org/api/assert.html) module.

```sh
npm i bare-assert
```

Usage [#usage]

```js
const assert = require('bare-assert')

assert(1 + 1 === 2, 'sum should be correct')

assert.equal(1, 1)
assert.notEqual(1, 2)
```

API [#api]

AssertionError [#assertionerror]

new AssertionError(opts?: { message?: string; actual?: any; expected?: any; operator?: string }) [#new-assertionerroropts--message-string-actual-any-expected-any-operator-string-]

Create an `AssertionError`, optionally setting its `message`, `actual`, `expected`, and `operator`.

**Parameters**

| Parameter | Type                                                                    | Default | Description                                                                                                                                          |
| --------- | ----------------------------------------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `opts?`   | `{ message?: string; actual?: any; expected?: any; operator?: string }` | —       | Fields to set on the new error: `message` (defaults to a generated `"<actual> <operator> <expected>"` string), `actual`, `expected`, and `operator`. |

actual: any [#actual-any]

The actual value that failed the assertion.

expected: any [#expected-any]

The expected value the assertion was checked against.

operator: string [#operator-string]

The comparison operator used by the assertion that failed, for example `'=='` or `'strictEqual'`.

Functions [#functions]

assert(value: any, message?: string | Error): void [#assertvalue-any-message-string--error-void]

Throw an `AssertionError` if `value` is falsy.

**Parameters**

| Parameter  | Type                | Default | Description                                                                                                        |
| ---------- | ------------------- | ------- | ------------------------------------------------------------------------------------------------------------------ |
| `value`    | `any`               | —       | The value to assert is truthy.                                                                                     |
| `message?` | `string` \| `Error` | —       | Custom message for the thrown error; if an `Error` instance, it is thrown directly instead of an `AssertionError`. |

**Throws**

* `AssertionError` — thrown if `value` is falsy (unless `message` is an `Error` instance, which is thrown instead).

assert.doesNotMatch(actual: string, expected: RegExp, message?: string | Error): void [#assertdoesnotmatchactual-string-expected-regexp-message-string--error-void]

**Parameters**

| Parameter  | Type                | Default | Description |
| ---------- | ------------------- | ------- | ----------- |
| `actual`   | `string`            | —       | —           |
| `expected` | `RegExp`            | —       | —           |
| `message?` | `string` \| `Error` | —       | —           |

assert.equal(actual: any, expected: any, message?: string | Error): void [#assertequalactual-any-expected-any-message-string--error-void]

**Parameters**

| Parameter  | Type                | Default | Description |
| ---------- | ------------------- | ------- | ----------- |
| `actual`   | `any`               | —       | —           |
| `expected` | `any`               | —       | —           |
| `message?` | `string` \| `Error` | —       | —           |

assert.ifError(actual: any): void [#assertiferroractual-any-void]

**Parameters**

| Parameter | Type  | Default | Description |
| --------- | ----- | ------- | ----------- |
| `actual`  | `any` | —       | —           |

assert.match(actual: string, expected: RegExp, message?: string | Error): void [#assertmatchactual-string-expected-regexp-message-string--error-void]

**Parameters**

| Parameter  | Type                | Default | Description |
| ---------- | ------------------- | ------- | ----------- |
| `actual`   | `string`            | —       | —           |
| `expected` | `RegExp`            | —       | —           |
| `message?` | `string` \| `Error` | —       | —           |

assert.notEqual(actual: any, expected: any, message?: string | Error): void [#assertnotequalactual-any-expected-any-message-string--error-void]

**Parameters**

| Parameter  | Type                | Default | Description |
| ---------- | ------------------- | ------- | ----------- |
| `actual`   | `any`               | —       | —           |
| `expected` | `any`               | —       | —           |
| `message?` | `string` \| `Error` | —       | —           |

assert.notStrictEqual(actual: any, expected: any, message?: string | Error): void [#assertnotstrictequalactual-any-expected-any-message-string--error-void]

**Parameters**

| Parameter  | Type                | Default | Description |
| ---------- | ------------------- | ------- | ----------- |
| `actual`   | `any`               | —       | —           |
| `expected` | `any`               | —       | —           |
| `message?` | `string` \| `Error` | —       | —           |

assert.ok(value: any, message?: string | Error): void [#assertokvalue-any-message-string--error-void]

**Parameters**

| Parameter  | Type                | Default | Description |
| ---------- | ------------------- | ------- | ----------- |
| `value`    | `any`               | —       | —           |
| `message?` | `string` \| `Error` | —       | —           |

assert.strictEqual(actual: any, expected: any, message?: string | Error): void [#assertstrictequalactual-any-expected-any-message-string--error-void]

**Parameters**

| Parameter  | Type                | Default | Description |
| ---------- | ------------------- | ------- | ----------- |
| `actual`   | `any`               | —       | —           |
| `expected` | `any`               | —       | —           |
| `message?` | `string` \| `Error` | —       | —           |

See also [#see-also]

* Builds on `bare-inspect`.
* [Bare modules](/reference/modules/bare-modules) — the full `bare-*` catalog.
* [Bare runtime API](/reference/bare/runtime) — the runtime these modules extend.


# bare-atomics



<mark style={{ backgroundColor: '#7dde9a', padding: '2px 8px', borderRadius: '4px', fontSize: '0.85em', fontWeight: 500 }}>
  stable
</mark>

[`bare-atomics`](https://github.com/holepunchto/bare-atomics) — Native synchronization primitives for JavaScript. It is a native addon and requires Bare `>=1.2.0`.

```sh
npm i bare-atomics
```

API [#api]

Mutex [#mutex]

new Mutex(opts?: MutexOptions) [#new-mutexopts-mutexoptions]

**Parameters**

| Parameter | Type                            | Default | Description                                                                                                                                           |
| --------- | ------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `opts?`   | [`MutexOptions`](#mutexoptions) | —       | Options; set `recursive: true` to let the owning thread lock the mutex more than once (default `false`). May also carry an existing `handle` to wrap. |

Mutex.destroy(): void [#mutexdestroy-void]

**Throws**

* The mutex is still held.

Mutex.handle: SharedArrayBuffer [#mutexhandle-sharedarraybuffer]

A `SharedArrayBuffer` with the underlying mutex handle.

held: boolean [#held-boolean]

Whether or not the current thread currently holds the mutex.

lock(): void [#lock-void]

**Throws**

* The mutex is already held and was not created with `recursive: true`.

Mutex.from(handle: SharedArrayBuffer, opts?: MutexOptions): Mutex [#mutexfromhandle-sharedarraybuffer-opts-mutexoptions-mutex]

Create a `Mutex` from an existing `handle`; options are the same as `new Mutex()`.

**Parameters**

| Parameter | Type                            | Default | Description                                                                    |
| --------- | ------------------------------- | ------- | ------------------------------------------------------------------------------ |
| `handle`  | `SharedArrayBuffer`             | —       | A `SharedArrayBuffer` holding an existing mutex, as exposed by `Mutex.handle`. |
| `opts?`   | [`MutexOptions`](#mutexoptions) | —       | Options, the same as `new Mutex()`.                                            |

**Returns** `Mutex` — A `Mutex` sharing the underlying `handle`.

recursive: boolean [#recursive-boolean]

tryLock(): boolean [#trylock-boolean]

**Throws**

* The mutex is already held and was not created with `recursive: true`.

unlock(): void [#unlock-void]

**Throws**

* The mutex is not currently held.

Semaphore [#semaphore]

new Semaphore(value: any) [#new-semaphorevalue-any]

**Parameters**

| Parameter | Type  | Default | Description                                        |
| --------- | ----- | ------- | -------------------------------------------------- |
| `value`   | `any` | —       | The initial value (permit count) of the semaphore. |

Semaphore.destroy(): void [#semaphoredestroy-void]

**Throws**

* The mutex is still held.

Semaphore.handle: SharedArrayBuffer [#semaphorehandle-sharedarraybuffer]

A `SharedArrayBuffer` with the underlying mutex handle.

post(): void [#post-void]

Semaphore.from(handle: SharedArrayBuffer): Semaphore [#semaphorefromhandle-sharedarraybuffer-semaphore]

**Parameters**

| Parameter | Type                | Default | Description                                                                            |
| --------- | ------------------- | ------- | -------------------------------------------------------------------------------------- |
| `handle`  | `SharedArrayBuffer` | —       | A `SharedArrayBuffer` holding an existing semaphore, as exposed by `Semaphore.handle`. |

**Returns** `Semaphore` — A `Semaphore` sharing the underlying `handle`.

tryWait(): boolean [#trywait-boolean]

wait(): void [#wait-void]

**Throws**

* The associated mutex is not held by the current thread.

Condition [#condition]

broadcast(): void [#broadcast-void]

Condition.from(handle: SharedArrayBuffer): Condition [#conditionfromhandle-sharedarraybuffer-condition]

**Parameters**

| Parameter | Type                | Default | Description                                                                                     |
| --------- | ------------------- | ------- | ----------------------------------------------------------------------------------------------- |
| `handle`  | `SharedArrayBuffer` | —       | A `SharedArrayBuffer` holding an existing condition variable, as exposed by `Condition.handle`. |

**Returns** `Condition` — A `Condition` sharing the underlying `handle`.

Condition.destroy(): void [#conditiondestroy-void]

Condition.handle: SharedArrayBuffer [#conditionhandle-sharedarraybuffer]

A `SharedArrayBuffer` with the underlying mutex handle.

signal(): void [#signal-void]

Condition.wait(): boolean [#conditionwait-boolean]

**Throws**

* The associated mutex is not held by the current thread.

Barrier [#barrier]

new Barrier(count: number) [#new-barriercount-number]

**Parameters**

| Parameter | Type     | Default | Description                                                                                              |
| --------- | -------- | ------- | -------------------------------------------------------------------------------------------------------- |
| `count`   | `number` | —       | The number of threads that must reach the barrier (call `wait()`) before they are all released together. |

Barrier.from(handle: SharedArrayBuffer): Barrier [#barrierfromhandle-sharedarraybuffer-barrier]

**Parameters**

| Parameter | Type                | Default | Description                                                                        |
| --------- | ------------------- | ------- | ---------------------------------------------------------------------------------- |
| `handle`  | `SharedArrayBuffer` | —       | A `SharedArrayBuffer` holding an existing barrier, as exposed by `Barrier.handle`. |

**Returns** `Barrier` — A `Barrier` sharing the underlying `handle`.

Barrier.destroy(): void [#barrierdestroy-void]

Barrier.handle: SharedArrayBuffer [#barrierhandle-sharedarraybuffer]

A `SharedArrayBuffer` with the underlying mutex handle.

Barrier.wait(): boolean [#barrierwait-boolean]

Types [#types]

MutexOptions [#mutexoptions]

```ts
interface MutexOptions {
  recursive?: boolean
}
```

See also [#see-also]

* [`bare-channel`](/reference/bare/modules/bare-channel) and [`bare-broadcast-channel`](/reference/bare/modules/bare-broadcast-channel)—higher-level message passing between threads.
* [Bare modules](/reference/modules/bare-modules) — the full `bare-*` catalog.
* [Bare runtime API](/reference/bare/runtime) — the runtime these modules extend.


# bare-bluetooth-android



<mark style={{ backgroundColor: '#7dde9a', padding: '2px 8px', borderRadius: '4px', fontSize: '0.85em', fontWeight: 500 }}>
  stable
</mark>

[`bare-bluetooth-android`](https://github.com/holepunchto/bare-bluetooth-android) — Android Bluetooth bindings for Bare. It is a native addon.

```sh
npm i bare-bluetooth-android
```

Usage [#usage]

```js
const { Central } = require('bare-bluetooth-android')

const central = new Central()

central.on('stateChange', (state) => {
  if (state === 'on') {
    central.startScan(['180D']) // Heart Rate service UUID
  }
})

central.on('discover', (peripheral) => {
  console.log('Found:', peripheral.name, peripheral.id)
  central.stopScan()
  central.connect(peripheral)
})

central.on('connect', (peripheral) => {
  peripheral.discoverServices()

  peripheral.on('servicesDiscover', (services) => {
    // Discover characteristics for each service
  })
})
```

API [#api]

BluetoothError [#bluetootherror]

new BluetoothError(msg: string, fn?: Function, code?: string) [#new-bluetootherrormsg-string-fn-function-code-string]

**Parameters**

| Parameter | Type       | Default | Description                                                                    |
| --------- | ---------- | ------- | ------------------------------------------------------------------------------ |
| `msg`     | `string`   | —       | A human-readable error message.                                                |
| `fn?`     | `Function` | —       | The function to omit from the captured stack trace (default `BluetoothError`). |
| `code?`   | `string`   | —       | The error code; defaults to `fn.name` (for example `SCAN_FAILED`).             |

BluetoothError.ADVERTISE_FAILED(msg: string): BluetoothError [#bluetootherroradvertise_failedmsg-string-bluetootherror]

**Parameters**

| Parameter | Type     | Default | Description |
| --------- | -------- | ------- | ----------- |
| `msg`     | `string` | —       | —           |

BluetoothError.CHANNEL_FAILED(msg: string): BluetoothError [#bluetootherrorchannel_failedmsg-string-bluetootherror]

**Parameters**

| Parameter | Type     | Default | Description |
| --------- | -------- | ------- | ----------- |
| `msg`     | `string` | —       | —           |

BluetoothError.CHANNEL_PUBLISH_FAILED(msg: string): BluetoothError [#bluetootherrorchannel_publish_failedmsg-string-bluetootherror]

**Parameters**

| Parameter | Type     | Default | Description |
| --------- | -------- | ------- | ----------- |
| `msg`     | `string` | —       | —           |

BluetoothError.CONNECTION_FAILED(msg: string, id: string): BluetoothError [#bluetootherrorconnection_failedmsg-string-id-string-bluetootherror]

**Parameters**

| Parameter | Type     | Default | Description                                               |
| --------- | -------- | ------- | --------------------------------------------------------- |
| `msg`     | `string` | —       | A human-readable error message.                           |
| `id`      | `string` | —       | The id of the peripheral the connection attempt targeted. |

BluetoothError.DISCONNECT(msg: string, id: string): BluetoothError [#bluetootherrordisconnectmsg-string-id-string-bluetootherror]

**Parameters**

| Parameter | Type     | Default | Description                                 |
| --------- | -------- | ------- | ------------------------------------------- |
| `msg`     | `string` | —       | A human-readable error message.             |
| `id`      | `string` | —       | The id of the peripheral that disconnected. |

BluetoothError.DISCOVER_FAILED(msg: string): BluetoothError [#bluetootherrordiscover_failedmsg-string-bluetootherror]

**Parameters**

| Parameter | Type     | Default | Description |
| --------- | -------- | ------- | ----------- |
| `msg`     | `string` | —       | —           |

BluetoothError.MTU_CHANGE_FAILED(msg: string): BluetoothError [#bluetootherrormtu_change_failedmsg-string-bluetootherror]

**Parameters**

| Parameter | Type     | Default | Description |
| --------- | -------- | ------- | ----------- |
| `msg`     | `string` | —       | —           |

BluetoothError.NOTIFY_FAILED(msg: string): BluetoothError [#bluetootherrornotify_failedmsg-string-bluetootherror]

**Parameters**

| Parameter | Type     | Default | Description |
| --------- | -------- | ------- | ----------- |
| `msg`     | `string` | —       | —           |

BluetoothError.NOTIFY_STATE_FAILED(msg: string): BluetoothError [#bluetootherrornotify_state_failedmsg-string-bluetootherror]

**Parameters**

| Parameter | Type     | Default | Description |
| --------- | -------- | ------- | ----------- |
| `msg`     | `string` | —       | —           |

BluetoothError.READ_FAILED(msg: string): BluetoothError [#bluetootherrorread_failedmsg-string-bluetootherror]

**Parameters**

| Parameter | Type     | Default | Description |
| --------- | -------- | ------- | ----------- |
| `msg`     | `string` | —       | —           |

BluetoothError.SCAN_FAILED(msg: string): BluetoothError [#bluetootherrorscan_failedmsg-string-bluetootherror]

**Parameters**

| Parameter | Type     | Default | Description |
| --------- | -------- | ------- | ----------- |
| `msg`     | `string` | —       | —           |

BluetoothError.SERVICE_ADD_FAILED(msg: string): BluetoothError [#bluetootherrorservice_add_failedmsg-string-bluetootherror]

**Parameters**

| Parameter | Type     | Default | Description |
| --------- | -------- | ------- | ----------- |
| `msg`     | `string` | —       | —           |

BluetoothError.WRITE_FAILED(msg: string): BluetoothError [#bluetootherrorwrite_failedmsg-string-bluetootherror]

**Parameters**

| Parameter | Type     | Default | Description |
| --------- | -------- | ------- | ----------- |
| `msg`     | `string` | —       | —           |

code: string [#code-string]

BluetoothError.id: string [#bluetootherrorid-string]

name: 'BluetoothError' [#name-bluetootherror]

L2CAPChannel [#l2capchannel]

new L2CAPChannel(channelHandle: ArrayBuffer) [#new-l2capchannelchannelhandle-arraybuffer]

A duplex stream representing an L2CAP connection-oriented channel. Extends `Duplex` from \<[https://github.com/holepunchto/bare-stream>](https://github.com/holepunchto/bare-stream>). Typically obtained via the `'channelOpen'` event rather than constructed directly.

**Parameters**

| Parameter       | Type          | Default | Description                                                                                                          |
| --------------- | ------------- | ------- | -------------------------------------------------------------------------------------------------------------------- |
| `channelHandle` | `ArrayBuffer` | —       | The native channel handle backing the stream; supplied internally when a channel opens, not usually passed directly. |

peer: string | null [#peer-string--null]

The address of the remote peer, or `null`.

psm: number [#psm-number]

The Protocol/Service Multiplexer number of the channel.

Service [#service]

new Service(uuid: string, characteristics?: Characteristic[], opts?: ServiceOptions) [#new-serviceuuid-string-characteristics-characteristic-opts-serviceoptions]

Create a new GATT service definition.

**Parameters**

| Parameter          | Type                                | Default | Description                                                  |
| ------------------ | ----------------------------------- | ------- | ------------------------------------------------------------ |
| `uuid`             | `string`                            | —       | The service's UUID.                                          |
| `characteristics?` | `Characteristic[]`                  | —       | The characteristics belonging to the service.                |
| `opts?`            | [`ServiceOptions`](#serviceoptions) | —       | Options; set `primary: true` to mark this a primary service. |

characteristics: Characteristic[] [#characteristics-characteristic]

The array of characteristics belonging to the service.

primary: boolean [#primary-boolean]

Whether the service is a primary service.

Service.uuid: string [#serviceuuid-string]

The UUID of the service.

Characteristic [#characteristic]

new Characteristic(uuid: string, opts?: CharacteristicOptions) [#new-characteristicuuid-string-opts-characteristicoptions]

Create a new GATT characteristic definition.

**Parameters**

| Parameter | Type                                              | Default | Description                                                                            |
| --------- | ------------------------------------------------- | ------- | -------------------------------------------------------------------------------------- |
| `uuid`    | `string`                                          | —       | The characteristic's UUID.                                                             |
| `opts?`   | [`CharacteristicOptions`](#characteristicoptions) | —       | Options selecting the characteristic `properties`, `permissions`, and initial `value`. |

Characteristic.PROPERTY_INDICATE: number [#characteristicproperty_indicate-number]

Characteristic property constants.

Characteristic.PROPERTY_NOTIFY: number [#characteristicproperty_notify-number]

Characteristic.PROPERTY_READ: number [#characteristicproperty_read-number]

Characteristic.PROPERTY_WRITE: number [#characteristicproperty_write-number]

Characteristic.PROPERTY_WRITE_WITHOUT_RESPONSE: number [#characteristicproperty_write_without_response-number]

permissions: number | null [#permissions-number--null]

The permission flags of the characteristic, or `null` if inferred.

properties: number [#properties-number]

The property flags of the characteristic.

Characteristic.uuid: string [#characteristicuuid-string]

The UUID of the characteristic.

value: Uint8Array | null [#value-uint8array--null]

The current value of the characteristic, or `null`.

Server [#server]

new Server() [#new-server]

Create a new BLE peripheral server for advertising services and handling client requests.

addService(service: Service): void [#addserviceservice-service-void]

Add a `service` to the GATT server. The `'serviceAdd'` event is emitted when the service has been registered.

**Parameters**

| Parameter | Type      | Default | Description                                     |
| --------- | --------- | ------- | ----------------------------------------------- |
| `service` | `Service` | —       | The `Service` to register with the GATT server. |

Server.destroy(): void [#serverdestroy-void]

Destroy the server, stopping advertising and unpublishing all L2CAP channels.

publishChannel(opts?: ChannelOptions): void [#publishchannelopts-channeloptions-void]

Publish an L2CAP channel. The `'channelPublish'` event is emitted with the assigned PSM.

**Parameters**

| Parameter | Type                                | Default | Description                               |
| --------- | ----------------------------------- | ------- | ----------------------------------------- |
| `opts?`   | [`ChannelOptions`](#channeloptions) | —       | Options for the L2CAP channel to publish. |

respondToRequest(request: ReadRequest, result: number, data?: Uint8Array): void [#respondtorequestrequest-readrequest-result-number-data-uint8array-void]

Respond to a read or write `request` with a `result` code and optional `data`. Use the `Server.ATT_*` constants for the result.

**Parameters**

| Parameter | Type                          | Default | Description                                                       |
| --------- | ----------------------------- | ------- | ----------------------------------------------------------------- |
| `request` | [`ReadRequest`](#readrequest) | —       | The read or write request to respond to.                          |
| `result`  | `number`                      | —       | The ATT result code; use the `Server.ATT_*` constants.            |
| `data?`   | `Uint8Array`                  | —       | The value to return for a read request; omit for write responses. |

Server.ATT_INSUFFICIENT_RESOURCES: number [#serveratt_insufficient_resources-number]

Server.ATT_INVALID_HANDLE: number [#serveratt_invalid_handle-number]

Server.ATT_READ_NOT_PERMITTED: number [#serveratt_read_not_permitted-number]

Server.ATT_SUCCESS: number [#serveratt_success-number]

Server.ATT_UNLIKELY_ERROR: number [#serveratt_unlikely_error-number]

ATT result codes for use with `server.respondToRequest()`.

Server.ATT_WRITE_NOT_PERMITTED: number [#serveratt_write_not_permitted-number]

Server.CONNECTION_STATE_CONNECTED: number [#serverconnection_state_connected-number]

Server.CONNECTION_STATE_CONNECTING: number [#serverconnection_state_connecting-number]

Server.CONNECTION_STATE_DISCONNECTED: number [#serverconnection_state_disconnected-number]

Server.CONNECTION_STATE_DISCONNECTING: number [#serverconnection_state_disconnecting-number]

Server.PERMISSION_READ_ENCRYPTED: number [#serverpermission_read_encrypted-number]

Server.PERMISSION_READABLE: number [#serverpermission_readable-number]

Server.PERMISSION_WRITE_ENCRYPTED: number [#serverpermission_write_encrypted-number]

Characteristic permission constants.

Server.PERMISSION_WRITEABLE: number [#serverpermission_writeable-number]

Server.PROPERTY_INDICATE: number [#serverproperty_indicate-number]

Characteristic property constants.

Server.PROPERTY_NOTIFY: number [#serverproperty_notify-number]

Server.PROPERTY_READ: number [#serverproperty_read-number]

Server.PROPERTY_WRITE: number [#serverproperty_write-number]

Server.PROPERTY_WRITE_WITHOUT_RESPONSE: number [#serverproperty_write_without_response-number]

Server.STATE_OFF: number [#serverstate_off-number]

Server.STATE_ON: number [#serverstate_on-number]

Server.STATE_TURNING_OFF: number [#serverstate_turning_off-number]

Server.STATE_TURNING_ON: number [#serverstate_turning_on-number]

startAdvertising(opts?: AdvertisingOptions): void [#startadvertisingopts-advertisingoptions-void]

Start advertising the server.

**Parameters**

| Parameter | Type                                        | Default | Description                                                                       |
| --------- | ------------------------------------------- | ------- | --------------------------------------------------------------------------------- |
| `opts?`   | [`AdvertisingOptions`](#advertisingoptions) | —       | Advertising options such as the local `name` and the `serviceUUIDs` to advertise. |

Server.state: BluetoothState [#serverstate-bluetoothstate]

The current Bluetooth adapter state. One of `'off'`, `'turningOn'`, `'on'`, or `'turningOff'`.

stopAdvertising(): void [#stopadvertising-void]

Stop advertising.

unpublishChannel(psm: number): void [#unpublishchannelpsm-number-void]

Unpublish an L2CAP channel with the given `psm`.

**Parameters**

| Parameter | Type     | Default | Description                                                             |
| --------- | -------- | ------- | ----------------------------------------------------------------------- |
| `psm`     | `number` | —       | The PSM of the channel to unpublish, as assigned when it was published. |

updateValue(characteristic: Characteristic, data: Uint8Array): boolean [#updatevaluecharacteristic-characteristic-data-uint8array-boolean]

Update the value of `characteristic` with `data` and notify subscribed clients.

**Parameters**

| Parameter        | Type             | Default | Description                                  |
| ---------------- | ---------------- | ------- | -------------------------------------------- |
| `characteristic` | `Characteristic` | —       | The characteristic whose value changed.      |
| `data`           | `Uint8Array`     | —       | The new value to send to subscribed clients. |

**Returns** `boolean` — Whether the notification was sent to subscribed clients successfully.

Central [#central]

new Central() [#new-central]

Create a new BLE central manager for scanning and connecting to peripherals.

Central.CALLBACK_TYPE_ALL_MATCHES: number [#centralcallback_type_all_matches-number]

Central.CALLBACK_TYPE_FIRST_MATCH: number [#centralcallback_type_first_match-number]

Central.CALLBACK_TYPE_MATCH_LOST: number [#centralcallback_type_match_lost-number]

Central.SCAN_MODE_BALANCED: number [#centralscan_mode_balanced-number]

Central.SCAN_MODE_LOW_LATENCY: number [#centralscan_mode_low_latency-number]

Scan mode constants for use with `central.startScan()`.

Central.SCAN_MODE_LOW_POWER: number [#centralscan_mode_low_power-number]

Central.SCAN_MODE_OPPORTUNISTIC: number [#centralscan_mode_opportunistic-number]

Central.STATE_OFF: number [#centralstate_off-number]

Central.STATE_ON: number [#centralstate_on-number]

Central.STATE_TURNING_OFF: number [#centralstate_turning_off-number]

Central.STATE_TURNING_ON: number [#centralstate_turning_on-number]

connect(peripheral: Peripheral): void [#connectperipheral-peripheral-void]

Connect to a discovered `peripheral`.

**Parameters**

| Parameter    | Type         | Default | Description                            |
| ------------ | ------------ | ------- | -------------------------------------- |
| `peripheral` | `Peripheral` | —       | A discovered peripheral to connect to. |

Central.destroy(): void [#centraldestroy-void]

Destroy the central manager, stopping any active scan and disconnecting all connected peripherals.

disconnect(peripheral: Peripheral): void [#disconnectperipheral-peripheral-void]

Disconnect from a connected `peripheral`.

**Parameters**

| Parameter    | Type         | Default | Description                                  |
| ------------ | ------------ | ------- | -------------------------------------------- |
| `peripheral` | `Peripheral` | —       | The connected peripheral to disconnect from. |

startScan(serviceUUIDs?: string[], opts?: { scanMode?: number; callbackType?: number }): void [#startscanserviceuuids-string-opts--scanmode-number-callbacktype-number--void]

Start scanning for peripherals advertising the given `serviceUUIDs`. Pass `null` to scan for all peripherals.

**Parameters**

| Parameter       | Type                                           | Default | Description                                                                                     |
| --------------- | ---------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------- |
| `serviceUUIDs?` | `string[]`                                     | —       | The service UUIDs to filter advertisements by; pass `null` to scan for all peripherals.         |
| `opts?`         | `{ scanMode?: number; callbackType?: number }` | —       | Options; `scanMode` selects the Android scan mode (one of the `Central.SCAN_MODE_*` constants). |

Central.state: BluetoothState [#centralstate-bluetoothstate]

The current Bluetooth adapter state. One of `'off'`, `'turningOn'`, `'on'`, or `'turningOff'`.

stopScan(): void [#stopscan-void]

Stop scanning for peripherals.

Peripheral [#peripheral]

new Peripheral(opts: PeripheralOptions) [#new-peripheralopts-peripheraloptions]

Create a new peripheral instance from a `ScanResult`. Typically obtained via the `'discover'` event on `Central` rather than constructed directly. Its identity and advertised metadata are derived from the scan result.

**Parameters**

| Parameter | Type                                      | Default | Description                                                        |
| --------- | ----------------------------------------- | ------- | ------------------------------------------------------------------ |
| `opts`    | [`PeripheralOptions`](#peripheraloptions) | —       | Options carrying the `ScanResult` this peripheral is derived from. |

Peripheral.destroy(): void [#peripheraldestroy-void]

Destroy the peripheral, releasing its underlying resources.

discoverCharacteristics(service: Service): void [#discovercharacteristicsservice-service-void]

Discover characteristics for the given `service`. Results are emitted via the `'characteristicsDiscover'` event.

**Parameters**

| Parameter | Type      | Default | Description                                 |
| --------- | --------- | ------- | ------------------------------------------- |
| `service` | `Service` | —       | The service to discover characteristics on. |

discoverServices(): void [#discoverservices-void]

Discover services offered by the peripheral. Results are emitted via the `'servicesDiscover'` event.

Peripheral.id: string [#peripheralid-string]

The unique identifier of the peripheral, equal to `scanResult.device.address`.

name: string | null [#name-string--null]

The advertised name of the peripheral, or `null` if unavailable. Equal to `scanResult.device.name`.

openL2CAPChannel(psm: number): void [#openl2capchannelpsm-number-void]

Open an L2CAP channel to the peripheral using the given `psm`. The result is emitted via the `'channelOpen'` event.

**Parameters**

| Parameter | Type     | Default | Description                                                    |
| --------- | -------- | ------- | -------------------------------------------------------------- |
| `psm`     | `number` | —       | The PSM (Protocol/Service Multiplexer) of the channel to open. |

Peripheral.PROPERTY_INDICATE: number [#peripheralproperty_indicate-number]

Characteristic property constants.

Peripheral.PROPERTY_NOTIFY: number [#peripheralproperty_notify-number]

Peripheral.PROPERTY_READ: number [#peripheralproperty_read-number]

Peripheral.PROPERTY_WRITE: number [#peripheralproperty_write-number]

Peripheral.PROPERTY_WRITE_WITHOUT_RESPONSE: number [#peripheralproperty_write_without_response-number]

read(characteristic: Characteristic): void [#readcharacteristic-characteristic-void]

Read the value of `characteristic`. The result is emitted via the `'read'` event.

**Parameters**

| Parameter        | Type             | Default | Description                 |
| ---------------- | ---------------- | ------- | --------------------------- |
| `characteristic` | `Characteristic` | —       | The characteristic to read. |

requestMtu(mtu: number): void [#requestmtumtu-number-void]

Request a new MTU size. The result is emitted via the `'mtuChanged'` event.

**Parameters**

| Parameter | Type     | Default | Description                         |
| --------- | -------- | ------- | ----------------------------------- |
| `mtu`     | `number` | —       | The desired ATT MTU size, in bytes. |

rssi: number [#rssi-number]

The signal strength of the most recent advertisement, equal to `scanResult.rssi`.

scanResult: ScanResult [#scanresult-scanresult]

The `ScanResult` from the most recent advertisement for this peripheral.

serviceData: ServiceData | null [#servicedata-servicedata--null]

The advertised service data, or `null` when the advertisement carried no scan record or no service data.

subscribe(characteristic: Characteristic): void [#subscribecharacteristic-characteristic-void]

Subscribe to notifications for `characteristic`.

**Parameters**

| Parameter        | Type             | Default | Description                                              |
| ---------------- | ---------------- | ------- | -------------------------------------------------------- |
| `characteristic` | `Characteristic` | —       | The characteristic to start receiving notifications for. |

unsubscribe(characteristic: Characteristic): void [#unsubscribecharacteristic-characteristic-void]

Unsubscribe from notifications for `characteristic`.

**Parameters**

| Parameter        | Type             | Default | Description                                             |
| ---------------- | ---------------- | ------- | ------------------------------------------------------- |
| `characteristic` | `Characteristic` | —       | The characteristic to stop receiving notifications for. |

write(characteristic: Characteristic, data: Uint8Array, withResponse?: boolean): void [#writecharacteristic-characteristic-data-uint8array-withresponse-boolean-void]

Write `data` to `characteristic`. If `withResponse` is `true` (the default), a write confirmation is requested.

**Parameters**

| Parameter        | Type             | Default | Description                                                 |
| ---------------- | ---------------- | ------- | ----------------------------------------------------------- |
| `characteristic` | `Characteristic` | —       | The characteristic to write to.                             |
| `data`           | `Uint8Array`     | —       | The bytes to write.                                         |
| `withResponse?`  | `boolean`        | —       | Whether a write confirmation is requested (default `true`). |

Types [#types]

ServiceOptions [#serviceoptions]

```ts
interface ServiceOptions {
  primary?: boolean
}
```

CharacteristicOptions [#characteristicoptions]

```ts
interface CharacteristicOptions {
  read?: boolean
  write?: boolean
  writeWithoutResponse?: boolean
  notify?: boolean
  indicate?: boolean
  permissions?: number
  value?: Uint8Array | null
}
```

BluetoothState [#bluetoothstate]

```ts
type BluetoothState = 'off' | 'turningOn' | 'on' | 'turningOff'
```

AdvertisingOptions [#advertisingoptions]

```ts
interface AdvertisingOptions {
  name?: string
  serviceUUIDs?: string[]
}
```

ChannelOptions [#channeloptions]

```ts
interface ChannelOptions {
  encrypted?: boolean
}
```

ReadRequest [#readrequest]

```ts
interface ReadRequest {
  handle: unknown
  requestId: number
  characteristicUuid: string
  offset: number
}
```

WriteRequest [#writerequest]

```ts
interface WriteRequest {
  handle: unknown
  requestId: number
  characteristicUuid: string
  data: Uint8Array
  offset: number
  responseNeeded: boolean
}
```

PeripheralOptions [#peripheraloptions]

```ts
interface PeripheralOptions {
  scanResult: ScanResult
}
```

ServiceData [#servicedata]

```ts
type ServiceData = {
  [uuid: string]: Uint8Array
}
```

Classes [#classes]

ScanResult [#scanresult]

```ts
class ScanResult {
  device: Device
  rssi: number
  scanRecord: ScanRecord | null
}
```

ScanRecord [#scanrecord]

```ts
class ScanRecord {
  serviceData: ServiceData | null
}
```

Device [#device]

```ts
class Device {
  address: string
  name: string | null
}
```

See also [#see-also]

* Builds on `bare-events` and `bare-stream`.
* Runs on Android only — on Apple platforms use [`bare-bluetooth-apple`](/reference/bare/modules/bare-bluetooth-apple).
* [One core, many platforms](/explanation/bare-on-native) — using platform bindings from a native shell.
* [Bare modules](/reference/modules/bare-modules) — the full `bare-*` catalog.
* [Bare runtime API](/reference/bare/runtime) — the runtime these modules extend.


# bare-bluetooth-apple



<mark style={{ backgroundColor: '#7dde9a', padding: '2px 8px', borderRadius: '4px', fontSize: '0.85em', fontWeight: 500 }}>
  stable
</mark>

[`bare-bluetooth-apple`](https://github.com/holepunchto/bare-bluetooth-apple) — CoreBluetooth bindings for Bare. It is a native addon.

```sh
npm i bare-bluetooth-apple
```

Usage [#usage]

```js
const bluetooth = require('bare-bluetooth-apple')

const manager = new bluetooth.PeripheralManager()

manager.on('stateChange', (state) => {
  if (state !== 'poweredOn') return

  const char = new bluetooth.Characteristic('01230001-0000-1000-8000-00805F9B34FB', {
    write: true,
    notify: true
  })

  const service = new bluetooth.Service('01230000-0000-1000-8000-00805F9B34FB', [char])
  manager.addService(service)
})

manager.on('serviceAdd', (uuid, error) => {
  if (error) return

  manager.startAdvertising({
    name: 'MyDevice',
    serviceUUIDs: ['01230000-0000-1000-8000-00805F9B34FB']
  })
})

manager.on('error', (err) => {
  console.error('manager error:', err.code, err.message)
})

manager.on('writeRequest', (requests) => {
  // Handle incoming write requests
  manager.respondToRequest(requests[0], bluetooth.PeripheralManager.ATT_SUCCESS, null)
})
```

API [#api]

L2CAPChannel [#l2capchannel]

new L2CAPChannel(channelHandle: ArrayBuffer) [#new-l2capchannelchannelhandle-arraybuffer]

An L2CAP channel, obtained through the `'channelOpen'` event on `PeripheralManager` or `Peripheral`. Extends `Duplex` from `bare-stream` and supports standard readable and writable stream operations.

**Parameters**

| Parameter       | Type          | Default | Description                                                                                                          |
| --------------- | ------------- | ------- | -------------------------------------------------------------------------------------------------------------------- |
| `channelHandle` | `ArrayBuffer` | —       | The native channel handle backing the stream; supplied internally when a channel opens, not usually passed directly. |

peer: string | null [#peer-string--null]

The UUID of the remote peer if available

psm: number [#psm-number]

The L2CAP PSM (Protocol/Service Multiplexer) for this channel

Service [#service]

new Service(uuid: string, characteristics?: Characteristic[], opts?: ServiceOptions) [#new-serviceuuid-string-characteristics-characteristic-opts-serviceoptions]

Create a GATT service definition.

**Parameters**

| Parameter          | Type                                | Default | Description                                                  |
| ------------------ | ----------------------------------- | ------- | ------------------------------------------------------------ |
| `uuid`             | `string`                            | —       | The service's UUID.                                          |
| `characteristics?` | `Characteristic[]`                  | —       | The characteristics belonging to the service.                |
| `opts?`            | [`ServiceOptions`](#serviceoptions) | —       | Options; set `primary: true` to mark this a primary service. |

characteristics: Characteristic[] [#characteristics-characteristic]

The characteristics belonging to this service

primary: boolean [#primary-boolean]

Whether this is a primary service

Service.uuid: string [#serviceuuid-string]

The service UUID

Characteristic [#characteristic]

new Characteristic(uuid: string, opts?: CharacteristicOptions) [#new-characteristicuuid-string-opts-characteristicoptions]

Create a GATT characteristic definition.

**Parameters**

| Parameter | Type                                              | Default | Description                                                                                                                                                           |
| --------- | ------------------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `uuid`    | `string`                                          | —       | The characteristic's UUID.                                                                                                                                            |
| `opts?`   | [`CharacteristicOptions`](#characteristicoptions) | —       | Options selecting the characteristic `properties` (`read`, `write`, `writeWithoutResponse`, `notify`, `indicate`) and its optional `permissions` and initial `value`. |

Characteristic.PROPERTY_INDICATE: number [#characteristicproperty_indicate-number]

Characteristic.PROPERTY_NOTIFY: number [#characteristicproperty_notify-number]

Characteristic.PROPERTY_READ: number [#characteristicproperty_read-number]

Characteristic.PROPERTY_WRITE: number [#characteristicproperty_write-number]

Characteristic.PROPERTY_WRITE_WITHOUT_RESPONSE: number [#characteristicproperty_write_without_response-number]

permissions: number | null [#permissions-number--null]

Bitmask of characteristic permissions, if set explicitly

properties: number [#properties-number]

Bitmask of characteristic properties

Characteristic.uuid: string [#characteristicuuid-string]

The characteristic UUID

value: Uint8Array | null [#value-uint8array--null]

The current value, if set

PeripheralManager [#peripheralmanager]

new PeripheralManager() [#new-peripheralmanager]

Create a new BLE peripheral manager. Advertises services and handles read/write requests from centrals.

addService(service: Service): void [#addserviceservice-service-void]

Add a `service` to the manager. The service and its characteristics will be registered with the system.

**Parameters**

| Parameter | Type      | Default | Description                                                                |
| --------- | --------- | ------- | -------------------------------------------------------------------------- |
| `service` | `Service` | —       | The `Service` to register with the system, along with its characteristics. |

PeripheralManager.destroy(): void [#peripheralmanagerdestroy-void]

Destroy the instance and release all resources.

PeripheralManager.ATT_INSUFFICIENT_RESOURCES: number [#peripheralmanageratt_insufficient_resources-number]

PeripheralManager.ATT_INVALID_HANDLE: number [#peripheralmanageratt_invalid_handle-number]

PeripheralManager.ATT_READ_NOT_PERMITTED: number [#peripheralmanageratt_read_not_permitted-number]

PeripheralManager.ATT_SUCCESS: number [#peripheralmanageratt_success-number]

PeripheralManager.ATT_UNLIKELY_ERROR: number [#peripheralmanageratt_unlikely_error-number]

ATT result codes for use with `manager.respondToRequest()`.

PeripheralManager.ATT_WRITE_NOT_PERMITTED: number [#peripheralmanageratt_write_not_permitted-number]

PeripheralManager.PERMISSION_READ_ENCRYPTED: number [#peripheralmanagerpermission_read_encrypted-number]

PeripheralManager.PERMISSION_READABLE: number [#peripheralmanagerpermission_readable-number]

PeripheralManager.PERMISSION_WRITE_ENCRYPTED: number [#peripheralmanagerpermission_write_encrypted-number]

Characteristic permission flags.

PeripheralManager.PERMISSION_WRITEABLE: number [#peripheralmanagerpermission_writeable-number]

PeripheralManager.PROPERTY_INDICATE: number [#peripheralmanagerproperty_indicate-number]

Characteristic property flags.

PeripheralManager.PROPERTY_NOTIFY: number [#peripheralmanagerproperty_notify-number]

PeripheralManager.PROPERTY_READ: number [#peripheralmanagerproperty_read-number]

PeripheralManager.PROPERTY_WRITE: number [#peripheralmanagerproperty_write-number]

PeripheralManager.PROPERTY_WRITE_WITHOUT_RESPONSE: number [#peripheralmanagerproperty_write_without_response-number]

PeripheralManager.STATE_POWERED_OFF: number [#peripheralmanagerstate_powered_off-number]

PeripheralManager.STATE_POWERED_ON: number [#peripheralmanagerstate_powered_on-number]

PeripheralManager.STATE_RESETTING: number [#peripheralmanagerstate_resetting-number]

PeripheralManager.STATE_UNAUTHORIZED: number [#peripheralmanagerstate_unauthorized-number]

PeripheralManager.STATE_UNKNOWN: number [#peripheralmanagerstate_unknown-number]

PeripheralManager.STATE_UNSUPPORTED: number [#peripheralmanagerstate_unsupported-number]

Bluetooth state constants.

publishChannel(opts?: ChannelOptions): void [#publishchannelopts-channeloptions-void]

Publish an L2CAP channel.

**Parameters**

| Parameter | Type                                | Default | Description                               |
| --------- | ----------------------------------- | ------- | ----------------------------------------- |
| `opts?`   | [`ChannelOptions`](#channeloptions) | —       | Options for the L2CAP channel to publish. |

respondToRequest(request: ReadRequest, result: number, data?: Uint8Array | null): void [#respondtorequestrequest-readrequest-result-number-data-uint8array--null-void]

Respond to a read or write `request` with the given ATT `result` code. Optionally include `data` for read responses.

**Parameters**

| Parameter | Type                          | Default | Description                                                                                          |
| --------- | ----------------------------- | ------- | ---------------------------------------------------------------------------------------------------- |
| `request` | [`ReadRequest`](#readrequest) | —       | The read or write request to respond to, as delivered by the `'readRequest'`/`'writeRequest'` event. |
| `result`  | `number`                      | —       | The ATT result code, for example `PeripheralManager.ATT_SUCCESS`.                                    |
| `data?`   | `Uint8Array` \| `null`        | —       | The value to return for a read request; omit for write responses.                                    |

startAdvertising(opts?: AdvertisingOptions): void [#startadvertisingopts-advertisingoptions-void]

Start advertising.

**Parameters**

| Parameter | Type                                        | Default | Description                                                                       |
| --------- | ------------------------------------------- | ------- | --------------------------------------------------------------------------------- |
| `opts?`   | [`AdvertisingOptions`](#advertisingoptions) | —       | Advertising options such as the local `name` and the `serviceUUIDs` to advertise. |

PeripheralManager.state: BluetoothState [#peripheralmanagerstate-bluetoothstate]

The current Bluetooth adapter state

stopAdvertising(): void [#stopadvertising-void]

Stop advertising.

unpublishChannel(psm: number): void [#unpublishchannelpsm-number-void]

Unpublish a previously published L2CAP channel identified by `psm`.

**Parameters**

| Parameter | Type     | Default | Description                                                             |
| --------- | -------- | ------- | ----------------------------------------------------------------------- |
| `psm`     | `number` | —       | The PSM of the channel to unpublish, as assigned when it was published. |

updateValue(characteristic: Characteristic, data: Uint8Array): boolean [#updatevaluecharacteristic-characteristic-data-uint8array-boolean]

Update the value of a `characteristic` and notify subscribed centrals.

**Parameters**

| Parameter        | Type             | Default | Description                                   |
| ---------------- | ---------------- | ------- | --------------------------------------------- |
| `characteristic` | `Characteristic` | —       | The characteristic whose value changed.       |
| `data`           | `Uint8Array`     | —       | The new value to send to subscribed centrals. |

**Returns** `boolean` — Whether the notification was sent to subscribed centrals successfully.

Central [#central]

new Central() [#new-central]

Create a new BLE central manager. The central scans for and connects to peripherals.

Central.STATE_POWERED_OFF: number [#centralstate_powered_off-number]

Central.STATE_POWERED_ON: number [#centralstate_powered_on-number]

Central.STATE_RESETTING: number [#centralstate_resetting-number]

Central.STATE_UNAUTHORIZED: number [#centralstate_unauthorized-number]

Central.STATE_UNKNOWN: number [#centralstate_unknown-number]

Central.STATE_UNSUPPORTED: number [#centralstate_unsupported-number]

connect(peripheral: DiscoveredPeripheral): void [#connectperipheral-discoveredperipheral-void]

Connect to a discovered `peripheral`.

**Parameters**

| Parameter    | Type                                            | Default | Description                            |
| ------------ | ----------------------------------------------- | ------- | -------------------------------------- |
| `peripheral` | [`DiscoveredPeripheral`](#discoveredperipheral) | —       | A discovered peripheral to connect to. |

Central.destroy(): void [#centraldestroy-void]

Destroy the instance and release all resources.

disconnect(peripheral: Peripheral): void [#disconnectperipheral-peripheral-void]

Disconnect from a connected `peripheral`.

**Parameters**

| Parameter    | Type         | Default | Description                                  |
| ------------ | ------------ | ------- | -------------------------------------------- |
| `peripheral` | `Peripheral` | —       | The connected peripheral to disconnect from. |

startScan(serviceUUIDs?: string[], opts?: { allowDuplicates?: boolean }): void [#startscanserviceuuids-string-opts--allowduplicates-boolean--void]

Start scanning for peripherals. If `serviceUUIDs` is provided, only peripherals advertising those services will be discovered.

**Parameters**

| Parameter       | Type                            | Default | Description                                                                      |
| --------------- | ------------------------------- | ------- | -------------------------------------------------------------------------------- |
| `serviceUUIDs?` | `string[]`                      | —       | The service UUIDs to filter advertisements by; omit to discover all peripherals. |
| `opts?`         | `{ allowDuplicates?: boolean }` | —       | —                                                                                |

Central.state: BluetoothState [#centralstate-bluetoothstate]

The current Bluetooth adapter state

stopScan(): void [#stopscan-void]

Stop scanning for peripherals.

Peripheral [#peripheral]

new Peripheral(peripheralHandle: ArrayBuffer, opts?: PeripheralOptions) [#new-peripheralperipheralhandle-arraybuffer-opts-peripheraloptions]

Represents a connected BLE peripheral. Obtained through the `'connect'` event on `Central` — not typically constructed directly.

**Parameters**

| Parameter          | Type                                      | Default | Description                                                                                                    |
| ------------------ | ----------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------- |
| `peripheralHandle` | `ArrayBuffer`                             | —       | The native peripheral handle; supplied internally when Central emits `'connect'`, not usually passed directly. |
| `opts?`            | [`PeripheralOptions`](#peripheraloptions) | —       | Options carrying the peripheral's advertised metadata.                                                         |

Peripheral.destroy(): void [#peripheraldestroy-void]

Destroy the instance and release all resources.

discoverCharacteristics(service: Service, characteristicUUIDs?: string[]): void [#discovercharacteristicsservice-service-characteristicuuids-string-void]

Discover characteristics for a `service`. If `characteristicUUIDs` is provided, only those characteristics will be discovered.

**Parameters**

| Parameter              | Type       | Default | Description                                                                                |
| ---------------------- | ---------- | ------- | ------------------------------------------------------------------------------------------ |
| `service`              | `Service`  | —       | The service to discover characteristics on.                                                |
| `characteristicUUIDs?` | `string[]` | —       | The characteristic UUIDs to discover; omit to discover all characteristics of the service. |

discoverServices(serviceUUIDs?: string[]): void [#discoverservicesserviceuuids-string-void]

Discover services on the peripheral. If `serviceUUIDs` is provided, only those services will be discovered.

**Parameters**

| Parameter       | Type       | Default | Description                                                   |
| --------------- | ---------- | ------- | ------------------------------------------------------------- |
| `serviceUUIDs?` | `string[]` | —       | The service UUIDs to discover; omit to discover all services. |

id: string [#id-string]

The peripheral UUID identifier

name: string | null [#name-string--null]

The peripheral name, if available

openL2CAPChannel(psm: number): void [#openl2capchannelpsm-number-void]

Open an L2CAP channel to the peripheral using the given `psm`.

**Parameters**

| Parameter | Type     | Default | Description                                                    |
| --------- | -------- | ------- | -------------------------------------------------------------- |
| `psm`     | `number` | —       | The PSM (Protocol/Service Multiplexer) of the channel to open. |

Peripheral.PROPERTY_INDICATE: number [#peripheralproperty_indicate-number]

Peripheral.PROPERTY_NOTIFY: number [#peripheralproperty_notify-number]

Peripheral.PROPERTY_READ: number [#peripheralproperty_read-number]

Peripheral.PROPERTY_WRITE: number [#peripheralproperty_write-number]

Peripheral.PROPERTY_WRITE_WITHOUT_RESPONSE: number [#peripheralproperty_write_without_response-number]

read(characteristic: Characteristic): void [#readcharacteristic-characteristic-void]

Read the value of a `characteristic`.

**Parameters**

| Parameter        | Type             | Default | Description                 |
| ---------------- | ---------------- | ------- | --------------------------- |
| `characteristic` | `Characteristic` | —       | The characteristic to read. |

serviceData: { [uuid: string]: Uint8Array } | null [#servicedata--uuid-string-uint8array---null]

Service data captured from the most recent advertisement seen before connect, or null

subscribe(characteristic: Characteristic): void [#subscribecharacteristic-characteristic-void]

Subscribe to notifications for a `characteristic`.

**Parameters**

| Parameter        | Type             | Default | Description                                              |
| ---------------- | ---------------- | ------- | -------------------------------------------------------- |
| `characteristic` | `Characteristic` | —       | The characteristic to start receiving notifications for. |

unsubscribe(characteristic: Characteristic): void [#unsubscribecharacteristic-characteristic-void]

Unsubscribe from notifications for a `characteristic`.

**Parameters**

| Parameter        | Type             | Default | Description                                             |
| ---------------- | ---------------- | ------- | ------------------------------------------------------- |
| `characteristic` | `Characteristic` | —       | The characteristic to stop receiving notifications for. |

write(characteristic: Characteristic, data: Uint8Array, withResponse?: boolean): void [#writecharacteristic-characteristic-data-uint8array-withresponse-boolean-void]

Write `data` to a `characteristic`. If `withResponse` is `true` (the default), the write will be confirmed by the peripheral.

**Parameters**

| Parameter        | Type             | Default | Description                                                 |
| ---------------- | ---------------- | ------- | ----------------------------------------------------------- |
| `characteristic` | `Characteristic` | —       | The characteristic to write to.                             |
| `data`           | `Uint8Array`     | —       | The bytes to write.                                         |
| `withResponse?`  | `boolean`        | —       | Whether the peripheral confirms the write (default `true`). |

Types [#types]

ServiceOptions [#serviceoptions]

```ts
interface ServiceOptions {
  primary?: boolean
}
```

CharacteristicOptions [#characteristicoptions]

```ts
interface CharacteristicOptions {
  read?: boolean
  write?: boolean
  writeWithoutResponse?: boolean
  notify?: boolean
  indicate?: boolean
  permissions?: number
  value?: Uint8Array | null
}
```

BluetoothState [#bluetoothstate]

```ts
type BluetoothState = 'unknown' | 'resetting' | 'unsupported' | 'unauthorized' | 'poweredOff' | 'poweredOn'
```

AdvertisingOptions [#advertisingoptions]

```ts
interface AdvertisingOptions {
  name?: string
  serviceUUIDs?: string[]
  serviceData?: { [uuid: string]: Uint8Array }
}
```

ChannelOptions [#channeloptions]

```ts
interface ChannelOptions {
  encrypted?: boolean
}
```

ReadRequest [#readrequest]

```ts
interface ReadRequest {
  characteristicUuid: string
  offset: number
}
```

WriteRequest [#writerequest]

```ts
interface WriteRequest {
  characteristicUuid: string
  data: Uint8Array
  offset: number
}
```

PeripheralManagerEventMap [#peripheralmanagereventmap]

```ts
interface PeripheralManagerEventMap {
  stateChange: [state: BluetoothState]
  error: [error: BluetoothError]
  serviceAdd: [uuid: string]
  channelPublish: [psm: number]
  channelOpen: [channel: L2CAPChannel]
  readRequest: [request: ReadRequest]
  writeRequest: [requests: WriteRequest[]]
  subscribe: [centralHandle: ArrayBuffer, characteristicUuid: string]
  unsubscribe: [centralHandle: ArrayBuffer, characteristicUuid: string]
  readyToUpdate: []
}
```

DiscoveredPeripheral [#discoveredperipheral]

```ts
interface DiscoveredPeripheral {
  id: string
  name: string | null
  rssi: number
  serviceData: { [uuid: string]: Uint8Array } | null
}
```

CentralEventMap [#centraleventmap]

```ts
interface CentralEventMap {
  stateChange: [state: BluetoothState]
  error: [error: BluetoothError]
  discover: [peripheral: DiscoveredPeripheral]
  connect: [peripheral: Peripheral]
  disconnect: [peripheral: Peripheral | null]
}
```

PeripheralOptions [#peripheraloptions]

```ts
interface PeripheralOptions {
  central?: Central
  id?: string
  name?: string
  serviceData?: { [uuid: string]: Uint8Array } | null
}
```

PeripheralEventMap [#peripheraleventmap]

```ts
interface PeripheralEventMap {
  error: [error: BluetoothError]
  servicesDiscover: [services: Service[]]
  characteristicsDiscover: [service: Service | null, characteristics: Characteristic[]]
  read: [characteristic: Characteristic | null, data: Uint8Array | null]
  write: [characteristic: Characteristic | null]
  notify: [characteristic: Characteristic | null, data: Uint8Array | null]
  notifyState: [characteristic: Characteristic | null, isNotifying: boolean]
  channelOpen: [channel: L2CAPChannel]
}
```

See also [#see-also]

* Builds on `bare-events` and `bare-stream`.
* Runs on Apple platforms (iOS and macOS) — on Android use [`bare-bluetooth-android`](/reference/bare/modules/bare-bluetooth-android).
* [One core, many platforms](/explanation/bare-on-native) — using platform bindings from a native shell.
* [Bare modules](/reference/modules/bare-modules) — the full `bare-*` catalog.
* [Bare runtime API](/reference/bare/runtime) — the runtime these modules extend.


# bare-broadcast-channel



<mark style={{ backgroundColor: '#7dde9a', padding: '2px 8px', borderRadius: '4px', fontSize: '0.85em', fontWeight: 500 }}>
  stable
</mark>

[`bare-broadcast-channel`](https://github.com/holepunchto/bare-broadcast-channel) — Multi-producer, multi-consumer inter-thread broadcast messaging for JavaScript. It is a native addon.

```sh
npm i bare-broadcast-channel
```

Usage [#usage]

```js
const BroadcastChannel = require('bare-broadcast-channel')
const { Thread } = Bare

const channel = new BroadcastChannel()

const consumer = (label) =>
  new Thread(__filename, { data: { handle: channel.handle, label } }, async ({ handle, label }) => {
    const BroadcastChannel = require('bare-broadcast-channel')
    const port = BroadcastChannel.from(handle).connect()
    console.log(label, 'got', await port.read())
    await port.close()
  })

const a = consumer('a')
const b = consumer('b')

const port = channel.connect()

while (port.peers < 2) await new Promise((r) => setTimeout(r, 10))

await port.write('hello')
await port.close()

a.join()
b.join()
```

API [#api]

BroadcastChannel [#broadcastchannel]

new BroadcastChannel(opts?: BroadcastChannelOptions) [#new-broadcastchannelopts-broadcastchanneloptions]

Create a new broadcast channel. The channel is backed by a `SharedArrayBuffer` exposed as `channel.handle` that can be passed to other threads to share the channel across them.

**Parameters**

| Parameter | Type                                                  | Default | Description                                                                                                                                                                                              |
| --------- | ----------------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `opts?`   | [`BroadcastChannelOptions`](#broadcastchanneloptions) | —       | Channel options; `handle` backs the channel with an existing `SharedArrayBuffer`, `interfaces` registers serializable and transferable interfaces (default `[]`), and `portCapacity` defaults to `1024`. |

BroadcastChannel.from [#broadcastchannelfrom]

```ts
BroadcastChannel.from(handle: SharedArrayBuffer, opts?: BroadcastChannelOptions): BroadcastChannel
```

Restore a channel from its `SharedArrayBuffer` `handle`. `options` accepts the same fields as the constructor, except for `handle`.

**Parameters**

| Parameter | Type                                                  | Default | Description                                                                  |
| --------- | ----------------------------------------------------- | ------- | ---------------------------------------------------------------------------- |
| `handle`  | `SharedArrayBuffer`                                   | —       | The `SharedArrayBuffer` backing the channel, as exposed by `channel.handle`. |
| `opts?`   | [`BroadcastChannelOptions`](#broadcastchanneloptions) | —       | The same options as the constructor, except `handle`.                        |

**Returns** `BroadcastChannel` — A channel backed by the given `handle`.

BroadcastChannel.MAX_PORTS: number [#broadcastchannelmax_ports-number]

Maximum number of ports that may connect to a single channel over its lifetime.

connect(): Port<T> [#connect-portt]

Connect a new port to the channel. Throws if `MAX_PORTS` has been reached. Port slots are not reused, so the cap applies to the total number of connections over the channel's lifetime, not the number of concurrently connected ports.

**Returns** `Port<T>` — A new port connected to the channel.

handle: SharedArrayBuffer [#handle-sharedarraybuffer]

The `SharedArrayBuffer` backing the channel. Pass this to other threads to share the channel.

interfaces: SerializableConstructor[] [#interfaces-serializableconstructor]

The serializable and transferable interfaces registered on the channel.

Port [#port]

new Port(channel: BroadcastChannel<T>) [#new-portchannel-broadcastchannelt]

**Parameters**

| Parameter | Type                  | Default | Description |
| --------- | --------------------- | ------- | ----------- |
| `channel` | `BroadcastChannel<T>` | —       | —           |

close(): Promise<void> [#close-promisevoid]

createReadStream(opts?: ReadableOptions<Port<T>>): Readable [#createreadstreamopts-readableoptionsportt-readable]

**Parameters**

| Parameter | Type                       | Default | Description |
| --------- | -------------------------- | ------- | ----------- |
| `opts?`   | `ReadableOptions<Port<T>>` | —       | —           |

createStream(opts?: DuplexOptions<Port<T>>): Duplex [#createstreamopts-duplexoptionsportt-duplex]

**Parameters**

| Parameter | Type                     | Default | Description |
| --------- | ------------------------ | ------- | ----------- |
| `opts?`   | `DuplexOptions<Port<T>>` | —       | —           |

createWriteStream(opts?: WritableOptions<Port<T>>): Writable [#createwritestreamopts-writableoptionsportt-writable]

**Parameters**

| Parameter | Type                       | Default | Description |
| --------- | -------------------------- | ------- | ----------- |
| `opts?`   | `WritableOptions<Port<T>>` | —       | —           |

peers: number [#peers-number]

read(): Promise<T | null> [#read-promiset--null]

readSync(): T | null [#readsync-t--null]

ref(): void [#ref-void]

unref(): void [#unref-void]

write(value: T): Promise<boolean> [#writevalue-t-promiseboolean]

Broadcast a structured-cloneable `value` to peers.

**Parameters**

| Parameter | Type | Default | Description                                         |
| --------- | ---- | ------- | --------------------------------------------------- |
| `value`   | `T`  | —       | A structured-cloneable value to broadcast to peers. |

**Returns** `Promise<boolean>` — Whether the write flushed.

writeSync(value: T): boolean [#writesyncvalue-t-boolean]

Broadcast a structured-cloneable `value` to peers.

**Parameters**

| Parameter | Type | Default | Description                                         |
| --------- | ---- | ------- | --------------------------------------------------- |
| `value`   | `T`  | —       | A structured-cloneable value to broadcast to peers. |

**Returns** `boolean` — Whether the write flushed.

Types [#types]

BroadcastChannelOptions [#broadcastchanneloptions]

```ts
interface BroadcastChannelOptions {
  handle?: SharedArrayBuffer
  interfaces?: SerializableConstructor[]
  portCapacity?: number
}
```

PortEvents [#portevents]

```ts
interface PortEvents {
  peers: [count: number]
  close: []
}
```

See also [#see-also]

* Builds on `bare-events`, `bare-stream`, and `bare-structured-clone`.
* [Bare modules](/reference/modules/bare-modules) — the full `bare-*` catalog.
* [Bare runtime API](/reference/bare/runtime) — the runtime these modules extend.


# bare-buffer



<mark style={{ backgroundColor: '#7dde9a', padding: '2px 8px', borderRadius: '4px', fontSize: '0.85em', fontWeight: 500 }}>
  stable
</mark>

[`bare-buffer`](https://github.com/holepunchto/bare-buffer) — Native buffers for JavaScript. It is a native addon and requires Bare `>=1.20.0`.

Mirrors the Node.js [`buffer`](https://nodejs.org/api/buffer.html) module.

```sh
npm i bare-buffer
```

Usage [#usage]

```js
const Buffer = require('bare-buffer')

const message = Buffer.from('hello')
const empty = Buffer.alloc(16)
const buffer = Buffer.allocUnsafe(4).fill(123)
const combined = Buffer.concat([buffer, buffer])
```

API [#api]

Buffer [#buffer]

new Buffer(arrayBuffer: ArrayBuffer, offset?: number, length?: number) [#new-bufferarraybuffer-arraybuffer-offset-number-length-number]

Create a `Buffer` viewing `arrayBuffer`, optionally starting at `offset` for `length` bytes.

**Parameters**

| Parameter     | Type          | Default | Description                                                                   |
| ------------- | ------------- | ------- | ----------------------------------------------------------------------------- |
| `arrayBuffer` | `ArrayBuffer` | —       | The `ArrayBuffer` to view.                                                    |
| `offset?`     | `number`      | —       | Byte offset into `arrayBuffer` to start the view at; defaults to `0`.         |
| `length?`     | `number`      | —       | Number of bytes to view from `offset`; defaults to the rest of `arrayBuffer`. |

**Throws**

* `RangeError` — thrown if the resulting length would exceed `Buffer.constants.MAX_LENGTH`.

Buffer.alloc(size: number, fill: string, encoding?: BufferEncoding): Buffer [#bufferallocsize-number-fill-string-encoding-bufferencoding-buffer]

Allocate a new, zero-filled `Buffer` of `size` bytes, optionally filled with `fill`.

Overloads:

```ts
Buffer.alloc(size: number, fill: string, encoding?: BufferEncoding): Buffer
Buffer.alloc(size: number, fill?: Buffer | number | boolean): Buffer
```

**Parameters**

| Parameter   | Type             | Default | Description                                                                  |
| ----------- | ---------------- | ------- | ---------------------------------------------------------------------------- |
| `size`      | `number`         | —       | Number of bytes to allocate.                                                 |
| `fill`      | `string`         | —       | Value to fill the buffer with — a string, `Buffer`, number byte, or boolean. |
| `encoding?` | `BufferEncoding` | —       | Encoding used to interpret `fill` when it's a string; defaults to `'utf8'`.  |

**Throws**

* `RangeError` — thrown if `size` exceeds `Buffer.constants.MAX_LENGTH`.

Buffer.allocUnsafe(size: number): Buffer [#bufferallocunsafesize-number-buffer]

Allocate a new `Buffer` of `size` bytes without zeroing its contents first.

**Parameters**

| Parameter | Type     | Default | Description                  |
| --------- | -------- | ------- | ---------------------------- |
| `size`    | `number` | —       | Number of bytes to allocate. |

**Throws**

* `RangeError` — thrown if `size` exceeds `Buffer.constants.MAX_LENGTH`.

Buffer.allocUnsafeSlow(size: number): Buffer [#bufferallocunsafeslowsize-number-buffer]

Allocate a new `Buffer` of `size` bytes without zeroing its contents first, bypassing the internal buffer pool.

**Parameters**

| Parameter | Type     | Default | Description                  |
| --------- | -------- | ------- | ---------------------------- |
| `size`    | `number` | —       | Number of bytes to allocate. |

**Throws**

* `RangeError` — thrown if `size` exceeds `Buffer.constants.MAX_LENGTH`.

Buffer.atob(data: unknown): string [#bufferatobdata-unknown-string]

Decode a base64-encoded string into a Latin-1 binary string.

**Parameters**

| Parameter | Type      | Default | Description                          |
| --------- | --------- | ------- | ------------------------------------ |
| `data`    | `unknown` | —       | The base64-encoded string to decode. |

Buffer.btoa(data: unknown): string [#bufferbtoadata-unknown-string]

Encode a Latin-1 binary string into a base64 string.

**Parameters**

| Parameter | Type      | Default | Description                                                   |
| --------- | --------- | ------- | ------------------------------------------------------------- |
| `data`    | `unknown` | —       | The value to encode; non-strings are coerced with `String()`. |

Buffer.BufferEncoding [#bufferbufferencoding]

```ts
type BufferEncoding = | 'ascii'
  | 'base64'
  | 'binary'
  | 'hex'
  | 'latin1'
  | 'ucs-2'
  | 'ucs2'
  | 'utf-16le'
  | 'utf-8'
  | 'utf16le'
  | 'utf8'
```

The set of encodings supported by `Buffer` methods that convert between bytes and strings.

Buffer.byteLength [#bufferbytelength]

```ts
Buffer.byteLength(string: ArrayBufferView | ArrayBufferLike | string, encoding?: BufferEncoding): number
```

Return the number of bytes `string` would occupy once encoded as `encoding`.

**Parameters**

| Parameter   | Type                                               | Default | Description                                                                                                                                     |
| ----------- | -------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `string`    | `ArrayBufferView` \| `ArrayBufferLike` \| `string` | —       | The value whose encoded length to measure — a string, or an `ArrayBufferView`/`ArrayBufferLike` (whose own `byteLength` is returned unchanged). |
| `encoding?` | `BufferEncoding`                                   | —       | Encoding used to measure `string` when it's a string; defaults to `'utf8'`.                                                                     |

**Throws**

* `Error` — thrown if the encoding is not a recognized `BufferEncoding`.

Buffer.coerce(buffer: Buffer): Buffer [#buffercoercebuffer-buffer-buffer]

Return `buffer` unchanged if it is already a `Buffer`, otherwise wrap its underlying `ArrayBuffer` in a new `Buffer`.

**Parameters**

| Parameter | Type     | Default | Description                          |
| --------- | -------- | ------- | ------------------------------------ |
| `buffer`  | `Buffer` | —       | The value to coerce into a `Buffer`. |

Buffer.compare(a: Buffer, b: Buffer): number [#buffercomparea-buffer-b-buffer-number]

Compare two buffers' contents lexicographically, returning -1, 0, or 1 for sort ordering.

**Parameters**

| Parameter | Type     | Default | Description                   |
| --------- | -------- | ------- | ----------------------------- |
| `a`       | `Buffer` | —       | The first buffer to compare.  |
| `b`       | `Buffer` | —       | The second buffer to compare. |

Buffer.concat(buffers: Buffer[], length?: number): Buffer [#bufferconcatbuffers-buffer-length-number-buffer]

Concatenate `buffers` into a single new `Buffer`, optionally truncated or zero-padded to `length`.

**Parameters**

| Parameter | Type       | Default | Description                                                                 |
| --------- | ---------- | ------- | --------------------------------------------------------------------------- |
| `buffers` | `Buffer[]` | —       | The buffers to concatenate, in order.                                       |
| `length?` | `number`   | —       | Total byte length of the result; defaults to the sum of `buffers`' lengths. |

Buffer.constants: { MAX_LENGTH: number; MAX_STRING_LENGTH: number } [#bufferconstants--max_length-number-max_string_length-number-]

Limits for buffers and strings: `MAX_LENGTH` (largest possible `Buffer`) and `MAX_STRING_LENGTH` (largest possible string).

Buffer.copyBytesFrom(view: ArrayBufferLike, offset?: number, length?: number): Buffer [#buffercopybytesfromview-arraybufferlike-offset-number-length-number-buffer]

Copy the bytes of `view`, starting at `offset` for `length` elements, into a new `Buffer`.

**Parameters**

| Parameter | Type              | Default | Description                                                           |
| --------- | ----------------- | ------- | --------------------------------------------------------------------- |
| `view`    | `ArrayBufferLike` | —       | The typed array (or other `ArrayBufferLike` view) to copy bytes from. |
| `offset?` | `number`          | —       | Index of the first element to copy; defaults to `0`.                  |
| `length?` | `number`          | —       | Number of elements to copy; defaults to the rest of `view`.           |

**Throws**

* `RangeError` — thrown if `offset + length` exceeds `view.length`.

Buffer.from(data: Iterable<number>): Buffer [#bufferfromdata-iterablenumber-buffer]

Create a new `Buffer` from an array, array-like, string, or `ArrayBuffer`.

Overloads:

```ts
Buffer.from(data: Iterable<number>): Buffer
Buffer.from(data: ArrayLike<number>): Buffer
Buffer.from(string: string, encoding?: BufferEncoding): Buffer
Buffer.from(arrayBuffer: ArrayBufferLike, offset?: number, length?: number): Buffer
```

**Parameters**

| Parameter | Type               | Default | Description                                                                            |
| --------- | ------------------ | ------- | -------------------------------------------------------------------------------------- |
| `data`    | `Iterable<number>` | —       | The array, array-like, string, buffer, or `ArrayBuffer` to create a new `Buffer` from. |

**Throws**

* `Error` — thrown if the encoding is not a recognized `BufferEncoding`.

Buffer.isAscii(buffer: Buffer): boolean [#bufferisasciibuffer-buffer-boolean]

Check whether `buffer` contains only valid ASCII-encoded data.

**Parameters**

| Parameter | Type     | Default | Description          |
| --------- | -------- | ------- | -------------------- |
| `buffer`  | `Buffer` | —       | The buffer to check. |

Buffer.isASCII(buffer: Buffer): boolean [#bufferisasciibuffer-buffer-boolean-1]

Check whether `buffer` contains only valid ASCII-encoded data.

**Parameters**

| Parameter | Type     | Default | Description          |
| --------- | -------- | ------- | -------------------- |
| `buffer`  | `Buffer` | —       | The buffer to check. |

Buffer.isBuffer(value: unknown): value is Buffer [#bufferisbuffervalue-unknown-value-is-buffer]

Check whether `value` is a `Buffer`.

**Parameters**

| Parameter | Type      | Default | Description         |
| --------- | --------- | ------- | ------------------- |
| `value`   | `unknown` | —       | The value to check. |

Buffer.isEncoding(encoding: string): encoding is BufferEncoding [#bufferisencodingencoding-string-encoding-is-bufferencoding]

Check whether `encoding` is a supported `BufferEncoding`.

**Parameters**

| Parameter  | Type     | Default | Description                 |
| ---------- | -------- | ------- | --------------------------- |
| `encoding` | `string` | —       | The encoding name to check. |

Buffer.isUtf8(buffer: Buffer): boolean [#bufferisutf8buffer-buffer-boolean]

Check whether `buffer` contains only valid UTF-8-encoded data.

**Parameters**

| Parameter | Type     | Default | Description          |
| --------- | -------- | ------- | -------------------- |
| `buffer`  | `Buffer` | —       | The buffer to check. |

Buffer.isUTF8(buffer: Buffer): boolean [#bufferisutf8buffer-buffer-boolean-1]

Check whether `buffer` contains only valid UTF-8-encoded data.

**Parameters**

| Parameter | Type     | Default | Description          |
| --------- | -------- | ------- | -------------------- |
| `buffer`  | `Buffer` | —       | The buffer to check. |

Buffer.poolSize: number [#bufferpoolsize-number]

The size, in bytes, of the internal buffer pool used to satisfy small allocations.

Buffer.transcode(buffer: Buffer, from: BufferEncoding, to: BufferEncoding): Buffer [#buffertranscodebuffer-buffer-from-bufferencoding-to-bufferencoding-buffer]

Re-encode `buffer` from one encoding to another, returning a new `Buffer`.

**Parameters**

| Parameter | Type             | Default | Description                            |
| --------- | ---------------- | ------- | -------------------------------------- |
| `buffer`  | `Buffer`         | —       | The buffer to re-encode.               |
| `from`    | `BufferEncoding` | —       | The encoding `buffer` is currently in. |
| `to`      | `BufferEncoding` | —       | The encoding to convert to.            |

**Throws**

* `Error` — thrown if the encoding is not a recognized `BufferEncoding`.

compare [#compare]

```ts
compare(target: Buffer, targetStart?: number, targetEnd?: number, sourceStart?: number, sourceEnd?: number): number
```

Compare two buffers' contents lexicographically, returning -1, 0, or 1 for sort ordering.

**Parameters**

| Parameter      | Type     | Default | Description                                                                                |
| -------------- | -------- | ------- | ------------------------------------------------------------------------------------------ |
| `target`       | `Buffer` | —       | The buffer to compare against.                                                             |
| `targetStart?` | `number` | —       | Offset within `target` to start comparing from; defaults to `0`.                           |
| `targetEnd?`   | `number` | —       | Offset within `target` (exclusive) to stop comparing at; defaults to `target.byteLength`.  |
| `sourceStart?` | `number` | —       | Offset within this buffer to start comparing from; defaults to `0`.                        |
| `sourceEnd?`   | `number` | —       | Offset within this buffer (exclusive) to stop comparing at; defaults to `this.byteLength`. |

copy(target: Buffer, targetStart?: number, sourceStart?: number, sourceEnd?: number): number [#copytarget-buffer-targetstart-number-sourcestart-number-sourceend-number-number]

Copy bytes from this buffer into `target`, returning the number of bytes copied.

**Parameters**

| Parameter      | Type     | Default | Description                                                                              |
| -------------- | -------- | ------- | ---------------------------------------------------------------------------------------- |
| `target`       | `Buffer` | —       | The buffer to copy into.                                                                 |
| `targetStart?` | `number` | —       | Offset within `target` to start writing at; defaults to `0`.                             |
| `sourceStart?` | `number` | —       | Offset within this buffer to start copying from; defaults to `0`.                        |
| `sourceEnd?`   | `number` | —       | Offset within this buffer (exclusive) to stop copying at; defaults to `this.byteLength`. |

equals(target: Buffer): boolean [#equalstarget-buffer-boolean]

Check whether this buffer and `target` have identical contents.

**Parameters**

| Parameter | Type     | Default | Description                                           |
| --------- | -------- | ------- | ----------------------------------------------------- |
| `target`  | `Buffer` | —       | The buffer to compare this buffer's contents against. |

fill(value: string, encoding?: BufferEncoding): this [#fillvalue-string-encoding-bufferencoding-this]

Fill this buffer with `value`, repeating as needed, and return it.

Overloads:

```ts
fill(value: string, encoding?: BufferEncoding): this
fill(value: string, offset?: number, encoding?: BufferEncoding): this
fill(value: string, offset?: number, end?: number, encoding?: BufferEncoding): this
fill(value: Buffer | number | boolean, offset?: number, end?: number): this
```

**Parameters**

| Parameter   | Type             | Default | Description                                                                                       |
| ----------- | ---------------- | ------- | ------------------------------------------------------------------------------------------------- |
| `value`     | `string`         | —       | The value to fill with — a string (repeated across the range), or a `Buffer`/number/boolean byte. |
| `encoding?` | `BufferEncoding` | —       | Encoding used to interpret `value` when it's a string; defaults to `'utf8'`.                      |

**Throws**

* `Error` — thrown if the encoding is not a recognized `BufferEncoding`.

includes(value: string, encoding?: BufferEncoding): boolean [#includesvalue-string-encoding-bufferencoding-boolean]

Check whether this buffer contains `value`.

Overloads:

```ts
includes(value: string, encoding?: BufferEncoding): boolean
includes(value: string, offset?: number, encoding?: BufferEncoding): boolean
includes(value: Buffer | number | boolean, offset?: number): boolean
```

**Parameters**

| Parameter   | Type             | Default | Description                                                                  |
| ----------- | ---------------- | ------- | ---------------------------------------------------------------------------- |
| `value`     | `string`         | —       | The value to search for — a string, `Buffer`, number byte, or boolean.       |
| `encoding?` | `BufferEncoding` | —       | Encoding used to interpret `value` when it's a string; defaults to `'utf8'`. |

**Throws**

* `Error` — thrown if the encoding is not a recognized `BufferEncoding`.

indexOf(value: string, encoding?: BufferEncoding): number [#indexofvalue-string-encoding-bufferencoding-number]

Return the first index at which `value` occurs in this buffer, or `-1` if not found.

Overloads:

```ts
indexOf(value: string, encoding?: BufferEncoding): number
indexOf(value: string, offset?: number, encoding?: BufferEncoding): number
indexOf(value: Buffer | number | boolean, offset?: number): number
```

**Parameters**

| Parameter   | Type             | Default | Description                                                                  |
| ----------- | ---------------- | ------- | ---------------------------------------------------------------------------- |
| `value`     | `string`         | —       | The value to search for — a string, `Buffer`, number byte, or boolean.       |
| `encoding?` | `BufferEncoding` | —       | Encoding used to interpret `value` when it's a string; defaults to `'utf8'`. |

**Throws**

* `Error` — thrown if the encoding is not a recognized `BufferEncoding`.

lastIndexOf(value: string, encoding?: BufferEncoding): number [#lastindexofvalue-string-encoding-bufferencoding-number]

Return the last index at which `value` occurs in this buffer, or `-1` if not found.

Overloads:

```ts
lastIndexOf(value: string, encoding?: BufferEncoding): number
lastIndexOf(value: string, offset?: number, encoding?: BufferEncoding): number
lastIndexOf(value: Buffer | number | boolean, offset?: number): number
```

**Parameters**

| Parameter   | Type             | Default | Description                                                                  |
| ----------- | ---------------- | ------- | ---------------------------------------------------------------------------- |
| `value`     | `string`         | —       | The value to search for — a string, `Buffer`, number byte, or boolean.       |
| `encoding?` | `BufferEncoding` | —       | Encoding used to interpret `value` when it's a string; defaults to `'utf8'`. |

**Throws**

* `Error` — thrown if the encoding is not a recognized `BufferEncoding`.

readBigInt64BE(offset?: number): bigint [#readbigint64beoffset-number-bigint]

Read a signed 64-bit big-endian integer at `offset`.

**Parameters**

| Parameter | Type     | Default | Description                                |
| --------- | -------- | ------- | ------------------------------------------ |
| `offset?` | `number` | —       | Byte offset to read from; defaults to `0`. |

readBigInt64LE(offset?: number): bigint [#readbigint64leoffset-number-bigint]

Read a signed 64-bit little-endian integer at `offset`.

**Parameters**

| Parameter | Type     | Default | Description                                |
| --------- | -------- | ------- | ------------------------------------------ |
| `offset?` | `number` | —       | Byte offset to read from; defaults to `0`. |

readBigUint64BE(offset?: number): bigint [#readbiguint64beoffset-number-bigint]

Read an unsigned 64-bit big-endian integer at `offset`.

**Parameters**

| Parameter | Type     | Default | Description                                |
| --------- | -------- | ------- | ------------------------------------------ |
| `offset?` | `number` | —       | Byte offset to read from; defaults to `0`. |

readBigUInt64BE(offset?: number): bigint [#readbiguint64beoffset-number-bigint-1]

Read an unsigned 64-bit big-endian integer at `offset`.

**Parameters**

| Parameter | Type     | Default | Description                                |
| --------- | -------- | ------- | ------------------------------------------ |
| `offset?` | `number` | —       | Byte offset to read from; defaults to `0`. |

readBigUint64LE(offset?: number): bigint [#readbiguint64leoffset-number-bigint]

Read an unsigned 64-bit little-endian integer at `offset`.

**Parameters**

| Parameter | Type     | Default | Description                                |
| --------- | -------- | ------- | ------------------------------------------ |
| `offset?` | `number` | —       | Byte offset to read from; defaults to `0`. |

readBigUInt64LE(offset?: number): bigint [#readbiguint64leoffset-number-bigint-1]

Read an unsigned 64-bit little-endian integer at `offset`.

**Parameters**

| Parameter | Type     | Default | Description                                |
| --------- | -------- | ------- | ------------------------------------------ |
| `offset?` | `number` | —       | Byte offset to read from; defaults to `0`. |

readDoubleBE(offset?: number): number [#readdoublebeoffset-number-number]

Read a 64-bit big-endian double at `offset`.

**Parameters**

| Parameter | Type     | Default | Description                                |
| --------- | -------- | ------- | ------------------------------------------ |
| `offset?` | `number` | —       | Byte offset to read from; defaults to `0`. |

readDoubleLE(offset?: number): number [#readdoubleleoffset-number-number]

Read a 64-bit little-endian double at `offset`.

**Parameters**

| Parameter | Type     | Default | Description                                |
| --------- | -------- | ------- | ------------------------------------------ |
| `offset?` | `number` | —       | Byte offset to read from; defaults to `0`. |

readFloatBE(offset?: number): number [#readfloatbeoffset-number-number]

Read a 32-bit big-endian float at `offset`.

**Parameters**

| Parameter | Type     | Default | Description                                |
| --------- | -------- | ------- | ------------------------------------------ |
| `offset?` | `number` | —       | Byte offset to read from; defaults to `0`. |

readFloatLE(offset?: number): number [#readfloatleoffset-number-number]

Read a 32-bit little-endian float at `offset`.

**Parameters**

| Parameter | Type     | Default | Description                                |
| --------- | -------- | ------- | ------------------------------------------ |
| `offset?` | `number` | —       | Byte offset to read from; defaults to `0`. |

readInt16BE(offset?: number): number [#readint16beoffset-number-number]

Read a signed 16-bit big-endian integer at `offset`.

**Parameters**

| Parameter | Type     | Default | Description                                |
| --------- | -------- | ------- | ------------------------------------------ |
| `offset?` | `number` | —       | Byte offset to read from; defaults to `0`. |

readInt16LE(offset?: number): number [#readint16leoffset-number-number]

Read a signed 16-bit little-endian integer at `offset`.

**Parameters**

| Parameter | Type     | Default | Description                                |
| --------- | -------- | ------- | ------------------------------------------ |
| `offset?` | `number` | —       | Byte offset to read from; defaults to `0`. |

readInt32BE(offset?: number): number [#readint32beoffset-number-number]

Read a signed 32-bit big-endian integer at `offset`.

**Parameters**

| Parameter | Type     | Default | Description                                |
| --------- | -------- | ------- | ------------------------------------------ |
| `offset?` | `number` | —       | Byte offset to read from; defaults to `0`. |

readInt32LE(offset?: number): number [#readint32leoffset-number-number]

Read a signed 32-bit little-endian integer at `offset`.

**Parameters**

| Parameter | Type     | Default | Description                                |
| --------- | -------- | ------- | ------------------------------------------ |
| `offset?` | `number` | —       | Byte offset to read from; defaults to `0`. |

readInt8(offset?: number): number [#readint8offset-number-number]

Read a signed 8-bit integer at `offset`.

**Parameters**

| Parameter | Type     | Default | Description                                |
| --------- | -------- | ------- | ------------------------------------------ |
| `offset?` | `number` | —       | Byte offset to read from; defaults to `0`. |

readIntBE(offset: number, byteLength: number): number [#readintbeoffset-number-bytelength-number-number]

Read a signed, big-endian, `byteLength`-byte integer at `offset`.

**Parameters**

| Parameter    | Type     | Default | Description                               |
| ------------ | -------- | ------- | ----------------------------------------- |
| `offset`     | `number` | —       | Byte offset to read from.                 |
| `byteLength` | `number` | —       | Number of bytes to read, from `1` to `6`. |

**Throws**

* `RangeError` — thrown if `byteLength` is not between `1` and `6`.

readIntLE(offset: number, byteLength: number): number [#readintleoffset-number-bytelength-number-number]

Read a signed, little-endian, `byteLength`-byte integer at `offset`.

**Parameters**

| Parameter    | Type     | Default | Description                               |
| ------------ | -------- | ------- | ----------------------------------------- |
| `offset`     | `number` | —       | Byte offset to read from.                 |
| `byteLength` | `number` | —       | Number of bytes to read, from `1` to `6`. |

**Throws**

* `RangeError` — thrown if `byteLength` is not between `1` and `6`.

readUint16BE(offset?: number): number [#readuint16beoffset-number-number]

Read an unsigned 16-bit big-endian integer at `offset`.

**Parameters**

| Parameter | Type     | Default | Description                                |
| --------- | -------- | ------- | ------------------------------------------ |
| `offset?` | `number` | —       | Byte offset to read from; defaults to `0`. |

readUInt16BE(offset?: number): number [#readuint16beoffset-number-number-1]

Read an unsigned 16-bit big-endian integer at `offset`.

**Parameters**

| Parameter | Type     | Default | Description                                |
| --------- | -------- | ------- | ------------------------------------------ |
| `offset?` | `number` | —       | Byte offset to read from; defaults to `0`. |

readUint16LE(offset?: number): number [#readuint16leoffset-number-number]

Read an unsigned 16-bit little-endian integer at `offset`.

**Parameters**

| Parameter | Type     | Default | Description                                |
| --------- | -------- | ------- | ------------------------------------------ |
| `offset?` | `number` | —       | Byte offset to read from; defaults to `0`. |

readUInt16LE(offset?: number): number [#readuint16leoffset-number-number-1]

Read an unsigned 16-bit little-endian integer at `offset`.

**Parameters**

| Parameter | Type     | Default | Description                                |
| --------- | -------- | ------- | ------------------------------------------ |
| `offset?` | `number` | —       | Byte offset to read from; defaults to `0`. |

readUint32BE(offset?: number): number [#readuint32beoffset-number-number]

Read an unsigned 32-bit big-endian integer at `offset`.

**Parameters**

| Parameter | Type     | Default | Description                                |
| --------- | -------- | ------- | ------------------------------------------ |
| `offset?` | `number` | —       | Byte offset to read from; defaults to `0`. |

readUInt32BE(offset?: number): number [#readuint32beoffset-number-number-1]

Read an unsigned 32-bit big-endian integer at `offset`.

**Parameters**

| Parameter | Type     | Default | Description                                |
| --------- | -------- | ------- | ------------------------------------------ |
| `offset?` | `number` | —       | Byte offset to read from; defaults to `0`. |

readUint32LE(offset?: number): number [#readuint32leoffset-number-number]

Read an unsigned 32-bit little-endian integer at `offset`.

**Parameters**

| Parameter | Type     | Default | Description                                |
| --------- | -------- | ------- | ------------------------------------------ |
| `offset?` | `number` | —       | Byte offset to read from; defaults to `0`. |

readUInt32LE(offset?: number): number [#readuint32leoffset-number-number-1]

Read an unsigned 32-bit little-endian integer at `offset`.

**Parameters**

| Parameter | Type     | Default | Description                                |
| --------- | -------- | ------- | ------------------------------------------ |
| `offset?` | `number` | —       | Byte offset to read from; defaults to `0`. |

readUint8(offset?: number): number [#readuint8offset-number-number]

Read an unsigned 8-bit integer at `offset`.

**Parameters**

| Parameter | Type     | Default | Description                                |
| --------- | -------- | ------- | ------------------------------------------ |
| `offset?` | `number` | —       | Byte offset to read from; defaults to `0`. |

readUInt8(offset?: number): number [#readuint8offset-number-number-1]

Read an unsigned 8-bit integer at `offset`.

**Parameters**

| Parameter | Type     | Default | Description                                |
| --------- | -------- | ------- | ------------------------------------------ |
| `offset?` | `number` | —       | Byte offset to read from; defaults to `0`. |

readUintBE(offset: number, byteLength: number): number [#readuintbeoffset-number-bytelength-number-number]

Read an unsigned, big-endian, `byteLength`-byte integer at `offset`.

**Parameters**

| Parameter    | Type     | Default | Description                               |
| ------------ | -------- | ------- | ----------------------------------------- |
| `offset`     | `number` | —       | Byte offset to read from.                 |
| `byteLength` | `number` | —       | Number of bytes to read, from `1` to `6`. |

**Throws**

* `RangeError` — thrown if `byteLength` is not between `1` and `6`.

readUIntBE(offset: number, byteLength: number): number [#readuintbeoffset-number-bytelength-number-number-1]

Read an unsigned, big-endian, `byteLength`-byte integer at `offset`.

**Parameters**

| Parameter    | Type     | Default | Description                               |
| ------------ | -------- | ------- | ----------------------------------------- |
| `offset`     | `number` | —       | Byte offset to read from.                 |
| `byteLength` | `number` | —       | Number of bytes to read, from `1` to `6`. |

**Throws**

* `RangeError` — thrown if `byteLength` is not between `1` and `6`.

readUintLE(offset: number, byteLength: number): number [#readuintleoffset-number-bytelength-number-number]

Read an unsigned, little-endian, `byteLength`-byte integer at `offset`.

**Parameters**

| Parameter    | Type     | Default | Description                               |
| ------------ | -------- | ------- | ----------------------------------------- |
| `offset`     | `number` | —       | Byte offset to read from.                 |
| `byteLength` | `number` | —       | Number of bytes to read, from `1` to `6`. |

**Throws**

* `RangeError` — thrown if `byteLength` is not between `1` and `6`.

readUIntLE(offset: number, byteLength: number): number [#readuintleoffset-number-bytelength-number-number-1]

Read an unsigned, little-endian, `byteLength`-byte integer at `offset`.

**Parameters**

| Parameter    | Type     | Default | Description                               |
| ------------ | -------- | ------- | ----------------------------------------- |
| `offset`     | `number` | —       | Byte offset to read from.                 |
| `byteLength` | `number` | —       | Number of bytes to read, from `1` to `6`. |

**Throws**

* `RangeError` — thrown if `byteLength` is not between `1` and `6`.

swap16(): this [#swap16-this]

Swap the byte order of each 16-bit group in this buffer in place, and return it.

**Throws**

* `RangeError` — thrown if the buffer's length is not a multiple of 2 bytes.

swap32(): this [#swap32-this]

Swap the byte order of each 32-bit group in this buffer in place, and return it.

**Throws**

* `RangeError` — thrown if the buffer's length is not a multiple of 4 bytes.

swap64(): this [#swap64-this]

Swap the byte order of each 64-bit group in this buffer in place, and return it.

**Throws**

* `RangeError` — thrown if the buffer's length is not a multiple of 8 bytes.

toJSON(): number[] [#tojson-number]

Return an array of this buffer's bytes, used when the buffer is passed to `JSON.stringify()`.

toString(encoding?: BufferEncoding, start?: number, end?: number): string [#tostringencoding-bufferencoding-start-number-end-number-string]

Decode this buffer (or a slice of it) to a string using `encoding`.

**Parameters**

| Parameter   | Type             | Default | Description                                                                 |
| ----------- | ---------------- | ------- | --------------------------------------------------------------------------- |
| `encoding?` | `BufferEncoding` | —       | Encoding used to decode the bytes; defaults to `'utf8'`.                    |
| `start?`    | `number`         | —       | Byte offset to start decoding from; defaults to `0`.                        |
| `end?`      | `number`         | —       | Byte offset (exclusive) to stop decoding at; defaults to `this.byteLength`. |

**Throws**

* `Error` — thrown if the encoding is not a recognized `BufferEncoding`.

write(string: string, encoding?: BufferEncoding): number [#writestring-string-encoding-bufferencoding-number]

Write `string` into this buffer using `encoding`, returning the number of bytes written.

Overloads:

```ts
write(string: string, encoding?: BufferEncoding): number
write(string: string, offset?: number, encoding?: BufferEncoding): number
write(string: string, offset?: number, length?: number, encoding?: BufferEncoding): number
```

**Parameters**

| Parameter   | Type             | Default | Description                                             |
| ----------- | ---------------- | ------- | ------------------------------------------------------- |
| `string`    | `string`         | —       | The string to write.                                    |
| `encoding?` | `BufferEncoding` | —       | Encoding used to encode `string`; defaults to `'utf8'`. |

**Throws**

* `Error` — thrown if the encoding is not a recognized `BufferEncoding`.

writeBigInt64BE(value: bigint, offset?: number): number [#writebigint64bevalue-bigint-offset-number-number]

Write a signed 64-bit big-endian integer at `offset`.

**Parameters**

| Parameter | Type     | Default | Description                               |
| --------- | -------- | ------- | ----------------------------------------- |
| `value`   | `bigint` | —       | The signed `bigint` to write.             |
| `offset?` | `number` | —       | Byte offset to write to; defaults to `0`. |

**Returns** `number` — `offset + 8`, the offset immediately following the written value.

writeBigInt64LE(value: bigint, offset?: number): number [#writebigint64levalue-bigint-offset-number-number]

Write a signed 64-bit little-endian integer at `offset`.

**Parameters**

| Parameter | Type     | Default | Description                               |
| --------- | -------- | ------- | ----------------------------------------- |
| `value`   | `bigint` | —       | The signed `bigint` to write.             |
| `offset?` | `number` | —       | Byte offset to write to; defaults to `0`. |

**Returns** `number` — `offset + 8`, the offset immediately following the written value.

writeBigUint64BE(value: bigint, offset?: number): number [#writebiguint64bevalue-bigint-offset-number-number]

Write an unsigned 64-bit big-endian integer at `offset`.

**Parameters**

| Parameter | Type     | Default | Description                               |
| --------- | -------- | ------- | ----------------------------------------- |
| `value`   | `bigint` | —       | The unsigned `bigint` to write.           |
| `offset?` | `number` | —       | Byte offset to write to; defaults to `0`. |

**Returns** `number` — `offset + 8`, the offset immediately following the written value.

writeBigUInt64BE(value: bigint, offset?: number): number [#writebiguint64bevalue-bigint-offset-number-number-1]

Write an unsigned 64-bit big-endian integer at `offset`.

**Parameters**

| Parameter | Type     | Default | Description                               |
| --------- | -------- | ------- | ----------------------------------------- |
| `value`   | `bigint` | —       | The unsigned `bigint` to write.           |
| `offset?` | `number` | —       | Byte offset to write to; defaults to `0`. |

**Returns** `number` — `offset + 8`, the offset immediately following the written value.

writeBigUint64LE(value: bigint, offset?: number): number [#writebiguint64levalue-bigint-offset-number-number]

Write an unsigned 64-bit little-endian integer at `offset`.

**Parameters**

| Parameter | Type     | Default | Description                               |
| --------- | -------- | ------- | ----------------------------------------- |
| `value`   | `bigint` | —       | The unsigned `bigint` to write.           |
| `offset?` | `number` | —       | Byte offset to write to; defaults to `0`. |

**Returns** `number` — `offset + 8`, the offset immediately following the written value.

writeBigUInt64LE(value: bigint, offset?: number): number [#writebiguint64levalue-bigint-offset-number-number-1]

Write an unsigned 64-bit little-endian integer at `offset`.

**Parameters**

| Parameter | Type     | Default | Description                               |
| --------- | -------- | ------- | ----------------------------------------- |
| `value`   | `bigint` | —       | The unsigned `bigint` to write.           |
| `offset?` | `number` | —       | Byte offset to write to; defaults to `0`. |

**Returns** `number` — `offset + 8`, the offset immediately following the written value.

writeDoubleBE(value: number, offset?: number): number [#writedoublebevalue-number-offset-number-number]

Write a 64-bit big-endian double at `offset`.

**Parameters**

| Parameter | Type     | Default | Description                               |
| --------- | -------- | ------- | ----------------------------------------- |
| `value`   | `number` | —       | The double-precision number to write.     |
| `offset?` | `number` | —       | Byte offset to write to; defaults to `0`. |

**Returns** `number` — `offset + 8`, the offset immediately following the written value.

writeDoubleLE(value: number, offset?: number): number [#writedoublelevalue-number-offset-number-number]

Write a 64-bit little-endian double at `offset`.

**Parameters**

| Parameter | Type     | Default | Description                               |
| --------- | -------- | ------- | ----------------------------------------- |
| `value`   | `number` | —       | The double-precision number to write.     |
| `offset?` | `number` | —       | Byte offset to write to; defaults to `0`. |

**Returns** `number` — `offset + 8`, the offset immediately following the written value.

writeFloatBE(value: number, offset?: number): number [#writefloatbevalue-number-offset-number-number]

Write a 32-bit big-endian float at `offset`.

**Parameters**

| Parameter | Type     | Default | Description                               |
| --------- | -------- | ------- | ----------------------------------------- |
| `value`   | `number` | —       | The single-precision number to write.     |
| `offset?` | `number` | —       | Byte offset to write to; defaults to `0`. |

**Returns** `number` — `offset + 4`, the offset immediately following the written value.

writeFloatLE(value: number, offset?: number): number [#writefloatlevalue-number-offset-number-number]

Write a 32-bit little-endian float at `offset`.

**Parameters**

| Parameter | Type     | Default | Description                               |
| --------- | -------- | ------- | ----------------------------------------- |
| `value`   | `number` | —       | The single-precision number to write.     |
| `offset?` | `number` | —       | Byte offset to write to; defaults to `0`. |

**Returns** `number` — `offset + 4`, the offset immediately following the written value.

writeInt16BE(value: number, offset?: number): number [#writeint16bevalue-number-offset-number-number]

Write a signed 16-bit big-endian integer at `offset`.

**Parameters**

| Parameter | Type     | Default | Description                               |
| --------- | -------- | ------- | ----------------------------------------- |
| `value`   | `number` | —       | The signed integer to write.              |
| `offset?` | `number` | —       | Byte offset to write to; defaults to `0`. |

**Returns** `number` — `offset + 2`, the offset immediately following the written value.

writeInt16LE(value: number, offset?: number): number [#writeint16levalue-number-offset-number-number]

Write a signed 16-bit little-endian integer at `offset`.

**Parameters**

| Parameter | Type     | Default | Description                               |
| --------- | -------- | ------- | ----------------------------------------- |
| `value`   | `number` | —       | The signed integer to write.              |
| `offset?` | `number` | —       | Byte offset to write to; defaults to `0`. |

**Returns** `number` — `offset + 2`, the offset immediately following the written value.

writeInt32BE(value: number, offset?: number): number [#writeint32bevalue-number-offset-number-number]

Write a signed 32-bit big-endian integer at `offset`.

**Parameters**

| Parameter | Type     | Default | Description                               |
| --------- | -------- | ------- | ----------------------------------------- |
| `value`   | `number` | —       | The signed integer to write.              |
| `offset?` | `number` | —       | Byte offset to write to; defaults to `0`. |

**Returns** `number` — `offset + 4`, the offset immediately following the written value.

writeInt32LE(value: number, offset?: number): number [#writeint32levalue-number-offset-number-number]

Write a signed 32-bit little-endian integer at `offset`.

**Parameters**

| Parameter | Type     | Default | Description                               |
| --------- | -------- | ------- | ----------------------------------------- |
| `value`   | `number` | —       | The signed integer to write.              |
| `offset?` | `number` | —       | Byte offset to write to; defaults to `0`. |

**Returns** `number` — `offset + 4`, the offset immediately following the written value.

writeInt8(value: number, offset?: number): number [#writeint8value-number-offset-number-number]

Write a signed 8-bit integer at `offset`.

**Parameters**

| Parameter | Type     | Default | Description                               |
| --------- | -------- | ------- | ----------------------------------------- |
| `value`   | `number` | —       | The signed integer to write.              |
| `offset?` | `number` | —       | Byte offset to write to; defaults to `0`. |

**Returns** `number` — `offset + 1`, the offset immediately following the written value.

writeIntBE(value: number, offset: number, byteLength: number): number [#writeintbevalue-number-offset-number-bytelength-number-number]

Write a signed, big-endian, `byteLength`-byte integer at `offset`.

**Parameters**

| Parameter    | Type     | Default | Description                                |
| ------------ | -------- | ------- | ------------------------------------------ |
| `value`      | `number` | —       | The signed integer to write.               |
| `offset`     | `number` | —       | Byte offset to write to.                   |
| `byteLength` | `number` | —       | Number of bytes to write, from `1` to `6`. |

**Returns** `number` — `offset + byteLength`, the offset immediately following the written value.

**Throws**

* `RangeError` — thrown if `byteLength` is not between `1` and `6`.

writeIntLE(value: number, offset: number, byteLength: number): number [#writeintlevalue-number-offset-number-bytelength-number-number]

Write a signed, little-endian, `byteLength`-byte integer at `offset`.

**Parameters**

| Parameter    | Type     | Default | Description                                |
| ------------ | -------- | ------- | ------------------------------------------ |
| `value`      | `number` | —       | The signed integer to write.               |
| `offset`     | `number` | —       | Byte offset to write to.                   |
| `byteLength` | `number` | —       | Number of bytes to write, from `1` to `6`. |

**Returns** `number` — `offset + byteLength`, the offset immediately following the written value.

**Throws**

* `RangeError` — thrown if `byteLength` is not between `1` and `6`.

writeUint16BE(value: number, offset?: number): number [#writeuint16bevalue-number-offset-number-number]

Write an unsigned 16-bit big-endian integer at `offset`.

**Parameters**

| Parameter | Type     | Default | Description                               |
| --------- | -------- | ------- | ----------------------------------------- |
| `value`   | `number` | —       | The unsigned integer to write.            |
| `offset?` | `number` | —       | Byte offset to write to; defaults to `0`. |

**Returns** `number` — `offset + 2`, the offset immediately following the written value.

writeUInt16BE(value: number, offset?: number): number [#writeuint16bevalue-number-offset-number-number-1]

Write an unsigned 16-bit big-endian integer at `offset`.

**Parameters**

| Parameter | Type     | Default | Description                               |
| --------- | -------- | ------- | ----------------------------------------- |
| `value`   | `number` | —       | The unsigned integer to write.            |
| `offset?` | `number` | —       | Byte offset to write to; defaults to `0`. |

**Returns** `number` — `offset + 2`, the offset immediately following the written value.

writeUint16LE(value: number, offset?: number): number [#writeuint16levalue-number-offset-number-number]

Write an unsigned 16-bit little-endian integer at `offset`.

**Parameters**

| Parameter | Type     | Default | Description                               |
| --------- | -------- | ------- | ----------------------------------------- |
| `value`   | `number` | —       | The unsigned integer to write.            |
| `offset?` | `number` | —       | Byte offset to write to; defaults to `0`. |

**Returns** `number` — `offset + 2`, the offset immediately following the written value.

writeUInt16LE(value: number, offset?: number): number [#writeuint16levalue-number-offset-number-number-1]

Write an unsigned 16-bit little-endian integer at `offset`.

**Parameters**

| Parameter | Type     | Default | Description                               |
| --------- | -------- | ------- | ----------------------------------------- |
| `value`   | `number` | —       | The unsigned integer to write.            |
| `offset?` | `number` | —       | Byte offset to write to; defaults to `0`. |

**Returns** `number` — `offset + 2`, the offset immediately following the written value.

writeUint32BE(value: number, offset?: number): number [#writeuint32bevalue-number-offset-number-number]

Write an unsigned 32-bit big-endian integer at `offset`.

**Parameters**

| Parameter | Type     | Default | Description                               |
| --------- | -------- | ------- | ----------------------------------------- |
| `value`   | `number` | —       | The unsigned integer to write.            |
| `offset?` | `number` | —       | Byte offset to write to; defaults to `0`. |

**Returns** `number` — `offset + 4`, the offset immediately following the written value.

writeUInt32BE(value: number, offset?: number): number [#writeuint32bevalue-number-offset-number-number-1]

Write an unsigned 32-bit big-endian integer at `offset`.

**Parameters**

| Parameter | Type     | Default | Description                               |
| --------- | -------- | ------- | ----------------------------------------- |
| `value`   | `number` | —       | The unsigned integer to write.            |
| `offset?` | `number` | —       | Byte offset to write to; defaults to `0`. |

**Returns** `number` — `offset + 4`, the offset immediately following the written value.

writeUint32LE(value: number, offset?: number): number [#writeuint32levalue-number-offset-number-number]

Write an unsigned 32-bit little-endian integer at `offset`.

**Parameters**

| Parameter | Type     | Default | Description                               |
| --------- | -------- | ------- | ----------------------------------------- |
| `value`   | `number` | —       | The unsigned integer to write.            |
| `offset?` | `number` | —       | Byte offset to write to; defaults to `0`. |

**Returns** `number` — `offset + 4`, the offset immediately following the written value.

writeUInt32LE(value: number, offset?: number): number [#writeuint32levalue-number-offset-number-number-1]

Write an unsigned 32-bit little-endian integer at `offset`.

**Parameters**

| Parameter | Type     | Default | Description                               |
| --------- | -------- | ------- | ----------------------------------------- |
| `value`   | `number` | —       | The unsigned integer to write.            |
| `offset?` | `number` | —       | Byte offset to write to; defaults to `0`. |

**Returns** `number` — `offset + 4`, the offset immediately following the written value.

writeUint8(value: number, offset?: number): number [#writeuint8value-number-offset-number-number]

Write an unsigned 8-bit integer at `offset`.

**Parameters**

| Parameter | Type     | Default | Description                               |
| --------- | -------- | ------- | ----------------------------------------- |
| `value`   | `number` | —       | The unsigned integer to write.            |
| `offset?` | `number` | —       | Byte offset to write to; defaults to `0`. |

**Returns** `number` — `offset + 1`, the offset immediately following the written value.

writeUInt8(value: number, offset?: number): number [#writeuint8value-number-offset-number-number-1]

Write an unsigned 8-bit integer at `offset`.

**Parameters**

| Parameter | Type     | Default | Description                               |
| --------- | -------- | ------- | ----------------------------------------- |
| `value`   | `number` | —       | The unsigned integer to write.            |
| `offset?` | `number` | —       | Byte offset to write to; defaults to `0`. |

**Returns** `number` — `offset + 1`, the offset immediately following the written value.

writeUintBE(value: number, offset: number, byteLength: number): number [#writeuintbevalue-number-offset-number-bytelength-number-number]

Write an unsigned, big-endian, `byteLength`-byte integer at `offset`.

**Parameters**

| Parameter    | Type     | Default | Description                                |
| ------------ | -------- | ------- | ------------------------------------------ |
| `value`      | `number` | —       | The unsigned integer to write.             |
| `offset`     | `number` | —       | Byte offset to write to.                   |
| `byteLength` | `number` | —       | Number of bytes to write, from `1` to `6`. |

**Returns** `number` — `offset + byteLength`, the offset immediately following the written value.

**Throws**

* `RangeError` — thrown if `byteLength` is not between `1` and `6`.

writeUIntBE(value: number, offset: number, byteLength: number): number [#writeuintbevalue-number-offset-number-bytelength-number-number-1]

Write an unsigned, big-endian, `byteLength`-byte integer at `offset`.

**Parameters**

| Parameter    | Type     | Default | Description                                |
| ------------ | -------- | ------- | ------------------------------------------ |
| `value`      | `number` | —       | The unsigned integer to write.             |
| `offset`     | `number` | —       | Byte offset to write to.                   |
| `byteLength` | `number` | —       | Number of bytes to write, from `1` to `6`. |

**Returns** `number` — `offset + byteLength`, the offset immediately following the written value.

**Throws**

* `RangeError` — thrown if `byteLength` is not between `1` and `6`.

writeUintLE(value: number, offset: number, byteLength: number): number [#writeuintlevalue-number-offset-number-bytelength-number-number]

Write an unsigned, little-endian, `byteLength`-byte integer at `offset`.

**Parameters**

| Parameter    | Type     | Default | Description                                |
| ------------ | -------- | ------- | ------------------------------------------ |
| `value`      | `number` | —       | The unsigned integer to write.             |
| `offset`     | `number` | —       | Byte offset to write to.                   |
| `byteLength` | `number` | —       | Number of bytes to write, from `1` to `6`. |

**Returns** `number` — `offset + byteLength`, the offset immediately following the written value.

**Throws**

* `RangeError` — thrown if `byteLength` is not between `1` and `6`.

writeUIntLE(value: number, offset: number, byteLength: number): number [#writeuintlevalue-number-offset-number-bytelength-number-number-1]

Write an unsigned, little-endian, `byteLength`-byte integer at `offset`.

**Parameters**

| Parameter    | Type     | Default | Description                                |
| ------------ | -------- | ------- | ------------------------------------------ |
| `value`      | `number` | —       | The unsigned integer to write.             |
| `offset`     | `number` | —       | Byte offset to write to.                   |
| `byteLength` | `number` | —       | Number of bytes to write, from `1` to `6`. |

**Returns** `number` — `offset + byteLength`, the offset immediately following the written value.

**Throws**

* `RangeError` — thrown if `byteLength` is not between `1` and `6`.

bare-buffer/global [#bare-bufferglobal]

Types [#types]

BufferConstructor [#bufferconstructor]

```ts
type BufferConstructor = typeof buffer.Buffer
```

bare-buffer/constants [#bare-bufferconstants]

Constants and variables [#constants-and-variables]

constants: { MAX_LENGTH: number; MAX_STRING_LENGTH: number } [#constants--max_length-number-max_string_length-number-]

Limits for buffers and strings: `MAX_LENGTH` (largest possible `Buffer`) and `MAX_STRING_LENGTH` (largest possible string).

See also [#see-also]

* [Bare modules](/reference/modules/bare-modules) — the full `bare-*` catalog.
* [Bare runtime API](/reference/bare/runtime) — the runtime these modules extend.


# bare-bundle-id



<mark style={{ backgroundColor: '#7dde9a', padding: '2px 8px', borderRadius: '4px', fontSize: '0.85em', fontWeight: 500 }}>
  stable
</mark>

[`bare-bundle-id`](https://github.com/holepunchto/bare-bundle-id) — Construct a unique ID for a bundle.

```sh
npm i bare-bundle-id
```

Usage [#usage]

```js
const Bundle = require('bare-bundle')
const id = require('bare-bundle-id')

const bundle = new Bundle()
  .write('/foo.js', "module.exports = require('./bar')", {
    main: true,
    imports: {
      './bar': '/bar.js'
    }
  })
  .write('/bar.js', 'module.exports = 42')

bundle.id = id(bundle).toString('hex')
// 33824862...
```

API [#api]

Functions [#functions]

id(bundle: Bundle): Buffer [#idbundle-bundle-buffer]

Returns a 32-byte BLAKE2b hash of `bundle`'s sorted file entries (path, contents, and mode), uniquely identifying the bundle's contents.

**Parameters**

| Parameter | Type     | Default | Description                                                                                                                                                                                             |
| --------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `bundle`  | `Bundle` | —       | The [`bare-bundle`](https://github.com/holepunchto/bare-bundle) instance to hash; its file entries are sorted by path before hashing, so the ID is stable regardless of the order they were written in. |

See also [#see-also]

* [Bare modules](/reference/modules/bare-modules) — the full `bare-*` catalog.
* [Bare runtime API](/reference/bare/runtime) — the runtime these modules extend.


# bare-bundle



<mark style={{ backgroundColor: '#7dde9a', padding: '2px 8px', borderRadius: '4px', fontSize: '0.85em', fontWeight: 500 }}>
  stable
</mark>

[`bare-bundle`](https://github.com/holepunchto/bare-bundle) — Application bundle format for JavaScript.

```sh
npm i bare-bundle
```

API [#api]

Bundle [#bundle]

new Bundle(opts?: BundleOptions) [#new-bundleopts-bundleoptions]

Create an empty `Bundle`, optionally supplying a custom `File` class to back stored files.

**Parameters**

| Parameter | Type                              | Default | Description                               |
| --------- | --------------------------------- | ------- | ----------------------------------------- |
| `opts?`   | [`BundleOptions`](#bundleoptions) | —       | Options; `File` defaults to `MemoryFile`. |

addons: string[] [#addons-string]

The keys of files in the bundle that are native addons.

assets: string[] [#assets-string]

The keys of files in the bundle that are non-JavaScript assets.

Bundle.from(value: string | Buffer | Bundle): Bundle [#bundlefromvalue-string--buffer--bundle-bundle]

Coerce `value` — a serialized bundle string, a `Buffer`, or an existing `Bundle` — into a `Bundle`.

**Parameters**

| Parameter | Type                             | Default | Description                                                               |
| --------- | -------------------------------- | ------- | ------------------------------------------------------------------------- |
| `value`   | `string` \| `Buffer` \| `Bundle` | —       | The serialized bundle string or buffer to parse, or an existing `Bundle`. |

**Returns** `Bundle` — The parsed `Bundle`, or `value` itself if it is already a `Bundle`.

**Throws**

* `INVALID_BUNDLE_HEADER` — the serialized header is not valid JSON.

Bundle.isBundle(value: unknown): value is Bundle [#bundleisbundlevalue-unknown-value-is-bundle]

Check whether `value` is a `Bundle`.

**Parameters**

| Parameter | Type      | Default | Description         |
| --------- | --------- | ------- | ------------------- |
| `value`   | `unknown` | —       | The value to check. |

**Returns** `value is Bundle` — `true` if `value` is a `Bundle` instance or exposes the bundle kind symbol, `false` otherwise.

Bundle.version: number [#bundleversion-number]

The bundle format version this implementation produces and expects.

empty(): boolean [#empty-boolean]

Check whether the bundle contains no files.

**Returns** `boolean` — `true` if the bundle contains no files, `false` otherwise.

exists(key: string): boolean [#existskey-string-boolean]

Check whether a file exists at `key`.

**Parameters**

| Parameter | Type     | Default | Description                     |
| --------- | -------- | ------- | ------------------------------- |
| `key`     | `string` | —       | The key of the file to look up. |

**Returns** `boolean` — `true` if a file exists at `key`, `false` otherwise.

files: Record<string, MemoryFile> [#files-recordstring-memoryfile]

The bundle's files, keyed by path, as `MemoryFile` instances.

id: string | null [#id-string--null]

An optional identifier for the bundle, or `null` if unset.

imports: RecursiveStringObject [#imports-recursivestringobject]

The bundle's import map, mapping specifiers to file keys.

keys(): string[] [#keys-string]

Return the keys of all files in the bundle.

main: string | null [#main-string--null]

The key of the bundle's entry file, or `null` if unset.

mode(key: string): number [#modekey-string-number]

Return the file mode (permission bits) of the file at `key`, or `0` if it doesn't exist.

**Parameters**

| Parameter | Type     | Default | Description                     |
| --------- | -------- | ------- | ------------------------------- |
| `key`     | `string` | —       | The key of the file to look up. |

mount(root: string | URL, opts?: BundleMountOptions): Bundle [#mountroot-string--url-opts-bundlemountoptions-bundle]

Return a copy of the bundle with all file keys and import/resolution specifiers rewritten as absolute URLs resolved against `root`.

**Parameters**

| Parameter | Type                                        | Default | Description                                                                   |
| --------- | ------------------------------------------- | ------- | ----------------------------------------------------------------------------- |
| `root`    | `string` \| `URL`                           | —       | The base URL (or URL string) to resolve keys and specifiers against.          |
| `opts?`   | [`BundleMountOptions`](#bundlemountoptions) | —       | Options; `conditions` maps import-map condition names to per-condition roots. |

**Returns** `Bundle` — A new `Bundle` with rewritten keys; the original bundle is left unchanged.

read(key: string): Buffer [#readkey-string-buffer]

Return the contents of the file at `key` as a `Buffer`, or `null` if it doesn't exist.

**Parameters**

| Parameter | Type     | Default | Description                  |
| --------- | -------- | ------- | ---------------------------- |
| `key`     | `string` | —       | The key of the file to read. |

resolutions: RecursiveStringObject [#resolutions-recursivestringobject]

The bundle's per-file import resolutions map, used to override the default import map for specific files.

toBuffer(opts?: BundleToBufferOptions): Buffer [#tobufferopts-bundletobufferoptions-buffer]

Serialize the bundle to a single `Buffer` containing its header and file contents.

**Parameters**

| Parameter | Type                                              | Default | Description                                                |
| --------- | ------------------------------------------------- | ------- | ---------------------------------------------------------- |
| `opts?`   | [`BundleToBufferOptions`](#bundletobufferoptions) | —       | Options; `indent` defaults to `0` and `shared` to `false`. |

unmount(root: string | URL, opts?: BundleMountOptions): Bundle [#unmountroot-string--url-opts-bundlemountoptions-bundle]

Return a copy of the bundle with all file keys and import/resolution specifiers rewritten as paths relative to `root`, reversing `mount()`.

**Parameters**

| Parameter | Type                                        | Default | Description                                                                   |
| --------- | ------------------------------------------- | ------- | ----------------------------------------------------------------------------- |
| `root`    | `string` \| `URL`                           | —       | The base URL (or URL string) to make keys and specifiers relative to.         |
| `opts?`   | [`BundleMountOptions`](#bundlemountoptions) | —       | Options; `conditions` maps import-map condition names to per-condition roots. |

**Returns** `Bundle` — A new `Bundle` with rewritten keys; the original bundle is left unchanged.

version: number [#version-number]

The bundle format version this implementation produces and expects.

write(key: string, data: string, opts?: BundleWriteOptions): this [#writekey-string-data-string-opts-bundlewriteoptions-this]

Add or replace the file at `key` with `data`, optionally marking it as the main entry, an addon, an asset, or aliased in the import map.

**Parameters**

| Parameter | Type                                        | Default | Description                                                                                                 |
| --------- | ------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------- |
| `key`     | `string`                                    | —       | The key (path) to store the file under.                                                                     |
| `data`    | `string`                                    | —       | The file contents.                                                                                          |
| `opts?`   | [`BundleWriteOptions`](#bundlewriteoptions) | —       | Options; `main`, `addon`, `asset`, and `executable` default to `false`, and `alias` and `imports` to unset. |

**Returns** `this` — The bundle itself, for chaining writes.

**Throws**

* `TypeError` — `key` is not a string.

MemoryFile [#memoryfile]

new MemoryFile(data: string | Buffer, opts?: MemoryFileOptions) [#new-memoryfiledata-string--buffer-opts-memoryfileoptions]

Create a `MemoryFile` from `data`, optionally marking it executable or setting an explicit `mode`.

**Parameters**

| Parameter | Type                                      | Default | Description                                                                         |
| --------- | ----------------------------------------- | ------- | ----------------------------------------------------------------------------------- |
| `data`    | `string` \| `Buffer`                      | —       | The file contents; a string is converted to a `Buffer`.                             |
| `opts?`   | [`MemoryFileOptions`](#memoryfileoptions) | —       | Options; `mode` defaults to `0o755` when `executable` is `true`, otherwise `0o644`. |

mode(): number [#mode-number]

Return the file's mode (permission bits).

read(): Buffer [#read-buffer]

Return the file's contents as a `Buffer`.

size(): number [#size-number]

Return the file's byte length.

Types [#types]

MemoryFileOptions [#memoryfileoptions]

```ts
interface MemoryFileOptions {
  executable?: boolean
  mode?: number
}
```

BundleOptions [#bundleoptions]

```ts
interface BundleOptions {
  File?: typeof MemoryFile
}
```

BundleWriteOptions [#bundlewriteoptions]

```ts
interface BundleWriteOptions {
  addon?: boolean
  alias?: string
  asset?: boolean
  executable?: boolean
  imports?: RecursiveStringObject
  main?: boolean
  mode?: number
}
```

BundleMountOptions [#bundlemountoptions]

```ts
interface BundleMountOptions {
  conditions?: { [condition: string]: string | URL }
}
```

BundleToBufferOptions [#bundletobufferoptions]

```ts
interface BundleToBufferOptions {
  indent?: number
  shared?: boolean
}
```

Format [#format]

```
[#!hashbang]
<header length><header><...files>
```

The header length is an integer literal denoting the total length of the header. The header itself is a JSON string literal of header length bytes and has the following format:

```js
{
  "version": 0,
  "id": null | "<string>",
  "main": null | "<url>",
  "imports": {
    "<from>": "<to>"
  },
  "resolutions": {
    "<url>": "<imports>"
  },
  "addons": ["<url>"],
  "assets": ["<url>"],
  "files": {
    "<url>": {
      "offset": number,
      "length": number,
      "mode": number
    }
  }
}
```

For each `<url>` in `files`, `offset` provides the byte offset to the file **after** the header and `length` provides the byte length of the file.

The bundle may optionally be prefixed with a hashbang, `#!`, for use with script interpreters. The hashbang is ignored during parsing.

See also [#see-also]

* [Bare modules](/reference/modules/bare-modules) — the full `bare-*` catalog.
* [Bare runtime API](/reference/bare/runtime) — the runtime these modules extend.


# bare-channel



<mark style={{ backgroundColor: '#7dde9a', padding: '2px 8px', borderRadius: '4px', fontSize: '0.85em', fontWeight: 500 }}>
  stable
</mark>

[`bare-channel`](https://github.com/holepunchto/bare-channel) provides point-to-point messaging between [Bare threads](/reference/bare/runtime#barethread). A channel exposes a transferable `handle`; pass it to another thread, reconstruct with `Channel.from(handle)`, and exchange structured-cloned values over a port. It's a native addon and requires Bare `>=1.7.0`. For one-to-many fan-out, see [`bare-broadcast-channel`](/reference/bare/modules/bare-broadcast-channel).

```sh
npm i bare-channel
```

Usage [#usage]

```js
const Channel = require('bare-channel')
const { Thread } = Bare

const channel = new Channel()

new Thread(__filename, { data: channel.handle }, async (handle) => {
  const Channel = require('bare-channel')
  const port = Channel.from(handle).connect()
  console.log(await port.read())
  await port.close()
})

const port = channel.connect()
await port.write('hello')
```

API [#api]

Channel [#channel]

const channel = new Channel([options]) · Channel.from(handle[, options]) [#const-channel--new-channeloptions--channelfromhandle-options]

Create a channel, or reconstruct one from a transferred `channel.handle`. `channel.interfaces` lists its interfaces; `channel.connect()` returns a `Port`.

`options` include:

```js
options = {
  handle,
  interfaces: []
}
```

`handle` is an existing `SharedArrayBuffer` returned by `channel.handle` on another thread. When provided, the new channel is wired up to the same underlying channel. If omitted, a fresh channel is created.

`interfaces` is an array of constructors with `bare-structured-clone` serialize and/or transfer symbols. Instances of these types may be passed to `port.write()` and will be reconstructed on the receiving side.

channel.handle [#channelhandle]

The underlying `SharedArrayBuffer` for the channel. Pass this across thread boundaries (for example, via `Bare.Thread`'s `data` option) and reconstruct the channel on the other side with `Channel.from(handle)`.

channel.interfaces [#channelinterfaces]

The array of constructors passed to the constructor.

const port = channel.connect() [#const-port--channelconnect]

Connect a new `Port` to the channel. A channel supports exactly two connected ports; messages written on one port appear in the read queue of the other.

Port [#port]

await port.write(value[, options]) · port.writeSync(value[, options]) [#await-portwritevalue-options--portwritesyncvalue-options]

Send a structured-cloneable value; returns whether the write flushed.

const data = await port.read() · port.readSync() [#const-data--await-portread--portreadsync]

Read the next value. A port is also iterable (`for await (const data of port)`).

port.createReadStream([options]) · port.createWriteStream([options]) · port.createStream([options]) [#portcreatereadstreamoptions--portcreatewritestreamoptions--portcreatestreamoptions]

Stream interfaces over the port.

port.ref() · port.unref() · await port.close() [#portref--portunref--await-portclose]

Event-loop references and teardown. Ports emit `end` and `close`.

Related modules [#related-modules]

Builds on `bare-events`, [`bare-stream`](/reference/bare/modules/bare-stream), and `bare-structured-clone` (see [Bare modules](/reference/modules/bare-modules)).

See also [#see-also]

* [`bare-broadcast-channel`](/reference/bare/modules/bare-broadcast-channel)—multi-producer, multi-consumer messaging.
* [`bare-atomics`](/reference/bare/modules/bare-atomics)—low-level thread synchronization.
* [Bare runtime API](/reference/bare/runtime#barethread)—`Bare.Thread`.


# bare-collabora



<mark style={{ backgroundColor: '#7dde9a', padding: '2px 8px', borderRadius: '4px', fontSize: '0.85em', fontWeight: 500 }}>
  stable
</mark>

[`bare-collabora`](https://github.com/holepunchto/bare-collabora) — Collabora bindings for Bare. It is a native addon.

```sh
npm i bare-collabora
```

Usage [#usage]

```js
const { Document } = require('bare-collabora')

const document = new Document('/path/to/sample.md')

document.saveAs('/path/to/sample.pdf')
```

API [#api]

Document [#document]

new Document(url: string) [#new-documenturl-string]

Loads the document at `url`, a local file path or `file:` URL pointing to a document in any format supported by Collabora.

**Parameters**

| Parameter | Type     | Default | Description                                                                                   |
| --------- | -------- | ------- | --------------------------------------------------------------------------------------------- |
| `url`     | `string` | —       | A local file path or `file:` URL pointing to a document in any format supported by Collabora. |

**Throws**

* The document at `url` cannot be opened.

saveAs(url: string, format?: string, options?: string): boolean [#saveasurl-string-format-string-options-string-boolean]

Saves the document to `url` in the given `format`. If `format` is omitted, it is inferred from the extension of `url`. `options` is a comma-separated string of filter options forwarded to Collabora; see the Collabora documentation for the filters available for a given format.

**Parameters**

| Parameter  | Type     | Default | Description                                                                                                                                      |
| ---------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `url`      | `string` | —       | The destination path or `file:` URL to write to.                                                                                                 |
| `format?`  | `string` | —       | The output format; when omitted, it is inferred from the extension of `url`.                                                                     |
| `options?` | `string` | —       | A comma-separated string of filter options forwarded to Collabora. See the Collabora documentation for the filters available for a given format. |

**Throws**

* The document cannot be saved.

See also [#see-also]

* Builds on `bare-env`, `bare-path`, and `bare-url`.
* [Bare modules](/reference/modules/bare-modules) — the full `bare-*` catalog.
* [Bare runtime API](/reference/bare/runtime) — the runtime these modules extend.


# bare-console



<mark style={{ backgroundColor: '#7dde9a', padding: '2px 8px', borderRadius: '4px', fontSize: '0.85em', fontWeight: 500 }}>
  stable
</mark>

[`bare-console`](https://github.com/holepunchto/bare-console) — WHATWG debugging console for JavaScript.

Mirrors the Node.js [`console`](https://nodejs.org/api/console.html) module.

```sh
npm i bare-console
```

Usage [#usage]

```js
const Console = require('bare-console')

const console = new Console()

console.log('Hello')
console.error(new Error('Something happened'))

console.time()
for (let i = 0; i < 1000000000; i++) {}
console.timeEnd()

console.trace('Show me')
```

To install `console` as a global, require the `bare-console/global` subpath:

```js
require('bare-console/global')

console.log('Hello')
```

API [#api]

Console [#console]

new Console(log?: Log) [#new-consolelog-log]

Construct a new `Console`. By default, output is written through `bare-logger` (\<[https://github.com/holepunchto/bare-logger>](https://github.com/holepunchto/bare-logger>)), or `bare-system-logger` (\<[https://github.com/holepunchto/bare-system-logger>](https://github.com/holepunchto/bare-system-logger>)) on Android.

**Parameters**

| Parameter | Type  | Default | Description                                                                                                                                                                                                                                                                     |
| --------- | ----- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `log?`    | `Log` | —       | The logging backend to write through. Defaults to a `bare-logger` instance, or `bare-system-logger` on Android. The object must implement the methods used by console operations: `{ debug(...data), info(...data), warn(...data), error(...data), clear(), format(...data) }`. |

assert(condition: unknown, ...data: unknown[]): void [#assertcondition-unknown-data-unknown-void]

If `condition` is falsy, log `data` prefixed with `'Assertion failed'`. Otherwise do nothing.

**Parameters**

| Parameter   | Type        | Default | Description                                                                    |
| ----------- | ----------- | ------- | ------------------------------------------------------------------------------ |
| `condition` | `unknown`   | —       | The value tested for truthiness; when falsy, `data` is logged.                 |
| `data`      | `unknown[]` | —       | Values logged after the `'Assertion failed'` prefix when `condition` is falsy. |

clear(): void [#clear-void]

Forward to `log.clear()`.

Console: ConsoleConstructor [#console-consoleconstructor]

Construct a new `Console`. By default, output is written through `bare-logger` (\<[https://github.com/holepunchto/bare-logger>](https://github.com/holepunchto/bare-logger>)), or `bare-system-logger` (\<[https://github.com/holepunchto/bare-system-logger>](https://github.com/holepunchto/bare-system-logger>)) on Android.

count(label?: string): void [#countlabel-string-void]

Increment and log the counter identified by `label` (default `'default'`).

**Parameters**

| Parameter | Type     | Default | Description                                                       |
| --------- | -------- | ------- | ----------------------------------------------------------------- |
| `label?`  | `string` | —       | The label identifying the timer or counter (default `'default'`). |

countReset(label?: string): void [#countresetlabel-string-void]

Remove the counter identified by `label` (default `'default'`).

**Parameters**

| Parameter | Type     | Default | Description                                                       |
| --------- | -------- | ------- | ----------------------------------------------------------------- |
| `label?`  | `string` | —       | The label identifying the timer or counter (default `'default'`). |

debug(...data: unknown[]): void [#debugdata-unknown-void]

Forward `data` to the corresponding method on the backend.

**Parameters**

| Parameter | Type        | Default | Description    |
| --------- | ----------- | ------- | -------------- |
| `data`    | `unknown[]` | —       | Values to log. |

error(...data: unknown[]): void [#errordata-unknown-void]

Forward `data` to the corresponding method on the backend.

**Parameters**

| Parameter | Type        | Default | Description    |
| --------- | ----------- | ------- | -------------- |
| `data`    | `unknown[]` | —       | Values to log. |

info(...data: unknown[]): void [#infodata-unknown-void]

Forward `data` to the corresponding method on the backend.

**Parameters**

| Parameter | Type        | Default | Description    |
| --------- | ----------- | ------- | -------------- |
| `data`    | `unknown[]` | —       | Values to log. |

log(...data: unknown[]): void [#logdata-unknown-void]

Alias for `info`; forward `data` to the corresponding method on the backend.

**Parameters**

| Parameter | Type        | Default | Description    |
| --------- | ----------- | ------- | -------------- |
| `data`    | `unknown[]` | —       | Values to log. |

table(tabularData: unknown, properties?: readonly string[]): void [#tabletabulardata-unknown-properties-readonly-string-void]

Render `tabularData` as a table. Arrays and plain objects use an `(index)` column; `Map` and `Set` use an `(iteration index)` column with `key` and `values` (or `values` only) headers. Pass `properties` to restrict which object keys are shown as columns; the argument is ignored for `Map` and `Set`. Values that aren't tabular (primitives, `null`, functions) fall back to `console.log(tabularData)`.

**Parameters**

| Parameter     | Type                | Default | Description                                                     |
| ------------- | ------------------- | ------- | --------------------------------------------------------------- |
| `tabularData` | `unknown`           | —       | The data to render as a table.                                  |
| `properties?` | `readonly string[]` | —       | Object keys to include as columns; ignored for `Map` and `Set`. |

time(label?: string): void [#timelabel-string-void]

Start a timer identified by `label` (default `'default'`). Warns if a timer with the same label is already running.

**Parameters**

| Parameter | Type     | Default | Description                                                       |
| --------- | -------- | ------- | ----------------------------------------------------------------- |
| `label?`  | `string` | —       | The label identifying the timer or counter (default `'default'`). |

timeEnd(label?: string): void [#timeendlabel-string-void]

Log the elapsed time and remove the timer identified by `label` (default `'default'`).

**Parameters**

| Parameter | Type     | Default | Description                                                       |
| --------- | -------- | ------- | ----------------------------------------------------------------- |
| `label?`  | `string` | —       | The label identifying the timer or counter (default `'default'`). |

timeLog(label?: string, ...data: unknown[]): void [#timeloglabel-string-data-unknown-void]

Log the elapsed time for the timer identified by `label` (default `'default'`), along with any additional `data`. Output uses milliseconds for short durations and seconds beyond one second.

**Parameters**

| Parameter | Type        | Default | Description                                            |
| --------- | ----------- | ------- | ------------------------------------------------------ |
| `label?`  | `string`    | —       | The label identifying the timer (default `'default'`). |
| `data`    | `unknown[]` | —       | Additional values logged after the elapsed time.       |

trace(...data: unknown[]): void [#tracedata-unknown-void]

Log a stack trace prefixed with the formatted `data`.

**Parameters**

| Parameter | Type        | Default | Description                                         |
| --------- | ----------- | ------- | --------------------------------------------------- |
| `data`    | `unknown[]` | —       | Values formatted and prefixed onto the stack trace. |

warn(...data: unknown[]): void [#warndata-unknown-void]

Forward `data` to the corresponding method on the backend.

**Parameters**

| Parameter | Type        | Default | Description    |
| --------- | ----------- | ------- | -------------- |
| `data`    | `unknown[]` | —       | Values to log. |

See also [#see-also]

* Builds on `bare-format`, `bare-hrtime`, `bare-logger`, `bare-system-logger`, and `bare-type`.
* It's pure JavaScript.
* [`bare-inspector`](/reference/bare/modules/bare-inspector) — deeper debugging via the V8 inspector.
* [Bare modules](/reference/modules/bare-modules) — the full `bare-*` catalog.
* [Bare runtime API](/reference/bare/runtime) — the runtime these modules extend.


# bare-crypto



<mark style={{ backgroundColor: '#7dde9a', padding: '2px 8px', borderRadius: '4px', fontSize: '0.85em', fontWeight: 500 }}>
  stable
</mark>

[`bare-crypto`](https://github.com/holepunchto/bare-crypto) — Cryptographic primitives for JavaScript. It is a native addon.

Mirrors the Node.js [`crypto`](https://nodejs.org/api/crypto.html) module.

```sh
npm i bare-crypto
```

Usage [#usage]

```js
const crypto = require('bare-crypto')

const hash = crypto.createHash('sha256')

hash.update('Hello, world!')

const digest = hash.digest('hex')

console.log(digest)
```

API [#api]

Hash [#hash]

new Hash(algorithm: HashAlgorithm | number, opts?: TransformOptions<CryptoHash>) [#new-hashalgorithm-hashalgorithm--number-opts-transformoptionscryptohash]

**Parameters**

| Parameter   | Type                           | Default | Description                                                                                                        |
| ----------- | ------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------ |
| `algorithm` | `HashAlgorithm` \| `number`    | —       | The hash algorithm, as a string (for example `'sha256'`, `'sha-256'`) or a numeric constant from `constants.hash`. |
| `opts?`     | `TransformOptions<CryptoHash>` | —       | Options forwarded to the `Transform` constructor from `bare-stream`.                                               |

**Throws**

* `UNKNOWN_HASH` — `algorithm` is a string that does not name a supported hash algorithm.

Hash.digest(encoding: BufferEncoding): string [#hashdigestencoding-bufferencoding-string]

Finalize the hash and return the digest. If `encoding` is provided (and is not `'buffer'`), the digest is returned as a string in that encoding; otherwise as a `Buffer`. Further calls to `update()` or `digest()` throw.

Overloads:

```ts
digest(encoding: BufferEncoding): string
digest(): Buffer
```

**Parameters**

| Parameter  | Type             | Default | Description                                                                        |
| ---------- | ---------------- | ------- | ---------------------------------------------------------------------------------- |
| `encoding` | `BufferEncoding` | —       | The encoding for the returned digest; omit (or pass `'buffer'`) to get a `Buffer`. |

Hash.HashAlgorithm [#hashhashalgorithm]

```ts
type HashAlgorithm = | 'md5'
  | 'sha-1'
  | 'sha-256'
  | 'sha-384'
  | 'sha-512'
  | 'blake2b-256'
  | 'ripemd-160'
```

Hash.update(data: string, encoding?: BufferEncoding): this [#hashupdatedata-string-encoding-bufferencoding-this]

Push `data` into the hash. If `data` is a string, it is decoded using `encoding` (defaults to `'utf8'`). Returns the same `hash` for chaining. Throws once `digest()` has been called.

Overloads:

```ts
update(data: string, encoding?: BufferEncoding): this
update(data: Buffer, encoding?: 'buffer'): this
```

**Parameters**

| Parameter   | Type             | Default | Description                                                        |
| ----------- | ---------------- | ------- | ------------------------------------------------------------------ |
| `data`      | `string`         | —       | The data to push into the hash.                                    |
| `encoding?` | `BufferEncoding` | —       | The encoding of `data` when it is a string (defaults to `'utf8'`). |

Hmac [#hmac]

Hmac [#hmac-1]

```ts
new Hmac(algorithm: HashAlgorithm | number, key: string | Buffer, opts?: TransformOptions<CryptoHmac>)
```

**Parameters**

| Parameter   | Type                           | Default | Description                                                                                                        |
| ----------- | ------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------ |
| `algorithm` | `HashAlgorithm` \| `number`    | —       | The hash algorithm, as a string (for example `'sha256'`, `'sha-256'`) or a numeric constant from `constants.hash`. |
| `key`       | `string` \| `Buffer`           | —       | The HMAC key; a string is decoded using the `encoding` option (defaults to `'utf8'`).                              |
| `opts?`     | `TransformOptions<CryptoHmac>` | —       | Options forwarded to the `Transform` constructor from `bare-stream`.                                               |

**Throws**

* `UNKNOWN_HASH` — `algorithm` is a string that does not name a supported hash algorithm.

Hmac.digest(encoding: BufferEncoding): string [#hmacdigestencoding-bufferencoding-string]

Finalize the HMAC. Same semantics as `hash.digest()`.

Overloads:

```ts
digest(encoding: BufferEncoding): string
digest(): Buffer
```

**Parameters**

| Parameter  | Type             | Default | Description                                                                        |
| ---------- | ---------------- | ------- | ---------------------------------------------------------------------------------- |
| `encoding` | `BufferEncoding` | —       | The encoding for the returned digest; omit (or pass `'buffer'`) to get a `Buffer`. |

Hmac.update(data: string, encoding?: BufferEncoding): this [#hmacupdatedata-string-encoding-bufferencoding-this]

Push `data` into the HMAC. Same semantics as `hash.update()`.

Overloads:

```ts
update(data: string, encoding?: BufferEncoding): this
update(data: Buffer, encoding?: 'buffer'): this
```

**Parameters**

| Parameter   | Type             | Default | Description                                                        |
| ----------- | ---------------- | ------- | ------------------------------------------------------------------ |
| `data`      | `string`         | —       | The data to push into the HMAC.                                    |
| `encoding?` | `BufferEncoding` | —       | The encoding of `data` when it is a string (defaults to `'utf8'`). |

Cipheriv [#cipheriv]

Cipheriv [#cipheriv-1]

```ts
new Cipheriv(algorithm: CipherAlgorithm | number, key: string | Buffer, iv: string | Buffer, opts?: TransformOptions<Cipheriv>)
```

**Parameters**

| Parameter   | Type                          | Default | Description                                                                                                                                                                |
| ----------- | ----------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `algorithm` | `CipherAlgorithm` \| `number` | —       | The cipher algorithm, as a string or a numeric constant from `constants.cipher`.                                                                                           |
| `key`       | `string` \| `Buffer`          | —       | The encryption key; must match the algorithm's required length.                                                                                                            |
| `iv`        | `string` \| `Buffer`          | —       | The initialization vector / nonce; must match the algorithm's required length.                                                                                             |
| `opts?`     | `TransformOptions<Cipheriv>`  | —       | Options forwarded to `Transform`; may include `encoding` (defaults to `'utf8'`) and, for AEAD algorithms, `authTagLength` (defaults to `16`; must be `12`, `14`, or `16`). |

**Throws**

* `UNKNOWN_CIPHER` — `algorithm` is a string that does not name a supported cipher.
* `RangeError` — `key` or `iv` does not match the algorithm's required length, or (AEAD) `authTagLength` is not `12`, `14`, or `16`.

Cipheriv.final(outputEncoding?: BufferEncoding): string | Buffer [#cipherivfinaloutputencoding-bufferencoding-string--buffer]

Finalize encryption. For AEAD ciphers, the auth tag becomes available via `getAuthTag()` after this call.

**Parameters**

| Parameter         | Type             | Default | Description                                                             |
| ----------------- | ---------------- | ------- | ----------------------------------------------------------------------- |
| `outputEncoding?` | `BufferEncoding` | —       | If provided, the final output is returned as a string in this encoding. |

getAuthTag(): Buffer [#getauthtag-buffer]

Return the auth tag produced by `final()`. AEAD ciphers only.

Cipheriv.setAAD(buffer: string | Buffer, opts?: { encoding?: BufferEncoding }): this [#cipherivsetaadbuffer-string--buffer-opts--encoding-bufferencoding--this]

Provide additional authenticated data. AEAD ciphers only. The `options` may include an `encoding` for string inputs.

**Parameters**

| Parameter | Type                            | Default | Description                                           |
| --------- | ------------------------------- | ------- | ----------------------------------------------------- |
| `buffer`  | `string` \| `Buffer`            | —       | The additional authenticated data.                    |
| `opts?`   | `{ encoding?: BufferEncoding }` | —       | May include an `encoding` for string `buffer` inputs. |

setAutoPadding(pad: unknown): this [#setautopaddingpad-unknown-this]

Enable or disable automatic padding. Block ciphers only.

**Parameters**

| Parameter | Type      | Default | Description                                                |
| --------- | --------- | ------- | ---------------------------------------------------------- |
| `pad`     | `unknown` | —       | `true` to enable automatic padding, `false` to disable it. |

Cipheriv.update [#cipherivupdate]

```ts
update(data: string | Buffer, inputEncoding?: BufferEncoding, outputEncoding?: BufferEncoding): string | Buffer
```

Encrypt a chunk. Returns a `Buffer`, or a string if `outputEncoding` is provided. For AEAD ciphers, encrypted output is delivered all at once from `final()`.

**Parameters**

| Parameter         | Type                 | Default | Description                                                                 |
| ----------------- | -------------------- | ------- | --------------------------------------------------------------------------- |
| `data`            | `string` \| `Buffer` | —       | The chunk to encrypt.                                                       |
| `inputEncoding?`  | `BufferEncoding`     | —       | The encoding of `data` when it is a string.                                 |
| `outputEncoding?` | `BufferEncoding`     | —       | If provided, the encrypted result is returned as a string in this encoding. |

Decipheriv [#decipheriv]

Decipheriv [#decipheriv-1]

```ts
new Decipheriv(algorithm: CipherAlgorithm | number, key: string | Buffer, iv: string | Buffer, opts?: TransformOptions<Cipheriv>)
```

**Parameters**

| Parameter   | Type                          | Default | Description                                                                      |
| ----------- | ----------------------------- | ------- | -------------------------------------------------------------------------------- |
| `algorithm` | `CipherAlgorithm` \| `number` | —       | The cipher algorithm, as a string or a numeric constant from `constants.cipher`. |
| `key`       | `string` \| `Buffer`          | —       | The decryption key; must match the algorithm's required length.                  |
| `iv`        | `string` \| `Buffer`          | —       | The initialization vector / nonce; must match the algorithm's required length.   |
| `opts?`     | `TransformOptions<Cipheriv>`  | —       | Accepts the same options as `createCipheriv`.                                    |

**Throws**

* `UNKNOWN_CIPHER` — `algorithm` is a string that does not name a supported cipher.
* `RangeError` — `key` or `iv` does not match the algorithm's required length, or (AEAD) `authTagLength` is not `12`, `14`, or `16`.

Decipheriv.final(outputEncoding?: BufferEncoding): string | Buffer [#decipherivfinaloutputencoding-bufferencoding-string--buffer]

Finalize decryption. For AEAD ciphers, `setAuthTag()` must be called before `final()`.

**Parameters**

| Parameter         | Type             | Default | Description                                                             |
| ----------------- | ---------------- | ------- | ----------------------------------------------------------------------- |
| `outputEncoding?` | `BufferEncoding` | —       | If provided, the final output is returned as a string in this encoding. |

Decipheriv.setAAD(buffer: string | Buffer, opts?: { encoding?: BufferEncoding }): this [#decipherivsetaadbuffer-string--buffer-opts--encoding-bufferencoding--this]

Provide additional authenticated data. AEAD ciphers only. The `options` may include an `encoding` for string inputs.

**Parameters**

| Parameter | Type                            | Default | Description                                           |
| --------- | ------------------------------- | ------- | ----------------------------------------------------- |
| `buffer`  | `string` \| `Buffer`            | —       | The additional authenticated data.                    |
| `opts?`   | `{ encoding?: BufferEncoding }` | —       | May include an `encoding` for string `buffer` inputs. |

setAuthTag(authTag: string | Buffer, encoding?: BufferEncoding): this [#setauthtagauthtag-string--buffer-encoding-bufferencoding-this]

Set the expected auth tag prior to calling `final()`. AEAD ciphers only.

**Parameters**

| Parameter   | Type                 | Default | Description                                    |
| ----------- | -------------------- | ------- | ---------------------------------------------- |
| `authTag`   | `string` \| `Buffer` | —       | The expected authentication tag.               |
| `encoding?` | `BufferEncoding`     | —       | The encoding of `authTag` when it is a string. |

setAutoPadding(pad: boolean): this [#setautopaddingpad-boolean-this]

Enable or disable automatic padding. Block ciphers only.

**Parameters**

| Parameter | Type      | Default | Description                                                |
| --------- | --------- | ------- | ---------------------------------------------------------- |
| `pad`     | `boolean` | —       | `true` to enable automatic padding, `false` to disable it. |

Decipheriv.update [#decipherivupdate]

```ts
update(data: string | Buffer, inputEncoding?: BufferEncoding, outputEncoding?: BufferEncoding): string | Buffer
```

Decrypt a chunk. Same semantics as `cipher.update()`.

**Parameters**

| Parameter         | Type                 | Default | Description                                                                 |
| ----------------- | -------------------- | ------- | --------------------------------------------------------------------------- |
| `data`            | `string` \| `Buffer` | —       | The chunk to decrypt.                                                       |
| `inputEncoding?`  | `BufferEncoding`     | —       | The encoding of `data` when it is a string.                                 |
| `outputEncoding?` | `BufferEncoding`     | —       | If provided, the decrypted result is returned as a string in this encoding. |

Functions [#functions]

createHash(algorithm: HashAlgorithm | number, opts?: TransformOptions<Hash>): Hash [#createhashalgorithm-hashalgorithm--number-opts-transformoptionshash-hash]

Create a new `Hash` instance with the specified `algorithm`. `algorithm` may be a string (for example `'sha256'`, `'sha-256'`) or a numeric constant from `constants.hash`. The `options` are forwarded to the `Transform` constructor from `bare-stream` (\<[https://github.com/holepunchto/bare-stream>](https://github.com/holepunchto/bare-stream>)).

**Parameters**

| Parameter   | Type                        | Default | Description                                                                                                        |
| ----------- | --------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------ |
| `algorithm` | `HashAlgorithm` \| `number` | —       | The hash algorithm, as a string (for example `'sha256'`, `'sha-256'`) or a numeric constant from `constants.hash`. |
| `opts?`     | `TransformOptions<Hash>`    | —       | Options forwarded to the `Transform` constructor from `bare-stream`.                                               |

**Throws**

* `UNKNOWN_HASH` — `algorithm` is a string that does not name a supported hash algorithm.

createHmac [#createhmac]

```ts
createHmac(algorithm: HashAlgorithm | number, key: string | Buffer, opts?: TransformOptions<Hmac>): Hmac
```

Create a new `Hmac` instance using `algorithm` and `key`. `key` may be a string or `ArrayBufferView`. If `key` is a string, an `encoding` option (defaults to `'utf8'`) controls how it is decoded. The `options` are also forwarded to `Transform`.

**Parameters**

| Parameter   | Type                        | Default | Description                                                                                                        |
| ----------- | --------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------ |
| `algorithm` | `HashAlgorithm` \| `number` | —       | The hash algorithm, as a string (for example `'sha256'`, `'sha-256'`) or a numeric constant from `constants.hash`. |
| `key`       | `string` \| `Buffer`        | —       | The HMAC key; a string is decoded using the `encoding` option (defaults to `'utf8'`).                              |
| `opts?`     | `TransformOptions<Hmac>`    | —       | Options forwarded to the `Transform` constructor from `bare-stream`.                                               |

**Throws**

* `UNKNOWN_HASH` — `algorithm` is a string that does not name a supported hash algorithm.

createCipheriv [#createcipheriv]

```ts
createCipheriv(algorithm: CipherAlgorithm | number, key: string | Buffer, iv: string | Buffer, opts?: TransformOptions<Cipheriv>): Cipheriv
```

Create a new `Cipheriv` instance using `algorithm`, `key`, and `iv` (initialization vector / nonce). `key` and `iv` must match the algorithm's required lengths. For AEAD algorithms (for example `AES128GCM`, `CHACHA20POLY1305`), the `options` may include an `authTagLength` (defaults to `16`).

**Parameters**

| Parameter   | Type                          | Default | Description                                                                                                                                                                |
| ----------- | ----------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `algorithm` | `CipherAlgorithm` \| `number` | —       | The cipher algorithm, as a string or a numeric constant from `constants.cipher`.                                                                                           |
| `key`       | `string` \| `Buffer`          | —       | The encryption key; must match the algorithm's required length.                                                                                                            |
| `iv`        | `string` \| `Buffer`          | —       | The initialization vector / nonce; must match the algorithm's required length.                                                                                             |
| `opts?`     | `TransformOptions<Cipheriv>`  | —       | Options forwarded to `Transform`; may include `encoding` (defaults to `'utf8'`) and, for AEAD algorithms, `authTagLength` (defaults to `16`; must be `12`, `14`, or `16`). |

**Throws**

* `UNKNOWN_CIPHER` — `algorithm` is a string that does not name a supported cipher.
* `RangeError` — `key` or `iv` does not match the algorithm's required length, or (AEAD) `authTagLength` is not `12`, `14`, or `16`.

createDecipheriv [#createdecipheriv]

```ts
createDecipheriv(algorithm: CipherAlgorithm | number, key: string | Buffer, iv: string | Buffer, opts?: TransformOptions<Cipheriv>): Decipheriv
```

Create a new `Decipheriv` instance using `algorithm`, `key`, and `iv`. Accepts the same `options` as `createCipheriv`.

**Parameters**

| Parameter   | Type                          | Default | Description                                                                      |
| ----------- | ----------------------------- | ------- | -------------------------------------------------------------------------------- |
| `algorithm` | `CipherAlgorithm` \| `number` | —       | The cipher algorithm, as a string or a numeric constant from `constants.cipher`. |
| `key`       | `string` \| `Buffer`          | —       | The decryption key; must match the algorithm's required length.                  |
| `iv`        | `string` \| `Buffer`          | —       | The initialization vector / nonce; must match the algorithm's required length.   |
| `opts?`     | `TransformOptions<Cipheriv>`  | —       | Accepts the same options as `createCipheriv`.                                    |

**Throws**

* `UNKNOWN_CIPHER` — `algorithm` is a string that does not name a supported cipher.
* `RangeError` — `key` or `iv` does not match the algorithm's required length, or (AEAD) `authTagLength` is not `12`, `14`, or `16`.

randomBytes(size: number): Buffer [#randombytessize-number-buffer]

Generate `size` cryptographically secure random bytes.

Overloads:

```ts
randomBytes(size: number): Buffer
randomBytes(size: number, callback: (err: Error | null, buffer: Buffer) => void): void
```

**Parameters**

| Parameter | Type     | Default | Description                             |
| --------- | -------- | ------- | --------------------------------------- |
| `size`    | `number` | —       | The number of random bytes to generate. |

randomFill [#randomfill]

```ts
randomFill<B extends ArrayBuffer | ArrayBufferView>(buffer: B, offset?: number, size?: number): B
```

Fill `buffer` with cryptographically secure random bytes, optionally restricted to `[offset, offset + size)`. `offset` defaults to `0` and `size` to `buffer.byteLength - offset`. Returns the same `buffer`. Accepts an optional `callback` for a non-blocking, asynchronous form, distinct from the fully synchronous `randomFillSync`.

Synchronous form: `randomFillSync<B extends ArrayBuffer | ArrayBufferView>(buffer: B, offset?: number, size?: number): B`

**Parameters**

| Parameter | Type     | Default | Description                                                |
| --------- | -------- | ------- | ---------------------------------------------------------- |
| `buffer`  | `B`      | —       | The buffer to fill.                                        |
| `offset?` | `number` | —       | Offset at which filling starts (defaults to `0`).          |
| `size?`   | `number` | —       | Amount to fill (defaults to `buffer.byteLength - offset`). |

**Throws**

* `RangeError` — `offset`, `size`, or `offset + size` is out of range for `buffer`.

randomUUID(): string [#randomuuid-string]

Generate a random RFC 4122 version-4 UUID string.

pbkdf2 [#pbkdf2]

```ts
pbkdf2(password: string | ArrayBuffer | ArrayBufferView, salt: string | ArrayBuffer | ArrayBufferView, iterations: number, keylen: number, digest: HashAlgorithm | number): Buffer
```

Derive a key from `password` and `salt` using the specified `digest` algorithm and number of `iterations`. Returns a `keylen`-byte `Buffer`. `password` and `salt` may be strings or `ArrayBufferView`s. Accepts an optional `callback` for an asynchronous form — PBKDF2 key derivation is available in both synchronous (`pbkdf2Sync`) and callback-based asynchronous forms.

Synchronous form: `pbkdf2Sync(password: string | ArrayBufferView, salt: string | ArrayBufferView, iterations: number, keylen: number, digest: HashAlgorithm | number): Buffer`

**Parameters**

| Parameter    | Type                                           | Default | Description                                                                  |
| ------------ | ---------------------------------------------- | ------- | ---------------------------------------------------------------------------- |
| `password`   | `string` \| `ArrayBuffer` \| `ArrayBufferView` | —       | The password to derive the key from.                                         |
| `salt`       | `string` \| `ArrayBuffer` \| `ArrayBufferView` | —       | The salt.                                                                    |
| `iterations` | `number`                                       | —       | The number of PBKDF2 iterations; must be between `1` and `2^32 - 1`.         |
| `keylen`     | `number`                                       | —       | The length in bytes of the derived key.                                      |
| `digest`     | `HashAlgorithm` \| `number`                    | —       | The hash algorithm, as a string or a numeric constant from `constants.hash`. |

**Throws**

* `RangeError` — `iterations` or `keylen` is out of range.
* `UNKNOWN_HASH` — `digest` is a string that does not name a supported hash algorithm.

generateKeyPair [#generatekeypair]

```ts
generateKeyPair(type: SignatureAlgorithm | Lowercase<SignatureAlgorithm>): {
  publicKey: CryptoKey
  privateKey: CryptoKey
}
```

Generate a new asymmetric key pair. `type` may be a string (for example `'ed25519'`) or a numeric constant from `constants.keyType`.

**Parameters**

| Parameter | Type                                                  | Default | Description                                                                                         |
| --------- | ----------------------------------------------------- | ------- | --------------------------------------------------------------------------------------------------- |
| `type`    | `SignatureAlgorithm \| Lowercase<SignatureAlgorithm>` | —       | The key type, as a string (for example `'ed25519'`) or a numeric constant from `constants.keyType`. |

**Throws**

* `UNKNOWN_KEY_TYPE` — `type` is a string that does not name a supported key type.

sign(algorithm: null, data: ArrayBuffer | ArrayBufferView, key: CryptoKey): Buffer [#signalgorithm-null-data-arraybuffer--arraybufferview-key-cryptokey-buffer]

Sign `data` using `key`. For Ed25519, `algorithm` is ignored — pass `null`. `data` may be an `ArrayBuffer` or `ArrayBufferView`. Returns a `Buffer` containing the signature.

**Parameters**

| Parameter   | Type                               | Default | Description                        |
| ----------- | ---------------------------------- | ------- | ---------------------------------- |
| `algorithm` | `null`                             | —       | Ignored for Ed25519 — pass `null`. |
| `data`      | `ArrayBuffer` \| `ArrayBufferView` | —       | The data to sign.                  |
| `key`       | `CryptoKey`                        | —       | The key to sign with.              |

verify [#verify]

```ts
verify(algorithm: null, data: ArrayBuffer | ArrayBufferView, key: CryptoKey, signature: Buffer): boolean
```

Verify that `signature` is a valid signature over `data` for `key`. Returns `true` or `false`.

**Parameters**

| Parameter   | Type                               | Default | Description                        |
| ----------- | ---------------------------------- | ------- | ---------------------------------- |
| `algorithm` | `null`                             | —       | Ignored for Ed25519 — pass `null`. |
| `data`      | `ArrayBuffer` \| `ArrayBufferView` | —       | The signed data.                   |
| `key`       | `CryptoKey`                        | —       | The key to verify against.         |
| `signature` | `Buffer`                           | —       | The signature to check.            |

timingSafeEqual(a: ArrayBuffer | ArrayBufferView, b: ArrayBuffer | ArrayBufferView): boolean [#timingsafeequala-arraybuffer--arraybufferview-b-arraybuffer--arraybufferview-boolean]

Compare two `ArrayBuffer`s or `ArrayBufferView`s in constant time. Returns `true` if `a` and `b` contain the same bytes, otherwise `false`. Throws a `RangeError` if `a` and `b` differ in byte length. Use this whenever comparing MACs, signatures, capability tokens, or other secret-equality checks.

**Parameters**

| Parameter | Type                               | Default | Description                   |
| --------- | ---------------------------------- | ------- | ----------------------------- |
| `a`       | `ArrayBuffer` \| `ArrayBufferView` | —       | The first buffer to compare.  |
| `b`       | `ArrayBuffer` \| `ArrayBufferView` | —       | The second buffer to compare. |

**Throws**

* `RangeError` — `a` and `b` differ in byte length.

Constants and variables [#constants-and-variables]

constants [#constants]

```ts
constants: {
  hash: Record<HashAlgorithm, number>
  signature: Record<SignatureAlgorithm, number>
  cipher: Record<CipherAlgorithm, number>
  keyType: Record<SignatureAlgorithm, number>
}
```

The supported algorithm constants: `hash` (hash algorithms), `cipher` (symmetric cipher algorithms), `signature` (signature algorithms), and `keyType` (asymmetric key types).

webcrypto [#webcrypto]

A namespace implementing a subset of the W3C Web Crypto API (\<[https://w3c.github.io/webcrypto>](https://w3c.github.io/webcrypto>)). Exposes `Crypto`, `SubtleCrypto`, `CryptoKey`, `getRandomValues`, `randomUUID`, and `subtle` (a pre-constructed `SubtleCrypto` instance). Supports HMAC, Ed25519, PBKDF2, and SHA-1 / SHA-256 / SHA-384 / SHA-512.

bare-crypto/web [#bare-cryptoweb]

Functions [#functions-1]

getRandomValues [#getrandomvalues]

```ts
getRandomValues<B extends ArrayBuffer | ArrayBufferView>(buffer: B, offset?: number, size?: number): B
```

Fill `array` with cryptographically secure random bytes and return the same `array`. Equivalent to `randomFillSync(array)`.

**Parameters**

| Parameter | Type     | Default | Description                                                |
| --------- | -------- | ------- | ---------------------------------------------------------- |
| `buffer`  | `B`      | —       | The buffer to fill.                                        |
| `offset?` | `number` | —       | Offset at which filling starts (defaults to `0`).          |
| `size?`   | `number` | —       | Amount to fill (defaults to `buffer.byteLength - offset`). |

**Throws**

* `RangeError` — `offset`, `size`, or `offset + size` is out of range for `buffer`.

web.randomUUID(): string [#webrandomuuid-string]

Generate a random RFC 4122 version-4 UUID string.

Constants and variables [#constants-and-variables-1]

CryptoKey [#cryptokey]

subtle: SubtleCrypto [#subtle-subtlecrypto]

Types [#types]

SubtleCrypto [#subtlecrypto]

```ts
interface SubtleCrypto {
  generateKey(
    algorithm: { name: 'HMAC'; hash: HashArg; length?: number },
    extractable: boolean,
    usages: ('sign' | 'verify')[]
  ): Promise<CryptoKey<'HMAC'>>
  importKey(
    format: 'raw',
    keyData: Buffer | ArrayBuffer,
    algorithm: { name: 'HMAC'; hash: HashArg },
    extractable: boolean,
    usages: ('sign' | 'verify')[]
  ): Promise<CryptoKey<'HMAC'>>
  exportKey(format: 'raw' | 'spki' | 'pkcs8', key: CryptoKey): Promise<ArrayBuffer>
  sign(algorithm: 'HMAC' | 'Ed25519', key: CryptoKey, data: Buffer): Promise<ArrayBuffer>
  verify(
    algorithm: 'HMAC' | 'Ed25519',
    key: CryptoKey,
    signature: ArrayBuffer,
    data: Buffer
  ): Promise<boolean>
  deriveBits(
    algorithm: { name: 'PBKDF2'; hash: HashArg; salt: Buffer; iterations: number } | 'PBKDF2',
    key: CryptoKey,
    length: number
  ): Promise<ArrayBuffer>
  deriveKey(
    algorithm: { name: 'PBKDF2'; hash: HashArg; salt: Buffer; iterations: number },
    baseKey: CryptoKey,
    derivedKeyType: { name: 'HMAC'; hash: HashArg },
    extractable: boolean,
    usages: ('sign' | 'verify')[]
  ): Promise<CryptoKey>
  digest(algorithm: HashArg, data: Buffer): Promise<ArrayBuffer>
}
```

Crypto [#crypto]

```ts
interface Crypto {
  readonly subtle: SubtleCrypto
  getRandomValues<B extends ArrayBuffer | ArrayBufferView>(array: B): B
  randomUUID(): string
}
```

JWK [#jwk]

```ts
interface JWK {
  alg?: string
  crv?: string
  d?: string
  ext?: boolean
  k?: string
  key_ops?: string[]
  kty?: string
  use?: string
  x?: string
}
```

HashArg [#hasharg]

```ts
type HashArg = 'SHA-1' | 'SHA-256' | 'SHA-384' | 'SHA-512' | { name: HashArg }
```

bare-crypto/global [#bare-cryptoglobal]

Constants and variables [#constants-and-variables-2]

crypto [#crypto-1]

Installed as a global by importing `bare-crypto/global`, along with `Crypto`, `CryptoKey`, and `SubtleCrypto`.

See also [#see-also]

* Builds on `bare-assert` and `bare-stream`.
* [Bare modules](/reference/modules/bare-modules) — the full `bare-*` catalog.
* [Bare runtime API](/reference/bare/runtime) — the runtime these modules extend.


# bare-dns



<mark style={{ backgroundColor: '#7dde9a', padding: '2px 8px', borderRadius: '4px', fontSize: '0.85em', fontWeight: 500 }}>
  stable
</mark>

[`bare-dns`](https://github.com/holepunchto/bare-dns) — Domain name resolution for JavaScript. It is a native addon and requires Bare `>=1.7.0`.

Mirrors the Node.js [`dns`](https://nodejs.org/api/dns.html) module.

```sh
npm i bare-dns
```

Usage [#usage]

```js
const dns = require('bare-dns')

dns.lookup('github.com', (err, address, family) => {
  console.log(address, family)
})
```

API [#api]

dns [#dns]

dns.IPFamily [#dnsipfamily]

```ts
type IPFamily = 4 | 6
```

The IP address family: `4` for IPv4 or `6` for IPv6.

dns.lookup [#dnslookup]

```ts
dns.lookup(hostname: string, cb: (err: Error | null, address: string | null, family: IPFamily | 0) => void): void
```

Resolve `hostname` into an IP address using the operating system's `getaddrinfo` facility, not the DNS protocol directly. With `all: true`, the callback receives every resolved address instead of just the first.

**Parameters**

| Parameter  | Type                                                                           | Default | Description                                                                   |
| ---------- | ------------------------------------------------------------------------------ | ------- | ----------------------------------------------------------------------------- |
| `hostname` | `string`                                                                       | —       | The host name to resolve.                                                     |
| `cb`       | `(err: Error \| null, address: string \| null, family: IPFamily \| 0) => void` | —       | Called with `(err, address, family)`, or `(err, addresses)` when `all: true`. |

dns.resolveTxt(hostname: string, cb: (err: Error | null, records: string[][]) => void): void [#dnsresolvetxthostname-string-cb-err-error--null-records-string--void-void]

Use the DNS protocol to resolve TXT records for `hostname`. The callback receives an array of records, each itself an array of the strings that make up that record.

**Parameters**

| Parameter  | Type                                                | Default | Description                                                                         |
| ---------- | --------------------------------------------------- | ------- | ----------------------------------------------------------------------------------- |
| `hostname` | `string`                                            | —       | The host name to query TXT records for.                                             |
| `cb`       | `(err: Error \| null, records: string[][]) => void` | —       | Called with `(err, records)`; each record is an array of the strings it is made of. |

DNSResolver [#dnsresolver]

destroy(): void [#destroy-void]

Cancel any pending queries on this resolver and release its underlying handle.

resolveTxt(hostname: string, cb: (err: Error | null, records: string[][]) => void): void [#resolvetxthostname-string-cb-err-error--null-records-string--void-void]

Use the DNS protocol to resolve TXT records for `hostname`. The callback receives an array of records, each itself an array of the strings that make up that record.

**Parameters**

| Parameter  | Type                                                | Default | Description                                                                         |
| ---------- | --------------------------------------------------- | ------- | ----------------------------------------------------------------------------------- |
| `hostname` | `string`                                            | —       | The host name to query TXT records for.                                             |
| `cb`       | `(err: Error \| null, records: string[][]) => void` | —       | Called with `(err, records)`; each record is an array of the strings it is made of. |

Types [#types]

LookupOptions [#lookupoptions]

```ts
interface LookupOptions {
  family?: `IPv${IPFamily}` | IPFamily | 0
  hints?: number
  all?: boolean
}
```

See also [#see-also]

* [Bare modules](/reference/modules/bare-modules) — the full `bare-*` catalog.
* [Bare runtime API](/reference/bare/runtime) — the runtime these modules extend.


# bare-encoding



<mark style={{ backgroundColor: '#7dde9a', padding: '2px 8px', borderRadius: '4px', fontSize: '0.85em', fontWeight: 500 }}>
  stable
</mark>

[`bare-encoding`](https://github.com/holepunchto/bare-encoding) — WHATWG text encoding interfaces for JavaScript.

```sh
npm i bare-encoding
```

Usage [#usage]

```js
const { TextEncoder, TextDecoder } = require('bare-encoding')
```

API [#api]

TextEncoder [#textencoder]

encode(input: string): Buffer [#encodeinput-string-buffer]

Encode `input` as UTF-8 and return the result as a `Buffer`.

**Parameters**

| Parameter | Type     | Default | Description           |
| --------- | -------- | ------- | --------------------- |
| `input`   | `string` | —       | The string to encode. |

encodeInto [#encodeinto]

```ts
encodeInto(input: string, destination: ArrayBufferView | ArrayBuffer | SharedArrayBuffer): { read: number; written: number }
```

Encode `input` as UTF-8 into `destination`. Returns the number of UTF-16 units of `input` read and the number of bytes written.

**Parameters**

| Parameter     | Type                                                      | Default | Description                               |
| ------------- | --------------------------------------------------------- | ------- | ----------------------------------------- |
| `input`       | `string`                                                  | —       | The string to encode.                     |
| `destination` | `ArrayBufferView` \| `ArrayBuffer` \| `SharedArrayBuffer` | —       | The buffer to write the UTF-8 bytes into. |

TextEncoder.encoding: 'utf-8' [#textencoderencoding-utf-8]

Always `'utf-8'`.

TextDecoder [#textdecoder]

new TextDecoder(label?: string) [#new-textdecoderlabel-string]

Create a `TextDecoder` for `label`. Only `'utf-8'` (and its aliases) is supported; any other label throws.

**Parameters**

| Parameter | Type     | Default | Description                                                                          |
| --------- | -------- | ------- | ------------------------------------------------------------------------------------ |
| `label?`  | `string` | —       | The encoding label; only `'utf-8'` and its aliases are accepted (default `'utf-8'`). |

**Throws**

* `INVALID_LABEL` — `label` is not `'utf-8'` or one of its aliases.

decode [#decode]

```ts
decode(input: ArrayBufferView | ArrayBuffer | SharedArrayBuffer, options?: { stream: boolean }): string
```

Decode `input` to a string. If `options.stream` is `true`, buffers any incomplete trailing sequence for the next call instead of including it in the result.

**Parameters**

| Parameter  | Type                                                      | Default | Description                                                             |
| ---------- | --------------------------------------------------------- | ------- | ----------------------------------------------------------------------- |
| `input`    | `ArrayBufferView` \| `ArrayBuffer` \| `SharedArrayBuffer` | —       | The bytes to decode.                                                    |
| `options?` | `{ stream: boolean }`                                     | —       | Options; set `stream: true` when `input` is a chunk of a larger stream. |

TextDecoder.encoding: 'utf-8' [#textdecoderencoding-utf-8]

The encoding this decoder was constructed with, always `'utf-8'`.

Classes [#classes]

TextEncoderStream [#textencoderstream]

```ts
class TextEncoderStream {
  encoding: 'utf-8'
  readable: ReadableStream
  writable: WritableStream
}
```

TextDecoderStream [#textdecoderstream]

```ts
class TextDecoderStream {
  encoding: 'utf-8'
  readable: ReadableStream
  writable: WritableStream
}
```

bare-encoding/global [#bare-encodingglobal]

Types [#types]

TextEncoderConstructor [#textencoderconstructor]

```ts
type TextEncoderConstructor = typeof encoding.TextEncoder
```

The type of the `TextEncoder` class, used to type the global `TextEncoder` constructor.

TextDecoderConstructor [#textdecoderconstructor]

```ts
type TextDecoderConstructor = typeof encoding.TextDecoder
```

The type of the `TextDecoder` class, used to type the global `TextDecoder` constructor.

TextEncoderStreamConstructor [#textencoderstreamconstructor]

```ts
type TextEncoderStreamConstructor = typeof encoding.TextEncoderStream
```

TextDecoderStreamConstructor [#textdecoderstreamconstructor]

```ts
type TextDecoderStreamConstructor = typeof encoding.TextDecoderStream
```

bare-encoding/errors [#bare-encodingerrors]

EncodingError [#encodingerror]

code: string [#code-string]

The error code identifying the failure.

EncodingError.INVALID_LABEL(msg: string): EncodingError [#encodingerrorinvalid_labelmsg-string-encodingerror]

The label passed to `TextDecoder` is not a valid encoding.

**Parameters**

| Parameter | Type     | Default | Description        |
| --------- | -------- | ------- | ------------------ |
| `msg`     | `string` | —       | The error message. |

**Returns** `EncodingError` — An `EncodingError` with `code` set to `'INVALID_LABEL'`, for the caller to throw.

See also [#see-also]

* [Bare modules](/reference/modules/bare-modules) — the full `bare-*` catalog.
* [Bare runtime API](/reference/bare/runtime) — the runtime these modules extend.


# bare-env



<mark style={{ backgroundColor: '#7dde9a', padding: '2px 8px', borderRadius: '4px', fontSize: '0.85em', fontWeight: 500 }}>
  stable
</mark>

[`bare-env`](https://github.com/holepunchto/bare-env) — Environment variable support for JavaScript.

```sh
npm i bare-env
```

Usage [#usage]

```js
const env = require('bare-env')

console.log(env.PATH)
```

API [#api]

Constants and variables [#constants-and-variables]

env: Env [#env-env]

The process environment as a map of variable names to values. Reads, writes, `delete`, and key enumeration are forwarded to the underlying `bare-os` environment; assigned values must be strings, numbers, or booleans (stored as strings) — assigning any other type throws.

Types [#types]

Env [#env]

```ts
interface Env {
}
```

See also [#see-also]

* Builds on `bare-os`.
* [Bare modules](/reference/modules/bare-modules) — the full `bare-*` catalog.
* [Bare runtime API](/reference/bare/runtime) — the runtime these modules extend.


# bare-events



<mark style={{ backgroundColor: '#7dde9a', padding: '2px 8px', borderRadius: '4px', fontSize: '0.85em', fontWeight: 500 }}>
  stable
</mark>

[`bare-events`](https://github.com/holepunchto/bare-events) — Event emitters for JavaScript.

Mirrors the Node.js [`events`](https://nodejs.org/api/events.html) module.

```sh
npm i bare-events
```

Usage [#usage]

```js
const EventEmitter = require('bare-events')

const e = new EventEmitter()

e.on('hello', function (data) {
  console.log(data)
})

e.emit('hello', 'world')
```

API [#api]

Adding and removing listeners [#adding-and-removing-listeners]

addListener<E extends keyof M, R>(name: E, fn: EventHandler<M[E], R>): this [#addlistenere-extends-keyof-m-rname-e-fn-eventhandlerme-r-this]

Add `fn` as a listener for `name`, called on every subsequent emit. Returns `this` for chaining.

**Parameters**

| Parameter | Type                    | Default | Description                                                            |
| --------- | ----------------------- | ------- | ---------------------------------------------------------------------- |
| `name`    | `E`                     | —       | The event name to listen for.                                          |
| `fn`      | `EventHandler<M[E], R>` | —       | The listener function, called with the event's arguments on each emit. |

addOnceListener<E extends keyof M, R>(name: E, fn: EventHandler<M[E], R>): this [#addoncelistenere-extends-keyof-m-rname-e-fn-eventhandlerme-r-this]

Add `fn` as a listener for `name` that is removed after it fires once. Returns `this` for chaining.

**Parameters**

| Parameter | Type                    | Default | Description                                                                 |
| --------- | ----------------------- | ------- | --------------------------------------------------------------------------- |
| `name`    | `E`                     | —       | The event name to listen for.                                               |
| `fn`      | `EventHandler<M[E], R>` | —       | The listener function, called once with the event's arguments then removed. |

prependListener<E extends keyof M, R>(name: E, fn: EventHandler<M[E], R>): this [#prependlistenere-extends-keyof-m-rname-e-fn-eventhandlerme-r-this]

Like `addListener`, but adds `fn` to the beginning of the listener list instead of the end.

**Parameters**

| Parameter | Type                    | Default | Description                                                                        |
| --------- | ----------------------- | ------- | ---------------------------------------------------------------------------------- |
| `name`    | `E`                     | —       | The event name to listen for.                                                      |
| `fn`      | `EventHandler<M[E], R>` | —       | The listener function to add to the front of the listener list instead of the end. |

**Returns** `this` — The emitter itself, for chaining, like `addListener`.

prependOnceListener<E extends keyof M, R>(name: E, fn: EventHandler<M[E], R>): this [#prependoncelistenere-extends-keyof-m-rname-e-fn-eventhandlerme-r-this]

Like `addOnceListener`, but adds `fn` to the beginning of the listener list instead of the end.

**Parameters**

| Parameter | Type                    | Default | Description                                                                                  |
| --------- | ----------------------- | ------- | -------------------------------------------------------------------------------------------- |
| `name`    | `E`                     | —       | The event name to listen for.                                                                |
| `fn`      | `EventHandler<M[E], R>` | —       | The listener function to add to the front of the listener list, removed after it fires once. |

**Returns** `this` — The emitter itself, for chaining, like `addOnceListener`.

removeListener<E extends keyof M, R>(name: E, fn: EventHandler<M[E], R>): this [#removelistenere-extends-keyof-m-rname-e-fn-eventhandlerme-r-this]

Remove one instance of `fn` from the listeners for `name`. Returns `this` for chaining.

**Parameters**

| Parameter | Type                    | Default | Description                                 |
| --------- | ----------------------- | ------- | ------------------------------------------- |
| `name`    | `E`                     | —       | The event name to remove the listener from. |
| `fn`      | `EventHandler<M[E], R>` | —       | The listener function to remove.            |

removeAllListeners<E extends keyof M>(name?: E): this [#removealllistenerse-extends-keyof-mname-e-this]

Remove all listeners, or only those for `name` if given. Returns `this` for chaining.

**Parameters**

| Parameter | Type | Default | Description                                                                                          |
| --------- | ---- | ------- | ---------------------------------------------------------------------------------------------------- |
| `name?`   | `E`  | —       | If given, remove listeners only for this event name; otherwise remove all listeners for every event. |

on<E extends keyof M, R>(name: E, fn: EventHandler<M[E], R>): this [#one-extends-keyof-m-rname-e-fn-eventhandlerme-r-this]

**Parameters**

| Parameter | Type                    | Default | Description                                                            |
| --------- | ----------------------- | ------- | ---------------------------------------------------------------------- |
| `name`    | `E`                     | —       | The event name.                                                        |
| `fn`      | `EventHandler<M[E], R>` | —       | The listener function, called with the event's arguments on each emit. |

**Returns** `this` — The emitter itself, for chaining — implemented identically to `addListener`.

once<E extends keyof M, R>(name: E, fn: EventHandler<M[E], R>): this [#oncee-extends-keyof-m-rname-e-fn-eventhandlerme-r-this]

**Parameters**

| Parameter | Type                    | Default | Description                                                                 |
| --------- | ----------------------- | ------- | --------------------------------------------------------------------------- |
| `name`    | `E`                     | —       | The event name.                                                             |
| `fn`      | `EventHandler<M[E], R>` | —       | The listener function, called once with the event's arguments then removed. |

**Returns** `this` — The emitter itself, for chaining — implemented identically to `addOnceListener`.

off<E extends keyof M, R>(name: E, fn: EventHandler<M[E], R>): this [#offe-extends-keyof-m-rname-e-fn-eventhandlerme-r-this]

Alias for `removeListener`.

**Parameters**

| Parameter | Type                    | Default | Description                                 |
| --------- | ----------------------- | ------- | ------------------------------------------- |
| `name`    | `E`                     | —       | The event name to remove the listener from. |
| `fn`      | `EventHandler<M[E], R>` | —       | The listener function to remove.            |

**Returns** `this` — The emitter itself, for chaining — implemented identically to `removeListener`.

Emitting [#emitting]

emit<E extends keyof M>(name: E, ...args: M[E]): boolean [#emite-extends-keyof-mname-e-args-me-boolean]

Synchronously call each listener registered for `name`, in registration order, with `args`. Returns `true` if there were listeners, `false` otherwise. Emitting `'error'` with no `'error'` listeners throws the error asynchronously instead of calling any listener.

**Parameters**

| Parameter | Type   | Default | Description                                              |
| --------- | ------ | ------- | -------------------------------------------------------- |
| `name`    | `E`    | —       | The event name to emit.                                  |
| `args`    | `M[E]` | —       | Arguments passed to each listener registered for `name`. |

Inspecting listeners [#inspecting-listeners]

listeners<E extends keyof M, R>(name: E): EventHandler<M[E], R> [#listenerse-extends-keyof-m-rname-e-eventhandlerme-r]

Return a copy of the listener array for `name`.

**Parameters**

| Parameter | Type | Default | Description                                      |
| --------- | ---- | ------- | ------------------------------------------------ |
| `name`    | `E`  | —       | The event name to return the listener array for. |

rawListeners<E extends keyof M, R>(name: E): EventHandler<M[E], R>[] [#rawlistenerse-extends-keyof-m-rname-e-eventhandlerme-r]

Return a copy of the listener array for `name`, including one-time wrapper listeners as registered.

**Parameters**

| Parameter | Type | Default | Description                                          |
| --------- | ---- | ------- | ---------------------------------------------------- |
| `name`    | `E`  | —       | The event name to return the raw listener array for. |

eventNames(): (keyof M)[] [#eventnames-keyof-m]

Return an array of the event names that currently have listeners.

listenerCount<E extends keyof M>(name: E): number [#listenercounte-extends-keyof-mname-e-number]

Return the number of listeners registered for `name`.

**Parameters**

| Parameter | Type | Default | Description     |
| --------- | ---- | ------- | --------------- |
| `name`    | `E`  | —       | The event name. |

getMaxListeners(): number [#getmaxlisteners-number]

**Returns** `number` — `EventEmitter.defaultMaxListeners`; bare-events does not track a per-instance limit separately.

setMaxListeners(n: number): void [#setmaxlistenersn-number-void]

**Parameters**

| Parameter | Type     | Default | Description                               |
| --------- | -------- | ------- | ----------------------------------------- |
| `n`       | `number` | —       | The maximum number of listeners to allow. |

Static utilities [#static-utilities]

EventEmitter.defaultMaxListeners: number [#eventemitterdefaultmaxlisteners-number]

The default max-listeners value used by `getMaxListeners()`.

EventEmitter.forward [#eventemitterforward]

```ts
EventEmitter.forward<F extends EventMap, E extends keyof F, T extends Pick<F, E>>(from: EventEmitter<F>, to: EventEmitter<T>, names: E | E[], opts?: { emit?: (name: E, ...args: T[E]) => void }): void
```

Forward events named in `names` from `from` to `to`, re-emitting them on `to` only while `to` has at least one listener for that event.

**Parameters**

| Parameter | Type                                          | Default | Description                                                                                    |
| --------- | --------------------------------------------- | ------- | ---------------------------------------------------------------------------------------------- |
| `from`    | `EventEmitter<F>`                             | —       | The emitter to forward events from.                                                            |
| `to`      | `EventEmitter<T>`                             | —       | The emitter to forward events to.                                                              |
| `names`   | `E` \| `E[]`                                  | —       | The event name, or array of event names, to forward.                                           |
| `opts?`   | `{ emit?: (name: E, ...args: T[E]) => void }` | —       | Options; `emit` overrides how forwarded events are re-emitted on `to` (defaults to `to.emit`). |

EventEmitter.getMaxListeners(emitter: EventEmitter): number [#eventemittergetmaxlistenersemitter-eventemitter-number]

**Parameters**

| Parameter | Type           | Default | Description           |
| --------- | -------------- | ------- | --------------------- |
| `emitter` | `EventEmitter` | —       | The emitter to query. |

**Returns** `number` — `EventEmitter.defaultMaxListeners`; bare-events does not track a per-instance limit separately.

EventEmitter.listenerCount [#eventemitterlistenercount]

```ts
EventEmitter.listenerCount<M extends EventMap, E extends keyof M>(emitter: EventEmitter<M>, name: E): number
```

Return the number of listeners registered for `name`.

**Parameters**

| Parameter | Type              | Default | Description           |
| --------- | ----------------- | ------- | --------------------- |
| `emitter` | `EventEmitter<M>` | —       | The emitter to query. |
| `name`    | `E`               | —       | The event name.       |

EventEmitter.on [#eventemitteron]

```ts
EventEmitter.on<M extends EventMap, E extends keyof M>(emitter: EventEmitter<M>, name: E, opts?: { signal?: AbortSignal }): AsyncIterableIterator<M[E]>
```

**Parameters**

| Parameter | Type                       | Default | Description                                                                       |
| --------- | -------------------------- | ------- | --------------------------------------------------------------------------------- |
| `emitter` | `EventEmitter<M>`          | —       | The emitter to iterate events from.                                               |
| `name`    | `E`                        | —       | The event name.                                                                   |
| `opts?`   | `{ signal?: AbortSignal }` | —       | Options; `signal` aborts the iteration, rejecting it with an `EventEmitterError`. |

EventEmitter.once [#eventemitteronce]

```ts
EventEmitter.once<M extends EventMap, E extends keyof M>(emitter: EventEmitter<M>, name: E, opts?: { signal?: AbortSignal }): Promise<M[E]>
```

**Parameters**

| Parameter | Type                       | Default | Description                                                                           |
| --------- | -------------------------- | ------- | ------------------------------------------------------------------------------------- |
| `emitter` | `EventEmitter<M>`          | —       | The emitter to wait on.                                                               |
| `name`    | `E`                        | —       | The event name.                                                                       |
| `opts?`   | `{ signal?: AbortSignal }` | —       | Options; `signal` aborts the wait, rejecting the promise with an `EventEmitterError`. |

EventEmitter.setMaxListeners(n: number, ...emitters: EventEmitter[]): void [#eventemittersetmaxlistenersn-number-emitters-eventemitter-void]

**Parameters**

| Parameter  | Type             | Default | Description                                                                          |
| ---------- | ---------------- | ------- | ------------------------------------------------------------------------------------ |
| `n`        | `number`         | —       | The maximum number of listeners to allow.                                            |
| `emitters` | `EventEmitter[]` | —       | The emitters to apply the new limit to; if omitted, sets the global default instead. |

Errors [#errors]

EventEmitterError.OPERATION_ABORTED(cause: Error, msg?: string): EventEmitterError [#eventemittererroroperation_abortedcause-error-msg-string-eventemittererror]

Create an `EventEmitterError` wrapping `cause`, used when an `AbortSignal` aborts a pending `events.on` or `events.once` wait.

**Parameters**

| Parameter | Type     | Default | Description                                        |
| --------- | -------- | ------- | -------------------------------------------------- |
| `cause`   | `Error`  | —       | The abort reason wrapped by the error.             |
| `msg?`    | `string` | —       | An optional custom message for the wrapping error. |

EventEmitterError.UNHANDLED_ERROR(cause: Error, msg?: string): EventEmitterError [#eventemittererrorunhandled_errorcause-error-msg-string-eventemittererror]

Create an `EventEmitterError` wrapping `cause`, used when an `'error'` event is emitted with no listeners attached.

**Parameters**

| Parameter | Type     | Default | Description                                        |
| --------- | -------- | ------- | -------------------------------------------------- |
| `cause`   | `Error`  | —       | The underlying error wrapped by the error.         |
| `msg?`    | `string` | —       | An optional custom message for the wrapping error. |

Types [#types]

EventMap [#eventmap]

```ts
interface EventMap {
}
```

EventHandler [#eventhandler]

```ts
interface EventHandler<in A extends unknown[] = unknown[], out R = unknown> {
}
```

bare-events/global [#bare-eventsglobal]

Types [#types-1]

EventConstructor [#eventconstructor]

```ts
type EventConstructor = typeof events.Event
```

CustomEventConstructor [#customeventconstructor]

```ts
type CustomEventConstructor = typeof events.CustomEvent
```

EventTargetConstructor [#eventtargetconstructor]

```ts
type EventTargetConstructor = typeof events.EventTarget
```

bare-events/web [#bare-eventsweb]

Event [#event]

new Event(type: string, options?: EventOptions) [#new-eventtype-string-options-eventoptions]

**Parameters**

| Parameter  | Type           | Default | Description                                                  |
| ---------- | -------------- | ------- | ------------------------------------------------------------ |
| `type`     | `string`       | —       | The event's type, exposed as `event.type`.                   |
| `options?` | `EventOptions` | —       | Options controlling `bubbles`, `cancelable`, and `composed`. |

bubbles: boolean [#bubbles-boolean]

cancelable: boolean [#cancelable-boolean]

composed: boolean [#composed-boolean]

currentTarget: EventTarget | null [#currenttarget-eventtarget--null]

defaultPrevented: boolean [#defaultprevented-boolean]

isTrusted: boolean [#istrusted-boolean]

preventDefault(): void [#preventdefault-void]

stopImmediatePropagation(): void [#stopimmediatepropagation-void]

stopPropagation(): void [#stoppropagation-void]

target: EventTarget | null [#target-eventtarget--null]

type: string [#type-string]

CustomEvent [#customevent]

new CustomEvent(type: string, options?: CustomEventOptions<T>) [#new-customeventtype-string-options-customeventoptionst]

**Parameters**

| Parameter  | Type                    | Default | Description                                                                    |
| ---------- | ----------------------- | ------- | ------------------------------------------------------------------------------ |
| `type`     | `string`                | —       | The event's type, exposed as `event.type`.                                     |
| `options?` | `CustomEventOptions<T>` | —       | Options controlling `bubbles`/`cancelable`/`composed` plus the `detail` value. |

detail: T [#detail-t]

EventTarget [#eventtarget]

new EventTarget() [#new-eventtarget]

addEventListener [#addeventlistener]

```ts
addEventListener(type: string, callback: EventListener, options?: AddEventListenerOptions | boolean): void
```

**Parameters**

| Parameter  | Type                                   | Default | Description                                                                                                                                         |
| ---------- | -------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`     | `string`                               | —       | The event type to listen for.                                                                                                                       |
| `callback` | `EventListener`                        | —       | The listener function, or an object with a `handleEvent` method.                                                                                    |
| `options?` | `AddEventListenerOptions` \| `boolean` | —       | Options, or a boolean shorthand for `capture`; `once` removes the listener after it fires, `signal` removes it when the given `AbortSignal` aborts. |

dispatchEvent(event: Event): boolean [#dispatcheventevent-event-boolean]

**Parameters**

| Parameter | Type    | Default | Description                                       |
| --------- | ------- | ------- | ------------------------------------------------- |
| `event`   | `Event` | —       | The event to dispatch to this target's listeners. |

**Returns** `boolean` — `false` if the event is cancelable and `preventDefault()` was called on it during dispatch, `true` otherwise.

removeEventListener [#removeeventlistener]

```ts
removeEventListener(type: string, callback: EventListener, options?: RemoveEventListenerOptions | boolean): void
```

**Parameters**

| Parameter  | Type                                      | Default | Description                                                                                                 |
| ---------- | ----------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------- |
| `type`     | `string`                                  | —       | The event type to stop listening for.                                                                       |
| `callback` | `EventListener`                           | —       | The listener to remove.                                                                                     |
| `options?` | `RemoveEventListenerOptions` \| `boolean` | —       | Options, or a boolean shorthand for `capture`; must match the `capture` value passed to `addEventListener`. |

Types [#types-2]

AbortSignal [#abortsignal]

```ts
interface AbortSignal {
  addEventListener(
    type: string,
    callback: EventListener,
    options?: AddEventListenerOptions | boolean
  ): void
  removeEventListener(
    type: string,
    callback: EventListener,
    options?: RemoveEventListenerOptions | boolean
  ): void
  dispatchEvent(event: Event): boolean
}
```

EventOptions [#eventoptions]

```ts
interface EventOptions {
  bubbles?: boolean
  cancelable?: boolean
  composed?: boolean
}
```

CustomEventOptions [#customeventoptions]

```ts
interface CustomEventOptions<T = any> {
  detail?: T
  bubbles?: boolean
  cancelable?: boolean
  composed?: boolean
}
```

AddEventListenerOptions [#addeventlisteneroptions]

```ts
interface AddEventListenerOptions {
  capture?: boolean
  passive?: boolean
  once?: boolean
  signal?: AbortSignal | null
}
```

RemoveEventListenerOptions [#removeeventlisteneroptions]

```ts
interface RemoveEventListenerOptions {
  capture?: boolean
}
```

EventListener [#eventlistener]

```ts
type EventListener = EventCallback | EventHandler
```

EventCallback [#eventcallback]

```ts
interface EventCallback {
}
```

web.EventHandler [#webeventhandler]

```ts
interface EventHandler {
  handleEvent(event: Event): void
}
```

See also [#see-also]

* [Bare modules](/reference/modules/bare-modules) — the full `bare-*` catalog.
* [Bare runtime API](/reference/bare/runtime) — the runtime these modules extend.


# bare-fetch



<mark style={{ backgroundColor: '#7dde9a', padding: '2px 8px', borderRadius: '4px', fontSize: '0.85em', fontWeight: 500 }}>
  stable
</mark>

[`bare-fetch`](https://github.com/holepunchto/bare-fetch) — WHATWG Fetch implementation for Bare.

```sh
npm i bare-fetch
```

Usage [#usage]

```js
const fetch = require('bare-fetch')

const res = await fetch('https://example.com/data')

console.log(await res.json())
```

API [#api]

Headers [#headers]

Headers.new Headers(init?: Record<string, string> | Iterable<[string, string]>) [#headersnew-headersinit-recordstring-string--iterablestring-string]

Construct a new `Headers` collection, optionally initialized from `init`.

**Parameters**

| Parameter | Type                                                   | Default | Description                                                                                              |
| --------- | ------------------------------------------------------ | ------- | -------------------------------------------------------------------------------------------------------- |
| `init?`   | `Record<string, string> \| Iterable<[string, string]>` | —       | A plain object of name–value pairs, an iterable of `[name, value]` pairs, or another `Headers` instance. |

Headers.append(name: string, value: string): void [#headersappendname-string-value-string-void]

Append a value to the header `name`. If the header already exists, the value is added to the existing list.

**Parameters**

| Parameter | Type     | Default | Description                        |
| --------- | -------- | ------- | ---------------------------------- |
| `name`    | `string` | —       | The header name.                   |
| `value`   | `string` | —       | The value to append to the header. |

**Throws**

* `INVALID_HEADER_NAME` — `name` is empty or contains characters that are not valid in a header name.
* `INVALID_HEADER_VALUE` — `value` contains a NUL, CR, or LF character.

Headers.delete(name: string): void [#headersdeletename-string-void]

Delete the header `name`.

**Parameters**

| Parameter | Type     | Default | Description      |
| --------- | -------- | ------- | ---------------- |
| `name`    | `string` | —       | The header name. |

Headers.entries(): IterableIterator<[name: string, value: string]> [#headersentries-iterableiteratorname-string-value-string]

Return an iterator over `[name, value]` pairs.

Headers.forEach(callback: (value: string, name: string, headers: Headers) => void, thisArg?: any): void [#headersforeachcallback-value-string-name-string-headers-headers--void-thisarg-any-void]

Call `callback` for each header with the arguments `(value, name, headers)`.

**Parameters**

| Parameter  | Type                                                      | Default | Description                                           |
| ---------- | --------------------------------------------------------- | ------- | ----------------------------------------------------- |
| `callback` | `(value: string, name: string, headers: Headers) => void` | —       | Called with `(value, name, headers)` for each header. |
| `thisArg?` | `any`                                                     | —       | The value of `this` inside `callback`.                |

Headers.get(name: string): string | null [#headersgetname-string-string--null]

Get the value of the header `name` as a comma-separated string, or `null` if it does not exist.

**Parameters**

| Parameter | Type     | Default | Description      |
| --------- | -------- | ------- | ---------------- |
| `name`    | `string` | —       | The header name. |

Headers.has(name: string): boolean [#headershasname-string-boolean]

Return whether the header `name` exists.

**Parameters**

| Parameter | Type     | Default | Description      |
| --------- | -------- | ------- | ---------------- |
| `name`    | `string` | —       | The header name. |

Headers.keys(): IterableIterator<string> [#headerskeys-iterableiteratorstring]

Return an iterator over header names.

Headers.set(name: string, value: string): void [#headerssetname-string-value-string-void]

Set the header `name` to `value`, replacing any existing values.

**Parameters**

| Parameter | Type     | Default | Description                                      |
| --------- | -------- | ------- | ------------------------------------------------ |
| `name`    | `string` | —       | The header name.                                 |
| `value`   | `string` | —       | The value to set, replacing any existing values. |

**Throws**

* `INVALID_HEADER_NAME` — `name` is empty or contains characters that are not valid in a header name.
* `INVALID_HEADER_VALUE` — `value` contains a NUL, CR, or LF character.

Headers.values(): IterableIterator<string> [#headersvalues-iterableiteratorstring]

Return an iterator over header values.

Request [#request]

Request.new Request(input: string | URL | Request, init?: RequestInit) [#requestnew-requestinput-string--url--request-init-requestinit]

Construct a new `Request` from `input`, which may be a URL string, a `URL`, or another `Request`.

**Parameters**

| Parameter | Type                           | Default | Description                                                   |
| --------- | ------------------------------ | ------- | ------------------------------------------------------------- |
| `input`   | `string` \| `URL` \| `Request` | —       | The URL string, `URL`, or `Request` to base the request on.   |
| `init?`   | `RequestInit`                  | —       | Request options, identical to the ones accepted by `fetch()`. |

**Throws**

* `INVALID_URL` — `input` is not a valid URL.
* `BODY_UNUSABLE` — `init.body` is a `ReadableStream` that is locked or has already been consumed.

Request.headers: Headers [#requestheaders-headers]

The request headers as a `Headers` object.

Request.method: HTTPMethod [#requestmethod-httpmethod]

The request method. Standard methods (`GET`, `POST`, `PUT`, `DELETE`, `HEAD`, `OPTIONS`) are uppercased automatically.

Request.RequestInit [#requestrequestinit]

```ts
interface RequestInit {
  body?: unknown
  method?: HTTPMethod
  headers?: Headers
  signal?: AbortSignal
  agent?: HTTPAgent
}
```

Request.signal: AbortSignal | null [#requestsignal-abortsignal--null]

The abort signal associated with the request, or `null`.

Request.url: string [#requesturl-string]

The request URL as a string.

Response [#response]

Response.new Response(body: unknown, init?: ResponseInit) [#responsenew-responsebody-unknown-init-responseinit]

Construct a new `Response` wrapping `body`.

**Parameters**

| Parameter | Type           | Default | Description                                                                                     |
| --------- | -------------- | ------- | ----------------------------------------------------------------------------------------------- |
| `body`    | `unknown`      | —       | The response body, or `null` (default `null`).                                                  |
| `init?`   | `ResponseInit` | —       | Options; `status` defaults to `200`, `statusText` to `''`, and `headers` to an empty `Headers`. |

**Throws**

* `BODY_UNUSABLE` — `body` is a `ReadableStream` that is locked or has already been consumed.

Response.headers: Headers [#responseheaders-headers]

The response headers as a `Headers` object.

Response.ok: boolean [#responseok-boolean]

Whether the status code is in the range 200-299.

Response.redirected: boolean [#responseredirected-boolean]

Whether the request was redirected to a different URL.

Response.Response.error(): Response [#responseresponseerror-response]

Response.Response.json(data: unknown, init?: ResponseInit): Response [#responseresponsejsondata-unknown-init-responseinit-response]

Consume the body and return a parsed JSON value.

**Parameters**

| Parameter | Type           | Default | Description |
| --------- | -------------- | ------- | ----------- |
| `data`    | `unknown`      | —       | —           |
| `init?`   | `ResponseInit` | —       | —           |

**Throws**

* `BODY_UNUSABLE` — the body has already been consumed.

Response.Response.redirect(url: string | URL, status?: HTTPStatusCode): Response [#responseresponseredirecturl-string--url-status-httpstatuscode-response]

**Parameters**

| Parameter | Type              | Default | Description |
| --------- | ----------------- | ------- | ----------- |
| `url`     | `string` \| `URL` | —       | —           |
| `status?` | `HTTPStatusCode`  | —       | —           |

Response.status: HTTPStatusCode [#responsestatus-httpstatuscode]

The HTTP status code of the response.

Response.statusText: HTTPStatusMessage [#responsestatustext-httpstatusmessage]

The HTTP status message of the response.

Response.type: ResponseType [#responsetype-responsetype]

Response.url: string | null [#responseurl-string--null]

The final response URL as a string, or `null` if no request has been made.

Functions [#functions]

fetch(input: string | URL | Request, init?: RequestInit): Promise<Response> [#fetchinput-string--url--request-init-requestinit-promiseresponse]

Perform an HTTP or HTTPS request. `input` may be a URL string, a `URL` object, or a `Request` object. `init` is an optional options object.

**Parameters**

| Parameter | Type                           | Default | Description                                                                                                                 |
| --------- | ------------------------------ | ------- | --------------------------------------------------------------------------------------------------------------------------- |
| `input`   | `string` \| `URL` \| `Request` | —       | The URL string, `URL`, or `Request` to fetch.                                                                               |
| `init?`   | `RequestInit`                  | —       | Request options; `body`, `signal`, and `agent` default to `null`, `method` to `'GET'`, and `headers` to an empty `Headers`. |

**Returns** `Promise<Response>` — A promise that resolves with the `Response` once the response headers arrive.

**Throws**

* `INVALID_URL` — `input` or a redirect `Location` is not a valid URL.
* `UNKNOWN_PROTOCOL` — the URL protocol is neither `http:` nor `https:`.
* `TOO_MANY_REDIRECTS` — more than 20 redirects were followed.
* `NETWORK_ERROR` — the underlying request failed or the connection was lost.

bare-fetch/global [#bare-fetchglobal]

Types [#types]

Fetch [#fetch]

```ts
type Fetch = typeof fetch
```

The type of the `fetch` function, used to type the global `fetch`.

bare-fetch/errors [#bare-fetcherrors]

Classes [#classes]

FetchError [#fetcherror]

```ts
class FetchError {
  code: string
}
```

An error produced by this module, carrying a `code` identifying the failure.

bare-fetch/body [#bare-fetchbody]

Body [#body]

arrayBuffer(): Promise<ArrayBuffer> [#arraybuffer-promisearraybuffer]

Consume the body and return an `ArrayBuffer`.

**Throws**

* `BODY_UNUSABLE` — the body has already been consumed.

body: ReadableStream [#body-readablestream]

The body as a `ReadableStream`, or `null`.

bodyUsed: boolean [#bodyused-boolean]

Whether the body stream has already been consumed.

buffer(): Promise<Buffer> [#buffer-promisebuffer]

Consume the body and return a `Buffer`.

**Throws**

* `BODY_UNUSABLE` — the body has already been consumed.

bytes(): Promise<Buffer> [#bytes-promisebuffer]

Consume the body and return a `Uint8Array`.

**Throws**

* `BODY_UNUSABLE` — the body has already been consumed.

formData(): Promise<FormData> [#formdata-promiseformdata]

Consume the body and return a `FormData` object. Supports `multipart/form-data` and `application/x-www-form-urlencoded` content types.

**Throws**

* `BODY_UNUSABLE` — the body has already been consumed.
* `INVALID_FORM_DATA` — the content type is not form data, or the multipart boundary parameter is missing.

json(): Promise<JSON> [#json-promisejson]

Consume the body and return a parsed JSON value.

**Throws**

* `BODY_UNUSABLE` — the body has already been consumed.

text(): Promise<string> [#text-promisestring]

Consume the body and return a UTF-8 string.

**Throws**

* `BODY_UNUSABLE` — the body has already been consumed.

bare-fetch/request [#bare-fetchrequest]

Request [#request-1]

Request.new Request(input: string | URL | Request, init?: RequestInit) [#requestnew-requestinput-string--url--request-init-requestinit-1]

Construct a new `Request` from `input`, which may be a URL string, a `URL`, or another `Request`.

**Parameters**

| Parameter | Type                           | Default | Description                                                   |
| --------- | ------------------------------ | ------- | ------------------------------------------------------------- |
| `input`   | `string` \| `URL` \| `Request` | —       | The URL string, `URL`, or `Request` to base the request on.   |
| `init?`   | `RequestInit`                  | —       | Request options, identical to the ones accepted by `fetch()`. |

**Throws**

* `INVALID_URL` — `input` is not a valid URL.
* `BODY_UNUSABLE` — `init.body` is a `ReadableStream` that is locked or has already been consumed.

Request.headers: Headers [#requestheaders-headers-1]

The request headers as a `Headers` object.

Request.method: HTTPMethod [#requestmethod-httpmethod-1]

The request method. Standard methods (`GET`, `POST`, `PUT`, `DELETE`, `HEAD`, `OPTIONS`) are uppercased automatically.

Request.signal: AbortSignal | null [#requestsignal-abortsignal--null-1]

The abort signal associated with the request, or `null`.

Request.url: string [#requesturl-string-1]

The request URL as a string.

Types [#types-1]

RequestInit [#requestinit]

```ts
interface RequestInit {
  body?: unknown
  method?: HTTPMethod
  headers?: Headers
  signal?: AbortSignal
  agent?: HTTPAgent
}
```

bare-fetch/response [#bare-fetchresponse]

Response [#response-1]

Response.new Response(body: unknown, init?: ResponseInit) [#responsenew-responsebody-unknown-init-responseinit-1]

Construct a new `Response` wrapping `body`.

**Parameters**

| Parameter | Type           | Default | Description                                                                                     |
| --------- | -------------- | ------- | ----------------------------------------------------------------------------------------------- |
| `body`    | `unknown`      | —       | The response body, or `null` (default `null`).                                                  |
| `init?`   | `ResponseInit` | —       | Options; `status` defaults to `200`, `statusText` to `''`, and `headers` to an empty `Headers`. |

**Throws**

* `BODY_UNUSABLE` — `body` is a `ReadableStream` that is locked or has already been consumed.

Response.headers: Headers [#responseheaders-headers-1]

The response headers as a `Headers` object.

Response.ok: boolean [#responseok-boolean-1]

Whether the status code is in the range 200-299.

Response.redirected: boolean [#responseredirected-boolean-1]

Whether the request was redirected to a different URL.

Response.Response.error(): Response [#responseresponseerror-response-1]

Response.Response.json(data: unknown, init?: ResponseInit): Response [#responseresponsejsondata-unknown-init-responseinit-response-1]

Consume the body and return a parsed JSON value.

**Parameters**

| Parameter | Type           | Default | Description |
| --------- | -------------- | ------- | ----------- |
| `data`    | `unknown`      | —       | —           |
| `init?`   | `ResponseInit` | —       | —           |

**Throws**

* `BODY_UNUSABLE` — the body has already been consumed.

Response.Response.redirect(url: string | URL, status?: HTTPStatusCode): Response [#responseresponseredirecturl-string--url-status-httpstatuscode-response-1]

**Parameters**

| Parameter | Type              | Default | Description |
| --------- | ----------------- | ------- | ----------- |
| `url`     | `string` \| `URL` | —       | —           |
| `status?` | `HTTPStatusCode`  | —       | —           |

Response.status: HTTPStatusCode [#responsestatus-httpstatuscode-1]

The HTTP status code of the response.

Response.statusText: HTTPStatusMessage [#responsestatustext-httpstatusmessage-1]

The HTTP status message of the response.

Response.type: ResponseType [#responsetype-responsetype-1]

Response.url: string | null [#responseurl-string--null-1]

The final response URL as a string, or `null` if no request has been made.

Types [#types-2]

ResponseInit [#responseinit]

```ts
interface ResponseInit {
  status?: HTTPStatusCode
  statusText?: HTTPStatusMessage
  headers?: Headers
}
```

bare-fetch/headers [#bare-fetchheaders]

Headers [#headers-1]

Headers.new Headers(init?: Record<string, string> | Iterable<[string, string]>) [#headersnew-headersinit-recordstring-string--iterablestring-string-1]

Construct a new `Headers` collection, optionally initialized from `init`.

**Parameters**

| Parameter | Type                                                   | Default | Description                                                                                              |
| --------- | ------------------------------------------------------ | ------- | -------------------------------------------------------------------------------------------------------- |
| `init?`   | `Record<string, string> \| Iterable<[string, string]>` | —       | A plain object of name–value pairs, an iterable of `[name, value]` pairs, or another `Headers` instance. |

Headers.append(name: string, value: string): void [#headersappendname-string-value-string-void-1]

Append a value to the header `name`. If the header already exists, the value is added to the existing list.

**Parameters**

| Parameter | Type     | Default | Description                        |
| --------- | -------- | ------- | ---------------------------------- |
| `name`    | `string` | —       | The header name.                   |
| `value`   | `string` | —       | The value to append to the header. |

**Throws**

* `INVALID_HEADER_NAME` — `name` is empty or contains characters that are not valid in a header name.
* `INVALID_HEADER_VALUE` — `value` contains a NUL, CR, or LF character.

Headers.delete(name: string): void [#headersdeletename-string-void-1]

Delete the header `name`.

**Parameters**

| Parameter | Type     | Default | Description      |
| --------- | -------- | ------- | ---------------- |
| `name`    | `string` | —       | The header name. |

Headers.entries(): IterableIterator<[name: string, value: string]> [#headersentries-iterableiteratorname-string-value-string-1]

Return an iterator over `[name, value]` pairs.

Headers.forEach(callback: (value: string, name: string, headers: Headers) => void, thisArg?: any): void [#headersforeachcallback-value-string-name-string-headers-headers--void-thisarg-any-void-1]

Call `callback` for each header with the arguments `(value, name, headers)`.

**Parameters**

| Parameter  | Type                                                      | Default | Description                                           |
| ---------- | --------------------------------------------------------- | ------- | ----------------------------------------------------- |
| `callback` | `(value: string, name: string, headers: Headers) => void` | —       | Called with `(value, name, headers)` for each header. |
| `thisArg?` | `any`                                                     | —       | The value of `this` inside `callback`.                |

Headers.get(name: string): string | null [#headersgetname-string-string--null-1]

Get the value of the header `name` as a comma-separated string, or `null` if it does not exist.

**Parameters**

| Parameter | Type     | Default | Description      |
| --------- | -------- | ------- | ---------------- |
| `name`    | `string` | —       | The header name. |

Headers.has(name: string): boolean [#headershasname-string-boolean-1]

Return whether the header `name` exists.

**Parameters**

| Parameter | Type     | Default | Description      |
| --------- | -------- | ------- | ---------------- |
| `name`    | `string` | —       | The header name. |

Headers.keys(): IterableIterator<string> [#headerskeys-iterableiteratorstring-1]

Return an iterator over header names.

Headers.set(name: string, value: string): void [#headerssetname-string-value-string-void-1]

Set the header `name` to `value`, replacing any existing values.

**Parameters**

| Parameter | Type     | Default | Description                                      |
| --------- | -------- | ------- | ------------------------------------------------ |
| `name`    | `string` | —       | The header name.                                 |
| `value`   | `string` | —       | The value to set, replacing any existing values. |

**Throws**

* `INVALID_HEADER_NAME` — `name` is empty or contains characters that are not valid in a header name.
* `INVALID_HEADER_VALUE` — `value` contains a NUL, CR, or LF character.

Headers.values(): IterableIterator<string> [#headersvalues-iterableiteratorstring-1]

Return an iterator over header values.

See also [#see-also]

* Builds on `bare-form-data`, `bare-http1`, `bare-https`, `bare-mime`, `bare-performance`, `bare-stream`, `bare-url`, and `bare-zlib`.
* The `fetch.Request`, `fetch.Response`, and `fetch.Headers` constructors are also attached to the function.
* It's pure JavaScript, built on [`bare-http1`](/reference/modules/bare-modules) and `bare-https`.
* [Bare modules](/reference/modules/bare-modules) — the full `bare-*` catalog.
* [Bare runtime API](/reference/bare/runtime) — the runtime these modules extend.


# bare-file-logger



<mark style={{ backgroundColor: '#7dde9a', padding: '2px 8px', borderRadius: '4px', fontSize: '0.85em', fontWeight: 500 }}>
  stable
</mark>

[`bare-file-logger`](https://github.com/holepunchto/bare-file-logger) — File system logger for Bare.

```sh
npm i bare-file-logger
```

Usage [#usage]

```js
const FileLog = require('bare-file-logger')

const log = new FileLog('my-logs.txt')

log.info('Hello %s', 'world!')
```

API [#api]

FileLog [#filelog]

new FileLog(path: string, options?: FileLogOptions) [#new-filelogpath-string-options-filelogoptions]

Construct a new `FileLog` that writes to the file at `path`.

**Parameters**

| Parameter  | Type                                | Default | Description                                                                   |
| ---------- | ----------------------------------- | ------- | ----------------------------------------------------------------------------- |
| `path`     | `string`                            | —       | Path to the log file; opened for appending, and created if it does not exist. |
| `options?` | [`FileLogOptions`](#filelogoptions) | —       | Options controlling log rotation; see [`FileLogOptions`](#filelogoptions).    |

append(label: string, ...data: unknown[]): void [#appendlabel-string-data-unknown-void]

Writes a single log line: the padded `label`, an ISO-8601 timestamp, and the formatted `data`, terminated by a newline.

**Parameters**

| Parameter | Type        | Default | Description                                                                                                                                 |
| --------- | ----------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `label`   | `string`    | —       | A short severity label, right-padded to five characters (for example `info`, `error`), prefixed to the line ahead of an ISO-8601 timestamp. |
| `data`    | `unknown[]` | —       | Values to format into the log message, using the same formatting as `console.log`.                                                          |

close(): void [#close-void]

Closes the underlying file descriptor and stops the rotation timer. Safe to call more than once.

Types [#types]

FileLogOptions [#filelogoptions]

```ts
interface FileLogOptions {
  maxSize?: number
  rotate?: (path: string) => string
  rotateInterval?: number
}
```

FileLogEvents [#filelogevents]

```ts
interface FileLogEvents {
  rotate: [path: string, archived: string | null]
}
```

See also [#see-also]

* Builds on `bare-fs` and `bare-logger`.
* [Bare modules](/reference/modules/bare-modules) — the full `bare-*` catalog.
* [Bare runtime API](/reference/bare/runtime) — the runtime these modules extend.


# bare-form-data



<mark style={{ backgroundColor: '#7dde9a', padding: '2px 8px', borderRadius: '4px', fontSize: '0.85em', fontWeight: 500 }}>
  stable
</mark>

[`bare-form-data`](https://github.com/holepunchto/bare-form-data) provides the WHATWG `FormData`, `Blob`, and `File` APIs for [Bare](/reference/bare/runtime), plus a `toBlob` helper to serialize a form into a multipart body. It's pure JavaScript and pairs with [`bare-fetch`](/reference/bare/modules/bare-fetch).

```sh
npm i bare-form-data
```

Usage [#usage]

```js
const { FormData, Blob, File, toBlob } = require('bare-form-data')

const form = new FormData()
form.append('title', 'Hello form')
form.append('attachment', new File(['My attachment'], 'attachment.txt', { type: 'text/plain' }))

const blob = toBlob(form)
```

Global registration [#global-registration]

To register `FormData`, `Blob`, and `File` as globals across the entire application:

```js
require('bare-form-data/global')
```

API [#api]

FormData [#formdata]

const formData = new FormData() [#const-formdata--new-formdata]

A multipart form: `append(name, value[, filename])`, `set(name, value[, filename])`, `delete(name)`, `get(name)`, `getAll(name)`, `has(name)`.

const result = isFormData(value) [#const-result--isformdatavalue]

A module-level export. Returns `true` if `value` is a `FormData` instance.

const blob = toBlob(formData[, mimeType]) [#const-blob--toblobformdata-mimetype]

A module-level export. Serializes `formData` to a `Blob`. `mimeType` defaults to `'multipart/form-data'`.

Blob [#blob]

const blob = new Blob(parts[, options]) [#const-blob--new-blobparts-options]

An immutable binary object: `size`, `type`, `stream()`, and the async readers `buffer()`, `bytes()`, `arrayBuffer()`, `text()`, plus `Blob.isBlob(value)`.

File [#file]

const file = new File(parts, name[, options]) [#const-file--new-fileparts-name-options]

A `Blob` with a `name` and `lastModified`, plus `File.isFile(value)`.

Related modules [#related-modules]

Builds on [`bare-buffer`](/reference/modules/bare-modules) and [`bare-stream`](/reference/bare/modules/bare-stream) (see [Bare modules](/reference/modules/bare-modules)).

See also [#see-also]

* [`bare-fetch`](/reference/bare/modules/bare-fetch)—send a `FormData`/`Blob` as a request body.
* [Bare modules](/reference/modules/bare-modules)—the full `bare-*` catalog.
* [Bare runtime API](/reference/bare/runtime)—the runtime this runs on.


# bare-format



<mark style={{ backgroundColor: '#7dde9a', padding: '2px 8px', borderRadius: '4px', fontSize: '0.85em', fontWeight: 500 }}>
  stable
</mark>

[`bare-format`](https://github.com/holepunchto/bare-format) — String formatting for JavaScript.

```sh
npm i bare-format
```

Usage [#usage]

```js
const format = require('bare-format')

format('Hello %s', 'world!')
// Hello world!
```

API [#api]

Functions [#functions]

format(...args: unknown[]): string [#formatargs-unknown-string]

Formats `args` into a string, printf-style. If the first argument is a string containing `%s`, `%d`, `%i`, `%f`, `%j`, `%o`, `%O`, or `%c` placeholders, each is substituted with the corresponding argument; any remaining arguments are appended, space-separated, using `bare-inspect` for non-string values.

**Parameters**

| Parameter | Type        | Default | Description                                                              |
| --------- | ----------- | ------- | ------------------------------------------------------------------------ |
| `args`    | `unknown[]` | —       | An optional printf-style format string followed by the values to format. |

**Returns** `string` — The formatted string.

format.format(...args: unknown[]): string [#formatformatargs-unknown-string]

**Parameters**

| Parameter | Type        | Default | Description |
| --------- | ----------- | ------- | ----------- |
| `args`    | `unknown[]` | —       | —           |

format.formatWithOptions(opts: {}, ...args: unknown[]): string [#formatformatwithoptionsopts--args-unknown-string]

**Parameters**

| Parameter | Type        | Default | Description |
| --------- | ----------- | ------- | ----------- |
| `opts`    | `{}`        | —       | —           |
| `args`    | `unknown[]` | —       | —           |

See also [#see-also]

* Builds on `bare-inspect`.
* [Bare modules](/reference/modules/bare-modules) — the full `bare-*` catalog.
* [Bare runtime API](/reference/bare/runtime) — the runtime these modules extend.


# bare-fs



<mark style={{ backgroundColor: '#7dde9a', padding: '2px 8px', borderRadius: '4px', fontSize: '0.85em', fontWeight: 500 }}>
  stable
</mark>

[`bare-fs`](https://github.com/holepunchto/bare-fs) — Native file system operations for Bare. It is a native addon and requires Bare `>=1.28.0`.

Mirrors the Node.js [`fs`](https://nodejs.org/api/fs.html) module.

```sh
npm i bare-fs
```

Usage [#usage]

```js
const fs = require('bare-fs')

const fd = await fs.open('hello.txt')

const buffer = Buffer.alloc(1024)

try {
  const length = await fs.read(fd, buffer)

  console.log('Read', length, 'bytes')
} finally {
  await fs.close(fd)
}
```

API [#api]

Opening, reading, and writing [#opening-reading-and-writing]

open(filepath: Path, flags?: Flag | number, mode?: string | number): Promise<number> [#openfilepath-path-flags-flag--number-mode-string--number-promisenumber]

Open a file, returning a file descriptor. `flags` defaults to `'r'` and `mode` defaults to `0o666`. `flags` may be a string such as `'r'`, `'w'`, `'a'`, `'r+'`, etc., or a numeric combination of `fs.constants` flags.

Overloads:

```ts
open(filepath: Path, flags?: Flag | number, mode?: string | number): Promise<number>
open(filepath: Path, flags: Flag | number, mode: string | number, cb: Callback<[fd: number]>): void
open(filepath: Path, flags: Flag | number, cb: Callback<[fd: number]>): void
open(filepath: Path, cb: Callback<[fd: number]>): void
```

Synchronous form: `openSync(filepath: Path, flags?: Flag | number, mode?: string | number): number`

**Parameters**

| Parameter  | Type                        | Default | Description                                                                                         |
| ---------- | --------------------------- | ------- | --------------------------------------------------------------------------------------------------- |
| `filepath` | [`Path`](#path)             | —       | —                                                                                                   |
| `flags?`   | [`Flag`](#flag) \| `number` | —       | Defaults to `'r'`. Selects read/write mode and whether the file is created, truncated, or appended. |
| `mode?`    | `string` \| `number`        | —       | Defaults to `0o666`. Applied only when `flags` creates a new file.                                  |

**Returns** `Promise<number>` — The file descriptor for the newly opened file.

**Throws**

* `ENOENT` — `filepath` does not exist and `flags` does not include a creating variant (for example the default `'r'`).
* `EEXIST` — `flags` is an exclusive variant (`'wx'`, `'ax'`, `'xw'`, `'xa'`, etc.) and `filepath` already exists.

close(fd: number): Promise<void> [#closefd-number-promisevoid]

Close a file descriptor.

Overloads:

```ts
close(fd: number): Promise<void>
close(fd: number, cb: Callback): void
```

Synchronous form: `closeSync(fd: number): void`

**Parameters**

| Parameter | Type     | Default | Description                                               |
| --------- | -------- | ------- | --------------------------------------------------------- |
| `fd`      | `number` | —       | The file descriptor to close, as returned by `fs.open()`. |

read [#read]

```ts
read(fd: number, buffer: Buffer | ArrayBufferView, offset?: number, len?: number, pos?: number): Promise<number>
```

Read from a file descriptor into `buffer`. `offset` defaults to `0`, `len` defaults to `buffer.byteLength - offset`, and `pos` defaults to `-1` (current position). Returns the number of bytes read.

Synchronous form: `readSync(fd: number, buffer: Buffer | ArrayBufferView, offset?: number, len?: number, pos?: number): number`

**Parameters**

| Parameter | Type                          | Default | Description                                                                                                          |
| --------- | ----------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------- |
| `fd`      | `number`                      | —       | The file descriptor to read from, as returned by `fs.open()`.                                                        |
| `buffer`  | `Buffer` \| `ArrayBufferView` | —       | —                                                                                                                    |
| `offset?` | `number`                      | —       | The offset within `buffer` to start writing to. Defaults to `0`.                                                     |
| `len?`    | `number`                      | —       | The number of bytes to read. Defaults to `buffer.byteLength - offset`.                                               |
| `pos?`    | `number`                      | —       | The position in the file to read from. Defaults to `-1`, which reads from the current file position and advances it. |

**Returns** `Promise<number>` — The number of bytes actually read, which may be less than `len` (`0` at end of file).

readv(fd: number, buffers: ArrayBufferView[], position?: number): Promise<number> [#readvfd-number-buffers-arraybufferview-position-number-promisenumber]

Read from a file descriptor into an array of `buffers`. `pos` defaults to `-1`.

Overloads:

```ts
readv(fd: number, buffers: ArrayBufferView[], position?: number): Promise<number>
readv(fd: number, buffers: ArrayBufferView[], position: number, cb: Callback<[len: number]>): void
readv(fd: number, buffers: ArrayBufferView[], cb: Callback<[len: number]>): void
```

Synchronous form: `readvSync(fd: number, buffers: ArrayBufferView[], position?: number): number`

**Parameters**

| Parameter   | Type                | Default | Description |
| ----------- | ------------------- | ------- | ----------- |
| `fd`        | `number`            | —       | —           |
| `buffers`   | `ArrayBufferView[]` | —       | —           |
| `position?` | `number`            | —       | —           |

**Returns** `Promise<number>` — The number of bytes actually read across all buffers.

write [#write]

```ts
write(fd: number, data: Buffer | ArrayBufferView, offset?: number, len?: number, pos?: number): Promise<number>
```

Write `data` to a file descriptor. When `data` is a string, the signature is `fs.write(fd, data[, pos[, encoding]])` where `encoding` defaults to `'utf8'`. Returns the number of bytes written.

Synchronous form: `writeSync(fd: number, data: Buffer | ArrayBufferView, offset?: number, len?: number, pos?: number): number`

**Parameters**

| Parameter | Type                          | Default | Description                                                                                                            |
| --------- | ----------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------- |
| `fd`      | `number`                      | —       | The file descriptor to write to, as returned by `fs.open()`.                                                           |
| `data`    | `Buffer` \| `ArrayBufferView` | —       | The bytes to write. May also be a string, in which case the signature becomes `fs.write(fd, data[, pos[, encoding]])`. |
| `offset?` | `number`                      | —       | The offset within `data` to start writing from. Defaults to `0`.                                                       |
| `len?`    | `number`                      | —       | The number of bytes to write. Defaults to `data.byteLength - offset`.                                                  |
| `pos?`    | `number`                      | —       | The position in the file to write to. Defaults to `-1`, which writes at the current file position and advances it.     |

**Returns** `Promise<number>` — The number of bytes actually written, which may be less than `data`'s length.

writev(fd: number, buffers: ArrayBufferView[], pos?: number): Promise<number> [#writevfd-number-buffers-arraybufferview-pos-number-promisenumber]

Write an array of `buffers` to a file descriptor. `pos` defaults to `-1`.

Overloads:

```ts
writev(fd: number, buffers: ArrayBufferView[], pos?: number): Promise<number>
writev(fd: number, buffers: ArrayBufferView[], pos: number, cb: Callback<[len: number]>): void
writev(fd: number, buffers: ArrayBufferView[], cb: Callback<[len: number]>): void
```

Synchronous form: `writevSync(fd: number, buffers: ArrayBufferView[], pos?: number): number`

**Parameters**

| Parameter | Type                | Default | Description |
| --------- | ------------------- | ------- | ----------- |
| `fd`      | `number`            | —       | —           |
| `buffers` | `ArrayBufferView[]` | —       | —           |
| `pos?`    | `number`            | —       | —           |

**Returns** `Promise<number>` — The number of bytes actually written across all buffers.

fsync(fd: number): Promise<void> [#fsyncfd-number-promisevoid]

Flush all modified in-core data of the file referred by its file descriptor to the disk device.

Overloads:

```ts
fsync(fd: number): Promise<void>
fsync(fd: number, cb: Callback): void
```

Synchronous form: `fsyncSync(fd: number): void`

**Parameters**

| Parameter | Type     | Default | Description |
| --------- | -------- | ------- | ----------- |
| `fd`      | `number` | —       | —           |

fdatasync(fd: number): Promise<void> [#fdatasyncfd-number-promisevoid]

Similar to `fsync`, but does not flush modified metadata unless necessary.

Overloads:

```ts
fdatasync(fd: number): Promise<void>
fdatasync(fd: number, cb: Callback): void
```

Synchronous form: `fdatasyncSync(fd: number): void`

**Parameters**

| Parameter | Type     | Default | Description |
| --------- | -------- | ------- | ----------- |
| `fd`      | `number` | —       | —           |

Whole-file helpers [#whole-file-helpers]

readFile(filepath: Path, opts: ReadFileOptions & { encoding: BufferEncoding }): Promise<string> [#readfilefilepath-path-opts-readfileoptions---encoding-bufferencoding--promisestring]

Read the entire contents of a file. Returns a `Buffer` by default, or a string if an `encoding` is specified.

Overloads:

```ts
readFile(filepath: Path, opts: ReadFileOptions & { encoding: BufferEncoding }): Promise<string>
readFile(filepath: Path, opts: ReadFileOptions & { encoding?: 'buffer' }): Promise<Buffer>
readFile(filepath: Path, opts: ReadFileOptions): Promise<string | Buffer>
readFile(filepath: Path, encoding: BufferEncoding): Promise<string>
readFile(filepath: Path, encoding: 'buffer'): Promise<Buffer>
readFile(filepath: Path, encoding?: BufferEncoding | 'buffer'): Promise<string | Buffer>
readFile(filepath: Path): Promise<Buffer>
readFile(filepath: Path, opts: ReadFileOptions & { encoding: BufferEncoding }, cb: Callback<[buffer?: string]>): void
readFile(filepath: Path, opts: ReadFileOptions & { encoding?: 'buffer' }, cb: Callback<[buffer?: Buffer]>): void
readFile(filepath: Path, opts: ReadFileOptions, cb: Callback<[buffer?: string | Buffer]>): void
readFile(filepath: Path, encoding: BufferEncoding, cb: Callback<[buffer?: string]>): void
readFile(filepath: Path, encoding: 'buffer', cb: Callback<[buffer?: Buffer]>): void
readFile(filepath: Path, encoding: BufferEncoding | 'buffer', cb: Callback<[buffer?: string | Buffer]>): void
readFile(filepath: Path, cb: Callback<[buffer?: Buffer]>): void
```

Synchronous form: `readFileSync(filepath: Path, opts: ReadFileOptions & { encoding: BufferEncoding }): string`

**Parameters**

| Parameter  | Type                                             | Default | Description                                                                                              |
| ---------- | ------------------------------------------------ | ------- | -------------------------------------------------------------------------------------------------------- |
| `filepath` | [`Path`](#path)                                  | —       | —                                                                                                        |
| `opts`     | `ReadFileOptions & { encoding: BufferEncoding }` | —       | `encoding` defaults to `'buffer'` (returning a `Buffer` rather than a string); `flag` defaults to `'r'`. |

writeFile [#writefile]

```ts
writeFile(filepath: Path, data: string | Buffer | ArrayBufferView, opts?: WriteFileOptions): Promise<void>
```

Write `data` to a file, replacing it if it already exists.

Synchronous form: `writeFileSync(filepath: Path, data: string | Buffer | ArrayBufferView, opts?: WriteFileOptions): void`

**Parameters**

| Parameter  | Type                                      | Default | Description                                                                          |
| ---------- | ----------------------------------------- | ------- | ------------------------------------------------------------------------------------ |
| `filepath` | [`Path`](#path)                           | —       | —                                                                                    |
| `data`     | `string` \| `Buffer` \| `ArrayBufferView` | —       | —                                                                                    |
| `opts?`    | [`WriteFileOptions`](#writefileoptions)   | —       | `flag` defaults to `'w'` (truncating any existing file); `mode` defaults to `0o666`. |

appendFile [#appendfile]

```ts
appendFile(filepath: Path, data: string | Buffer | ArrayBufferView, opts?: AppendFileOptions): Promise<void>
```

Append `data` to a file, creating it if it does not exist. Accepts the same options as `fs.writeFile()` but defaults to the `'a'` flag.

Synchronous form: `appendFileSync(filepath: Path, data: string | Buffer | ArrayBufferView, opts?: AppendFileOptions): void`

**Parameters**

| Parameter  | Type                                      | Default | Description |
| ---------- | ----------------------------------------- | ------- | ----------- |
| `filepath` | [`Path`](#path)                           | —       | —           |
| `data`     | `string` \| `Buffer` \| `ArrayBufferView` | —       | —           |
| `opts?`    | [`AppendFileOptions`](#appendfileoptions) | —       | —           |

access(filepath: Path, mode?: number): Promise<void> [#accessfilepath-path-mode-number-promisevoid]

Check whether the file at `filepath` is accessible. `mode` defaults to `fs.constants.F_OK`.

Overloads:

```ts
access(filepath: Path, mode?: number): Promise<void>
access(filepath: Path, mode: number, cb: Callback): void
access(filepath: Path, cb: Callback): void
```

Synchronous form: `accessSync(filepath: Path, mode?: number): void`

**Parameters**

| Parameter  | Type            | Default | Description                                                                                       |
| ---------- | --------------- | ------- | ------------------------------------------------------------------------------------------------- |
| `filepath` | [`Path`](#path) | —       | —                                                                                                 |
| `mode?`    | `number`        | —       | Defaults to `fs.constants.F_OK` (existence only); may also combine `R_OK`, `W_OK`, and/or `X_OK`. |

exists(filepath: Path): Promise<boolean> [#existsfilepath-path-promiseboolean]

Check whether a file exists at `filepath`. Returns `true` if the file is accessible, `false` otherwise.

Overloads:

```ts
exists(filepath: Path): Promise<boolean>
exists(filepath: Path, cb: (exists: boolean) => void): void
```

Synchronous form: `existsSync(filepath: Path): boolean`

**Parameters**

| Parameter  | Type            | Default | Description |
| ---------- | --------------- | ------- | ----------- |
| `filepath` | [`Path`](#path) | —       | —           |

Metadata and size [#metadata-and-size]

stat(filepath: Path): Promise<Stats> [#statfilepath-path-promisestats]

Get the status of a file. Returns a `Stats` object.

Overloads:

```ts
stat(filepath: Path): Promise<Stats>
stat(filepath: Path, cb: Callback<[stats: Stats | null]>): void
```

Synchronous form: `statSync(filepath: Path): Stats`

**Parameters**

| Parameter  | Type            | Default | Description |
| ---------- | --------------- | ------- | ----------- |
| `filepath` | [`Path`](#path) | —       | —           |

lstat(filepath: Path): Promise<Stats> [#lstatfilepath-path-promisestats]

Like `fs.stat()`, but if `filepath` is a symbolic link, the link itself is statted, not the file it refers to.

Overloads:

```ts
lstat(filepath: Path): Promise<Stats>
lstat(filepath: Path, cb: Callback<[stats: Stats | null]>): void
```

Synchronous form: `lstatSync(filepath: Path): Stats`

**Parameters**

| Parameter  | Type            | Default | Description |
| ---------- | --------------- | ------- | ----------- |
| `filepath` | [`Path`](#path) | —       | —           |

fstat(fd: number): Promise<Stats> [#fstatfd-number-promisestats]

Get the status of a file by its file descriptor. Returns a `Stats` object.

Overloads:

```ts
fstat(fd: number): Promise<Stats>
fstat(fd: number, cb: Callback<[stats: Stats | null]>): void
```

Synchronous form: `fstatSync(fd: number): Stats`

**Parameters**

| Parameter | Type     | Default | Description |
| --------- | -------- | ------- | ----------- |
| `fd`      | `number` | —       | —           |

statfs(filepath: Path): Promise<StatFs> [#statfsfilepath-path-promisestatfs]

Get filesystem statistics. Returns a `StatFs` object.

Overloads:

```ts
statfs(filepath: Path): Promise<StatFs>
statfs(filepath: Path, cb: Callback<[stats: StatFs | null]>): void
```

Synchronous form: `statfsSync(filepath: Path): StatFs`

**Parameters**

| Parameter  | Type            | Default | Description |
| ---------- | --------------- | ------- | ----------- |
| `filepath` | [`Path`](#path) | —       | —           |

truncate(filepath: Path, len?: number): Promise<void> [#truncatefilepath-path-len-number-promisevoid]

Truncate the file at `filename` to `len` bytes. `len` defaults to `0`.

Overloads:

```ts
truncate(filepath: Path, len?: number): Promise<void>
truncate(filepath: Path, len: number, cb: Callback): void
truncate(filepath: Path, cb: Callback): void
```

Synchronous form: `truncateSync(filepath: Path, len?: number): void`

**Parameters**

| Parameter  | Type            | Default | Description |
| ---------- | --------------- | ------- | ----------- |
| `filepath` | [`Path`](#path) | —       | —           |
| `len?`     | `number`        | —       | —           |

ftruncate(fd: number, len?: number): Promise<void> [#ftruncatefd-number-len-number-promisevoid]

Truncate a file to `len` bytes. `len` defaults to `0`.

Overloads:

```ts
ftruncate(fd: number, len?: number): Promise<void>
ftruncate(fd: number, len: number, cb: Callback): void
ftruncate(fd: number, cb: Callback): void
```

Synchronous form: `ftruncateSync(fd: number, len?: number): void`

**Parameters**

| Parameter | Type     | Default | Description |
| --------- | -------- | ------- | ----------- |
| `fd`      | `number` | —       | —           |
| `len?`    | `number` | —       | —           |

Permissions, ownership, and times [#permissions-ownership-and-times]

chmod(filepath: Path, mode: string | number): Promise<void> [#chmodfilepath-path-mode-string--number-promisevoid]

Change the permissions of a file. `mode` may be a numeric mode or a string that will be parsed as octal.

Overloads:

```ts
chmod(filepath: Path, mode: string | number): Promise<void>
chmod(filepath: Path, mode: string | number, cb: Callback): void
```

Synchronous form: `chmodSync(filepath: Path, mode: string | number): void`

**Parameters**

| Parameter  | Type                 | Default | Description |
| ---------- | -------------------- | ------- | ----------- |
| `filepath` | [`Path`](#path)      | —       | —           |
| `mode`     | `string` \| `number` | —       | —           |

fchmod(fd: number, mode: string | number): Promise<void> [#fchmodfd-number-mode-string--number-promisevoid]

Change the permissions of a file by its file descriptor.

Overloads:

```ts
fchmod(fd: number, mode: string | number): Promise<void>
fchmod(fd: number, mode: string | number, cb: Callback): void
```

Synchronous form: `fchmodSync(fd: number, mode: string | number): void`

**Parameters**

| Parameter | Type                 | Default | Description |
| --------- | -------------------- | ------- | ----------- |
| `fd`      | `number`             | —       | —           |
| `mode`    | `string` \| `number` | —       | —           |

chown(filepath: Path, uid: number, gid: number): Promise<void> [#chownfilepath-path-uid-number-gid-number-promisevoid]

Change the owner and group of a file.

Overloads:

```ts
chown(filepath: Path, uid: number, gid: number): Promise<void>
chown(filepath: Path, uid: number, gid: number, cb: Callback): void
```

Synchronous form: `chownSync(filepath: Path, uid: number, gid: number): void`

**Parameters**

| Parameter  | Type            | Default | Description |
| ---------- | --------------- | ------- | ----------- |
| `filepath` | [`Path`](#path) | —       | —           |
| `uid`      | `number`        | —       | —           |
| `gid`      | `number`        | —       | —           |

fchown(fd: number, uid: number, gid: number): Promise<void> [#fchownfd-number-uid-number-gid-number-promisevoid]

Change the owner and group of a file by its file descriptor.

Overloads:

```ts
fchown(fd: number, uid: number, gid: number): Promise<void>
fchown(fd: number, uid: number, gid: number, cb: Callback): void
```

Synchronous form: `fchownSync(fd: number, uid: number, gid: number): void`

**Parameters**

| Parameter | Type     | Default | Description |
| --------- | -------- | ------- | ----------- |
| `fd`      | `number` | —       | —           |
| `uid`     | `number` | —       | —           |
| `gid`     | `number` | —       | —           |

lchown(filepath: Path, uid: number, gid: number): Promise<void> [#lchownfilepath-path-uid-number-gid-number-promisevoid]

Change the owner and group of a file, but if `filepath` is a symbolic link, the changes are applied only to the link, not the file it refers to.

Overloads:

```ts
lchown(filepath: Path, uid: number, gid: number): Promise<void>
lchown(filepath: Path, uid: number, gid: number, cb: Callback): void
```

Synchronous form: `lchownSync(filepath: Path, uid: number, gid: number): void`

**Parameters**

| Parameter  | Type            | Default | Description |
| ---------- | --------------- | ------- | ----------- |
| `filepath` | [`Path`](#path) | —       | —           |
| `uid`      | `number`        | —       | —           |
| `gid`      | `number`        | —       | —           |

utimes(filepath: Path, atime: number | Date, mtime: number | Date): Promise<void> [#utimesfilepath-path-atime-number--date-mtime-number--date-promisevoid]

Change the access and modification times of a file. Times may be numbers (seconds since epoch) or `Date` objects.

Overloads:

```ts
utimes(filepath: Path, atime: number | Date, mtime: number | Date): Promise<void>
utimes(filepath: Path, atime: number | Date, mtime: number | Date, cb: Callback): void
```

Synchronous form: `utimesSync(filepath: Path, atime: number | Date, mtime: number | Date): void`

**Parameters**

| Parameter  | Type               | Default | Description |
| ---------- | ------------------ | ------- | ----------- |
| `filepath` | [`Path`](#path)    | —       | —           |
| `atime`    | `number` \| `Date` | —       | —           |
| `mtime`    | `number` \| `Date` | —       | —           |

lutimes(filepath: Path, atime: number | Date, mtime: number | Date): Promise<void> [#lutimesfilepath-path-atime-number--date-mtime-number--date-promisevoid]

Like `fs.utimes()`, but if `filepath` is a symbolic link, the timestamps of the link is changed, not the file it refers to.

Overloads:

```ts
lutimes(filepath: Path, atime: number | Date, mtime: number | Date): Promise<void>
lutimes(filepath: Path, atime: number | Date, mtime: number | Date, cb: Callback): void
```

Synchronous form: `lutimesSync(filepath: Path, atime: number | Date, mtime: number | Date): void`

**Parameters**

| Parameter  | Type               | Default | Description |
| ---------- | ------------------ | ------- | ----------- |
| `filepath` | [`Path`](#path)    | —       | —           |
| `atime`    | `number` \| `Date` | —       | —           |
| `mtime`    | `number` \| `Date` | —       | —           |

futimes(fd: number, atime: number | Date, mtime: number | Date): Promise<void> [#futimesfd-number-atime-number--date-mtime-number--date-promisevoid]

Change the access and modification times of a file by its file descriptor. Times may be numbers (seconds since epoch) or `Date` objects.

Overloads:

```ts
futimes(fd: number, atime: number | Date, mtime: number | Date): Promise<void>
futimes(fd: number, atime: number | Date, mtime: number | Date, cb: Callback): void
```

Synchronous form: `futimesSync(fd: number, atime: number | Date, mtime: number | Date): void`

**Parameters**

| Parameter | Type               | Default | Description |
| --------- | ------------------ | ------- | ----------- |
| `fd`      | `number`           | —       | —           |
| `atime`   | `number` \| `Date` | —       | —           |
| `mtime`   | `number` \| `Date` | —       | —           |

Directories [#directories]

mkdir(filepath: Path, opts?: MkdirOptions): Promise<void> [#mkdirfilepath-path-opts-mkdiroptions-promisevoid]

Create a directory at `filepath`.

Overloads:

```ts
mkdir(filepath: Path, opts?: MkdirOptions): Promise<void>
mkdir(filepath: Path, mode: number): Promise<void>
mkdir(filepath: Path, opts: MkdirOptions, cb: Callback): void
mkdir(filepath: Path, mode: number, cb: Callback): void
mkdir(filepath: Path, cb: Callback): void
```

Synchronous form: `mkdirSync(filepath: Path, opts?: MkdirOptions): void`

**Parameters**

| Parameter  | Type                            | Default | Description                                                                                                                                            |
| ---------- | ------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `filepath` | [`Path`](#path)                 | —       | —                                                                                                                                                      |
| `opts?`    | [`MkdirOptions`](#mkdiroptions) | —       | `mode` defaults to `0o777`. `recursive`, if `true`, creates missing parent directories and does not error if `filepath` already exists as a directory. |

**Throws**

* `ENOENT` — a parent directory in `filepath` does not exist and `opts.recursive` is not set.
* `EEXIST` — `filepath` already exists; when `opts.recursive` is set this is only thrown if the existing path is not itself a directory.

mkdtemp(prefix: Path): Promise<string> [#mkdtempprefix-path-promisestring]

Create a unique temporary directory.

Overloads:

```ts
mkdtemp(prefix: Path): Promise<string>
mkdtemp(prefix: Path, cb: Callback<[path: string | null]>): void
```

Synchronous form: `mkdtempSync(prefix: Path): string`

**Parameters**

| Parameter | Type            | Default | Description                                                                                                           |
| --------- | --------------- | ------- | --------------------------------------------------------------------------------------------------------------------- |
| `prefix`  | [`Path`](#path) | —       | The literal suffix `'XXXXXX'` is appended to `prefix` and replaced with random characters to form the directory name. |

**Returns** `Promise<string>` — The path of the newly created directory, including its randomly generated suffix.

rmdir(filepath: Path): Promise<void> [#rmdirfilepath-path-promisevoid]

Remove an empty directory.

Overloads:

```ts
rmdir(filepath: Path): Promise<void>
rmdir(filepath: Path, cb: Callback): void
```

Synchronous form: `rmdirSync(filepath: Path): void`

**Parameters**

| Parameter  | Type            | Default | Description |
| ---------- | --------------- | ------- | ----------- |
| `filepath` | [`Path`](#path) | —       | —           |

**Throws**

* `ENOTEMPTY` — the directory is not empty.

readdir [#readdir]

```ts
readdir(filepath: Path, opts: ReaddirOptions & { encoding?: BufferEncoding }): Promise<Dirent<string>[] | string[]>
```

Read the contents of a directory. Returns an array of filenames or, if `withFileTypes` is `true`, an array of `Dirent` objects.

Synchronous form: `readdirSync(filepath: Path, opts: ReaddirOptions & { encoding?: BufferEncoding }): Dirent<string>[] | string[]`

**Parameters**

| Parameter  | Type                                             | Default | Description                                                                             |
| ---------- | ------------------------------------------------ | ------- | --------------------------------------------------------------------------------------- |
| `filepath` | [`Path`](#path)                                  | —       | —                                                                                       |
| `opts`     | `ReaddirOptions & { encoding?: BufferEncoding }` | —       | `withFileTypes`, if `true`, returns `Dirent` objects instead of plain filename strings. |

opendir [#opendir]

```ts
opendir(filepath: Path, opts: OpendirOptions & { encoding?: BufferEncoding }): Promise<Dir<string>>
```

Open a directory for iteration. Returns a `Dir` object.

Synchronous form: `opendirSync(filepath: Path, opts: OpendirOptions & { encoding?: BufferEncoding }): Dir<string>`

**Parameters**

| Parameter  | Type                                             | Default | Description |
| ---------- | ------------------------------------------------ | ------- | ----------- |
| `filepath` | [`Path`](#path)                                  | —       | —           |
| `opts`     | `OpendirOptions & { encoding?: BufferEncoding }` | —       | —           |

Links, moving, copying, and removing [#links-moving-copying-and-removing]

link(src: Path, dst: Path): Promise<void> [#linksrc-path-dst-path-promisevoid]

Creates a new link (also known as a hard link) to an existing file.

Overloads:

```ts
link(src: Path, dst: Path): Promise<void>
link(src: Path, dst: Path, cb: Callback): void
```

Synchronous form: `linkSync(src: Path, dst: Path): void`

**Parameters**

| Parameter | Type            | Default | Description |
| --------- | --------------- | ------- | ----------- |
| `src`     | [`Path`](#path) | —       | —           |
| `dst`     | [`Path`](#path) | —       | —           |

symlink(target: Path, filepath: Path, type?: string | number): Promise<void> [#symlinktarget-path-filepath-path-type-string--number-promisevoid]

Create a symbolic link at `filepath` pointing to `target`. `type` may be `'file'`, `'dir'`, or `'junction'` (Windows only) or a numeric flag. On Windows, if `type` is not provided, it is inferred from the target.

Overloads:

```ts
symlink(target: Path, filepath: Path, type?: string | number): Promise<void>
symlink(target: Path, filepath: Path, type: string | number, cb: Callback): void
symlink(target: Path, filepath: Path, cb: Callback): void
```

Synchronous form: `symlinkSync(target: Path, filepath: Path, type?: string | number): void`

**Parameters**

| Parameter  | Type                 | Default | Description |
| ---------- | -------------------- | ------- | ----------- |
| `target`   | [`Path`](#path)      | —       | —           |
| `filepath` | [`Path`](#path)      | —       | —           |
| `type?`    | `string` \| `number` | —       | —           |

readlink(filepath: Path, opts: ReadlinkOptions & { encoding?: BufferEncoding }): Promise<string> [#readlinkfilepath-path-opts-readlinkoptions---encoding-bufferencoding--promisestring]

Read the target of a symbolic link.

Overloads:

```ts
readlink(filepath: Path, opts: ReadlinkOptions & { encoding?: BufferEncoding }): Promise<string>
readlink(filepath: Path, opts: ReadlinkOptions & { encoding: 'buffer' }): Promise<Buffer>
readlink(filepath: Path, opts: ReadlinkOptions): Promise<string | Buffer>
readlink(filepath: Path, encoding: BufferEncoding): Promise<string>
readlink(filepath: Path, encoding: 'buffer'): Promise<Buffer>
readlink(filepath: Path, encoding: BufferEncoding | 'buffer'): Promise<string | Buffer>
readlink(filepath: Path): Promise<string>
readlink(filepath: Path, opts: ReadlinkOptions & { encoding?: BufferEncoding }, cb: Callback<[link: string | null]>): void
readlink(filepath: Path, opts: ReadlinkOptions & { encoding: 'buffer' }, cb: Callback<[link: Buffer | null]>): void
readlink(filepath: Path, opts: ReadlinkOptions, cb: Callback<[link: string | Buffer | null]>): void
readlink(filepath: Path, encoding: BufferEncoding, cb: Callback<[link: string | null]>): void
readlink(filepath: Path, encoding: 'buffer', cb: Callback<[link: Buffer | null]>): void
readlink(filepath: Path, encoding: BufferEncoding | 'buffer', cb: Callback<[link: string | Buffer | null]>): void
readlink(filepath: Path, cb: Callback<[link: string | null]>): void
```

Synchronous form: `readlinkSync(filepath: Path, opts: ReadlinkOptions & { encoding?: BufferEncoding }): string`

**Parameters**

| Parameter  | Type                                              | Default | Description |
| ---------- | ------------------------------------------------- | ------- | ----------- |
| `filepath` | [`Path`](#path)                                   | —       | —           |
| `opts`     | `ReadlinkOptions & { encoding?: BufferEncoding }` | —       | —           |

realpath(filepath: Path, opts: RealpathOptions & { encoding?: BufferEncoding }): Promise<string> [#realpathfilepath-path-opts-realpathoptions---encoding-bufferencoding--promisestring]

Resolve the real path of `filepath`, expanding all symbolic links.

Overloads:

```ts
realpath(filepath: Path, opts: RealpathOptions & { encoding?: BufferEncoding }): Promise<string>
realpath(filepath: Path, opts: RealpathOptions & { encoding: 'buffer' }): Promise<Buffer>
realpath(filepath: Path, opts: RealpathOptions): Promise<string | Buffer>
realpath(filepath: Path, encoding: BufferEncoding): Promise<string>
realpath(filepath: Path, encoding: 'buffer'): Promise<Buffer>
realpath(filepath: Path, encoding: BufferEncoding | 'buffer'): Promise<string | Buffer>
realpath(filepath: Path): Promise<string>
realpath(filepath: Path, opts: RealpathOptions & { encoding?: BufferEncoding }, cb: Callback<[path: string | null]>): void
realpath(filepath: Path, opts: RealpathOptions & { encoding: 'buffer' }, cb: Callback<[path: Buffer | null]>): void
realpath(filepath: Path, opts: RealpathOptions, cb: Callback<[path: string | Buffer | null]>): void
realpath(filepath: Path, encoding: BufferEncoding, cb: Callback<[path: string | null]>): void
realpath(filepath: Path, encoding: 'buffer', cb: Callback<[path: Buffer | null]>): void
realpath(filepath: Path, encoding: BufferEncoding | 'buffer', cb: Callback<[path: string | Buffer | null]>): void
realpath(filepath: Path, cb: Callback<[path: string | null]>): void
```

Synchronous form: `realpathSync(filepath: Path, opts: RealpathOptions & { encoding?: BufferEncoding }): string`

**Parameters**

| Parameter  | Type                                              | Default | Description |
| ---------- | ------------------------------------------------- | ------- | ----------- |
| `filepath` | [`Path`](#path)                                   | —       | —           |
| `opts`     | `RealpathOptions & { encoding?: BufferEncoding }` | —       | —           |

rename(src: Path, dst: Path): Promise<void> [#renamesrc-path-dst-path-promisevoid]

Rename a file from `src` to `dst`.

Overloads:

```ts
rename(src: Path, dst: Path): Promise<void>
rename(src: Path, dst: Path, cb: Callback): void
```

Synchronous form: `renameSync(src: Path, dst: Path): void`

**Parameters**

| Parameter | Type            | Default | Description |
| --------- | --------------- | ------- | ----------- |
| `src`     | [`Path`](#path) | —       | —           |
| `dst`     | [`Path`](#path) | —       | —           |

unlink(filepath: Path): Promise<void> [#unlinkfilepath-path-promisevoid]

Remove a file.

Overloads:

```ts
unlink(filepath: Path): Promise<void>
unlink(filepath: Path, cb: Callback): void
```

Synchronous form: `unlinkSync(filepath: Path): void`

**Parameters**

| Parameter  | Type            | Default | Description                     |
| ---------- | --------------- | ------- | ------------------------------- |
| `filepath` | [`Path`](#path) | —       | The path of the file to remove. |

rm(filepath: Path, opts?: RmOptions): Promise<void> [#rmfilepath-path-opts-rmoptions-promisevoid]

Remove a file or directory at `filepath`.

Overloads:

```ts
rm(filepath: Path, opts?: RmOptions): Promise<void>
rm(filepath: Path, opts: RmOptions, cb: Callback): void
rm(filepath: Path, cb: Callback): void
```

Synchronous form: `rmSync(filepath: Path, opts?: RmOptions): void`

**Parameters**

| Parameter  | Type                      | Default | Description                                                                                                                              |
| ---------- | ------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `filepath` | [`Path`](#path)           | —       | —                                                                                                                                        |
| `opts?`    | [`RmOptions`](#rmoptions) | —       | `recursive`, if `true`, removes directories and their contents; `force`, if `true`, suppresses the error when `filepath` does not exist. |

**Throws**

* `EISDIR` — `filepath` is a directory and `opts.recursive` is not set.

copyFile(src: Path, dst: Path, mode?: number): Promise<void> [#copyfilesrc-path-dst-path-mode-number-promisevoid]

Copy a file from `src` to `dst`. `mode` is an optional bitmask created from `fs.constants.COPYFILE_EXCL`, `fs.constants.COPYFILE_FICLONE`, or `fs.constants.COPYFILE_FICLONE_FORCE`.

Overloads:

```ts
copyFile(src: Path, dst: Path, mode?: number): Promise<void>
copyFile(src: Path, dst: Path, mode: number, cb: Callback): void
copyFile(src: Path, dst: Path, cb: Callback): void
```

Synchronous form: `copyFileSync(src: Path, dst: Path, mode?: number): void`

**Parameters**

| Parameter | Type            | Default | Description                                                                                                                         |
| --------- | --------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `src`     | [`Path`](#path) | —       | —                                                                                                                                   |
| `dst`     | [`Path`](#path) | —       | —                                                                                                                                   |
| `mode?`   | `number`        | —       | Defaults to `0`. A bitmask of `fs.constants.COPYFILE_EXCL` (fail if `dst` exists), `COPYFILE_FICLONE`, or `COPYFILE_FICLONE_FORCE`. |

**Throws**

* `EEXIST` — `dst` already exists and `mode` includes `fs.constants.COPYFILE_EXCL`.

cp(src: Path, dst: Path, opts?: CpOptions): Promise<void> [#cpsrc-path-dst-path-opts-cpoptions-promisevoid]

Copy a file or directory from `src` to `dst`.

Overloads:

```ts
cp(src: Path, dst: Path, opts?: CpOptions): Promise<void>
cp(src: Path, dst: Path, opts: CpOptions, cb: Callback): void
cp(src: Path, dst: Path, cb: Callback): void
```

Synchronous form: `cpSync(src: Path, dst: Path, opts?: CpOptions): void`

**Parameters**

| Parameter | Type                      | Default | Description                                                                                     |
| --------- | ------------------------- | ------- | ----------------------------------------------------------------------------------------------- |
| `src`     | [`Path`](#path)           | —       | —                                                                                               |
| `dst`     | [`Path`](#path)           | —       | —                                                                                               |
| `opts?`   | [`CpOptions`](#cpoptions) | —       | `recursive` must be `true` to copy a directory; copying a directory without it throws `EISDIR`. |

**Throws**

* `EISDIR` — `src` is a directory and `opts.recursive` is not set.

Streams and watching [#streams-and-watching]

createReadStream(path: Path | null, opts?: ReadStreamOptions): ReadStream [#createreadstreampath-path--null-opts-readstreamoptions-readstream]

Create a readable stream for a file. Returns a `ReadStream`.

**Parameters**

| Parameter | Type                                      | Default | Description                                                                                                                                  |
| --------- | ----------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `path`    | [`Path`](#path) \| `null`                 | —       | May be `null` if `opts.fd` specifies an already-open file descriptor to read from instead of opening `path`.                                 |
| `opts?`   | [`ReadStreamOptions`](#readstreamoptions) | —       | `flags` defaults to `'r'`, `mode` to `0o666`, `start` (byte offset) to `0`; `end` (inclusive byte offset), if given, stops the stream early. |

createWriteStream(path: Path | null, opts?: WriteStreamOptions): WriteStream [#createwritestreampath-path--null-opts-writestreamoptions-writestream]

Create a writable stream for a file. Returns a `WriteStream`.

**Parameters**

| Parameter | Type                                        | Default | Description                                                                                                 |
| --------- | ------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------- |
| `path`    | [`Path`](#path) \| `null`                   | —       | May be `null` if `opts.fd` specifies an already-open file descriptor to write to instead of opening `path`. |
| `opts?`   | [`WriteStreamOptions`](#writestreamoptions) | —       | `flags` defaults to `'w'`, `mode` to `0o666`.                                                               |

watch [#watch]

```ts
watch(filepath: Path, opts: WatcherOptions & { encoding?: BufferEncoding }, cb: (eventType: WatcherEventType, filename: string) => void): Watcher<string>
```

Watch a file or directory for changes. Returns a `Watcher` object. The `callback`, if provided, is called with `(eventType, filename)` on each change.

**Parameters**

| Parameter  | Type                                                      | Default | Description                                                                                                                  |
| ---------- | --------------------------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `filepath` | [`Path`](#path)                                           | —       | —                                                                                                                            |
| `opts`     | `WatcherOptions & { encoding?: BufferEncoding }`          | —       | `persistent` defaults to `true`; `recursive` (default `false`) also watches subdirectories; `encoding` defaults to `'utf8'`. |
| `cb`       | `(eventType: WatcherEventType, filename: string) => void` | —       | Called with `(eventType, filename)` on each change; equivalent to listening for the `Watcher`'s `'change'` event.            |

Modules [#modules]

promises [#promises]

constants [#constants]

```ts
constants: {
  O_RDWR: number
  O_RDONLY: number
  O_WRONLY: number
  O_CREAT: number
  O_TRUNC: number
  O_APPEND: number

  F_OK: number
  R_OK: number
  W_OK: number
  X_OK: number

  S_IFMT: number
  S_IFREG: number
  S_IFDIR: number
  S_IFCHR: number
  S_IFLNK: number
  S_IFBLK: number
  S_IFIFO: number
  S_IFSOCK: number

  S_IRUSR: number
  S_IWUSR: number
  S_IXUSR: number
  S_IRGRP: number
  S_IWGRP: number
  S_IXGRP: number
  S_IROTH: number
  S_IWOTH: number
  S_IXOTH: number

  UV_DIRENT_UNKNOWN: number
  UV_DIRENT_FILE: number
  UV_DIRENT_DIR: number
  UV_DIRENT_LINK: number
  UV_DIRENT_FIFO: number
  UV_DIRENT_SOCKET: number
  UV_DIRENT_CHAR: number
  UV_DIRENT_BLOCK: number

  COPYFILE_EXCL: number
  COPYFILE_FICLONE: number
  COPYFILE_FICLONE_FORCE: number
  UV_FS_SYMLINK_DIR: number
  UV_FS_SYMLINK_JUNCTION: number
}
```

An object containing file system constants, such as file access modes and file type flags. See `fs/constants` for the full list.

Dir [#dir]

close(): Promise<void> [#close-promisevoid]

Close the directory handle opened by `fs.opendir()`.

Overloads:

```ts
close(): Promise<void>
close(cb: Callback): void
```

closeSync(): void [#closesync-void]

Close the directory handle opened by `fs.opendirSync()`.

path: string [#path-string]

The path of the directory.

read(): Promise<Dirent<T> | null> [#read-promisedirentt--null]

Read the next entry from the directory.

Overloads:

```ts
read(): Promise<Dirent<T> | null>
read(cb: Callback<[dirent: Dirent<T> | null]>): void
```

**Returns** `Promise<Dirent<T> | null>` — The next `Dirent` for the directory, or `null` once every entry has been read.

readSync(): Dirent<T> | null [#readsync-direntt--null]

Read the next entry from the directory.

**Returns** `Dirent<T> | null` — The next `Dirent` for the directory, or `null` once every entry has been read.

Dirent [#dirent]

Dirent.isBlockDevice(): boolean [#direntisblockdevice-boolean]

Returns `true` if the file is a block device.

Dirent.isCharacterDevice(): boolean [#direntischaracterdevice-boolean]

Returns `true` if the file is a character device.

Dirent.isDirectory(): boolean [#direntisdirectory-boolean]

Returns `true` if the file is a directory.

Dirent.isFIFO(): boolean [#direntisfifo-boolean]

Returns `true` if the file is a FIFO (named pipe).

Dirent.isFile(): boolean [#direntisfile-boolean]

Returns `true` if the file is a regular file.

Dirent.isSocket(): boolean [#direntissocket-boolean]

Returns `true` if the file is a socket.

Dirent.isSymbolicLink(): boolean [#direntissymboliclink-boolean]

Returns `true` if the file is a symbolic link. Only meaningful when using `fs.lstat()`.

name: T [#name-t]

The name of the directory entry, as a string or `Buffer` depending on the encoding.

parentPath: string [#parentpath-string]

The path of the parent directory.

type: number [#type-number]

The numeric type of the directory entry.

Stats [#stats]

atime: Date [#atime-date]

The access time as a `Date` object.

atimeMs: number [#atimems-number]

The access time in milliseconds since the epoch.

birthtime: Date [#birthtime-date]

The creation time as a `Date` object.

birthtimeMs: number [#birthtimems-number]

The creation time in milliseconds since the epoch.

blksize: number [#blksize-number]

The file system block size for I/O operations.

blocks: number [#blocks-number]

The number of 512-byte blocks allocated.

ctime: Date [#ctime-date]

The change time as a `Date` object.

ctimeMs: number [#ctimems-number]

The change time in milliseconds since the epoch.

dev: number [#dev-number]

The device identifier.

gid: number [#gid-number]

The group identifier of the file owner.

ino: number [#ino-number]

The inode number.

Stats.isBlockDevice(): boolean [#statsisblockdevice-boolean]

Returns `true` if the file is a block device.

Stats.isCharacterDevice(): boolean [#statsischaracterdevice-boolean]

Returns `true` if the file is a character device.

Stats.isDirectory(): boolean [#statsisdirectory-boolean]

Returns `true` if the file is a directory.

Stats.isFIFO(): boolean [#statsisfifo-boolean]

Returns `true` if the file is a FIFO (named pipe).

Stats.isFile(): boolean [#statsisfile-boolean]

Returns `true` if the file is a regular file.

Stats.isSocket(): boolean [#statsissocket-boolean]

Returns `true` if the file is a socket.

Stats.isSymbolicLink(): boolean [#statsissymboliclink-boolean]

Returns `true` if the file is a symbolic link. Only meaningful when using `fs.lstat()`.

mode: number [#mode-number]

The file mode (type and permissions).

mtime: Date [#mtime-date]

The modification time as a `Date` object.

mtimeMs: number [#mtimems-number]

The modification time in milliseconds since the epoch.

nlink: number [#nlink-number]

The number of hard links.

rdev: number [#rdev-number]

The device identifier for special files.

size: number [#size-number]

The size of the file in bytes.

uid: number [#uid-number]

The user identifier of the file owner.

Watcher [#watcher]

close(): void [#close-void]

Stop watching for further changes. Once closed, a `close` event is emitted.

ref(): void [#ref-void]

Prevent the event loop from exiting while the watcher is active.

unref(): void [#unref-void]

Allow the event loop to exit even if the watcher is still active.

Types [#types]

Path [#path]

```ts
type Path = string | Buffer | URL
```

Flag [#flag]

```ts
type Flag = | 'a'
  | 'a+'
  | 'as'
  | 'as+'
  | 'ax'
  | 'ax+'
  | 'r'
  | 'r+'
  | 'rs'
  | 'rs+'
  | 'sa'
  | 'sa+'
  | 'sr'
  | 'sr+'
  | 'w'
  | 'w+'
  | 'wx'
  | 'wx+'
  | 'xa'
  | 'xa+'
  | 'xw'
  | 'xw+'
```

ReadStreamOptions [#readstreamoptions]

```ts
interface ReadStreamOptions {
  fd?: number
  flags?: Flag
  mode?: number
  start?: number
  end?: number
}
```

Options for `fs.createReadStream()`. `fd`, if given, is used instead of opening `path`. `flags` defaults to `'r'` and `mode` to `0o666`. `start` (default `0`) is the first byte read; `end`, if given, is the last byte read (inclusive).

WriteStreamOptions [#writestreamoptions]

```ts
interface WriteStreamOptions {
  fd?: number
  flags?: Flag
  mode?: number
}
```

Options for `fs.createWriteStream()`. `fd`, if given, is used instead of opening `path`. `flags` defaults to `'w'` and `mode` to `0o666`.

WatcherOptions [#watcheroptions]

```ts
interface WatcherOptions {
  persistent?: boolean
  recursive?: boolean
  encoding?: BufferEncoding | 'buffer'
}
```

Options for `fs.watch()`. `persistent` defaults to `true` (if `false`, the watcher is `unref()`'d immediately so it does not keep the process alive). `recursive` defaults to `false` and also watches subdirectories. `encoding` defaults to `'utf8'`.

WatcherEventType [#watchereventtype]

```ts
type WatcherEventType = 'rename' | 'change'
```

WatcherEvents [#watcherevents]

```ts
interface WatcherEvents<T extends string | Buffer = string | Buffer> {
  error: [err: Error]
  change: [eventType: WatcherEventType, filename: T]
  close: []
}
```

AppendFileOptions [#appendfileoptions]

```ts
interface AppendFileOptions {
  encoding?: BufferEncoding
  flag?: string
  mode?: number
}
```

CpOptions [#cpoptions]

```ts
interface CpOptions {
  recursive?: boolean
}
```

Options for `fs.cp()`. `recursive` must be `true` to copy a directory; without it, copying a directory throws `EISDIR`.

MkdirOptions [#mkdiroptions]

```ts
interface MkdirOptions {
  mode?: number
  recursive?: boolean
}
```

Options for `fs.mkdir()`. `mode` defaults to `0o777`. `recursive`, if `true`, creates any missing parent directories and does not error if `filepath` already exists as a directory.

OpendirOptions [#opendiroptions]

```ts
interface OpendirOptions {
  encoding?: BufferEncoding | 'buffer'
  bufferSize?: number
}
```

Options for `fs.opendir()`. `bufferSize` defaults to `32` and sets how many directory entries are buffered internally per read.

ReadFileOptions [#readfileoptions]

```ts
interface ReadFileOptions {
  encoding?: BufferEncoding | 'buffer'
  flag?: Flag
}
```

ReaddirOptions [#readdiroptions]

```ts
interface ReaddirOptions {
  withFileTypes?: boolean
  encoding?: BufferEncoding | 'buffer'
  bufferSize?: number
}
```

ReadlinkOptions [#readlinkoptions]

```ts
interface ReadlinkOptions {
  encoding?: BufferEncoding | 'buffer'
}
```

RealpathOptions [#realpathoptions]

```ts
interface RealpathOptions {
  encoding?: BufferEncoding | 'buffer'
}
```

RmOptions [#rmoptions]

```ts
interface RmOptions {
  force?: boolean
  recursive?: boolean
}
```

Options for `fs.rm()`. `recursive`, if `true`, removes directories and their contents. `force`, if `true`, suppresses the error when `filepath` does not exist.

WriteFileOptions [#writefileoptions]

```ts
interface WriteFileOptions {
  encoding?: BufferEncoding
  flag?: Flag
  mode?: number
}
```

Classes [#classes]

StatFs [#statfs]

```ts
class StatFs {
  bavail: number
  bfree: number
  blocks: number
  bsize: number
  ffree: number
  files: number
  frsize: number
  type: number
}
```

ReadStream [#readstream]

```ts
class ReadStream {
  fd: number
  flags: Flag
  mode: number
  path: string | null
}
```

WriteStream [#writestream]

```ts
class WriteStream {
  fd: number
  flags: Flag
  mode: number
  path: string | null
}
```

bare-fs/promises [#bare-fspromises]

Functions [#functions]

open(filepath: Path, flags?: Flag | number, mode?: string | number): Promise<FileHandle> [#openfilepath-path-flags-flag--number-mode-string--number-promisefilehandle]

Open a file, returning a file descriptor. `flags` defaults to `'r'` and `mode` defaults to `0o666`. `flags` may be a string such as `'r'`, `'w'`, `'a'`, `'r+'`, etc., or a numeric combination of `fs.constants` flags.

**Parameters**

| Parameter  | Type                        | Default | Description                                                                                         |
| ---------- | --------------------------- | ------- | --------------------------------------------------------------------------------------------------- |
| `filepath` | [`Path`](#path)             | —       | —                                                                                                   |
| `flags?`   | [`Flag`](#flag) \| `number` | —       | Defaults to `'r'`. Selects read/write mode and whether the file is created, truncated, or appended. |
| `mode?`    | `string` \| `number`        | —       | Defaults to `0o666`. Applied only when `flags` creates a new file.                                  |

**Returns** `Promise<FileHandle>` — The file descriptor for the newly opened file.

**Throws**

* `ENOENT` — `filepath` does not exist and `flags` does not include a creating variant (for example the default `'r'`).
* `EEXIST` — `flags` is an exclusive variant (`'wx'`, `'ax'`, `'xw'`, `'xa'`, etc.) and `filepath` already exists.

promises.access(filepath: Path, mode?: number): Promise<void> [#promisesaccessfilepath-path-mode-number-promisevoid]

Check whether the file at `filepath` is accessible. `mode` defaults to `fs.constants.F_OK`.

**Parameters**

| Parameter  | Type            | Default | Description                                                                                       |
| ---------- | --------------- | ------- | ------------------------------------------------------------------------------------------------- |
| `filepath` | [`Path`](#path) | —       | —                                                                                                 |
| `mode?`    | `number`        | —       | Defaults to `fs.constants.F_OK` (existence only); may also combine `R_OK`, `W_OK`, and/or `X_OK`. |

promises.appendFile [#promisesappendfile]

```ts
appendFile(filepath: Path, data: string | Buffer | ArrayBufferView, opts?: AppendFileOptions): Promise<void>
```

Append `data` to a file, creating it if it does not exist. Accepts the same options as `fs.writeFile()` but defaults to the `'a'` flag.

**Parameters**

| Parameter  | Type                                      | Default | Description |
| ---------- | ----------------------------------------- | ------- | ----------- |
| `filepath` | [`Path`](#path)                           | —       | —           |
| `data`     | `string` \| `Buffer` \| `ArrayBufferView` | —       | —           |
| `opts?`    | [`AppendFileOptions`](#appendfileoptions) | —       | —           |

promises.chmod(filepath: Path, mode: string | number): Promise<void> [#promiseschmodfilepath-path-mode-string--number-promisevoid]

Change the permissions of a file. `mode` may be a numeric mode or a string that will be parsed as octal.

**Parameters**

| Parameter  | Type                 | Default | Description |
| ---------- | -------------------- | ------- | ----------- |
| `filepath` | [`Path`](#path)      | —       | —           |
| `mode`     | `string` \| `number` | —       | —           |

promises.chown(filepath: Path, uid: number, gid: number): Promise<void> [#promiseschownfilepath-path-uid-number-gid-number-promisevoid]

Change the owner and group of a file.

**Parameters**

| Parameter  | Type            | Default | Description |
| ---------- | --------------- | ------- | ----------- |
| `filepath` | [`Path`](#path) | —       | —           |
| `uid`      | `number`        | —       | —           |
| `gid`      | `number`        | —       | —           |

promises.copyFile(src: Path, dst: Path, mode?: number): Promise<void> [#promisescopyfilesrc-path-dst-path-mode-number-promisevoid]

Copy a file from `src` to `dst`. `mode` is an optional bitmask created from `fs.constants.COPYFILE_EXCL`, `fs.constants.COPYFILE_FICLONE`, or `fs.constants.COPYFILE_FICLONE_FORCE`.

**Parameters**

| Parameter | Type            | Default | Description                                                                                                                         |
| --------- | --------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `src`     | [`Path`](#path) | —       | —                                                                                                                                   |
| `dst`     | [`Path`](#path) | —       | —                                                                                                                                   |
| `mode?`   | `number`        | —       | Defaults to `0`. A bitmask of `fs.constants.COPYFILE_EXCL` (fail if `dst` exists), `COPYFILE_FICLONE`, or `COPYFILE_FICLONE_FORCE`. |

**Throws**

* `EEXIST` — `dst` already exists and `mode` includes `fs.constants.COPYFILE_EXCL`.

promises.cp(src: Path, dst: Path, opts?: CpOptions): Promise<void> [#promisescpsrc-path-dst-path-opts-cpoptions-promisevoid]

Copy a file or directory from `src` to `dst`.

**Parameters**

| Parameter | Type                      | Default | Description                                                                                     |
| --------- | ------------------------- | ------- | ----------------------------------------------------------------------------------------------- |
| `src`     | [`Path`](#path)           | —       | —                                                                                               |
| `dst`     | [`Path`](#path)           | —       | —                                                                                               |
| `opts?`   | [`CpOptions`](#cpoptions) | —       | `recursive` must be `true` to copy a directory; copying a directory without it throws `EISDIR`. |

**Throws**

* `EISDIR` — `src` is a directory and `opts.recursive` is not set.

promises.lchown(filepath: Path, uid: number, gid: number): Promise<void> [#promiseslchownfilepath-path-uid-number-gid-number-promisevoid]

Change the owner and group of a file, but if `filepath` is a symbolic link, the changes are applied only to the link, not the file it refers to.

**Parameters**

| Parameter  | Type            | Default | Description |
| ---------- | --------------- | ------- | ----------- |
| `filepath` | [`Path`](#path) | —       | —           |
| `uid`      | `number`        | —       | —           |
| `gid`      | `number`        | —       | —           |

promises.lutimes(filepath: Path, atime: number | Date, mtime: number | Date): Promise<void> [#promiseslutimesfilepath-path-atime-number--date-mtime-number--date-promisevoid]

Like `fs.utimes()`, but if `filepath` is a symbolic link, the timestamps of the link is changed, not the file it refers to.

**Parameters**

| Parameter  | Type               | Default | Description |
| ---------- | ------------------ | ------- | ----------- |
| `filepath` | [`Path`](#path)    | —       | —           |
| `atime`    | `number` \| `Date` | —       | —           |
| `mtime`    | `number` \| `Date` | —       | —           |

promises.link(src: Path, dst: Path): Promise<void> [#promiseslinksrc-path-dst-path-promisevoid]

Creates a new link (also known as a hard link) to an existing file.

**Parameters**

| Parameter | Type            | Default | Description |
| --------- | --------------- | ------- | ----------- |
| `src`     | [`Path`](#path) | —       | —           |
| `dst`     | [`Path`](#path) | —       | —           |

promises.lstat(filepath: Path): Promise<Stats> [#promiseslstatfilepath-path-promisestats]

Like `fs.stat()`, but if `filepath` is a symbolic link, the link itself is statted, not the file it refers to.

**Parameters**

| Parameter  | Type            | Default | Description |
| ---------- | --------------- | ------- | ----------- |
| `filepath` | [`Path`](#path) | —       | —           |

promises.mkdir(filepath: Path, opts?: MkdirOptions): Promise<void> [#promisesmkdirfilepath-path-opts-mkdiroptions-promisevoid]

Create a directory at `filepath`.

Overloads:

```ts
mkdir(filepath: Path, opts?: MkdirOptions): Promise<void>
mkdir(filepath: Path, mode: number): Promise<void>
```

**Parameters**

| Parameter  | Type                            | Default | Description                                                                                                                                            |
| ---------- | ------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `filepath` | [`Path`](#path)                 | —       | —                                                                                                                                                      |
| `opts?`    | [`MkdirOptions`](#mkdiroptions) | —       | `mode` defaults to `0o777`. `recursive`, if `true`, creates missing parent directories and does not error if `filepath` already exists as a directory. |

**Throws**

* `ENOENT` — a parent directory in `filepath` does not exist and `opts.recursive` is not set.
* `EEXIST` — `filepath` already exists; when `opts.recursive` is set this is only thrown if the existing path is not itself a directory.

promises.mkdtemp(prefix: Path): Promise<string> [#promisesmkdtempprefix-path-promisestring]

Create a unique temporary directory.

**Parameters**

| Parameter | Type            | Default | Description                                                                                                           |
| --------- | --------------- | ------- | --------------------------------------------------------------------------------------------------------------------- |
| `prefix`  | [`Path`](#path) | —       | The literal suffix `'XXXXXX'` is appended to `prefix` and replaced with random characters to form the directory name. |

**Returns** `Promise<string>` — The path of the newly created directory, including its randomly generated suffix.

promises.opendir [#promisesopendir]

```ts
opendir(filepath: Path, opts: OpendirOptions & { encoding?: BufferEncoding }): Promise<Dir<string>>
```

Open a directory for iteration. Returns a `Dir` object.

**Parameters**

| Parameter  | Type                                             | Default | Description |
| ---------- | ------------------------------------------------ | ------- | ----------- |
| `filepath` | [`Path`](#path)                                  | —       | —           |
| `opts`     | `OpendirOptions & { encoding?: BufferEncoding }` | —       | —           |

promises.readFile(filepath: Path, opts: ReadFileOptions & { encoding: BufferEncoding }): Promise<string> [#promisesreadfilefilepath-path-opts-readfileoptions---encoding-bufferencoding--promisestring]

Read the entire contents of a file. Returns a `Buffer` by default, or a string if an `encoding` is specified.

Overloads:

```ts
readFile(filepath: Path, opts: ReadFileOptions & { encoding: BufferEncoding }): Promise<string>
readFile(filepath: Path, opts: ReadFileOptions & { encoding?: 'buffer' }): Promise<Buffer>
readFile(filepath: Path, opts: ReadFileOptions): Promise<string | Buffer>
readFile(filepath: Path, encoding: BufferEncoding): Promise<string>
readFile(filepath: Path, encoding: 'buffer'): Promise<Buffer>
readFile(filepath: Path, encoding?: BufferEncoding | 'buffer'): Promise<string | Buffer>
readFile(filepath: Path): Promise<Buffer>
```

**Parameters**

| Parameter  | Type                                             | Default | Description                                                                                              |
| ---------- | ------------------------------------------------ | ------- | -------------------------------------------------------------------------------------------------------- |
| `filepath` | [`Path`](#path)                                  | —       | —                                                                                                        |
| `opts`     | `ReadFileOptions & { encoding: BufferEncoding }` | —       | `encoding` defaults to `'buffer'` (returning a `Buffer` rather than a string); `flag` defaults to `'r'`. |

promises.readdir [#promisesreaddir]

```ts
readdir(filepath: Path, opts: ReaddirOptions & { encoding?: BufferEncoding }): Promise<Dir<string>[] | string[]>
```

Read the contents of a directory. Returns an array of filenames or, if `withFileTypes` is `true`, an array of `Dirent` objects.

**Parameters**

| Parameter  | Type                                             | Default | Description                                                                             |
| ---------- | ------------------------------------------------ | ------- | --------------------------------------------------------------------------------------- |
| `filepath` | [`Path`](#path)                                  | —       | —                                                                                       |
| `opts`     | `ReaddirOptions & { encoding?: BufferEncoding }` | —       | `withFileTypes`, if `true`, returns `Dirent` objects instead of plain filename strings. |

promises.readlink(filepath: Path, opts: ReadlinkOptions & { encoding?: BufferEncoding }): Promise<string> [#promisesreadlinkfilepath-path-opts-readlinkoptions---encoding-bufferencoding--promisestring]

Read the target of a symbolic link.

Overloads:

```ts
readlink(filepath: Path, opts: ReadlinkOptions & { encoding?: BufferEncoding }): Promise<string>
readlink(filepath: Path, opts: ReadlinkOptions & { encoding: 'buffer' }): Promise<Buffer>
readlink(filepath: Path, opts: ReadlinkOptions): Promise<string | Buffer>
readlink(filepath: Path, encoding: BufferEncoding): Promise<string>
readlink(filepath: Path, encoding: 'buffer'): Promise<Buffer>
readlink(filepath: Path, encoding: BufferEncoding | 'buffer'): Promise<string | Buffer>
readlink(filepath: Path): Promise<string>
```

**Parameters**

| Parameter  | Type                                              | Default | Description |
| ---------- | ------------------------------------------------- | ------- | ----------- |
| `filepath` | [`Path`](#path)                                   | —       | —           |
| `opts`     | `ReadlinkOptions & { encoding?: BufferEncoding }` | —       | —           |

promises.realpath(filepath: Path, opts: RealpathOptions & { encoding?: BufferEncoding }): Promise<string> [#promisesrealpathfilepath-path-opts-realpathoptions---encoding-bufferencoding--promisestring]

Resolve the real path of `filepath`, expanding all symbolic links.

Overloads:

```ts
realpath(filepath: Path, opts: RealpathOptions & { encoding?: BufferEncoding }): Promise<string>
realpath(filepath: Path, opts: RealpathOptions & { encoding: 'buffer' }): Promise<Buffer>
realpath(filepath: Path, opts: RealpathOptions): Promise<string | Buffer>
realpath(filepath: Path, encoding: BufferEncoding): Promise<string>
realpath(filepath: Path, encoding: 'buffer'): Promise<Buffer>
realpath(filepath: Path, encoding: BufferEncoding | 'buffer'): Promise<string | Buffer>
realpath(filepath: Path): Promise<string>
```

**Parameters**

| Parameter  | Type                                              | Default | Description |
| ---------- | ------------------------------------------------- | ------- | ----------- |
| `filepath` | [`Path`](#path)                                   | —       | —           |
| `opts`     | `RealpathOptions & { encoding?: BufferEncoding }` | —       | —           |

promises.rename(src: Path, dst: Path): Promise<void> [#promisesrenamesrc-path-dst-path-promisevoid]

Rename a file from `src` to `dst`.

**Parameters**

| Parameter | Type            | Default | Description |
| --------- | --------------- | ------- | ----------- |
| `src`     | [`Path`](#path) | —       | —           |
| `dst`     | [`Path`](#path) | —       | —           |

promises.rm(filepath: Path, opts?: RmOptions): Promise<void> [#promisesrmfilepath-path-opts-rmoptions-promisevoid]

Remove a file or directory at `filepath`.

**Parameters**

| Parameter  | Type                      | Default | Description                                                                                                                              |
| ---------- | ------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `filepath` | [`Path`](#path)           | —       | —                                                                                                                                        |
| `opts?`    | [`RmOptions`](#rmoptions) | —       | `recursive`, if `true`, removes directories and their contents; `force`, if `true`, suppresses the error when `filepath` does not exist. |

**Throws**

* `EISDIR` — `filepath` is a directory and `opts.recursive` is not set.

promises.rmdir(filepath: Path): Promise<void> [#promisesrmdirfilepath-path-promisevoid]

Remove an empty directory.

**Parameters**

| Parameter  | Type            | Default | Description |
| ---------- | --------------- | ------- | ----------- |
| `filepath` | [`Path`](#path) | —       | —           |

**Throws**

* `ENOTEMPTY` — the directory is not empty.

promises.stat(filepath: Path): Promise<Stats> [#promisesstatfilepath-path-promisestats]

Get the status of a file. Returns a `Stats` object.

**Parameters**

| Parameter  | Type            | Default | Description |
| ---------- | --------------- | ------- | ----------- |
| `filepath` | [`Path`](#path) | —       | —           |

promises.statfs(filepath: Path): Promise<StatFs> [#promisesstatfsfilepath-path-promisestatfs]

Get filesystem statistics. Returns a `StatFs` object.

**Parameters**

| Parameter  | Type            | Default | Description |
| ---------- | --------------- | ------- | ----------- |
| `filepath` | [`Path`](#path) | —       | —           |

promises.truncate(filepath: Path, len?: number): Promise<void> [#promisestruncatefilepath-path-len-number-promisevoid]

Truncate the file at `filename` to `len` bytes. `len` defaults to `0`.

**Parameters**

| Parameter  | Type            | Default | Description |
| ---------- | --------------- | ------- | ----------- |
| `filepath` | [`Path`](#path) | —       | —           |
| `len?`     | `number`        | —       | —           |

promises.symlink(target: Path, filepath: Path, type?: string | number): Promise<void> [#promisessymlinktarget-path-filepath-path-type-string--number-promisevoid]

Create a symbolic link at `filepath` pointing to `target`. `type` may be `'file'`, `'dir'`, or `'junction'` (Windows only) or a numeric flag. On Windows, if `type` is not provided, it is inferred from the target.

**Parameters**

| Parameter  | Type                 | Default | Description |
| ---------- | -------------------- | ------- | ----------- |
| `target`   | [`Path`](#path)      | —       | —           |
| `filepath` | [`Path`](#path)      | —       | —           |
| `type?`    | `string` \| `number` | —       | —           |

promises.unlink(filepath: Path): Promise<void> [#promisesunlinkfilepath-path-promisevoid]

Remove a file.

**Parameters**

| Parameter  | Type            | Default | Description                     |
| ---------- | --------------- | ------- | ------------------------------- |
| `filepath` | [`Path`](#path) | —       | The path of the file to remove. |

promises.utimes(filepath: Path, atime: number | Date, mtime: number | Date): Promise<void> [#promisesutimesfilepath-path-atime-number--date-mtime-number--date-promisevoid]

Change the access and modification times of a file. Times may be numbers (seconds since epoch) or `Date` objects.

**Parameters**

| Parameter  | Type               | Default | Description |
| ---------- | ------------------ | ------- | ----------- |
| `filepath` | [`Path`](#path)    | —       | —           |
| `atime`    | `number` \| `Date` | —       | —           |
| `mtime`    | `number` \| `Date` | —       | —           |

watch(filepath: Path, opts: WatcherOptions & { encoding?: BufferEncoding }): Watcher<string> [#watchfilepath-path-opts-watcheroptions---encoding-bufferencoding--watcherstring]

Watch a file or directory for changes. Returns a `Watcher` object. The `callback`, if provided, is called with `(eventType, filename)` on each change.

Overloads:

```ts
watch(filepath: Path, opts: WatcherOptions & { encoding?: BufferEncoding }): Watcher<string>
watch(filepath: Path, opts: WatcherOptions & { encoding: 'buffer' }): Watcher<Buffer>
watch(filepath: Path, opts: WatcherOptions): Watcher
watch(filepath: Path, encoding: BufferEncoding): Watcher<string>
watch(filepath: Path, encoding: 'buffer'): Watcher<Buffer>
watch(filepath: Path, encoding: BufferEncoding | 'buffer'): Watcher
watch(filepath: Path): Watcher<string>
```

**Parameters**

| Parameter  | Type                                             | Default | Description                                                                                                                  |
| ---------- | ------------------------------------------------ | ------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `filepath` | [`Path`](#path)                                  | —       | —                                                                                                                            |
| `opts`     | `WatcherOptions & { encoding?: BufferEncoding }` | —       | `persistent` defaults to `true`; `recursive` (default `false`) also watches subdirectories; `encoding` defaults to `'utf8'`. |

promises.writeFile [#promiseswritefile]

```ts
writeFile(filepath: Path, data: string | Buffer | ArrayBufferView, opts?: WriteFileOptions): Promise<void>
```

Write `data` to a file, replacing it if it already exists.

**Parameters**

| Parameter  | Type                                      | Default | Description                                                                          |
| ---------- | ----------------------------------------- | ------- | ------------------------------------------------------------------------------------ |
| `filepath` | [`Path`](#path)                           | —       | —                                                                                    |
| `data`     | `string` \| `Buffer` \| `ArrayBufferView` | —       | —                                                                                    |
| `opts?`    | [`WriteFileOptions`](#writefileoptions)   | —       | `flag` defaults to `'w'` (truncating any existing file); `mode` defaults to `0o666`. |

Constants and variables [#constants-and-variables]

promises.constants [#promisesconstants]

```ts
constants: {
  O_RDWR: number
  O_RDONLY: number
  O_WRONLY: number
  O_CREAT: number
  O_TRUNC: number
  O_APPEND: number

  F_OK: number
  R_OK: number
  W_OK: number
  X_OK: number

  S_IFMT: number
  S_IFREG: number
  S_IFDIR: number
  S_IFCHR: number
  S_IFLNK: number
  S_IFBLK: number
  S_IFIFO: number
  S_IFSOCK: number

  S_IRUSR: number
  S_IWUSR: number
  S_IXUSR: number
  S_IRGRP: number
  S_IWGRP: number
  S_IXGRP: number
  S_IROTH: number
  S_IWOTH: number
  S_IXOTH: number

  UV_DIRENT_UNKNOWN: number
  UV_DIRENT_FILE: number
  UV_DIRENT_DIR: number
  UV_DIRENT_LINK: number
  UV_DIRENT_FIFO: number
  UV_DIRENT_SOCKET: number
  UV_DIRENT_CHAR: number
  UV_DIRENT_BLOCK: number

  COPYFILE_EXCL: number
  COPYFILE_FICLONE: number
  COPYFILE_FICLONE_FORCE: number
  UV_FS_SYMLINK_DIR: number
  UV_FS_SYMLINK_JUNCTION: number
}
```

An object containing file system constants, such as file access modes and file type flags. See `fs/constants` for the full list.

bare-fs/constants [#bare-fsconstants]

Constants and variables [#constants-and-variables-1]

constants.constants [#constantsconstants]

```ts
constants: {
  O_RDWR: number
  O_RDONLY: number
  O_WRONLY: number
  O_CREAT: number
  O_TRUNC: number
  O_APPEND: number

  F_OK: number
  R_OK: number
  W_OK: number
  X_OK: number

  S_IFMT: number
  S_IFREG: number
  S_IFDIR: number
  S_IFCHR: number
  S_IFLNK: number
  S_IFBLK: number
  S_IFIFO: number
  S_IFSOCK: number

  S_IRUSR: number
  S_IWUSR: number
  S_IXUSR: number
  S_IRGRP: number
  S_IWGRP: number
  S_IXGRP: number
  S_IROTH: number
  S_IWOTH: number
  S_IXOTH: number

  UV_DIRENT_UNKNOWN: number
  UV_DIRENT_FILE: number
  UV_DIRENT_DIR: number
  UV_DIRENT_LINK: number
  UV_DIRENT_FIFO: number
  UV_DIRENT_SOCKET: number
  UV_DIRENT_CHAR: number
  UV_DIRENT_BLOCK: number

  COPYFILE_EXCL: number
  COPYFILE_FICLONE: number
  COPYFILE_FICLONE_FORCE: number
  UV_FS_SYMLINK_DIR: number
  UV_FS_SYMLINK_JUNCTION: number
}
```

An object containing file system constants, such as file access modes and file type flags. See `fs/constants` for the full list.

See also [#see-also]

* Builds on `bare-events`, `bare-path`, `bare-stream`, and `bare-url`.
* [Bare modules](/reference/modules/bare-modules) — the full `bare-*` catalog.
* [Bare runtime API](/reference/bare/runtime) — the runtime these modules extend.


# bare-hrtime



<mark style={{ backgroundColor: '#7dde9a', padding: '2px 8px', borderRadius: '4px', fontSize: '0.85em', fontWeight: 500 }}>
  stable
</mark>

[`bare-hrtime`](https://github.com/holepunchto/bare-hrtime) — High-resolution timers for JavaScript. It is a native addon.

```sh
npm i bare-hrtime
```

Usage [#usage]

```js
const hrtime = require('bare-hrtime')

hrtime() // returns [seconds, nanoseconds]
hrtime.bigint() // returns nanoseconds
```

API [#api]

Functions [#functions]

hrtime(prev?: ArrayLike<number>): [seconds: number, nanoseconds: number] [#hrtimeprev-arraylikenumber-seconds-number-nanoseconds-number]

Returns the current high-resolution time as a `[seconds, nanoseconds]` tuple. If `prev` (a previous `hrtime()` result) is given, returns the elapsed time since it instead.

**Parameters**

| Parameter | Type                | Default | Description                                                     |
| --------- | ------------------- | ------- | --------------------------------------------------------------- |
| `prev?`   | `ArrayLike<number>` | —       | A previous `hrtime()` result to compute the elapsed time since. |

hrtime.bigint(): bigint [#hrtimebigint-bigint]

See also [#see-also]

* [Bare modules](/reference/modules/bare-modules) — the full `bare-*` catalog.
* [Bare runtime API](/reference/bare/runtime) — the runtime these modules extend.


# bare-http1



<mark style={{ backgroundColor: '#7dde9a', padding: '2px 8px', borderRadius: '4px', fontSize: '0.85em', fontWeight: 500 }}>
  stable
</mark>

[`bare-http1`](https://github.com/holepunchto/bare-http1) — Native HTTP/1 library for JavaScript.

Mirrors the Node.js [`http`](https://nodejs.org/api/http.html) module.

```sh
npm i bare-http1
```

Usage [#usage]

```js
const http = require('bare-http1')

const server = http.createServer((req, res) => {
  res.statusCode = 200
  res.setHeader('Content-Length', 10)
  res.write('hello world!')
  res.end()
})

server.listen(0, () => {
  const { port } = server.address()
  console.log('server is bound on', port)

  const client = http.request({ port }, (res) => {
    res.on('data', (data) => console.log(data.toString()))
  })
  client.end()
})
```

API [#api]

constants [#constants]

constants.HTTPMethod [#constantshttpmethod]

```ts
type HTTPMethod = keyof typeof constants.method
```

A key of `constants.method`, that is one of the supported HTTP method names.

constants.HTTPStatusCode [#constantshttpstatuscode]

```ts
type HTTPStatusCode = keyof typeof constants.status
```

A key of `constants.status`, that is a supported HTTP status code.

constants.HTTPStatusMessage [#constantshttpstatusmessage]

```ts
type HTTPStatusMessage = (typeof constants.status)[HTTPStatusCode]
```

The reason phrase for a given `HTTPStatusCode`, as found in `constants.status`.

HTTPIncomingMessage [#httpincomingmessage]

new HTTPIncomingMessage(socket?: TCPSocket, opts?: HTTPIncomingMessageOptions) [#new-httpincomingmessagesocket-tcpsocket-opts-httpincomingmessageoptions]

A readable stream representing an incoming HTTP request (on the server) or response (on the client). Carries the parsed `headers`, `method`/`url` or `statusCode`/`statusMessage`, and the underlying `socket`.

**Parameters**

| Parameter | Type                                                        | Default | Description                                                                                                            |
| --------- | ----------------------------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------- |
| `socket?` | `TCPSocket`                                                 | —       | The socket the message is read from.                                                                                   |
| `opts?`   | [`HTTPIncomingMessageOptions`](#httpincomingmessageoptions) | —       | Initial values for `headers`, plus `method` and `url` (server side) or `statusCode` and `statusMessage` (client side). |

HTTPIncomingMessage.getHeader(name: string): string | number | undefined [#httpincomingmessagegetheadername-string-string--number--undefined]

Returns the value of header `name` (case-insensitive), or `undefined` if not set.

**Parameters**

| Parameter | Type     | Default | Description                         |
| --------- | -------- | ------- | ----------------------------------- |
| `name`    | `string` | —       | The header name (case-insensitive). |

HTTPIncomingMessage.getHeaders(): Record<string, string | number> [#httpincomingmessagegetheaders-recordstring-string--number]

Returns a shallow copy of all headers.

HTTPIncomingMessage.hasHeader(name: string): boolean [#httpincomingmessagehasheadername-string-boolean]

Returns whether header `name` (case-insensitive) is set.

**Parameters**

| Parameter | Type     | Default | Description                         |
| --------- | -------- | ------- | ----------------------------------- |
| `name`    | `string` | —       | The header name (case-insensitive). |

HTTPIncomingMessage.headers: Record<string, string | number> [#httpincomingmessageheaders-recordstring-string--number]

The parsed headers, keyed by lowercase name.

httpVersion: '1.1' [#httpversion-11]

The HTTP version of the message. Always `'1.1'`.

HTTPIncomingMessage.method: HTTPMethod [#httpincomingmessagemethod-httpmethod]

The request method. Only meaningful on the server side.

HTTPIncomingMessage.setTimeout(ms: number, ontimeout?: () => void): this [#httpincomingmessagesettimeoutms-number-ontimeout---void-this]

Sets the underlying socket's timeout to `ms` and, if given, adds `ontimeout` as a one-time `'timeout'` listener.

**Parameters**

| Parameter    | Type         | Default | Description                               |
| ------------ | ------------ | ------- | ----------------------------------------- |
| `ms`         | `number`     | —       | The socket timeout in milliseconds.       |
| `ontimeout?` | `() => void` | —       | Added as a one-time `'timeout'` listener. |

HTTPIncomingMessage.socket: TCPSocket [#httpincomingmessagesocket-tcpsocket]

The underlying `TCPSocket` the message was read from.

HTTPIncomingMessage.statusCode: HTTPStatusCode [#httpincomingmessagestatuscode-httpstatuscode]

The response status code. Only meaningful on the client side.

statusMessage: HTTPStatusMessage [#statusmessage-httpstatusmessage]

The response status reason phrase. Only meaningful on the client side.

HTTPIncomingMessage.upgrade: boolean [#httpincomingmessageupgrade-boolean]

Whether the connection was upgraded (for example to a WebSocket) after this message.

url: string [#url-string]

The request URL path. Only meaningful on the server side.

HTTPOutgoingMessage [#httpoutgoingmessage]

new HTTPOutgoingMessage(socket?: TCPSocket) [#new-httpoutgoingmessagesocket-tcpsocket]

A writable stream representing an outgoing HTTP request (on the client) or response (on the server). Base class of `HTTPClientRequest` and `HTTPServerResponse`.

**Parameters**

| Parameter | Type        | Default | Description                           |
| --------- | ----------- | ------- | ------------------------------------- |
| `socket?` | `TCPSocket` | —       | The socket the message is written to. |

flushHeaders(): void [#flushheaders-void]

Sends the headers immediately, if they haven't already been sent, instead of waiting for the first write.

HTTPOutgoingMessage.getHeader(name: string): string | number | undefined [#httpoutgoingmessagegetheadername-string-string--number--undefined]

Returns the value of header `name` (case-insensitive), or `undefined` if not set.

**Parameters**

| Parameter | Type     | Default | Description                         |
| --------- | -------- | ------- | ----------------------------------- |
| `name`    | `string` | —       | The header name (case-insensitive). |

HTTPOutgoingMessage.getHeaders(): Record<string, string | number> [#httpoutgoingmessagegetheaders-recordstring-string--number]

Returns a shallow copy of all headers set so far.

HTTPOutgoingMessage.hasHeader(name: string): boolean [#httpoutgoingmessagehasheadername-string-boolean]

Returns whether header `name` (case-insensitive) is set.

**Parameters**

| Parameter | Type     | Default | Description                         |
| --------- | -------- | ------- | ----------------------------------- |
| `name`    | `string` | —       | The header name (case-insensitive). |

HTTPOutgoingMessage.headers: Record<string, string | number> [#httpoutgoingmessageheaders-recordstring-string--number]

The headers set so far, keyed by lowercase name. Assigning validates each header name and value.

headersSent: boolean [#headerssent-boolean]

Whether the headers have already been sent.

setHeader(name: string, value: string | number): void [#setheadername-string-value-string--number-void]

Sets header `name` (case-insensitive) to `value`, validating both.

**Parameters**

| Parameter | Type                 | Default | Description                                                         |
| --------- | -------------------- | ------- | ------------------------------------------------------------------- |
| `name`    | `string`             | —       | The header name (case-insensitive); must be a valid RFC 7230 token. |
| `value`   | `string` \| `number` | —       | The header value; must not contain line-terminating characters.     |

**Throws**

* `INVALID_HEADER_NAME` — `name` is not a valid RFC 7230 token.
* `INVALID_HEADER_VALUE` — `value` contains a line-terminating character.

HTTPOutgoingMessage.setTimeout(ms: number, ontimeout?: () => void): this [#httpoutgoingmessagesettimeoutms-number-ontimeout---void-this]

Sets the underlying socket's timeout to `ms` and, if given, adds `ontimeout` as a one-time `'timeout'` listener.

**Parameters**

| Parameter    | Type         | Default | Description                               |
| ------------ | ------------ | ------- | ----------------------------------------- |
| `ms`         | `number`     | —       | The socket timeout in milliseconds.       |
| `ontimeout?` | `() => void` | —       | Added as a one-time `'timeout'` listener. |

HTTPOutgoingMessage.socket: TCPSocket [#httpoutgoingmessagesocket-tcpsocket]

The underlying `TCPSocket` the message is written to.

HTTPOutgoingMessage.upgrade: boolean [#httpoutgoingmessageupgrade-boolean]

Whether the connection was upgraded (for example to a WebSocket) after this message.

HTTPAgent [#httpagent]

new HTTPAgent(opts?: HTTPAgentOptions & TCPSocketOptions & TCPSocketConnectOptions) [#new-httpagentopts-httpagentoptions--tcpsocketoptions--tcpsocketconnectoptions]

Manages a pool of `TCPSocket` connections shared across requests to the same host and port, reusing idle keep-alive sockets instead of opening a new connection per request.

**Parameters**

| Parameter | Type                                                            | Default | Description                                                                                                                                    |
| --------- | --------------------------------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `opts?`   | `HTTPAgentOptions & TCPSocketOptions & TCPSocketConnectOptions` | —       | Agent options (`keepAlive`, `keepAliveMsecs`, `defaultPort`) plus TCP socket and connect options applied to each connection the agent creates. |

addRequest(req: HTTPClientRequest, opts: TCPSocketOptions & TCPSocketConnectOptions): void [#addrequestreq-httpclientrequest-opts-tcpsocketoptions--tcpsocketconnectoptions-void]

Assigns a socket to `req`, reusing an idle keep-alive socket for the same host and port if one is available, or creating a new one otherwise.

**Parameters**

| Parameter | Type                                         | Default | Description                                                                     |
| --------- | -------------------------------------------- | ------- | ------------------------------------------------------------------------------- |
| `req`     | `HTTPClientRequest`                          | —       | The request to assign a socket to.                                              |
| `opts`    | `TCPSocketOptions & TCPSocketConnectOptions` | —       | The socket and connection options, including the destination `host` and `port`. |

createConnection(opts?: TCPSocketOptions & TCPSocketConnectOptions): TCPSocket [#createconnectionopts-tcpsocketoptions--tcpsocketconnectoptions-tcpsocket]

Creates a new `TCPSocket` connection for a request. Throws if the agent is suspended.

**Parameters**

| Parameter | Type                                         | Default | Description                                                                     |
| --------- | -------------------------------------------- | ------- | ------------------------------------------------------------------------------- |
| `opts?`   | `TCPSocketOptions & TCPSocketConnectOptions` | —       | The socket and connection options, including the destination `host` and `port`. |

**Throws**

* `AGENT_SUSPENDED` — the agent is suspended.

destroy(): void [#destroy-void]

Destroys all sockets currently held by the agent, both in-use and free.

freeSockets: IterableIterator<TCPSocket> [#freesockets-iterableiteratortcpsocket]

An iterator over the agent's idle, keep-alive sockets awaiting reuse.

getName(opts: { host: string; port: number }): string [#getnameopts--host-string-port-number--string]

Returns the pool key used to group sockets by destination, derived from `opts.host` and `opts.port`.

**Parameters**

| Parameter | Type                             | Default | Description                                                    |
| --------- | -------------------------------- | ------- | -------------------------------------------------------------- |
| `opts`    | `{ host: string; port: number }` | —       | The destination `host` and `port` to derive the pool key from. |

HTTPAgent.global: HTTPAgent [#httpagentglobal-httpagent]

The agent's own default instance, used as `bare-http1`'s `globalAgent`.

keepSocketAlive(socket: TCPSocket): boolean [#keepsocketalivesocket-tcpsocket-boolean]

Marks `socket` to be kept alive and unreferenced instead of closed once a request completes. Returns whether the socket was kept alive.

**Parameters**

| Parameter | Type        | Default | Description                         |
| --------- | ----------- | ------- | ----------------------------------- |
| `socket`  | `TCPSocket` | —       | The socket to keep alive for reuse. |

resume(): void [#resume-void]

Resumes an agent suspended with `suspend()`, allowing it to create connections again.

resumed: Promise<void> | null [#resumed-promisevoid--null]

A promise that resolves once a suspended agent is resumed, or `null` if the agent isn't suspended.

reuseSocket(socket: TCPSocket, req?: HTTPClientRequest): void [#reusesocketsocket-tcpsocket-req-httpclientrequest-void]

Marks `socket` as back in active use, referencing it so it keeps the event loop alive.

**Parameters**

| Parameter | Type                | Default | Description                                 |
| --------- | ------------------- | ------- | ------------------------------------------- |
| `socket`  | `TCPSocket`         | —       | The socket to mark as back in active use.   |
| `req?`    | `HTTPClientRequest` | —       | The request the socket is being reused for. |

sockets: IterableIterator<TCPSocket> [#sockets-iterableiteratortcpsocket]

An iterator over all sockets currently held by the agent, both in-use and free.

suspend(): void [#suspend-void]

Suspends the agent, destroying all its sockets and preventing new connections until `resume()` is called.

suspended: boolean [#suspended-boolean]

Whether the agent is currently suspended.

HTTPServer [#httpserver]

HTTPServer [#httpserver-1]

```ts
new HTTPServer(opts?: HTTPServerConnectionOptions, onrequest?: (req: HTTPIncomingMessage, res: HTTPServerResponse) => void)
```

An HTTP/1.1 server, extending `TCPServer`. Emits `'request'` with an `HTTPIncomingMessage` and `HTTPServerResponse` for each request received.

**Parameters**

| Parameter    | Type                                                          | Default | Description                                                                                                   |
| ------------ | ------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------- |
| `opts?`      | [`HTTPServerConnectionOptions`](#httpserverconnectionoptions) | —       | Options passed to each `HTTPServerConnection`, such as custom `IncomingMessage` and `ServerResponse` classes. |
| `onrequest?` | `(req: HTTPIncomingMessage, res: HTTPServerResponse) => void` | —       | Added as a listener for the `'request'` event.                                                                |

HTTPServer.setTimeout(ms: number, ontimeout?: () => void): this [#httpserversettimeoutms-number-ontimeout---void-this]

Sets the idle-socket timeout to `ms` (default `0`, meaning no timeout) and, if given, adds `ontimeout` as a `'timeout'` listener.

**Parameters**

| Parameter    | Type         | Default | Description                                                             |
| ------------ | ------------ | ------- | ----------------------------------------------------------------------- |
| `ms`         | `number`     | —       | The idle-socket timeout in milliseconds; `0` (the default) disables it. |
| `ontimeout?` | `() => void` | —       | Added as a `'timeout'` listener.                                        |

timeout: number | undefined [#timeout-number--undefined]

The idle-socket timeout in milliseconds, or `undefined` if none is set.

HTTPServerResponse [#httpserverresponse]

new HTTPServerResponse(socket: TCPSocket, req: HTTPIncomingMessage) [#new-httpserverresponsesocket-tcpsocket-req-httpincomingmessage]

An outgoing HTTP response, extending `HTTPOutgoingMessage`. Defaults to status `200` and chunked transfer encoding unless a `Content-Length` header is set.

**Parameters**

| Parameter | Type                  | Default | Description                            |
| --------- | --------------------- | ------- | -------------------------------------- |
| `socket`  | `TCPSocket`           | —       | The socket the response is written to. |
| `req`     | `HTTPIncomingMessage` | —       | The request this response answers.     |

req: HTTPIncomingMessage [#req-httpincomingmessage]

The `HTTPIncomingMessage` this response is answering.

HTTPServerResponse.statusCode: HTTPStatusCode [#httpserverresponsestatuscode-httpstatuscode]

The response status code to send. Defaults to `200`.

statusMessage: HTTPStatusMessage | null [#statusmessage-httpstatusmessage--null]

The response status reason phrase to send. Defaults to the standard phrase for `statusCode`.

writeHead [#writehead]

```ts
writeHead(statusCode: HTTPStatusCode, statusMessage?: HTTPStatusMessage, headers?: Record<string, string | number>): void
```

Sets `statusCode`, and optionally `statusMessage` and additional `headers`, in one call.

**Parameters**

| Parameter        | Type                                      | Default | Description                                                                  |
| ---------------- | ----------------------------------------- | ------- | ---------------------------------------------------------------------------- |
| `statusCode`     | [`HTTPStatusCode`](#httpstatuscode)       | —       | The status code to send.                                                     |
| `statusMessage?` | [`HTTPStatusMessage`](#httpstatusmessage) | —       | The reason phrase to send; defaults to the standard phrase for `statusCode`. |
| `headers?`       | `Record<string, string \| number>`        | —       | Additional headers to merge into the response headers.                       |

**Throws**

* `INVALID_HEADER_NAME` — a header name is not a valid token.
* `INVALID_HEADER_VALUE` — `statusMessage` or a header value contains an invalid character.

HTTPServerConnection [#httpserverconnection]

HTTPServerConnection [#httpserverconnection-1]

```ts
new HTTPServerConnection(server: HTTPServer, socket: TCPSocket, opts?: HTTPServerConnectionOptions)
```

The per-socket state machine that parses incoming request data into `HTTPIncomingMessage`/`HTTPServerResponse` pairs for an `HTTPServer`.

**Parameters**

| Parameter | Type                                                          | Default | Description                                                                                  |
| --------- | ------------------------------------------------------------- | ------- | -------------------------------------------------------------------------------------------- |
| `server`  | `HTTPServer`                                                  | —       | The server the connection belongs to.                                                        |
| `socket`  | `TCPSocket`                                                   | —       | The connection socket.                                                                       |
| `opts?`   | [`HTTPServerConnectionOptions`](#httpserverconnectionoptions) | —       | Custom `IncomingMessage` and `ServerResponse` classes to use for requests on the connection. |

HTTPServerConnection.for(socket: TCPSocket): HTTPServerConnection [#httpserverconnectionforsocket-tcpsocket-httpserverconnection]

Returns the `HTTPServerConnection` associated with `socket`, or `null` if none exists.

**Parameters**

| Parameter | Type        | Default | Description            |
| --------- | ----------- | ------- | ---------------------- |
| `socket`  | `TCPSocket` | —       | The socket to look up. |

HTTPServerConnection.idle: boolean [#httpserverconnectionidle-boolean]

Whether the connection currently has no in-flight request.

req: HTTPIncomingMessage | null [#req-httpincomingmessage--null]

The `HTTPIncomingMessage` currently being read on this connection, or `null` if none.

res: HTTPServerResponse | null [#res-httpserverresponse--null]

The `HTTPServerResponse` currently being written on this connection, or `null` if none.

server: HTTPServer [#server-httpserver]

The `HTTPServer` this connection belongs to.

HTTPServerConnection.socket: TCPSocket | null [#httpserverconnectionsocket-tcpsocket--null]

The underlying `TCPSocket` for this connection.

HTTPClientRequest [#httpclientrequest]

new HTTPClientRequest(opts?: HTTPClientRequestOptions, onresponse?: () => void) [#new-httpclientrequestopts-httpclientrequestoptions-onresponse---void]

An outgoing HTTP request, extending `HTTPOutgoingMessage`. Uses chunked transfer encoding unless a `Content-Length` header is set or the method is `GET`/`HEAD`.

Overloads:

```ts
new HTTPClientRequest(opts?: HTTPClientRequestOptions, onresponse?: () => void)
new HTTPClientRequest(onresponse: () => void)
```

**Parameters**

| Parameter     | Type                                                    | Default | Description                                                                                                                                                                                                            |
| ------------- | ------------------------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `opts?`       | [`HTTPClientRequestOptions`](#httpclientrequestoptions) | —       | Request options; `method` defaults to `'GET'`, `path` to `'/'`, `host` to `'localhost'`, and `port` to the agent's default port (`80`). Set `agent` to choose the pooling agent, or `false` for a fresh, unpooled one. |
| `onresponse?` | `() => void`                                            | —       | Added as a one-time `'response'` listener.                                                                                                                                                                             |

**Throws**

* `INVALID_HEADER_NAME` — `method` or a header name is not a valid token.
* `INVALID_HEADER_VALUE` — `path` or a header value contains an invalid character.

HTTPClientRequest.headers: Record<string, string | number> [#httpclientrequestheaders-recordstring-string--number]

The headers to send with the request, keyed by lowercase name, including an auto-generated `host` header.

HTTPClientRequest.method: HTTPMethod [#httpclientrequestmethod-httpmethod]

The request method. Defaults to `'GET'`.

path: string [#path-string]

The request path. Defaults to `'/'`.

HTTPClientConnection [#httpclientconnection]

new HTTPClientConnection(socket: TCPSocket, opts?: HTTPClientConnectionOptions) [#new-httpclientconnectionsocket-tcpsocket-opts-httpclientconnectionoptions]

The per-socket state machine that parses response data for an `HTTPClientRequest`, and drives its `'response'` event.

**Parameters**

| Parameter | Type                                                          | Default | Description                                               |
| --------- | ------------------------------------------------------------- | ------- | --------------------------------------------------------- |
| `socket`  | `TCPSocket`                                                   | —       | The connection socket.                                    |
| `opts?`   | [`HTTPClientConnectionOptions`](#httpclientconnectionoptions) | —       | A custom `IncomingMessage` class to use for the response. |

HTTPClientConnection.for(socket: TCPSocket): HTTPClientConnection | null [#httpclientconnectionforsocket-tcpsocket-httpclientconnection--null]

Returns the `HTTPClientConnection` associated with `socket`, or `null` if none exists.

**Parameters**

| Parameter | Type        | Default | Description            |
| --------- | ----------- | ------- | ---------------------- |
| `socket`  | `TCPSocket` | —       | The socket to look up. |

HTTPClientConnection.from [#httpclientconnectionfrom]

```ts
HTTPClientConnection.from(socket: TCPSocket, opts?: HTTPClientConnectionOptions): HTTPClientConnection
```

Returns the existing `HTTPClientConnection` for `socket`, creating one with `opts` if none exists yet.

**Parameters**

| Parameter | Type                                                          | Default | Description                                       |
| --------- | ------------------------------------------------------------- | ------- | ------------------------------------------------- |
| `socket`  | `TCPSocket`                                                   | —       | The socket to look up or create a connection for. |
| `opts?`   | [`HTTPClientConnectionOptions`](#httpclientconnectionoptions) | —       | Options used if a new connection is created.      |

HTTPClientConnection.idle: boolean [#httpclientconnectionidle-boolean]

Whether the connection currently has no in-flight request.

req: HTTPClientRequest | null [#req-httpclientrequest--null]

The `HTTPClientRequest` currently in flight on this connection, or `null` if none.

res: HTTPIncomingMessage | null [#res-httpincomingmessage--null]

The `HTTPIncomingMessage` currently being read on this connection, or `null` if none.

HTTPClientConnection.socket: TCPSocket | null [#httpclientconnectionsocket-tcpsocket--null]

The underlying `TCPSocket` for this connection.

Functions [#functions]

createServer [#createserver]

```ts
createServer(opts?: HTTPServerConnectionOptions, onrequest?: (req: HTTPIncomingMessage, res: HTTPServerResponse) => void): HTTPServer
```

Creates an `HTTPServer`. If `onrequest` is given, it's added as a `'request'` listener.

**Parameters**

| Parameter    | Type                                                          | Default | Description                                                                                                   |
| ------------ | ------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------- |
| `opts?`      | [`HTTPServerConnectionOptions`](#httpserverconnectionoptions) | —       | Options passed to each `HTTPServerConnection`, such as custom `IncomingMessage` and `ServerResponse` classes. |
| `onrequest?` | `(req: HTTPIncomingMessage, res: HTTPServerResponse) => void` | —       | Added as a listener for the `'request'` event.                                                                |

request [#request]

```ts
request(url: URL | string, opts?: HTTPClientRequestOptions, onresponse?: (res: HTTPIncomingMessage) => void): HTTPClientRequest
```

Creates an `HTTPClientRequest` to `url` (a `URL` or a URL string). If `onresponse` is given, it's added as a one-time `'response'` listener. Does not send the request until it's ended.

**Parameters**

| Parameter     | Type                                                    | Default | Description                                                                                             |
| ------------- | ------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------- |
| `url`         | `URL` \| `string`                                       | —       | The URL to request, as a `URL` object or string; its host, port, and path populate the request options. |
| `opts?`       | [`HTTPClientRequestOptions`](#httpclientrequestoptions) | —       | Request options, merged over the values derived from `url`.                                             |
| `onresponse?` | `(res: HTTPIncomingMessage) => void`                    | —       | Added as a one-time `'response'` listener.                                                              |

get [#get]

```ts
get(url: URL | string, opts?: HTTPClientRequestOptions, onresponse?: (res: HTTPIncomingMessage) => void): HTTPClientRequest
```

Like `request()`, but ends the request immediately, since GET requests have no body.

**Parameters**

| Parameter     | Type                                                    | Default | Description                                                                                             |
| ------------- | ------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------- |
| `url`         | `URL` \| `string`                                       | —       | The URL to request, as a `URL` object or string; its host, port, and path populate the request options. |
| `opts?`       | [`HTTPClientRequestOptions`](#httpclientrequestoptions) | —       | Request options, merged over the values derived from `url`.                                             |
| `onresponse?` | `(res: HTTPIncomingMessage) => void`                    | —       | Added as a one-time `'response'` listener.                                                              |

Constants and variables [#constants-and-variables]

METHODS: HTTPMethod[] [#methods-httpmethod]

The list of all supported HTTP method names.

STATUS_CODES: typeof constants.status [#status_codes-typeof-constantsstatus]

An alias for `constants.status`, mapping status codes to their reason phrases.

globalAgent: HTTPAgent [#globalagent-httpagent]

The default `HTTPAgent` used by `request()` and `get()` when no `agent` option is given.

Types [#types]

HTTPMethod [#httpmethod]

```ts
type HTTPMethod = keyof typeof constants.method
```

A key of `constants.method`, that is one of the supported HTTP method names.

HTTPStatusCode [#httpstatuscode]

```ts
type HTTPStatusCode = keyof typeof constants.status
```

A key of `constants.status`, that is a supported HTTP status code.

HTTPStatusMessage [#httpstatusmessage]

```ts
type HTTPStatusMessage = (typeof constants.status)[HTTPStatusCode]
```

The reason phrase for a given `HTTPStatusCode`, as found in `constants.status`.

HTTPIncomingMessageEvents [#httpincomingmessageevents]

```ts
interface HTTPIncomingMessageEvents {
  timeout: []
  data: [data: unknown]
  end: []
  readable: []
  piping: [dest: Writable]
  close: []
  error: [err: Error]
}
```

The events an `HTTPIncomingMessage` emits in addition to the underlying readable stream's events: `timeout`, when the socket times out.

HTTPIncomingMessageOptions [#httpincomingmessageoptions]

```ts
interface HTTPIncomingMessageOptions {
  headers?: Record<string, string | number>
  method?: HTTPMethod
  url?: string
  statusCode?: HTTPStatusCode
  statusMessage?: HTTPStatusMessage
}
```

Options for constructing an `HTTPIncomingMessage` directly: initial `headers`, `method`, `url` (server-side), and `statusCode`/`statusMessage` (client-side).

HTTPOutgoingMessageEvents [#httpoutgoingmessageevents]

```ts
interface HTTPOutgoingMessageEvents {
  timeout: []
  drain: []
  finish: []
  pipe: [src: Readable]
  close: []
  error: [err: Error]
}
```

The events an `HTTPOutgoingMessage` emits in addition to the underlying writable stream's events: `timeout`, when the socket times out.

HTTPAgentOptions [#httpagentoptions]

```ts
interface HTTPAgentOptions {
  keepAlive?: boolean
  keepAliveMsecs?: number
}
```

Options for `HTTPAgent`. `keepAlive` keeps sockets open for reuse after a request completes, either `true` (using `keepAliveMsecs`) or a number of milliseconds. `keepAliveMsecs` is the keep-alive duration when `keepAlive` is `true`, defaulting to `1000`.

HTTPServerEvents [#httpserverevents]

```ts
interface HTTPServerEvents {
  request: [req: HTTPIncomingMessage, res: HTTPServerResponse]
  upgrade: [req: HTTPIncomingMessage, socket: TCPSocket, head: Buffer]
  timeout: [socket: TCPSocket]
  close: []
  connection: [socket: TCPSocket]
  drop: [info: TCPServerDropInfo]
  error: [err: Error]
  listening: []
  lookup: [err: Error | null, address: string | null, family: IPFamily | 0, host: string]
}
```

The events an `HTTPServer` emits in addition to the underlying TCP server's events: `request`, for each incoming request; `timeout`, when a connection's socket times out; `upgrade`, when a connection is upgraded (for example to a WebSocket).

HTTPServerConnectionOptions [#httpserverconnectionoptions]

```ts
interface HTTPServerConnectionOptions {
  IncomingMessage?: typeof HTTPIncomingMessage
  ServerResponse?: typeof HTTPServerResponse
}
```

Options for `HTTPServerConnection`, letting custom `IncomingMessage` and `ServerResponse` subclasses be used for requests handled on the connection.

HTTPClientRequestEvents [#httpclientrequestevents]

```ts
interface HTTPClientRequestEvents {
  response: [res: HTTPIncomingMessage]
  upgrade: [res: HTTPIncomingMessage, socket: TCPSocket, head: Buffer]
  timeout: []
  drain: []
  finish: []
  pipe: [src: Readable]
  close: []
  error: [err: Error]
}
```

The events an `HTTPClientRequest` emits in addition to the underlying writable stream's events: `response`, with the `HTTPIncomingMessage` reply; `upgrade`, when the connection is upgraded (for example to a WebSocket).

HTTPClientRequestOptions [#httpclientrequestoptions]

```ts
interface HTTPClientRequestOptions {
  agent?: HTTPAgent | false
  headers?: Record<string, string | number>
  method?: HTTPMethod
  path?: string
  lookup?: DNSLookup
  host?: string
  keepAlive?: boolean
  keepAliveInitialDelay?: boolean
  noDelay?: boolean
  port?: number
  timeout?: number
  family?: `IPv${IPFamily}` | IPFamily | 0
  hints?: number
  all?: boolean
}
```

Options for `HTTPClientRequest`: the `agent` to use (or `false` for a fresh, unpooled one), request `headers`, `method` (default `'GET'`), and `path` (default `'/'`).

HTTPClientConnectionOptions [#httpclientconnectionoptions]

```ts
interface HTTPClientConnectionOptions {
  IncomingMessage?: typeof HTTPIncomingMessage
}
```

Options for `HTTPClientConnection`, letting a custom `IncomingMessage` subclass be used for the response.

Classes [#classes]

HTTPError [#httperror]

```ts
class HTTPError {
  code: string
}
```

An error thrown by `bare-http1` for protocol-level failures, such as an unimplemented method, a lost connection, a suspended agent, or an invalid header. Carries a `code` identifying the specific failure.

bare-http1/constants [#bare-http1constants]

constants [#constants-1]

constants.constants.HTTPMethod [#constantsconstantshttpmethod]

```ts
type HTTPMethod = keyof typeof constants.method
```

A key of `constants.method`, that is one of the supported HTTP method names.

constants.constants.HTTPStatusCode [#constantsconstantshttpstatuscode]

```ts
type HTTPStatusCode = keyof typeof constants.status
```

A key of `constants.status`, that is a supported HTTP status code.

constants.constants.HTTPStatusMessage [#constantsconstantshttpstatusmessage]

```ts
type HTTPStatusMessage = (typeof constants.status)[HTTPStatusCode]
```

The reason phrase for a given `HTTPStatusCode`, as found in `constants.status`.

bare-http1/errors [#bare-http1errors]

Classes [#classes-1]

errors.HTTPError [#errorshttperror]

An error thrown by `bare-http1` for protocol-level failures, such as an unimplemented method, a lost connection, a suspended agent, or an invalid header. Carries a `code` identifying the specific failure.

See also [#see-also]

* Builds on `bare-events`, `bare-http-parser`, `bare-stream`, and `bare-tcp`.
* [Bare modules](/reference/modules/bare-modules) — the full `bare-*` catalog.
* [Bare runtime API](/reference/bare/runtime) — the runtime these modules extend.


# bare-https



<mark style={{ backgroundColor: '#7dde9a', padding: '2px 8px', borderRadius: '4px', fontSize: '0.85em', fontWeight: 500 }}>
  stable
</mark>

[`bare-https`](https://github.com/holepunchto/bare-https) — HTTPS library for JavaScript.

Mirrors the Node.js [`https`](https://nodejs.org/api/https.html) module.

```sh
npm i bare-https
```

Usage [#usage]

```js
const https = require('bare-https')

const options = {
  cert: fs.readFileSync('test/fixtures/cert.crt'),
  key: fs.readFileSync('test/fixtures/cert.key')
}

const server = https.createServer(options, (req, res) => {
  res.statusCode = 200
  res.setHeader('Content-Length', 10)
  res.write('hello world!')
  res.end()
})

server.listen(0, () => {
  const { port } = server.address()
  console.log('server is bound on', port)

  const client = https.request({ port }, (res) => {
    res.on('data', (data) => console.log(data.toString()))
  })
  client.end()
})
```

API [#api]

HTTPSAgent [#httpsagent]

createConnection(opts?: HTTPSSocketOptions): HTTPSSocket [#createconnectionopts-httpssocketoptions-httpssocket]

Creates a new `HTTPSSocket` connection wrapping a plain TCP connection in TLS.

**Parameters**

| Parameter | Type                                        | Default | Description                                                    |
| --------- | ------------------------------------------- | ------- | -------------------------------------------------------------- |
| `opts?`   | [`HTTPSSocketOptions`](#httpssocketoptions) | —       | Options for the underlying TCP connection and its TLS wrapper. |

HTTPSAgent.global: HTTPSAgent [#httpsagentglobal-httpsagent]

The agent's own default instance (created with `keepAlive: 1000` and `timeout: 5000`), used as `bare-https`'s `globalAgent`.

HTTPSServer [#httpsserver]

HTTPSServer [#httpsserver-1]

```ts
new HTTPSServer(opts?: HTTPSServerOptions, onrequest?: (req: HTTPIncomingMessage, res: HTTPServerResponse) => void)
```

An HTTPS server, reusing `bare-http1`'s request parsing and response handling over `HTTPSSocket` connections instead of plain `TCPSocket` connections.

**Parameters**

| Parameter    | Type                                                          | Default | Description                                                                                                 |
| ------------ | ------------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------- |
| `opts?`      | `HTTPSServerOptions`                                          | —       | Server options: TLS socket options (for example `cert`, `key`) plus `bare-http1` server connection options. |
| `onrequest?` | `(req: HTTPIncomingMessage, res: HTTPServerResponse) => void` | —       | Added as a `'request'` listener.                                                                            |

HTTPSClientRequest [#httpsclientrequest]

new HTTPSClientRequest(opts?: HTTPSClientRequestOptions, onresponse?: () => void) [#new-httpsclientrequestopts-httpsclientrequestoptions-onresponse---void]

An outgoing HTTPS request, extending `bare-http1`'s `HTTPClientRequest` but defaulting to an `HTTPSAgent` instead of an `HTTPAgent`.

Overloads:

```ts
new HTTPSClientRequest(opts?: HTTPSClientRequestOptions, onresponse?: () => void)
new HTTPSClientRequest(onresponse: () => void)
```

**Parameters**

| Parameter     | Type                        | Default | Description                                                                                                                       |
| ------------- | --------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `opts?`       | `HTTPSClientRequestOptions` | —       | `bare-http1` client request options; `agent` defaults to `HTTPSAgent.global`, or pass `agent: false` to use a fresh `HTTPSAgent`. |
| `onresponse?` | `() => void`                | —       | Added as a one-time `'response'` listener.                                                                                        |

Functions [#functions]

createServer [#createserver]

```ts
createServer(opts?: HTTPSServerOptions, onrequest?: (req: HTTPIncomingMessage, res: HTTPServerResponse) => void): HTTPSServer
```

Creates an `HTTPSServer`. If `onrequest` is given, it's added as a `'request'` listener.

**Parameters**

| Parameter    | Type                                                          | Default | Description                                                                                                 |
| ------------ | ------------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------- |
| `opts?`      | `HTTPSServerOptions`                                          | —       | Server options: TLS socket options (for example `cert`, `key`) plus `bare-http1` server connection options. |
| `onrequest?` | `(req: HTTPIncomingMessage, res: HTTPServerResponse) => void` | —       | Added as a `'request'` listener.                                                                            |

request [#request]

```ts
request(url: URL | string, opts?: HTTPSClientRequestOptions, onresponse?: (res: HTTPIncomingMessage) => void): HTTPSClientRequest
```

Creates an `HTTPSClientRequest` to `url` (a `URL` or a URL string), using TLS. If `onresponse` is given, it's added as a one-time `'response'` listener. Does not send the request until it's ended.

**Parameters**

| Parameter     | Type                                 | Default | Description                                                                                                                 |
| ------------- | ------------------------------------ | ------- | --------------------------------------------------------------------------------------------------------------------------- |
| `url`         | `URL` \| `string`                    | —       | The URL to request, as a `URL` object or a URL string.                                                                      |
| `opts?`       | `HTTPSClientRequestOptions`          | —       | `bare-http1` client request options; `agent` defaults to `globalAgent`, or pass `agent: false` to use a fresh `HTTPSAgent`. |
| `onresponse?` | `(res: HTTPIncomingMessage) => void` | —       | Added as a one-time `'response'` listener.                                                                                  |

Constants and variables [#constants-and-variables]

globalAgent: HTTPSAgent [#globalagent-httpsagent]

The default `HTTPSAgent` used by `request()` when no `agent` option is given.

Types [#types]

HTTPSSocketEvents [#httpssocketevents]

```ts
interface HTTPSSocketEvents {
  connect: []
  data: [data: unknown]
  end: []
  readable: []
  piping: [dest: Writable]
  close: []
  error: [err: Error]
  drain: []
  finish: []
  pipe: [src: Readable]
  lookup: [err: Error | null, address: string | null, family: IPFamily | 0, host: string]
  timeout: [ms: number]
}
```

The events an `HTTPSSocket` emits: those of both `TLSSocket` and `TCPSocket`.

HTTPSSocketOptions [#httpssocketoptions]

```ts
interface HTTPSSocketOptions {
  isServer?: boolean
  cert?: ArrayBufferView
  key?: ArrayBufferView
  host?: string
  rejectUnauthorized?: boolean
  ca?: ArrayBufferView
  alpnProtocols?: string[]
  eagerOpen?: boolean
  allowHalfOpen?: boolean
  readBufferSize?: number
  lookup?: DNSLookup
  keepAlive?: boolean
  keepAliveInitialDelay?: boolean
  noDelay?: boolean
  port?: number
  timeout?: number
  family?: `IPv${IPFamily}` | IPFamily | 0
  hints?: number
  all?: boolean
}
```

Options for `HTTPSSocket`: those of `TLSSocket` combined with `TCPSocket`'s connection options.

Classes [#classes]

HTTPSSocket [#httpssocket]

```ts
class HTTPSSocket {
}
```

A `TCPSocket` wrapped in TLS, extending both `TLSSocket` and `TCPSocket`. Used as the transport for HTTPS requests and responses.

See also [#see-also]

* Builds on `bare-http1`, `bare-tcp`, and `bare-tls`.
* [Bare modules](/reference/modules/bare-modules) — the full `bare-*` catalog.
* [Bare runtime API](/reference/bare/runtime) — the runtime these modules extend.


# bare-inspect



<mark style={{ backgroundColor: '#7dde9a', padding: '2px 8px', borderRadius: '4px', fontSize: '0.85em', fontWeight: 500 }}>
  stable
</mark>

[`bare-inspect`](https://github.com/holepunchto/bare-inspect) — Inspect objects as strings for debugging. It is a native addon and requires Bare `>=1.18.0`.

```sh
npm i bare-inspect
```

Usage [#usage]

```js
const inspect = require('bare-inspect')

console.log(inspect(globalThis))
```

API [#api]

Functions [#functions]

inspect(value: unknown, opts?: InspectOptions): string [#inspectvalue-unknown-opts-inspectoptions-string]

Returns a string representation of `value` for debugging, similar to Node's `util.inspect()`. If `value` has a `Symbol.for('bare.inspect')` or `Symbol.for('nodejs.util.inspect.custom')` method, it is used to produce the output.

**Parameters**

| Parameter | Type                                | Default | Description                                      |
| --------- | ----------------------------------- | ------- | ------------------------------------------------ |
| `value`   | `unknown`                           | —       | The value to produce a string representation of. |
| `opts?`   | [`InspectOptions`](#inspectoptions) | —       | Formatting options; see `InspectOptions`.        |

Constants and variables [#constants-and-variables]

inspect.styles [#inspectstyles]

```ts
inspect.styles: {
    bigint: string
    boolean: string
    date: string
    module: string
    name: string
    null: string
    number: string
    regexp: string
    special: string
    string: string
    symbol: string
    undefined: string
  }
```

Types [#types]

InspectOptions [#inspectoptions]

```ts
interface InspectOptions {
  colors?: boolean
  depth?: number
  breakLength?: number
  stylize?: InspectStylize
}
```

Options for `inspect()`. `colors` enables ANSI styling, `depth` limits how many levels of nested objects are inspected (defaults to `2`), `breakLength` sets the line-wrap width (defaults to `80`), and `stylize` is a custom function for applying styles to values.

InspectStylize [#inspectstylize]

```ts
interface InspectStylize {
}
```

A function that applies a named style (such as `'string'` or `'number'`) to a value before it's included in the output.

See also [#see-also]

* Builds on `bare-ansi-escapes` and `bare-type`.
* [Bare modules](/reference/modules/bare-modules) — the full `bare-*` catalog.
* [Bare runtime API](/reference/bare/runtime) — the runtime these modules extend.


# bare-inspector



<mark style={{ backgroundColor: '#7dde9a', padding: '2px 8px', borderRadius: '4px', fontSize: '0.85em', fontWeight: 500 }}>
  stable
</mark>

[`bare-inspector`](https://github.com/holepunchto/bare-inspector) — V8 inspector support for Bare. It is a native addon and requires Bare `>=1.29.0`.

Mirrors the Node.js [`inspector`](https://nodejs.org/api/inspector.html) module.

```sh
npm i bare-inspector
```

Usage [#usage]

```js
const { Session } = require('bare-inspector')

const session = new Session()
session.connect()

try {
  const { result } = await session.post('Runtime.evaluate', {
    expression: '1 + 2'
  })

  console.log(result)
} catch (err) {
  console.error(err)
}
```

Heap snapshots [#heap-snapshots]

```js
const { Session, HeapSnapshot } = require('bare-inspector')
const fs = require('bare-fs')

const session = new Session()
session.connect()

const snapshot = new HeapSnapshot(session)

snapshot.pipe(fs.createWriteStream('profile.heapsnapshot'))
```

API [#api]

Console [#console]

Console.assert(condition: unknown, ...data: unknown[]): void [#consoleassertcondition-unknown-data-unknown-void]

**Parameters**

| Parameter   | Type        | Default | Description                                                  |
| ----------- | ----------- | ------- | ------------------------------------------------------------ |
| `condition` | `unknown`   | —       | The value to test; the assertion logs only when it is falsy. |
| `data`      | `unknown[]` | —       | The values to log when `condition` is falsy.                 |

Console.clear(): void [#consoleclear-void]

Console.DirOptions [#consolediroptions]

```ts
interface DirOptions {
  colors?: number
  depth?: number
  showHidden?: boolean
}
```

Options for `dir()`: `colors`, `depth`, and `showHidden`, matching `util.inspect()`'s options of the same names.

Console.count(label?: string): void [#consolecountlabel-string-void]

**Parameters**

| Parameter | Type     | Default | Description               |
| --------- | -------- | ------- | ------------------------- |
| `label?`  | `string` | —       | The label of the counter. |

Console.countReset(label?: string): void [#consolecountresetlabel-string-void]

**Parameters**

| Parameter | Type     | Default | Description                        |
| --------- | -------- | ------- | ---------------------------------- |
| `label?`  | `string` | —       | The label of the counter to reset. |

Console.debug(...data: unknown[]): void [#consoledebugdata-unknown-void]

**Parameters**

| Parameter | Type        | Default | Description        |
| --------- | ----------- | ------- | ------------------ |
| `data`    | `unknown[]` | —       | The values to log. |

Console.dir(object: unknown, opts?: DirOptions): void [#consoledirobject-unknown-opts-diroptions-void]

**Parameters**

| Parameter | Type         | Default | Description                                              |
| --------- | ------------ | ------- | -------------------------------------------------------- |
| `object`  | `unknown`    | —       | The object to inspect.                                   |
| `opts?`   | `DirOptions` | —       | Inspection options: `colors`, `depth`, and `showHidden`. |

Console.dirxml(...data: unknown[]): void [#consoledirxmldata-unknown-void]

**Parameters**

| Parameter | Type        | Default | Description        |
| --------- | ----------- | ------- | ------------------ |
| `data`    | `unknown[]` | —       | The values to log. |

Console.error(...data: unknown[]): void [#consoleerrordata-unknown-void]

**Parameters**

| Parameter | Type        | Default | Description        |
| --------- | ----------- | ------- | ------------------ |
| `data`    | `unknown[]` | —       | The values to log. |

Console.group(...data: unknown[]): void [#consolegroupdata-unknown-void]

**Parameters**

| Parameter | Type        | Default | Description                             |
| --------- | ----------- | ------- | --------------------------------------- |
| `data`    | `unknown[]` | —       | The values to log as the group heading. |

Console.groupCollapsed(...data: unknown[]): void [#consolegroupcollapseddata-unknown-void]

**Parameters**

| Parameter | Type        | Default | Description                             |
| --------- | ----------- | ------- | --------------------------------------- |
| `data`    | `unknown[]` | —       | The values to log as the group heading. |

Console.groupEnd(): void [#consolegroupend-void]

Console.info(...data: unknown[]): void [#consoleinfodata-unknown-void]

**Parameters**

| Parameter | Type        | Default | Description        |
| --------- | ----------- | ------- | ------------------ |
| `data`    | `unknown[]` | —       | The values to log. |

Console.log(...data: unknown[]): void [#consolelogdata-unknown-void]

**Parameters**

| Parameter | Type        | Default | Description        |
| --------- | ----------- | ------- | ------------------ |
| `data`    | `unknown[]` | —       | The values to log. |

Console.profile(label?: string): void [#consoleprofilelabel-string-void]

**Parameters**

| Parameter | Type     | Default | Description               |
| --------- | -------- | ------- | ------------------------- |
| `label?`  | `string` | —       | The label of the profile. |

Console.profileEnd(label?: string): void [#consoleprofileendlabel-string-void]

**Parameters**

| Parameter | Type     | Default | Description                       |
| --------- | -------- | ------- | --------------------------------- |
| `label?`  | `string` | —       | The label of the profile to stop. |

Console.table(data: unknown, props?: string[]): void [#consoletabledata-unknown-props-string-void]

**Parameters**

| Parameter | Type       | Default | Description                               |
| --------- | ---------- | ------- | ----------------------------------------- |
| `data`    | `unknown`  | —       | The tabular data to display.              |
| `props?`  | `string[]` | —       | The property names to include as columns. |

Console.time(label?: string): void [#consoletimelabel-string-void]

**Parameters**

| Parameter | Type     | Default | Description             |
| --------- | -------- | ------- | ----------------------- |
| `label?`  | `string` | —       | The label of the timer. |

Console.timeEnd(label?: string): void [#consoletimeendlabel-string-void]

**Parameters**

| Parameter | Type     | Default | Description                     |
| --------- | -------- | ------- | ------------------------------- |
| `label?`  | `string` | —       | The label of the timer to stop. |

Console.timeLog(label?: string, ...data: unknown[]): void [#consoletimeloglabel-string-data-unknown-void]

**Parameters**

| Parameter | Type        | Default | Description                                          |
| --------- | ----------- | ------- | ---------------------------------------------------- |
| `label?`  | `string`    | —       | The label of the timer.                              |
| `data`    | `unknown[]` | —       | Additional values to log alongside the elapsed time. |

Console.timeStamp(label?: string): void [#consoletimestamplabel-string-void]

**Parameters**

| Parameter | Type     | Default | Description                        |
| --------- | -------- | ------- | ---------------------------------- |
| `label?`  | `string` | —       | The label of the timestamp marker. |

Console.trace(...data: unknown[]): void [#consoletracedata-unknown-void]

**Parameters**

| Parameter | Type        | Default | Description                             |
| --------- | ----------- | ------- | --------------------------------------- |
| `data`    | `unknown[]` | —       | The values to log with the stack trace. |

Console.warn(...data: unknown[]): void [#consolewarndata-unknown-void]

**Parameters**

| Parameter | Type        | Default | Description        |
| --------- | ----------- | ------- | ------------------ |
| `data`    | `unknown[]` | —       | The values to log. |

Session [#session]

new Session(onpaused?: () => boolean) [#new-sessiononpaused---boolean]

Dispatches messages to the V8 inspector back-end and receives responses and notifications, mirroring Node's `inspector.Session`. `onpaused` is called whenever the debugger pauses; return `true` to keep the pause, or a falsy value to resume immediately.

**Parameters**

| Parameter   | Type            | Default | Description                                                                                                                         |
| ----------- | --------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `onpaused?` | `() => boolean` | —       | Called whenever the debugger pauses; return `true` to keep the pause, or a falsy value to resume immediately (the default resumes). |

Session.connect(): void [#sessionconnect-void]

Connects the session to the inspector back-end, enabling `post()` to send messages. A no-op if already connected or destroyed.

Session.connected: boolean [#sessionconnected-boolean]

Whether the session is connected and not destroyed.

Session.destroy(): void [#sessiondestroy-void]

Destroys the session, releasing its inspector back-end handle. A no-op if already destroyed.

Session.destroyed: boolean [#sessiondestroyed-boolean]

Whether the session has been destroyed.

Session.post [#sessionpost]

```ts
post<T extends unknown = unknown>(method: string, cb: (err: Error, result: T) => void): Promise<T>
```

Posts `method` (with optional `params`) to the inspector back-end. Resolves or calls `cb` with the result, or with an `Error` if the inspector returns one.

**Parameters**

| Parameter | Type                              | Default | Description                                                            |
| --------- | --------------------------------- | ------- | ---------------------------------------------------------------------- |
| `method`  | `string`                          | —       | The inspector protocol method name (for example `'Runtime.evaluate'`). |
| `cb`      | `(err: Error, result: T) => void` | —       | Called with the error or result; when given, no promise is returned.   |

**Returns** `Promise<T>` — A promise settling with the inspector's response, or `undefined` when `cb` is given.

Session.InspectorSessionEvents [#sessioninspectorsessionevents]

```ts
interface InspectorSessionEvents {
  inspectorNotification: [message: SessionMessage]
}
```

The events a `Session` emits: `inspectorNotification` for every inspector notification, and one event per inspector protocol method name (for example `'Debugger.paused'`) carrying the same message.

Session.SessionMessage [#sessionsessionmessage]

```ts
interface SessionMessage {
  method: string
  params: Record<string, unknown>
}
```

An inspector protocol notification: the `method` name and its `params`.

Server [#server]

new Server(opts: InspectorServerOptions) [#new-serveropts-inspectorserveroptions]

A WebSocket server exposing a `Session` for remote debugging, compatible with Chrome DevTools and mirroring the endpoints Node's `--inspect` exposes (`/json/list` and a WebSocket debugger URL).

Overloads:

```ts
new Server(opts: InspectorServerOptions)
new Server(port: number, opts: InspectorServerOptions)
new Server(port: number, host: string, opts?: InspectorServerOptions)
```

**Parameters**

| Parameter | Type                     | Default | Description                                                                                 |
| --------- | ------------------------ | ------- | ------------------------------------------------------------------------------------------- |
| `opts`    | `InspectorServerOptions` | —       | Options; `path` is the script URL reported to DevTools and defaults to `require.main.path`. |

Server.address(): TCPSocketAddress [#serveraddress-tcpsocketaddress]

Returns the address the server is listening on.

Server.close(cb?: (err?: Error | null) => void): this [#serverclosecb-err-error--null--void-this]

Stops the server from accepting new connections, destroys existing connections and the underlying debugger session, and calls `cb` once closed.

**Parameters**

| Parameter | Type                            | Default | Description                                   |
| --------- | ------------------------------- | ------- | --------------------------------------------- |
| `cb?`     | `(err?: Error \| null) => void` | —       | Called once the underlying server has closed. |

Server.listening: boolean [#serverlistening-boolean]

Whether the server is currently listening for connections.

Server.ref(): this [#serverref-this]

Marks the server so the event loop won't exit while it's listening.

Server.InspectorServerEvents [#serverinspectorserverevents]

```ts
interface InspectorServerEvents {
  listening: []
}
```

The events an inspector `Server` emits: `listening`, once the server starts listening.

Server.InspectorServerOptions [#serverinspectorserveroptions]

```ts
interface InspectorServerOptions {
  path: URL | string
}
```

Options for `Server`: `path`, the entry-point URL reported to DevTools as the URL of the inspected script.

Server.unref(): this [#serverunref-this]

Unmarks the server so the event loop can exit even while it's listening.

HeapSnapshot [#heapsnapshot]

new HeapSnapshot(session: Session) [#new-heapsnapshotsession-session]

A readable stream of a V8 heap snapshot taken over `session`, using the inspector protocol's `HeapProfiler.takeHeapSnapshot`. Pipe it to a file (for example with a `.heapsnapshot` extension) to load it in Chrome DevTools, or async-iterate it with `for await (const chunk of snapshot)`, receiving it as a sequence of `Buffer` chunks.

**Parameters**

| Parameter | Type      | Default | Description                                        |
| --------- | --------- | ------- | -------------------------------------------------- |
| `session` | `Session` | —       | The connected `Session` to take the snapshot over. |

bare-inspector/console [#bare-inspectorconsole]

InspectorConsole [#inspectorconsole]

InspectorConsole.assert(condition: unknown, ...data: unknown[]): void [#inspectorconsoleassertcondition-unknown-data-unknown-void]

**Parameters**

| Parameter   | Type        | Default | Description                                                  |
| ----------- | ----------- | ------- | ------------------------------------------------------------ |
| `condition` | `unknown`   | —       | The value to test; the assertion logs only when it is falsy. |
| `data`      | `unknown[]` | —       | The values to log when `condition` is falsy.                 |

InspectorConsole.clear(): void [#inspectorconsoleclear-void]

InspectorConsole.count(label?: string): void [#inspectorconsolecountlabel-string-void]

**Parameters**

| Parameter | Type     | Default | Description               |
| --------- | -------- | ------- | ------------------------- |
| `label?`  | `string` | —       | The label of the counter. |

InspectorConsole.countReset(label?: string): void [#inspectorconsolecountresetlabel-string-void]

**Parameters**

| Parameter | Type     | Default | Description                        |
| --------- | -------- | ------- | ---------------------------------- |
| `label?`  | `string` | —       | The label of the counter to reset. |

InspectorConsole.debug(...data: unknown[]): void [#inspectorconsoledebugdata-unknown-void]

**Parameters**

| Parameter | Type        | Default | Description        |
| --------- | ----------- | ------- | ------------------ |
| `data`    | `unknown[]` | —       | The values to log. |

InspectorConsole.dir(object: unknown, opts?: DirOptions): void [#inspectorconsoledirobject-unknown-opts-diroptions-void]

**Parameters**

| Parameter | Type         | Default | Description                                              |
| --------- | ------------ | ------- | -------------------------------------------------------- |
| `object`  | `unknown`    | —       | The object to inspect.                                   |
| `opts?`   | `DirOptions` | —       | Inspection options: `colors`, `depth`, and `showHidden`. |

InspectorConsole.dirxml(...data: unknown[]): void [#inspectorconsoledirxmldata-unknown-void]

**Parameters**

| Parameter | Type        | Default | Description        |
| --------- | ----------- | ------- | ------------------ |
| `data`    | `unknown[]` | —       | The values to log. |

InspectorConsole.error(...data: unknown[]): void [#inspectorconsoleerrordata-unknown-void]

**Parameters**

| Parameter | Type        | Default | Description        |
| --------- | ----------- | ------- | ------------------ |
| `data`    | `unknown[]` | —       | The values to log. |

InspectorConsole.group(...data: unknown[]): void [#inspectorconsolegroupdata-unknown-void]

**Parameters**

| Parameter | Type        | Default | Description                             |
| --------- | ----------- | ------- | --------------------------------------- |
| `data`    | `unknown[]` | —       | The values to log as the group heading. |

InspectorConsole.groupCollapsed(...data: unknown[]): void [#inspectorconsolegroupcollapseddata-unknown-void]

**Parameters**

| Parameter | Type        | Default | Description                             |
| --------- | ----------- | ------- | --------------------------------------- |
| `data`    | `unknown[]` | —       | The values to log as the group heading. |

InspectorConsole.groupEnd(): void [#inspectorconsolegroupend-void]

InspectorConsole.info(...data: unknown[]): void [#inspectorconsoleinfodata-unknown-void]

**Parameters**

| Parameter | Type        | Default | Description        |
| --------- | ----------- | ------- | ------------------ |
| `data`    | `unknown[]` | —       | The values to log. |

InspectorConsole.log(...data: unknown[]): void [#inspectorconsolelogdata-unknown-void]

**Parameters**

| Parameter | Type        | Default | Description        |
| --------- | ----------- | ------- | ------------------ |
| `data`    | `unknown[]` | —       | The values to log. |

InspectorConsole.profile(label?: string): void [#inspectorconsoleprofilelabel-string-void]

**Parameters**

| Parameter | Type     | Default | Description               |
| --------- | -------- | ------- | ------------------------- |
| `label?`  | `string` | —       | The label of the profile. |

InspectorConsole.profileEnd(label?: string): void [#inspectorconsoleprofileendlabel-string-void]

**Parameters**

| Parameter | Type     | Default | Description                       |
| --------- | -------- | ------- | --------------------------------- |
| `label?`  | `string` | —       | The label of the profile to stop. |

InspectorConsole.table(data: unknown, props?: string[]): void [#inspectorconsoletabledata-unknown-props-string-void]

**Parameters**

| Parameter | Type       | Default | Description                               |
| --------- | ---------- | ------- | ----------------------------------------- |
| `data`    | `unknown`  | —       | The tabular data to display.              |
| `props?`  | `string[]` | —       | The property names to include as columns. |

InspectorConsole.time(label?: string): void [#inspectorconsoletimelabel-string-void]

**Parameters**

| Parameter | Type     | Default | Description             |
| --------- | -------- | ------- | ----------------------- |
| `label?`  | `string` | —       | The label of the timer. |

InspectorConsole.timeEnd(label?: string): void [#inspectorconsoletimeendlabel-string-void]

**Parameters**

| Parameter | Type     | Default | Description                     |
| --------- | -------- | ------- | ------------------------------- |
| `label?`  | `string` | —       | The label of the timer to stop. |

InspectorConsole.timeLog(label?: string, ...data: unknown[]): void [#inspectorconsoletimeloglabel-string-data-unknown-void]

**Parameters**

| Parameter | Type        | Default | Description                                          |
| --------- | ----------- | ------- | ---------------------------------------------------- |
| `label?`  | `string`    | —       | The label of the timer.                              |
| `data`    | `unknown[]` | —       | Additional values to log alongside the elapsed time. |

InspectorConsole.timeStamp(label?: string): void [#inspectorconsoletimestamplabel-string-void]

**Parameters**

| Parameter | Type     | Default | Description                        |
| --------- | -------- | ------- | ---------------------------------- |
| `label?`  | `string` | —       | The label of the timestamp marker. |

InspectorConsole.trace(...data: unknown[]): void [#inspectorconsoletracedata-unknown-void]

**Parameters**

| Parameter | Type        | Default | Description                             |
| --------- | ----------- | ------- | --------------------------------------- |
| `data`    | `unknown[]` | —       | The values to log with the stack trace. |

InspectorConsole.warn(...data: unknown[]): void [#inspectorconsolewarndata-unknown-void]

**Parameters**

| Parameter | Type        | Default | Description        |
| --------- | ----------- | ------- | ------------------ |
| `data`    | `unknown[]` | —       | The values to log. |

Types [#types]

DirOptions [#diroptions]

```ts
interface DirOptions {
  colors?: number
  depth?: number
  showHidden?: boolean
}
```

Options for `dir()`: `colors`, `depth`, and `showHidden`, matching `util.inspect()`'s options of the same names.

bare-inspector/session [#bare-inspectorsession]

InspectorSession [#inspectorsession]

new InspectorSession(onpaused?: () => boolean) [#new-inspectorsessiononpaused---boolean]

Dispatches messages to the V8 inspector back-end and receives responses and notifications, mirroring Node's `inspector.Session`. `onpaused` is called whenever the debugger pauses; return `true` to keep the pause, or a falsy value to resume immediately.

**Parameters**

| Parameter   | Type            | Default | Description                                                                                                                         |
| ----------- | --------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `onpaused?` | `() => boolean` | —       | Called whenever the debugger pauses; return `true` to keep the pause, or a falsy value to resume immediately (the default resumes). |

InspectorSession.connect(): void [#inspectorsessionconnect-void]

Connects the session to the inspector back-end, enabling `post()` to send messages. A no-op if already connected or destroyed.

InspectorSession.connected: boolean [#inspectorsessionconnected-boolean]

Whether the session is connected and not destroyed.

InspectorSession.destroy(): void [#inspectorsessiondestroy-void]

Destroys the session, releasing its inspector back-end handle. A no-op if already destroyed.

InspectorSession.destroyed: boolean [#inspectorsessiondestroyed-boolean]

Whether the session has been destroyed.

InspectorSession.post [#inspectorsessionpost]

```ts
post<T extends unknown = unknown>(method: string, cb: (err: Error, result: T) => void): Promise<T>
```

Posts `method` (with optional `params`) to the inspector back-end. Resolves or calls `cb` with the result, or with an `Error` if the inspector returns one.

**Parameters**

| Parameter | Type                              | Default | Description                                                            |
| --------- | --------------------------------- | ------- | ---------------------------------------------------------------------- |
| `method`  | `string`                          | —       | The inspector protocol method name (for example `'Runtime.evaluate'`). |
| `cb`      | `(err: Error, result: T) => void` | —       | Called with the error or result; when given, no promise is returned.   |

**Returns** `Promise<T>` — A promise settling with the inspector's response, or `undefined` when `cb` is given.

Types [#types-1]

SessionMessage [#sessionmessage]

```ts
interface SessionMessage {
  method: string
  params: Record<string, unknown>
}
```

An inspector protocol notification: the `method` name and its `params`.

InspectorSessionEvents [#inspectorsessionevents]

```ts
interface InspectorSessionEvents {
  inspectorNotification: [message: SessionMessage]
}
```

The events a `Session` emits: `inspectorNotification` for every inspector notification, and one event per inspector protocol method name (for example `'Debugger.paused'`) carrying the same message.

bare-inspector/server [#bare-inspectorserver]

InspectorServer [#inspectorserver]

new InspectorServer(opts: InspectorServerOptions) [#new-inspectorserveropts-inspectorserveroptions]

A WebSocket server exposing a `Session` for remote debugging, compatible with Chrome DevTools and mirroring the endpoints Node's `--inspect` exposes (`/json/list` and a WebSocket debugger URL).

Overloads:

```ts
new InspectorServer(opts: InspectorServerOptions)
new InspectorServer(port: number, opts: InspectorServerOptions)
new InspectorServer(port: number, host: string, opts?: InspectorServerOptions)
```

**Parameters**

| Parameter | Type                     | Default | Description                                                                                 |
| --------- | ------------------------ | ------- | ------------------------------------------------------------------------------------------- |
| `opts`    | `InspectorServerOptions` | —       | Options; `path` is the script URL reported to DevTools and defaults to `require.main.path`. |

InspectorServer.address(): TCPSocketAddress [#inspectorserveraddress-tcpsocketaddress]

Returns the address the server is listening on.

InspectorServer.close(cb?: (err?: Error | null) => void): this [#inspectorserverclosecb-err-error--null--void-this]

Stops the server from accepting new connections, destroys existing connections and the underlying debugger session, and calls `cb` once closed.

**Parameters**

| Parameter | Type                            | Default | Description                                   |
| --------- | ------------------------------- | ------- | --------------------------------------------- |
| `cb?`     | `(err?: Error \| null) => void` | —       | Called once the underlying server has closed. |

InspectorServer.listening: boolean [#inspectorserverlistening-boolean]

Whether the server is currently listening for connections.

InspectorServer.ref(): this [#inspectorserverref-this]

Marks the server so the event loop won't exit while it's listening.

InspectorServer.unref(): this [#inspectorserverunref-this]

Unmarks the server so the event loop can exit even while it's listening.

Types [#types-2]

InspectorServerEvents [#inspectorserverevents]

```ts
interface InspectorServerEvents {
  listening: []
}
```

The events an inspector `Server` emits: `listening`, once the server starts listening.

InspectorServerOptions [#inspectorserveroptions]

```ts
interface InspectorServerOptions {
  path: URL | string
}
```

Options for `Server`: `path`, the entry-point URL reported to DevTools as the URL of the inspected script.

bare-inspector/heap-snapshot [#bare-inspectorheap-snapshot]

InspectorHeapSnapshot [#inspectorheapsnapshot]

new InspectorHeapSnapshot(session: Session) [#new-inspectorheapsnapshotsession-session]

A readable stream of a V8 heap snapshot taken over `session`, using the inspector protocol's `HeapProfiler.takeHeapSnapshot`. Pipe it to a file (for example with a `.heapsnapshot` extension) to load it in Chrome DevTools, or async-iterate it with `for await (const chunk of snapshot)`, receiving it as a sequence of `Buffer` chunks.

**Parameters**

| Parameter | Type      | Default | Description                                        |
| --------- | --------- | ------- | -------------------------------------------------- |
| `session` | `Session` | —       | The connected `Session` to take the snapshot over. |

See also [#see-also]

* Builds on `bare-events`, `bare-http1`, `bare-stream`, `bare-url`, and `bare-ws`.
* It's the in-process counterpart to the [`bare`](/reference/bare/cli) `--inspect` flag, and what `pear-inspect` exposes remotely over [Hyperswarm](/reference/building-blocks/hyperswarm).
* [`bare-console`](/reference/bare/modules/bare-console) — everyday logging and timing.
* [Bare modules](/reference/modules/bare-modules) — the full `bare-*` catalog.
* [Bare runtime API](/reference/bare/runtime) — the runtime these modules extend.


# bare-ipc



<mark style={{ backgroundColor: '#7dde9a', padding: '2px 8px', borderRadius: '4px', fontSize: '0.85em', fontWeight: 500 }}>
  stable
</mark>

[`bare-ipc`](https://github.com/holepunchto/bare-ipc) — Lightweight pipe-based IPC for Bare.

```sh
npm i bare-ipc
```

Usage [#usage]

```js
const IPC = require('bare-ipc')

const [portA, portB] = IPC.open()

const a = portA.connect()
const b = portB.connect()

a.on('data', (data) => {
  // Handle data received from b
}).end('hello b')

b.on('data', (data) => {
  // Handle data received from a
}).end('hello a')
```

API [#api]

IPC [#ipc]

new IPC(port: IPCPort) [#new-ipcport-ipcport]

Returns a duplex stream using the provided `port`. See `bare-stream`'s `Duplex` (\<[https://github.com/holepunchto/bare-stream>](https://github.com/holepunchto/bare-stream>)) for the duplex stream API.

**Parameters**

| Parameter | Type      | Default | Description                                                    |
| --------- | --------- | ------- | -------------------------------------------------------------- |
| `port`    | `IPCPort` | —       | The port to open the stream over, as returned by `IPC.open()`. |

incoming: Pipe [#incoming-pipe]

The underlying `bare-pipe` `Pipe` used for reading. Read-only.

IPC.open(): [IPCPort, IPCPort] [#ipcopen-ipcport-ipcport]

Returns a pair of connected `IPCPort`s for constructing the IPC duplex stream based on `bare-pipe`. Each port is transferable and can be sent to another thread or process before being connected.

**Returns** `[IPCPort, IPCPort]` — A pair of connected ports, one for each end of the IPC channel.

outgoing: Pipe [#outgoing-pipe]

The underlying `bare-pipe` `Pipe` used for writing. Read-only.

ref(): this [#ref-this]

Increase the reference count for the IPC to keep the event loop alive.

unref(): this [#unref-this]

Decrease the reference count for the IPC to allow the event loop to exit.

IPCPort [#ipcport]

new IPCPort(incoming: number, outgoing: number) [#new-ipcportincoming-number-outgoing-number]

Constructs a port from a pair of file handles, `incoming` and `outgoing`.

**Parameters**

| Parameter  | Type     | Default | Description                       |
| ---------- | -------- | ------- | --------------------------------- |
| `incoming` | `number` | —       | The file handle used for reading. |
| `outgoing` | `number` | —       | The file handle used for writing. |

connect(): IPC [#connect-ipc]

Returns an `IPC` connected to the `port` and marks the `port` as detached.

**Returns** `IPC` — An `IPC` duplex stream connected to the port.

detached: boolean [#detached-boolean]

A boolean for whether the `port` is detached. A port becomes detached once it is connected or transferred, and a detached port cannot be transferred again.

incoming: number [#incoming-number]

The file handle used for reading. Read-only.

outgoing: number [#outgoing-number]

The file handle used for writing. Read-only.

bare-ipc/errors [#bare-ipcerrors]

IPCError [#ipcerror]

IPCError.ALREADY_CONNECTED(msg: string): IPCError [#ipcerroralready_connectedmsg-string-ipcerror]

Create the error thrown when transferring a port that has already been connected or transferred.

**Parameters**

| Parameter | Type     | Default | Description        |
| --------- | -------- | ------- | ------------------ |
| `msg`     | `string` | —       | The error message. |

**Returns** `IPCError` — An error with code `ALREADY_CONNECTED`.

See also [#see-also]

* Builds on `bare-pipe`, `bare-stream`, and `bare-structured-clone`.
* It's pure JavaScript.
* For the host↔worklet channel in native apps, see [`bare-kit`](/reference/bare/bare-kit) instead.
* [`bare-channel`](/reference/bare/modules/bare-channel) — inter-*thread* messaging (same idea, within a process).
* A common pattern is to call `ipc.ref()` on resume and `ipc.unref()` on suspend, for example `Bare.on('suspend', () => ipc.unref()).on('resume', () => ipc.ref())`.
* Errors emitted by the underlying incoming or outgoing pipes are propagated to the stream as `error` events, after which the stream is destroyed.
* [Bare modules](/reference/modules/bare-modules) — the full `bare-*` catalog.
* [Bare runtime API](/reference/bare/runtime) — the runtime these modules extend.


# bare-logger



<mark style={{ backgroundColor: '#7dde9a', padding: '2px 8px', borderRadius: '4px', fontSize: '0.85em', fontWeight: 500 }}>
  stable
</mark>

[`bare-logger`](https://github.com/holepunchto/bare-logger) — Low-level logger for Bare. It is a native addon.

```sh
npm i bare-logger
```

Usage [#usage]

```js
const Log = require('bare-logger')

const log = new Log()

log.info('Hello %s', 'world!')
```

API [#api]

Log [#log]

new Log(options?: LogOptions) [#new-logoptions-logoptions]

Create a logger. `colors` defaults to whether the current stream is a TTY.

**Parameters**

| Parameter  | Type                        | Default | Description                                                                                                     |
| ---------- | --------------------------- | ------- | --------------------------------------------------------------------------------------------------------------- |
| `options?` | [`LogOptions`](#logoptions) | —       | Logger options; `colors` forces ANSI color styling on or off, defaulting to whether the output stream is a TTY. |

clear(): void [#clear-void]

Clears the log output. A no-op on the base `Log`.

colors: boolean [#colors-boolean]

Whether this logger applies ANSI color styling to formatted output. Read-only.

debug(...data: unknown[]): void [#debugdata-unknown-void]

Logs `data` at debug level.

**Parameters**

| Parameter | Type        | Default | Description                                                                                                                                          |
| --------- | ----------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data`    | `unknown[]` | —       | Values to format and log; the first may be a `printf`-style format string (for example `%s`, `%d`, `%o`) with the remaining values as substitutions. |

error(...data: unknown[]): void [#errordata-unknown-void]

Logs `data` at error level.

**Parameters**

| Parameter | Type        | Default | Description                                                                                                                                          |
| --------- | ----------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data`    | `unknown[]` | —       | Values to format and log; the first may be a `printf`-style format string (for example `%s`, `%d`, `%o`) with the remaining values as substitutions. |

fatal(...data: unknown[]): void [#fataldata-unknown-void]

Logs `data` at fatal level.

**Parameters**

| Parameter | Type        | Default | Description                                                                                                                                          |
| --------- | ----------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data`    | `unknown[]` | —       | Values to format and log; the first may be a `printf`-style format string (for example `%s`, `%d`, `%o`) with the remaining values as substitutions. |

format(...data: unknown[]): string [#formatdata-unknown-string]

Formats `data` the same way `debug`, `info`, `warn`, `error`, and `fatal` do, and returns the resulting string without logging it.

**Parameters**

| Parameter | Type        | Default | Description                                                                                                                                          |
| --------- | ----------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data`    | `unknown[]` | —       | Values to format and log; the first may be a `printf`-style format string (for example `%s`, `%d`, `%o`) with the remaining values as substitutions. |

info(...data: unknown[]): void [#infodata-unknown-void]

Logs `data` at info level.

**Parameters**

| Parameter | Type        | Default | Description                                                                                                                                          |
| --------- | ----------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data`    | `unknown[]` | —       | Values to format and log; the first may be a `printf`-style format string (for example `%s`, `%d`, `%o`) with the remaining values as substitutions. |

warn(...data: unknown[]): void [#warndata-unknown-void]

Logs `data` at warn level.

**Parameters**

| Parameter | Type        | Default | Description                                                                                                                                          |
| --------- | ----------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data`    | `unknown[]` | —       | Values to format and log; the first may be a `printf`-style format string (for example `%s`, `%d`, `%o`) with the remaining values as substitutions. |

CompositeLog [#compositelog]

new CompositeLog(logs: Log[]) [#new-compositeloglogs-log]

Create a logger that forwards every call to each logger in `logs`, so a single log call can write to, for example, both the console and a file.

**Parameters**

| Parameter | Type    | Default | Description                                     |
| --------- | ------- | ------- | ----------------------------------------------- |
| `logs`    | `Log[]` | —       | The loggers to forward every call to, in order. |

Types [#types]

LogOptions [#logoptions]

```ts
interface LogOptions {
  colors?: boolean
}
```

Options for `Log`. `colors` forces ANSI color styling on or off in formatted output.

Multiple loggers [#multiple-loggers]

`CompositeLog` can be used to output to multiple loggers. Such as console and file loggers.

```js
const { Log, CompositeLog } = require('bare-logger')

const log1 = new Log()
const log2 = new Log()
const log = new CompositeLog([log1, log2])

log.info('Hello %s', 'world!')
```

See also [#see-also]

* Builds on `bare-format`.
* [Bare modules](/reference/modules/bare-modules) — the full `bare-*` catalog.
* [Bare runtime API](/reference/bare/runtime) — the runtime these modules extend.


# bare-make



<mark style={{ backgroundColor: '#7dde9a', padding: '2px 8px', borderRadius: '4px', fontSize: '0.85em', fontWeight: 500 }}>
  stable
</mark>

[`bare-make`](https://github.com/holepunchto/bare-make) — Opinionated build system generator based on CMake.

```sh
npm i bare-make
```

Usage [#usage]

Like CMake, builds happen in three steps: You first generate a build system, then run the build system, and finally install the built artefacts. To perform the steps programmatically from JavaScript, do:

```js
const make = require('bare-make')

await make.generate()
await make.build()
await make.install()
```

The steps can also be performed interactively from the command line using the included CLI:

```console
bare-make generate
bare-make build
bare-make install
```

Testing [#testing]

To run tests for projects that use [`enable_testing()`](https://cmake.org/cmake/help/latest/command/enable_testing.html#command:enable_testing) and [`add_test()`](https://cmake.org/cmake/help/latest/command/add_test.html#command:add_test), do:

```js
await make.test()
```

Tests can also be run from the command line:

```console
bare-make test
```

API [#api]

errors [#errors]

new errors(msg: string, code: string, fn?: MakeError) [#new-errorsmsg-string-code-string-fn-makeerror]

Construct a `MakeError` with the given message and `code`.

**Parameters**

| Parameter | Type        | Default | Description                                                                               |
| --------- | ----------- | ------- | ----------------------------------------------------------------------------------------- |
| `msg`     | `string`    | —       | Human-readable error message.                                                             |
| `code`    | `string`    | —       | The error code, assigned to `err.code`.                                                   |
| `fn?`     | `MakeError` | —       | The function to omit from the captured stack trace (default the `MakeError` constructor). |

errors.BUILD_FAILED(msg: string): MakeError [#errorsbuild_failedmsg-string-makeerror]

Create a `MakeError` with code `'BUILD_FAILED'`.

**Parameters**

| Parameter | Type     | Default | Description                   |
| --------- | -------- | ------- | ----------------------------- |
| `msg`     | `string` | —       | Human-readable error message. |

errors.GENERATE_FAILED(msg: string): MakeError [#errorsgenerate_failedmsg-string-makeerror]

Create a `MakeError` with code `'GENERATE_FAILED'`.

**Parameters**

| Parameter | Type     | Default | Description                   |
| --------- | -------- | ------- | ----------------------------- |
| `msg`     | `string` | —       | Human-readable error message. |

errors.INSTALL_FAILED(msg: string): MakeError [#errorsinstall_failedmsg-string-makeerror]

Create a `MakeError` with code `'INSTALL_FAILED'`.

**Parameters**

| Parameter | Type     | Default | Description                   |
| --------- | -------- | ------- | ----------------------------- |
| `msg`     | `string` | —       | Human-readable error message. |

errors.TEST_FAILED(msg: string): MakeError [#errorstest_failedmsg-string-makeerror]

Create a `MakeError` with code `'TEST_FAILED'`.

**Parameters**

| Parameter | Type     | Default | Description                   |
| --------- | -------- | ------- | ----------------------------- |
| `msg`     | `string` | —       | Human-readable error message. |

errors.UNKNOWN_TOOLCHAIN(msg: string): MakeError [#errorsunknown_toolchainmsg-string-makeerror]

Create a `MakeError` with code `'UNKNOWN_TOOLCHAIN'`.

**Parameters**

| Parameter | Type     | Default | Description                   |
| --------- | -------- | ------- | ----------------------------- |
| `msg`     | `string` | —       | Human-readable error message. |

Functions [#functions]

build(opts?: BuildOptions): Promise<void> [#buildopts-buildoptions-promisevoid]

**Parameters**

| Parameter | Type           | Default | Description                                                                                                                   |
| --------- | -------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `opts?`   | `BuildOptions` | —       | Options; `build` defaults to `'build'` (unset when `preset` is set), `parallel` to `0`, and `clean` and `verbose` to `false`. |

**Throws**

* `BUILD_FAILED` — the build exits with a non-zero status.

generate(opts?: GenerateOptions): Promise<void> [#generateopts-generateoptions-promisevoid]

**Parameters**

| Parameter | Type              | Default | Description                                                                                                                                                                                                               |
| --------- | ----------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `opts?`   | `GenerateOptions` | —       | Options; `source` defaults to `'.'`, `build` to `'build'`, `platform` and `arch` to the host, `cache` to `true`, and the build-type flags (`debug`, `fuzz`, `withDebugSymbols`, `withMinimalSize`, `verbose`) to `false`. |

**Throws**

* `UNKNOWN_TOOLCHAIN` — no toolchain is available for the resolved `platform`-`arch` target.
* `GENERATE_FAILED` — build system generation exits with a non-zero status.

install(opts?: InstallOptions): Promise<void> [#installopts-installoptions-promisevoid]

**Parameters**

| Parameter | Type             | Default | Description                                                                                                       |
| --------- | ---------------- | ------- | ----------------------------------------------------------------------------------------------------------------- |
| `opts?`   | `InstallOptions` | —       | Options; `build` defaults to `'build'`, `prefix` to `'prebuilds'`, and `link`, `strip`, and `verbose` to `false`. |

**Throws**

* `INSTALL_FAILED` — the install exits with a non-zero status.

test(opts?: TestOptions): Promise<void> [#testopts-testoptions-promisevoid]

**Parameters**

| Parameter | Type          | Default | Description                                                                                                      |
| --------- | ------------- | ------- | ---------------------------------------------------------------------------------------------------------------- |
| `opts?`   | `TestOptions` | —       | Options; `build` defaults to `'build'`, `timeout` to `30` seconds, `parallel` to `-1`, and `verbose` to `false`. |

**Throws**

* `TEST_FAILED` — one or more tests fail.

Types [#types]

build.BuildOptions [#buildbuildoptions]

```ts
interface BuildOptions {
  build?: string
  clean?: boolean
  cwd?: string
  parallel?: number
  preset?: string
  stdio?: Pipe
  target?: string
  verbose?: boolean
}
```

Options for `build()`.

generate.GenerateOptions [#generategenerateoptions]

```ts
interface GenerateOptions {
  arch?: string
  build?: string
  cache?: boolean
  cwd?: string
  debug?: boolean
  define?: string[]
  environment?: string
  fuzz?: boolean
  platform?: string
  preset?: string
  sanitize?: string
  simulator?: boolean
  source?: string
  stdio?: Pipe
  verbose?: boolean
  withDebugSymbols?: boolean
  withMinimalSize?: boolean
}
```

Options for `generate()`.

install.InstallOptions [#installinstalloptions]

```ts
interface InstallOptions {
  build?: string
  component?: string
  cwd?: string
  link?: boolean
  parallel?: boolean
  prefix?: string
  stdio?: Pipe
  strip?: boolean
  verbose?: boolean
}
```

Options for `install()`.

test.TestOptions [#testtestoptions]

```ts
interface TestOptions {
  build?: string
  cwd?: string
  parallel?: number
  preset?: string
  stdio?: Pipe
  timeout?: number
  verbose?: boolean
}
```

Options for `test()`.

bare-make/errors [#bare-makeerrors]

MakeError [#makeerror]

new MakeError(msg: string, code: string, fn?: MakeError) [#new-makeerrormsg-string-code-string-fn-makeerror]

Construct a `MakeError` with the given message and `code`.

**Parameters**

| Parameter | Type        | Default | Description                                                                               |
| --------- | ----------- | ------- | ----------------------------------------------------------------------------------------- |
| `msg`     | `string`    | —       | Human-readable error message.                                                             |
| `code`    | `string`    | —       | The error code, assigned to `err.code`.                                                   |
| `fn?`     | `MakeError` | —       | The function to omit from the captured stack trace (default the `MakeError` constructor). |

MakeError.BUILD_FAILED(msg: string): MakeError [#makeerrorbuild_failedmsg-string-makeerror]

Create a `MakeError` with code `'BUILD_FAILED'`.

**Parameters**

| Parameter | Type     | Default | Description                   |
| --------- | -------- | ------- | ----------------------------- |
| `msg`     | `string` | —       | Human-readable error message. |

MakeError.GENERATE_FAILED(msg: string): MakeError [#makeerrorgenerate_failedmsg-string-makeerror]

Create a `MakeError` with code `'GENERATE_FAILED'`.

**Parameters**

| Parameter | Type     | Default | Description                   |
| --------- | -------- | ------- | ----------------------------- |
| `msg`     | `string` | —       | Human-readable error message. |

MakeError.INSTALL_FAILED(msg: string): MakeError [#makeerrorinstall_failedmsg-string-makeerror]

Create a `MakeError` with code `'INSTALL_FAILED'`.

**Parameters**

| Parameter | Type     | Default | Description                   |
| --------- | -------- | ------- | ----------------------------- |
| `msg`     | `string` | —       | Human-readable error message. |

MakeError.TEST_FAILED(msg: string): MakeError [#makeerrortest_failedmsg-string-makeerror]

Create a `MakeError` with code `'TEST_FAILED'`.

**Parameters**

| Parameter | Type     | Default | Description                   |
| --------- | -------- | ------- | ----------------------------- |
| `msg`     | `string` | —       | Human-readable error message. |

MakeError.UNKNOWN_TOOLCHAIN(msg: string): MakeError [#makeerrorunknown_toolchainmsg-string-makeerror]

Create a `MakeError` with code `'UNKNOWN_TOOLCHAIN'`.

**Parameters**

| Parameter | Type     | Default | Description                   |
| --------- | -------- | ------- | ----------------------------- |
| `msg`     | `string` | —       | Human-readable error message. |

bare-make/build [#bare-makebuild]

Functions [#functions-1]

build.build(opts?: BuildOptions): Promise<void> [#buildbuildopts-buildoptions-promisevoid]

**Parameters**

| Parameter | Type           | Default | Description                                                                                                                   |
| --------- | -------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `opts?`   | `BuildOptions` | —       | Options; `build` defaults to `'build'` (unset when `preset` is set), `parallel` to `0`, and `clean` and `verbose` to `false`. |

**Throws**

* `BUILD_FAILED` — the build exits with a non-zero status.

Types [#types-1]

BuildOptions [#buildoptions]

```ts
interface BuildOptions {
  build?: string
  clean?: boolean
  cwd?: string
  parallel?: number
  preset?: string
  stdio?: Pipe
  target?: string
  verbose?: boolean
}
```

Options for `build()`.

bare-make/generate [#bare-makegenerate]

Functions [#functions-2]

generate.generate(opts?: GenerateOptions): Promise<void> [#generategenerateopts-generateoptions-promisevoid]

**Parameters**

| Parameter | Type              | Default | Description                                                                                                                                                                                                               |
| --------- | ----------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `opts?`   | `GenerateOptions` | —       | Options; `source` defaults to `'.'`, `build` to `'build'`, `platform` and `arch` to the host, `cache` to `true`, and the build-type flags (`debug`, `fuzz`, `withDebugSymbols`, `withMinimalSize`, `verbose`) to `false`. |

**Throws**

* `UNKNOWN_TOOLCHAIN` — no toolchain is available for the resolved `platform`-`arch` target.
* `GENERATE_FAILED` — build system generation exits with a non-zero status.

Types [#types-2]

GenerateOptions [#generateoptions]

```ts
interface GenerateOptions {
  arch?: string
  build?: string
  cache?: boolean
  cwd?: string
  debug?: boolean
  define?: string[]
  environment?: string
  fuzz?: boolean
  platform?: string
  preset?: string
  sanitize?: string
  simulator?: boolean
  source?: string
  stdio?: Pipe
  verbose?: boolean
  withDebugSymbols?: boolean
  withMinimalSize?: boolean
}
```

Options for `generate()`.

bare-make/install [#bare-makeinstall]

Functions [#functions-3]

install.install(opts?: InstallOptions): Promise<void> [#installinstallopts-installoptions-promisevoid]

**Parameters**

| Parameter | Type             | Default | Description                                                                                                       |
| --------- | ---------------- | ------- | ----------------------------------------------------------------------------------------------------------------- |
| `opts?`   | `InstallOptions` | —       | Options; `build` defaults to `'build'`, `prefix` to `'prebuilds'`, and `link`, `strip`, and `verbose` to `false`. |

**Throws**

* `INSTALL_FAILED` — the install exits with a non-zero status.

Types [#types-3]

InstallOptions [#installoptions]

```ts
interface InstallOptions {
  build?: string
  component?: string
  cwd?: string
  link?: boolean
  parallel?: boolean
  prefix?: string
  stdio?: Pipe
  strip?: boolean
  verbose?: boolean
}
```

Options for `install()`.

bare-make/test [#bare-maketest]

Functions [#functions-4]

test.test(opts?: TestOptions): Promise<void> [#testtestopts-testoptions-promisevoid]

**Parameters**

| Parameter | Type          | Default | Description                                                                                                      |
| --------- | ------------- | ------- | ---------------------------------------------------------------------------------------------------------------- |
| `opts?`   | `TestOptions` | —       | Options; `build` defaults to `'build'`, `timeout` to `30` seconds, `parallel` to `-1`, and `verbose` to `false`. |

**Throws**

* `TEST_FAILED` — one or more tests fail.

Types [#types-4]

TestOptions [#testoptions]

```ts
interface TestOptions {
  build?: string
  cwd?: string
  parallel?: number
  preset?: string
  stdio?: Pipe
  timeout?: number
  verbose?: boolean
}
```

Options for `test()`.

CLI [#cli]

bare-make generate [flags] [#bare-make-generate-flags]

Flags include:

```console
--source|-s <path>                   The path to the source tree
--build|-b <path>                    The path to the build tree
--platform|-p <name>                 The operating system platform to build for
--arch|-a <name>                     The operating system architecture to build for
--simulator                          Build for a simulator
--environment|-e <name>              The environment to build for
--no-cache                           Disregard the build variable cache
--preset <name>                      The preset to use
--debug|-d                           Configure a debug build
--with-debug-symbols                 Configure a release build with debug symbols
--with-minimal-size                  Configure a release build with minimal size
--sanitize <name>                    Enable a sanitizer
--fuzz                               Configure for fuzzing
--define|-D <var>[:<type>]=<value>   Create or update a build variable cache entry
--no-color                           Disable colored output
--verbose                            Enable verbose output
--help|-h                            Show help
```

bare-make build [flags] [#bare-make-build-flags]

Flags include:

```console
--build|-b <path>        The path to the build tree
--target|-t <name>       The target to build
--clean|-c               Clean before building
--parallel|-j <number>   Build in parallel using the given number of jobs
--preset <name>          The preset to use
--verbose                Enable verbose output
--help|-h                Show help
```

bare-make install [flags] [#bare-make-install-flags]

Flags include:

```console
--build|-b <path>        The path to the build tree
--prefix|-p <path>       The prefix to install to
--component|-c <name>    The component to install
--link|-l                Link rather than copy the files
--strip|-s               Strip before installing
--parallel|-j <number>   Install in parallel using the given number of jobs
--verbose                Enable verbose output
--help|-h                Show help
```

bare-make test [flags] [#bare-make-test-flags]

Flags include:

```console
--build|-b <path>        The path to the build tree
--timeout <seconds>      The default test timeout
--parallel|-j <number>   Run tests in parallel using the given number of jobs
--preset <name>          The preset to use
--verbose                Enable verbose output
--help|-h                Show help
```

See also [#see-also]

* Builds on `bare-env`, `bare-fs`, `bare-os`, `bare-path`, and `bare-process`.
* It drives CMake with Ninja and Clang for a consistent toolchain across platforms, while staying plain CMake underneath so you can eject.
* The CLI is installed globally via `npm i -g bare-make`.
* [Bundle a Bare app](/how-to/run-on-native/bundle-a-bare-app) — where addon compilation fits in packaging.
* [`bare-pack`](/reference/modules/bare-modules) — bundles the compiled addons.
* [Bare modules](/reference/modules/bare-modules) — the full `bare-*` catalog.
* [Bare runtime API](/reference/bare/runtime) — the runtime these modules extend.


# bare-mdns-discovery



<mark style={{ backgroundColor: '#7dde9a', padding: '2px 8px', borderRadius: '4px', fontSize: '0.85em', fontWeight: 500 }}>
  stable
</mark>

[`bare-mdns-discovery`](https://github.com/holepunchto/bare-mdns-discovery) — bare-mdns-discovery.

```sh
npm i bare-mdns-discovery
```

Usage [#usage]

Low-level mDNS queries [#low-level-mdns-queries]

```javascript
const { MDNS } = require('bare-mdns-discovery')

const mdns = new MDNS({ debug: true })
await mdns.ready()

mdns.on('records', (records, rinfo) => {
  console.log('from:', rinfo.address)
  for (const r of records) {
    console.log(r.type, r.name, r.data)
  }
})

mdns.query('_services._dns-sd._udp.local')
mdns.query('_http._tcp.local')
mdns.query('_googlecast._tcp.local')

setTimeout(() => mdns.close(), 10000)
```

Service discovery [#service-discovery]

```javascript
const { Discovery } = require('bare-mdns-discovery')

const discovery = new Discovery({ service: 'googlecast' })
await discovery.ready()

discovery.on('service', (service) => {
  console.log('Found:', service.name, service.address, service.port)
})

const services = await discovery.discover(10) // 10 second timeout
console.log('All services:', services)

await discovery.close()
```

Extending for specific services [#extending-for-specific-services]

```javascript
const { Discovery } = require('bare-mdns-discovery')

class MyServiceDiscovery extends Discovery {
  constructor(opts = {}) {
    super({ ...opts, service: 'myservice' })
  }

  _parseService(records, rinfo) {
    const service = super._parseService(records, rinfo)
    if (!service) return null

    // Add custom filtering or fields
    return {
      ...service,
      customField: service.txt.someKey
    }
  }
}
```

API [#api]

MDNS [#mdns]

new MDNS(opts?: MDNSOptions) [#new-mdnsopts-mdnsoptions]

Send and receive raw mDNS queries and records over UDP multicast. Extends `ReadyResource`; open it with `ready()` and release its socket with `close()`.

**Parameters**

| Parameter | Type                          | Default | Description                                 |
| --------- | ----------------------------- | ------- | ------------------------------------------- |
| `opts?`   | [`MDNSOptions`](#mdnsoptions) | —       | Options; see [`MDNSOptions`](#mdnsoptions). |

debug: boolean [#debug-boolean]

Whether internal activity is logged to the console (default `false`).

emit(event: 'records', records: Record[], rinfo: RecordInfo): boolean [#emitevent-records-records-record-rinfo-recordinfo-boolean]

Overloads:

```ts
emit(event: 'records', records: Record[], rinfo: RecordInfo): boolean
emit(event: 'error', err: Error): boolean
emit(event: 'ready'): boolean
emit(event: 'close'): boolean
```

**Parameters**

| Parameter | Type                        | Default | Description |
| --------- | --------------------------- | ------- | ----------- |
| `event`   | `'records'`                 | —       | —           |
| `records` | [`Record[]`](#record)       | —       | —           |
| `rinfo`   | [`RecordInfo`](#recordinfo) | —       | —           |

off(event: 'records', listener: (records: Record[], rinfo: RecordInfo) => void): this [#offevent-records-listener-records-record-rinfo-recordinfo--void-this]

Overloads:

```ts
off(event: 'records', listener: (records: Record[], rinfo: RecordInfo) => void): this
off(event: 'error', listener: (err: Error) => void): this
off(event: 'ready', listener: () => void): this
off(event: 'close', listener: () => void): this
```

**Parameters**

| Parameter  | Type                                             | Default | Description |
| ---------- | ------------------------------------------------ | ------- | ----------- |
| `event`    | `'records'`                                      | —       | —           |
| `listener` | `(records: Record[], rinfo: RecordInfo) => void` | —       | —           |

on(event: 'records', listener: (records: Record[], rinfo: RecordInfo) => void): this [#onevent-records-listener-records-record-rinfo-recordinfo--void-this]

Overloads:

```ts
on(event: 'records', listener: (records: Record[], rinfo: RecordInfo) => void): this
on(event: 'error', listener: (err: Error) => void): this
on(event: 'ready', listener: () => void): this
on(event: 'close', listener: () => void): this
```

**Parameters**

| Parameter  | Type                                             | Default | Description |
| ---------- | ------------------------------------------------ | ------- | ----------- |
| `event`    | `'records'`                                      | —       | —           |
| `listener` | `(records: Record[], rinfo: RecordInfo) => void` | —       | —           |

once(event: 'records', listener: (records: Record[], rinfo: RecordInfo) => void): this [#onceevent-records-listener-records-record-rinfo-recordinfo--void-this]

Overloads:

```ts
once(event: 'records', listener: (records: Record[], rinfo: RecordInfo) => void): this
once(event: 'error', listener: (err: Error) => void): this
once(event: 'ready', listener: () => void): this
once(event: 'close', listener: () => void): this
```

**Parameters**

| Parameter  | Type                                             | Default | Description |
| ---------- | ------------------------------------------------ | ------- | ----------- |
| `event`    | `'records'`                                      | —       | —           |
| `listener` | `(records: Record[], rinfo: RecordInfo) => void` | —       | —           |

query(name: string, type?: number): void [#queryname-string-type-number-void]

Sends an mDNS query for `name`.

**Parameters**

| Parameter | Type     | Default | Description                                                  |
| --------- | -------- | ------- | ------------------------------------------------------------ |
| `name`    | `string` | —       | The DNS name to query for, for example `'_http._tcp.local'`. |
| `type?`   | `number` | —       | The DNS record type to request (default `TYPE.PTR`).         |

socket: object | null [#socket-object--null]

The underlying UDP socket, or `null` before the resource has opened.

Discovery [#discovery]

new Discovery(opts?: DiscoveryOptions) [#new-discoveryopts-discoveryoptions]

Discovers instances of a specific mDNS `service` (such as `'googlecast'` or `'http'`) by periodically querying for it and parsing SRV, TXT, and address records into `Service` objects. Extends `MDNS`; subclass and override `_parseService` to customize how records are turned into a `Service` for a given service type.

**Parameters**

| Parameter | Type                                    | Default | Description                                           |
| --------- | --------------------------------------- | ------- | ----------------------------------------------------- |
| `opts?`   | [`DiscoveryOptions`](#discoveryoptions) | —       | Options; see [`DiscoveryOptions`](#discoveryoptions). |

discover(opts?: { first?: boolean; timeout?: number }): Promise<Service[]> [#discoveropts--first-boolean-timeout-number--promiseservice]

Queries for the configured service every 2 seconds until `timeout` milliseconds elapse (default `10000`), or resolves early when `opts.first` is set and a service has been found.

**Parameters**

| Parameter | Type                                    | Default | Description                                                                                                                                                                                            |
| --------- | --------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `opts?`   | `{ first?: boolean; timeout?: number }` | —       | Options: `timeout` is how long, in milliseconds, to keep querying before resolving (default `10000`); set `first` to resolve as soon as the first service is found instead of waiting out the timeout. |

**Returns** `Promise<Service[]>` — The discovered `Service` objects — a single-element array when `opts.first` resolved early.

emit(event: 'service', service: Service): boolean [#emitevent-service-service-service-boolean]

Overloads:

```ts
emit(event: 'service', service: Service): boolean
emit(event: 'records', records: Record[], rinfo: RecordInfo): boolean
emit(event: 'error', err: Error): boolean
emit(event: 'ready'): boolean
emit(event: 'close'): boolean
```

**Parameters**

| Parameter | Type                  | Default | Description |
| --------- | --------------------- | ------- | ----------- |
| `event`   | `'service'`           | —       | —           |
| `service` | [`Service`](#service) | —       | —           |

off(event: 'service', listener: (service: Service) => void): this [#offevent-service-listener-service-service--void-this]

Overloads:

```ts
off(event: 'service', listener: (service: Service) => void): this
off(event: 'records', listener: (records: Record[], rinfo: RecordInfo) => void): this
off(event: 'error', listener: (err: Error) => void): this
off(event: 'ready', listener: () => void): this
off(event: 'close', listener: () => void): this
```

**Parameters**

| Parameter  | Type                         | Default | Description |
| ---------- | ---------------------------- | ------- | ----------- |
| `event`    | `'service'`                  | —       | —           |
| `listener` | `(service: Service) => void` | —       | —           |

on(event: 'service', listener: (service: Service) => void): this [#onevent-service-listener-service-service--void-this]

Overloads:

```ts
on(event: 'service', listener: (service: Service) => void): this
on(event: 'records', listener: (records: Record[], rinfo: RecordInfo) => void): this
on(event: 'error', listener: (err: Error) => void): this
on(event: 'ready', listener: () => void): this
on(event: 'close', listener: () => void): this
```

**Parameters**

| Parameter  | Type                         | Default | Description |
| ---------- | ---------------------------- | ------- | ----------- |
| `event`    | `'service'`                  | —       | —           |
| `listener` | `(service: Service) => void` | —       | —           |

once(event: 'service', listener: (service: Service) => void): this [#onceevent-service-listener-service-service--void-this]

Overloads:

```ts
once(event: 'service', listener: (service: Service) => void): this
once(event: 'records', listener: (records: Record[], rinfo: RecordInfo) => void): this
once(event: 'error', listener: (err: Error) => void): this
once(event: 'ready', listener: () => void): this
once(event: 'close', listener: () => void): this
```

**Parameters**

| Parameter  | Type                         | Default | Description |
| ---------- | ---------------------------- | ------- | ----------- |
| `event`    | `'service'`                  | —       | —           |
| `listener` | `(service: Service) => void` | —       | —           |

service: string [#service-string]

The mDNS service name being discovered.

services: Map<string, Service> [#services-mapstring-service]

A map of discovered services, keyed by service `uid`, accumulated since the last `discover()` call.

Constants and variables [#constants-and-variables]

TYPE [#type]

```ts
TYPE: {
    readonly A: 1
    readonly PTR: 12
    readonly TXT: 16
    readonly AAAA: 28
    readonly SRV: 33
  }
```

DNS record type numbers used in mDNS queries and records, per RFC 6762: `A`, `PTR`, `TXT`, `AAAA`, and `SRV`.

MDNS_ADDR: '224.0.0.251' [#mdns_addr-22400251]

The IPv4 multicast address used for mDNS, `224.0.0.251`, per RFC 6762.

MDNS_PORT: 5353 [#mdns_port-5353]

The UDP port used for mDNS, `5353`, per RFC 6762.

Types [#types]

RecordInfo [#recordinfo]

```ts
interface RecordInfo {
  address: string
  port: number
  family: 'IPv4' | 'IPv6'
  size: number
}
```

The remote address information for a received mDNS packet: `address`, `port`, `family`, and the packet `size` in bytes.

SRVData [#srvdata]

```ts
interface SRVData {
  priority: number
  weight: number
  port: number
  target: string
}
```

The parsed data of an SRV record: `priority`, `weight`, `port`, and `target` hostname.

TXTData [#txtdata]

```ts
interface TXTData {
}
```

The parsed key/value pairs of a TXT record. A key with no `=` in its entry is stored with the value `true`.

Record [#record]

```ts
interface Record {
  name: string
  type: number
  class: number
  flush: boolean
  ttl: number
  data: string | TXTData | SRVData | Buffer
}
```

A single parsed DNS resource record from an mDNS response: `name`, `type`, `class`, the `flush` cache-flush bit, `ttl`, and the type-specific `data`.

Service [#service]

```ts
interface Service {
  uid: string
  name: string
  address: string
  addresses: {
      ipv4: string | null
      ipv6: string[]
    }
  port: number
  target: string
  txt: TXTData
}
```

A discovered service: its unique id, `name`, resolved `address`, all known `addresses` (IPv4 and IPv6), `port`, SRV `target` hostname, and `txt` record data.

MDNSOptions [#mdnsoptions]

```ts
interface MDNSOptions {
  debug?: boolean
  iface?: string
}
```

Options for `MDNS`. `debug` logs internal activity to the console. `iface` is the IPv4 address of the network interface to bind multicast membership on; required on Android, where it must be the WiFi interface IP so the kernel delivers mDNS responses on the correct interface.

DiscoveryOptions [#discoveryoptions]

```ts
interface DiscoveryOptions {
  service?: string
  debug?: boolean
  iface?: string
}
```

Options for `Discovery`, extending `MDNSOptions` with `service`, the mDNS service name to query for (for example `'googlecast'`).

See also [#see-also]

* Builds on `bare-dgram`.
* Without `iface` set, Android's `addMembership` falls back to the OS default interface, which may not be the WiFi interface, so responses are silently dropped — pass the WiFi IP, for example from `bare-wifi-android`'s `getWifiIP()`.
* `Discovery`'s `service` option is given without the DNS prefix/suffix — `'http'` or `'googlecast'`, not `'_http._tcp.local'`.
* [Bare modules](/reference/modules/bare-modules) — the full `bare-*` catalog.
* [Bare runtime API](/reference/bare/runtime) — the runtime these modules extend.


# bare-mime



[`bare-mime`](https://github.com/holepunchto/bare-mime) parses MIME types for [Bare](/reference/bare/runtime) into their `type`, `subtype`, and `parameters`. It's pure JavaScript.

```sh
npm i bare-mime
```

Usage [#usage]

```js
const MIME = require('bare-mime')

const mime = MIME.parse('text/plain;charset=utf-8')
console.log(mime.type)                      // 'text'
console.log(mime.subtype)                   // 'plain'
console.log(mime.parameters.get('charset')) // 'utf-8'
```

API [#api]

const mime = new MIME(type, subtype[, parameters]) [#const-mime--new-mimetype-subtype-parameters]

Construct a MIME type. Exposes `mime.type`, `mime.subtype`, and `mime.parameters` (a map of parameter names to values).

const mime = MIME.parse(input) [#const-mime--mimeparseinput]

Parse a MIME-type string into a `MIME`. Returns `null` on failure. The `type` and `subtype` are lowercased, and leading/trailing HTTP whitespace is stripped from the input. If the same parameter name appears more than once, the first occurrence is used and subsequent duplicates are ignored.

See also [#see-also]

* [`bare-fetch`](/reference/bare/modules/bare-fetch) and [`bare-form-data`](/reference/bare/modules/bare-form-data)—where content types are read and set.
* [Bare modules](/reference/modules/bare-modules)—the full `bare-*` catalog.
* [Bare runtime API](/reference/bare/runtime)—the runtime this runs on.


# bare-module-lexer



<mark style={{ backgroundColor: '#7dde9a', padding: '2px 8px', borderRadius: '4px', fontSize: '0.85em', fontWeight: 500 }}>
  stable
</mark>

[`bare-module-lexer`](https://github.com/holepunchto/bare-module-lexer) — Heuristic lexer for detecting imports and exports in JavaScript modules. It is a native addon.

```sh
npm i bare-module-lexer
```

Usage [#usage]

```js
const lex = require('bare-module-lexer')

lex(`
  const foo = require('./foo.js')
  exports.bar = 42
`)

// {
//   imports: [
//     { specifier: './foo.js', type: REQUIRE, names: [], position: [ 15, 24, 32 ] }
//   ],
//   exports: [
//     { name: 'bar', position: [ 37, 45, 48 ] }
//   ]
// }
```

API [#api]

Functions [#functions]

lex [#lex]

```ts
lex(input: string | Buffer, encoding?: BufferEncoding, opts?: object): {
  imports: Import[]
  exports: Export[]
}
```

Lex `input` for import and export statements, returning the detected `imports` and `exports`.

**Parameters**

| Parameter   | Type                 | Default | Description                                  |
| ----------- | -------------------- | ------- | -------------------------------------------- |
| `input`     | `string` \| `Buffer` | —       | The source to lex, as a string or buffer.    |
| `encoding?` | `BufferEncoding`     | —       | The encoding of `input` when it is a string. |
| `opts?`     | `object`             | —       | Reserved; currently unused.                  |

**Throws**

* `TypeError` — `input` is not a string or buffer.

Constants and variables [#constants-and-variables]

lex.constants [#lexconstants]

```ts
lex.constants: {
    REQUIRE: number
    IMPORT: number
    DYNAMIC: number
    ADDON: number
    ASSET: number
    RESOLVE: number
    REEXPORT: number
  }
```

Types [#types]

Import [#import]

```ts
interface Import {
  specifier: string
  type: number
  names: string[]
  attributes: { [attribute: string]: string }
  position: [importStart: number, specifierStart: number, specifierEnd: number]
}
```

An import detected in the source. `type` is a combination of the `lex.constants` flags (for example `REQUIRE`, `IMPORT`, `DYNAMIC`); `position` holds the offsets `[importStart, specifierStart, specifierEnd]`.

Export [#export]

```ts
interface Export {
  name: string
  position: [exportStart: number, nameStart: number, nameEnd: number]
}
```

An export detected in the source; `position` holds the offsets `[exportStart, nameStart, nameEnd]`.

See also [#see-also]

* [Bare modules](/reference/modules/bare-modules) — the full `bare-*` catalog.
* [Bare runtime API](/reference/bare/runtime) — the runtime these modules extend.


# bare-module-resolve



<mark style={{ backgroundColor: '#7dde9a', padding: '2px 8px', borderRadius: '4px', fontSize: '0.85em', fontWeight: 500 }}>
  stable
</mark>

[`bare-module-resolve`](https://github.com/holepunchto/bare-module-resolve) — Low-level module resolution algorithm for Bare.

```sh
npm i bare-module-resolve
```

Usage [#usage]

For synchronous resolution:

```js
const resolve = require('bare-module-resolve')

function readPackage(url) {
  // Read and parse `url` if it exists, otherwise `null`
}

for (const resolution of resolve('./file.js', new URL('file:///directory/'), readPackage)) {
  console.log(resolution)
}
```

For asynchronous resolution:

```js
const resolve = require('bare-module-resolve')

async function readPackage(url) {
  // Read and parse `url` if it exists, otherwise `null`
}

for await (const resolution of resolve('./file.js', new URL('file:///directory/'), readPackage)) {
  console.log(resolution)
}
```

API [#api]

Functions [#functions]

resolve [#resolve]

```ts
resolve(specifier: string, parentURL: URL, readPackage?: (url: URL) => JSON | null): Iterable<URL>
```

Resolve `specifier` relative to `parentURL`, which must be a WHATWG `URL` instance. `readPackage` is called with a `URL` instance for every package manifest to be read and must either return the parsed JSON package manifest, if it exists, or `null`. If `readPackage` returns a promise, synchronous iteration is not supported.

**Parameters**

| Parameter      | Type                         | Default | Description                                                                                                                                                               |
| -------------- | ---------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `specifier`    | `string`                     | —       | The module specifier to resolve, relative to `parentURL`.                                                                                                                 |
| `parentURL`    | `URL`                        | —       | The WHATWG `URL` that `specifier` is resolved against.                                                                                                                    |
| `readPackage?` | `(url: URL) => JSON \| null` | —       | Called with the `URL` of each package manifest to read; must return the parsed JSON manifest if it exists, or `null`. Returning a promise disables synchronous iteration. |

**Returns** `Iterable<URL>` — Yields each candidate resolution `URL` in the order the algorithm tries them, for the caller to test (for example check it exists); if none resolve, iteration simply ends without yielding further values — it does not throw or return `null` for an unresolved specifier.

**Throws**

* `INVALID_MODULE_SPECIFIER` — the specifier (or a `node:`-protocol target) is not a valid module or package specifier: empty, a scoped package name missing the `/`, invalid characters, a relative-style `node:` specifier, an unmatched internal `#import` specifier, or a `file:` path containing an encoded `/` or `\`.
* `INVALID_PACKAGE_TARGET` — a string target in a package's `"exports"` (or non-internal `"imports"`) map does not start with `./`.
* `PACKAGE_PATH_NOT_EXPORTED` — the requested subpath is not defined by the package's `"exports"` map.
* `PACKAGE_IMPORT_NOT_DEFINED` — an internal `#specifier` is not defined by the package's `"imports"` map.
* `UNSUPPORTED_ENGINE` — the package's `"engines"` requirement is not satisfied by the corresponding `opts.engines` entry.

resolve.builtinTarget [#resolvebuiltintarget]

```ts
resolve.builtinTarget(packageSpecifier: string, packageVersion: string, target: ConditionalSpecifier, opts?: ResolveOptions): Resolver
```

**Parameters**

| Parameter          | Type                                | Default | Description |
| ------------------ | ----------------------------------- | ------- | ----------- |
| `packageSpecifier` | `string`                            | —       | —           |
| `packageVersion`   | `string`                            | —       | —           |
| `target`           | `ConditionalSpecifier`              | —       | —           |
| `opts?`            | [`ResolveOptions`](#resolveoptions) | —       | —           |

resolve.directory(dirname: string, parentURL: URL, opts?: ResolveOptions): Resolver [#resolvedirectorydirname-string-parenturl-url-opts-resolveoptions-resolver]

**Parameters**

| Parameter   | Type                                | Default | Description |
| ----------- | ----------------------------------- | ------- | ----------- |
| `dirname`   | `string`                            | —       | —           |
| `parentURL` | `URL`                               | —       | —           |
| `opts?`     | [`ResolveOptions`](#resolveoptions) | —       | —           |

resolve.file [#resolvefile]

```ts
resolve.file(filename: string, parentURL: URL, isIndex: boolean, opts?: ResolveOptions): Resolver
```

**Parameters**

| Parameter   | Type                                | Default | Description |
| ----------- | ----------------------------------- | ------- | ----------- |
| `filename`  | `string`                            | —       | —           |
| `parentURL` | `URL`                               | —       | —           |
| `isIndex`   | `boolean`                           | —       | —           |
| `opts?`     | [`ResolveOptions`](#resolveoptions) | —       | —           |

resolve.module(specifier: string, parentURL: URL, opts?: ResolveOptions): Resolver [#resolvemodulespecifier-string-parenturl-url-opts-resolveoptions-resolver]

**Parameters**

| Parameter   | Type                                | Default | Description |
| ----------- | ----------------------------------- | ------- | ----------- |
| `specifier` | `string`                            | —       | —           |
| `parentURL` | `URL`                               | —       | —           |
| `opts?`     | [`ResolveOptions`](#resolveoptions) | —       | —           |

resolve.package(packageSpecifier: string, parentURL: URL, opts?: ResolveOptions): Resolver [#resolvepackagepackagespecifier-string-parenturl-url-opts-resolveoptions-resolver]

**Parameters**

| Parameter          | Type                                | Default | Description |
| ------------------ | ----------------------------------- | ------- | ----------- |
| `packageSpecifier` | `string`                            | —       | —           |
| `parentURL`        | `URL`                               | —       | —           |
| `opts?`            | [`ResolveOptions`](#resolveoptions) | —       | —           |

resolve.packageExports [#resolvepackageexports]

```ts
resolve.packageExports(packageURL: URL, subpath: string, packageExports: ExportsMap, opts?: ResolveOptions): Resolver
```

**Parameters**

| Parameter        | Type                                | Default | Description |
| ---------------- | ----------------------------------- | ------- | ----------- |
| `packageURL`     | `URL`                               | —       | —           |
| `subpath`        | `string`                            | —       | —           |
| `packageExports` | `ExportsMap`                        | —       | —           |
| `opts?`          | [`ResolveOptions`](#resolveoptions) | —       | —           |

resolve.packageImports(specifier: string, parentURL: URL, opts?: ResolveOptions): Resolver [#resolvepackageimportsspecifier-string-parenturl-url-opts-resolveoptions-resolver]

**Parameters**

| Parameter   | Type                                | Default | Description |
| ----------- | ----------------------------------- | ------- | ----------- |
| `specifier` | `string`                            | —       | —           |
| `parentURL` | `URL`                               | —       | —           |
| `opts?`     | [`ResolveOptions`](#resolveoptions) | —       | —           |

resolve.packageImportsExports [#resolvepackageimportsexports]

```ts
resolve.packageImportsExports(matchKey: string, matchObject: ImportsMap | ExportsMap, packageURL: URL, isImports: boolean, opts?: ResolveOptions): Resolver
```

**Parameters**

| Parameter     | Type                                | Default | Description |
| ------------- | ----------------------------------- | ------- | ----------- |
| `matchKey`    | `string`                            | —       | —           |
| `matchObject` | `ImportsMap` \| `ExportsMap`        | —       | —           |
| `packageURL`  | `URL`                               | —       | —           |
| `isImports`   | `boolean`                           | —       | —           |
| `opts?`       | [`ResolveOptions`](#resolveoptions) | —       | —           |

resolve.packageSelf [#resolvepackageself]

```ts
resolve.packageSelf(packageName: string, packageSubpath: string, parentURL: URL, opts?: ResolveOptions): Resolver
```

**Parameters**

| Parameter        | Type                                | Default | Description |
| ---------------- | ----------------------------------- | ------- | ----------- |
| `packageName`    | `string`                            | —       | —           |
| `packageSubpath` | `string`                            | —       | —           |
| `parentURL`      | `URL`                               | —       | —           |
| `opts?`          | [`ResolveOptions`](#resolveoptions) | —       | —           |

resolve.packageTarget [#resolvepackagetarget]

```ts
resolve.packageTarget(packageURL: URL, target: ConditionalSpecifier, patternMatch: string, isImports: boolean, opts?: ResolveOptions): Resolver
```

**Parameters**

| Parameter      | Type                                | Default | Description |
| -------------- | ----------------------------------- | ------- | ----------- |
| `packageURL`   | `URL`                               | —       | —           |
| `target`       | `ConditionalSpecifier`              | —       | —           |
| `patternMatch` | `string`                            | —       | —           |
| `isImports`    | `boolean`                           | —       | —           |
| `opts?`        | [`ResolveOptions`](#resolveoptions) | —       | —           |

resolve.preresolved [#resolvepreresolved]

```ts
resolve.preresolved(specifier: string, resolutions: ResolutionsMap, parentURL: URL, opts?: ResolveOptions): Resolver
```

**Parameters**

| Parameter     | Type                                | Default | Description |
| ------------- | ----------------------------------- | ------- | ----------- |
| `specifier`   | `string`                            | —       | —           |
| `resolutions` | `ResolutionsMap`                    | —       | —           |
| `parentURL`   | `URL`                               | —       | —           |
| `opts?`       | [`ResolveOptions`](#resolveoptions) | —       | —           |

resolve.url(url: string, parentURL: URL, opts?: ResolveOptions): Resolver [#resolveurlurl-string-parenturl-url-opts-resolveoptions-resolver]

**Parameters**

| Parameter   | Type                                | Default | Description |
| ----------- | ----------------------------------- | ------- | ----------- |
| `url`       | `string`                            | —       | —           |
| `parentURL` | `URL`                               | —       | —           |
| `opts?`     | [`ResolveOptions`](#resolveoptions) | —       | —           |

Constants and variables [#constants-and-variables]

resolve.constants [#resolveconstants]

```ts
resolve.constants: {
    UNRESOLVED: number
    YIELDED: number
    RESOLVED: number
  }
```

Types [#types]

resolve.Builtins [#resolvebuiltins]

```ts
type Builtins = ConditionalSpecifier[]
```

resolve.ConditionalSpecifier [#resolveconditionalspecifier]

```ts
type ConditionalSpecifier = string | ConditionalSpecifier[] | { [condition: string]: ConditionalSpecifier }
```

resolve.Conditions [#resolveconditions]

```ts
type Conditions = string[] | Conditions[]
```

resolve.Engines [#resolveengines]

```ts
type Engines = { [name: string]: string }
```

resolve.ExportsMap [#resolveexportsmap]

```ts
type ExportsMap = ImportsMap
```

resolve.ImportsMap [#resolveimportsmap]

```ts
type ImportsMap = { [specifier: string]: ConditionalSpecifier }
```

resolve.ResolutionsMap [#resolveresolutionsmap]

```ts
type ResolutionsMap = { [href: string]: ImportsMap }
```

resolve.Resolver [#resolveresolver]

```ts
type Resolver = Generator<
    { package: URL } | { resolution: URL },
    number,
    void | boolean | JSON | null
  >
```

ResolveOptions [#resolveoptions]

```ts
interface ResolveOptions {
  builtinProtocol?: string
  builtins?: Builtins
  conditions?: Conditions
  defer?: string[]
  deferredProtocol?: string
  engines?: Engines
  extensions?: string[]
  imports?: ImportsMap
  matchedConditions?: string[]
  resolutions?: ResolutionsMap
}
```

bare-module-resolve/errors [#bare-module-resolveerrors]

ModuleResolveError [#moduleresolveerror]

code: string [#code-string]

ModuleResolveError.INVALID_MODULE_SPECIFIER(msg: string): ModuleResolveError [#moduleresolveerrorinvalid_module_specifiermsg-string-moduleresolveerror]

**Parameters**

| Parameter | Type     | Default | Description        |
| --------- | -------- | ------- | ------------------ |
| `msg`     | `string` | —       | The error message. |

**Returns** `ModuleResolveError` — A new `ModuleResolveError` with code `INVALID_MODULE_SPECIFIER`.

ModuleResolveError.INVALID_PACKAGE_TARGET(msg: string): ModuleResolveError [#moduleresolveerrorinvalid_package_targetmsg-string-moduleresolveerror]

**Parameters**

| Parameter | Type     | Default | Description        |
| --------- | -------- | ------- | ------------------ |
| `msg`     | `string` | —       | The error message. |

**Returns** `ModuleResolveError` — A new `ModuleResolveError` with code `INVALID_PACKAGE_TARGET`.

ModuleResolveError.PACKAGE_IMPORT_NOT_DEFINED(msg: string): ModuleResolveError [#moduleresolveerrorpackage_import_not_definedmsg-string-moduleresolveerror]

**Parameters**

| Parameter | Type     | Default | Description        |
| --------- | -------- | ------- | ------------------ |
| `msg`     | `string` | —       | The error message. |

**Returns** `ModuleResolveError` — A new `ModuleResolveError` with code `PACKAGE_IMPORT_NOT_DEFINED`.

ModuleResolveError.PACKAGE_PATH_NOT_EXPORTED(msg: string): ModuleResolveError [#moduleresolveerrorpackage_path_not_exportedmsg-string-moduleresolveerror]

**Parameters**

| Parameter | Type     | Default | Description        |
| --------- | -------- | ------- | ------------------ |
| `msg`     | `string` | —       | The error message. |

**Returns** `ModuleResolveError` — A new `ModuleResolveError` with code `PACKAGE_PATH_NOT_EXPORTED`.

ModuleResolveError.UNSUPPORTED_ENGINE(msg: string): ModuleResolveError [#moduleresolveerrorunsupported_enginemsg-string-moduleresolveerror]

**Parameters**

| Parameter | Type     | Default | Description        |
| --------- | -------- | ------- | ------------------ |
| `msg`     | `string` | —       | The error message. |

**Returns** `ModuleResolveError` — A new `ModuleResolveError` with code `UNSUPPORTED_ENGINE`.

See also [#see-also]

* Builds on `bare-semver`.
* The algorithm's steps are exposed on `resolve` for fine-grained use (`resolve.module`, `resolve.url`, `resolve.preresolved`, `resolve.deferred`, `resolve.package`, `resolve.packageSelf`, `resolve.packageExports`, `resolve.packageImports`, `resolve.packageImportsExports`, `resolve.packageTarget`, `resolve.builtinTarget`, `resolve.file`, and `resolve.directory`); they're subject to change between minor releases; if using them directly, specify a tilde range (for example `~1.2.3`) when declaring the module dependency. See the [repository README](https://github.com/holepunchto/bare-module-resolve) for each step's signature and options.
* A low-level building block. Most applications resolve modules implicitly through the [runtime](/reference/bare/runtime) or bundle with [`bare-pack`](/reference/modules/bare-modules); reach for this directly only when implementing tooling.
* Paired with [`bare-addon-resolve`](/reference/bare/modules/bare-addon-resolve) — the matching algorithm for native addons — and used by [`bare-module-traverse`](/reference/bare/modules/bare-module-traverse) to walk a whole module graph.
* [Bare modules](/reference/modules/bare-modules) — the full `bare-*` catalog.
* [Bare runtime API](/reference/bare/runtime) — the runtime these modules extend.


# bare-module-traverse



<mark style={{ backgroundColor: '#7dde9a', padding: '2px 8px', borderRadius: '4px', fontSize: '0.85em', fontWeight: 500 }}>
  stable
</mark>

[`bare-module-traverse`](https://github.com/holepunchto/bare-module-traverse) — Low-level module graph traversal for Bare.

```sh
npm i bare-module-traverse
```

Usage [#usage]

For synchronous traversal:

```js
const traverse = require('bare-module-traverse')

function readModule(url) {
  // Read `url` if it exists, otherwise `null`
}

function* listPrefix(url) {
  // Yield URLs that have `url` as a prefix. The list may be empty.
}

for (const dependency of traverse(new URL('file:///directory/file.js'), readModule, listPrefix)) {
  console.log(dependency)
}
```

For asynchronous traversal:

```js
const traverse = require('bare-module-traverse')

async function readModule(url) {
  // Read `url` if it exists, otherwise `null`
}

async function* listPrefix(url) {
  // Yield URLs that have `url` as a prefix. The list may be empty.
}

for await (const dependency of traverse(
  new URL('file:///directory/file.js'),
  readModule,
  listPrefix
)) {
  console.log(dependency)
}
```

API [#api]

Functions [#functions]

traverse [#traverse]

```ts
traverse(entry: URL, readModule: (url: URL) => Buffer | string | null, listPrefix?: (url: URL) => Iterable<URL>, probeModule?: (url: URL) => boolean | undefined, resolveModule?: (url: URL) => URL): Iterable<Dependency>
```

Traverse the module graph rooted at `entry`, which must be a WHATWG `URL` instance. `readModule` is called with a `URL` instance for every module to be read and must either return the module source, if it exists, or `null`. `listPrefix` is called with a `URL` instance of every prefix to be listed and must yield `URL` instances that have the specified `URL` as a prefix. If not provided, prefixes won't be traversed. If `readModule` returns a promise or `listPrefix` returns a promise generator, synchronous iteration is not supported.

**Parameters**

| Parameter        | Type                                     | Default | Description                                                                                                                                                                     |
| ---------------- | ---------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `entry`          | `URL`                                    | —       | The WHATWG `URL` of the entry module to root the graph at.                                                                                                                      |
| `readModule`     | `(url: URL) => Buffer \| string \| null` | —       | Called with the `URL` of each module to read; returns its source as a `Buffer` or `string`, or `null` if it does not exist. Returning a promise disables synchronous iteration. |
| `listPrefix?`    | `(url: URL) => Iterable<URL>`            | —       | Called with the `URL` of each prefix to list; must yield the `URL`s that have it as a prefix. If omitted, prefixes are not traversed.                                           |
| `probeModule?`   | `(url: URL) => boolean \| undefined`     | —       | Called with the `URL` of each module to probe for existence; returns a boolean, or `undefined` to fall back to `readModule`.                                                    |
| `resolveModule?` | `(url: URL) => URL`                      | —       | Called with each resolution `URL` to transform; returns the `URL` to use in its place. Defaults to the identity function.                                                       |

**Returns** `Iterable<Dependency>` — An iterable of resolved `Dependency` records for the module graph; asynchronous when any callback returns a promise.

traverse.addons [#traverseaddons]

```ts
traverse.addons(parentURL: URL, artifacts: Artifacts, visited: Set<string>, opts?: TraverseOptions): Traversal
```

**Parameters**

| Parameter   | Type                                  | Default | Description |
| ----------- | ------------------------------------- | ------- | ----------- |
| `parentURL` | `URL`                                 | —       | —           |
| `artifacts` | [`Artifacts`](#artifacts)             | —       | —           |
| `visited`   | `Set<string>`                         | —       | —           |
| `opts?`     | [`TraverseOptions`](#traverseoptions) | —       | —           |

traverse.assets [#traverseassets]

```ts
traverse.assets(patterns: ConditionalSpecifier, parentURL: URL, artifacts: Artifacts, visited: Set<string>, opts?: TraverseOptions): Traversal
```

**Parameters**

| Parameter   | Type                                  | Default | Description |
| ----------- | ------------------------------------- | ------- | ----------- |
| `patterns`  | `ConditionalSpecifier`                | —       | —           |
| `parentURL` | `URL`                                 | —       | —           |
| `artifacts` | [`Artifacts`](#artifacts)             | —       | —           |
| `visited`   | `Set<string>`                         | —       | —           |
| `opts?`     | [`TraverseOptions`](#traverseoptions) | —       | —           |

traverse.imports [#traverseimports]

```ts
traverse.imports(parentURL: URL, source: string | Buffer, imports: ImportsMap, artifacts: Artifacts, lexer: {
      imports: Import[]
      exports: Export[]
    }, visited: Set<string>, opts?: TraverseOptions): Traversal
```

**Parameters**

| Parameter   | Type                                      | Default | Description |
| ----------- | ----------------------------------------- | ------- | ----------- |
| `parentURL` | `URL`                                     | —       | —           |
| `source`    | `string` \| `Buffer`                      | —       | —           |
| `imports`   | `ImportsMap`                              | —       | —           |
| `artifacts` | [`Artifacts`](#artifacts)                 | —       | —           |
| `lexer`     | `{ imports: Import[] exports: Export[] }` | —       | —           |
| `visited`   | `Set<string>`                             | —       | —           |
| `opts?`     | [`TraverseOptions`](#traverseoptions)     | —       | —           |

traverse.link [#traverselink]

```ts
traverse.link(entry: Import, specifier: string, condition: string, parentURL: URL, imports: ImportsMap, artifacts: Artifacts, visited: Set<string>, opts?: TraverseOptions): Traversal
```

**Parameters**

| Parameter   | Type                                  | Default | Description |
| ----------- | ------------------------------------- | ------- | ----------- |
| `entry`     | `Import`                              | —       | —           |
| `specifier` | `string`                              | —       | —           |
| `condition` | `string`                              | —       | —           |
| `parentURL` | `URL`                                 | —       | —           |
| `imports`   | `ImportsMap`                          | —       | —           |
| `artifacts` | [`Artifacts`](#artifacts)             | —       | —           |
| `visited`   | `Set<string>`                         | —       | —           |
| `opts?`     | [`TraverseOptions`](#traverseoptions) | —       | —           |

traverse.module [#traversemodule]

```ts
traverse.module(url: URL, source: string | Buffer, attributes: Record<string, string> | null, artifacts: Artifacts, visited: Set<string>, opts?: TraverseOptions): Traversal
```

**Parameters**

| Parameter    | Type                                  | Default | Description |
| ------------ | ------------------------------------- | ------- | ----------- |
| `url`        | `URL`                                 | —       | —           |
| `source`     | `string` \| `Buffer`                  | —       | —           |
| `attributes` | `Record<string, string> \| null`      | —       | —           |
| `artifacts`  | [`Artifacts`](#artifacts)             | —       | —           |
| `visited`    | `Set<string>`                         | —       | —           |
| `opts?`      | [`TraverseOptions`](#traverseoptions) | —       | —           |

traverse.package [#traversepackage]

```ts
traverse.package(url: URL, source: string | Buffer, artifacts: Artifacts, visited: Set<string>, opts?: TraverseOptions): Traversal
```

**Parameters**

| Parameter   | Type                                  | Default | Description |
| ----------- | ------------------------------------- | ------- | ----------- |
| `url`       | `URL`                                 | —       | —           |
| `source`    | `string` \| `Buffer`                  | —       | —           |
| `artifacts` | [`Artifacts`](#artifacts)             | —       | —           |
| `visited`   | `Set<string>`                         | —       | —           |
| `opts?`     | [`TraverseOptions`](#traverseoptions) | —       | —           |

traverse.preresolved [#traversepreresolved]

```ts
traverse.preresolved(url: URL, source: string | Buffer, resolution: ResolutionsMap, artifacts: Artifacts, visited: Set<string>, opts?: TraverseOptions): Traversal
```

**Parameters**

| Parameter    | Type                                  | Default | Description |
| ------------ | ------------------------------------- | ------- | ----------- |
| `url`        | `URL`                                 | —       | —           |
| `source`     | `string` \| `Buffer`                  | —       | —           |
| `resolution` | `ResolutionsMap`                      | —       | —           |
| `artifacts`  | [`Artifacts`](#artifacts)             | —       | —           |
| `visited`    | `Set<string>`                         | —       | —           |
| `opts?`      | [`TraverseOptions`](#traverseoptions) | —       | —           |

Constants and variables [#constants-and-variables]

traverse.constants [#traverseconstants]

```ts
traverse.constants: {
    SCRIPT: number
    MODULE: number
    JSON: number
    BUNDLE: number
    ADDON: number
    BINARY: number
    TEXT: number
  }
```

Types [#types]

traverse.Traversal [#traversetraversal]

```ts
type Traversal = Generator<
    | { module: URL; artifact: boolean }
    | { probe: URL }
    | { resolution: URL }
    | { prefix: URL }
    | { links: Traversal[] }
    | { children: Traversal; deferred: boolean }
    | { dependency: Dependency },
    boolean,
    void | URL | URL[] | Buffer | string | boolean | null
  >
```

TraverseOptions [#traverseoptions]

```ts
interface TraverseOptions {
  defaultType?: number
  aliases?: Record<string, AliasableExtension>
  resolve?: (entry: Import, parentURL: URL, opts?: ResolveOptions) => Resolver
  builtinProtocol?: string
  builtins?: Builtins
  conditions?: Conditions
  extensions?: string[]
  host?: string
  hosts?: string[]
  linked?: boolean
  linkedProtocol?: string
  matchedConditions?: string[]
  resolutions?: ResolutionsMap
}
```

Artifacts [#artifacts]

```ts
interface Artifacts {
  addons: URL[] | Set<string>
  assets: URL[] | Set<string>
}
```

Dependency [#dependency]

```ts
interface Dependency {
  url: URL
  source: string | Buffer
  type: number
  imports: ImportsMap
  lexer: {
    imports: Import[]
    exports: Export[]
  }
}
```

bare-module-traverse/resolve [#bare-module-traverseresolve]

Functions [#functions-1]

module(specifier: string, parentURL: URL, opts?: ResolveOptions): Resolver [#modulespecifier-string-parenturl-url-opts-resolveoptions-resolver]

**Parameters**

| Parameter   | Type             | Default | Description |
| ----------- | ---------------- | ------- | ----------- |
| `specifier` | `string`         | —       | —           |
| `parentURL` | `URL`            | —       | —           |
| `opts?`     | `ResolveOptions` | —       | —           |

addon(specifier: string, parentURL: URL, opts?: ResolveOptions): Resolver [#addonspecifier-string-parenturl-url-opts-resolveoptions-resolver]

**Parameters**

| Parameter   | Type             | Default | Description |
| ----------- | ---------------- | ------- | ----------- |
| `specifier` | `string`         | —       | —           |
| `parentURL` | `URL`            | —       | —           |
| `opts?`     | `ResolveOptions` | —       | —           |

default(entry: Import, parentURL: URL, opts?: ResolveOptions): Resolver [#defaultentry-import-parenturl-url-opts-resolveoptions-resolver]

The default resolver, which simply forwards to \<[https://github.com/holepunchto/bare-module-resolve>](https://github.com/holepunchto/bare-module-resolve>) and \<[https://github.com/holepunchto/bare-addon-resolve>](https://github.com/holepunchto/bare-addon-resolve>) with the literal options passed by the caller.

**Parameters**

| Parameter   | Type             | Default | Description                                                       |
| ----------- | ---------------- | ------- | ----------------------------------------------------------------- |
| `entry`     | `Import`         | —       | The import to resolve, as produced by `bare-module-lexer`.        |
| `parentURL` | `URL`            | —       | The WHATWG `URL` to resolve `entry` relative to.                  |
| `opts?`     | `ResolveOptions` | —       | Resolve options forwarded to the underlying resolution algorithm. |

**Returns** `Resolver` — A `Resolver` that yields the candidate resolutions for `entry`.

bare(entry: Import, parentURL: URL, opts?: BareResolveOptions): Resolver [#bareentry-import-parenturl-url-opts-bareresolveoptions-resolver]

The Bare resolver, which matches the options used by the Bare module system.

**Parameters**

| Parameter   | Type                 | Default | Description                                                       |
| ----------- | -------------------- | ------- | ----------------------------------------------------------------- |
| `entry`     | `Import`             | —       | The import to resolve, as produced by `bare-module-lexer`.        |
| `parentURL` | `URL`                | —       | The WHATWG `URL` to resolve `entry` relative to.                  |
| `opts?`     | `BareResolveOptions` | —       | Resolve options forwarded to the underlying resolution algorithm. |

**Returns** `Resolver` — A `Resolver` that yields the candidate resolutions for `entry`.

node(entry: Import, parentURL: URL, opts?: NodeResolveOptions): Resolver [#nodeentry-import-parenturl-url-opts-noderesolveoptions-resolver]

The Node.js resolver, which matches the options used by the Node.js module system.

**Parameters**

| Parameter   | Type                 | Default | Description                                                       |
| ----------- | -------------------- | ------- | ----------------------------------------------------------------- |
| `entry`     | `Import`             | —       | The import to resolve, as produced by `bare-module-lexer`.        |
| `parentURL` | `URL`                | —       | The WHATWG `URL` to resolve `entry` relative to.                  |
| `opts?`     | `NodeResolveOptions` | —       | Resolve options forwarded to the underlying resolution algorithm. |

**Returns** `Resolver` — A `Resolver` that yields the candidate resolutions for `entry`.

Types [#types-1]

bare.BareResolveOptions [#barebareresolveoptions]

```ts
interface BareResolveOptions {
  linked?: boolean
  host?: string
  hosts?: string[]
  builtinProtocol?: string
  builtins?: Builtins
  conditions?: Conditions
  extensions?: string[]
  linkedProtocol?: string
  matchedConditions?: string[]
  resolutions?: ResolutionsMap
}
```

node.NodeResolveOptions [#nodenoderesolveoptions]

```ts
interface NodeResolveOptions {
  host?: string
  hosts?: string[]
  builtinProtocol?: string
  builtins?: Builtins
  conditions?: Conditions
  extensions?: string[]
  linked?: boolean
  linkedProtocol?: string
  matchedConditions?: string[]
  resolutions?: ResolutionsMap
}
```

bare-module-traverse/resolve/default [#bare-module-traverseresolvedefault]

Functions [#functions-2]

resolve(entry: Import, parentURL: URL, opts?: ResolveOptions): Resolver [#resolveentry-import-parenturl-url-opts-resolveoptions-resolver]

**Parameters**

| Parameter   | Type             | Default | Description                                                       |
| ----------- | ---------------- | ------- | ----------------------------------------------------------------- |
| `entry`     | `Import`         | —       | The import to resolve, as produced by `bare-module-lexer`.        |
| `parentURL` | `URL`            | —       | The WHATWG `URL` to resolve `entry` relative to.                  |
| `opts?`     | `ResolveOptions` | —       | Resolve options forwarded to the underlying resolution algorithm. |

**Returns** `Resolver` — A `Resolver` that yields the candidate resolutions for `entry`.

bare-module-traverse/resolve/bare [#bare-module-traverseresolvebare]

Functions [#functions-3]

resolve(entry: Import, parentURL: URL, opts?: BareResolveOptions): Resolver [#resolveentry-import-parenturl-url-opts-bareresolveoptions-resolver]

**Parameters**

| Parameter   | Type                 | Default | Description                                                       |
| ----------- | -------------------- | ------- | ----------------------------------------------------------------- |
| `entry`     | `Import`             | —       | The import to resolve, as produced by `bare-module-lexer`.        |
| `parentURL` | `URL`                | —       | The WHATWG `URL` to resolve `entry` relative to.                  |
| `opts?`     | `BareResolveOptions` | —       | Resolve options forwarded to the underlying resolution algorithm. |

**Returns** `Resolver` — A `Resolver` that yields the candidate resolutions for `entry`.

Types [#types-2]

BareResolveOptions [#bareresolveoptions]

```ts
interface BareResolveOptions {
  linked?: boolean
  host?: string
  hosts?: string[]
  builtinProtocol?: string
  builtins?: Builtins
  conditions?: Conditions
  extensions?: string[]
  linkedProtocol?: string
  matchedConditions?: string[]
  resolutions?: ResolutionsMap
}
```

bare-module-traverse/resolve/node [#bare-module-traverseresolvenode]

Functions [#functions-4]

resolve(entry: Import, parentURL: URL, opts?: NodeResolveOptions): Resolver [#resolveentry-import-parenturl-url-opts-noderesolveoptions-resolver]

**Parameters**

| Parameter   | Type                 | Default | Description                                                       |
| ----------- | -------------------- | ------- | ----------------------------------------------------------------- |
| `entry`     | `Import`             | —       | The import to resolve, as produced by `bare-module-lexer`.        |
| `parentURL` | `URL`                | —       | The WHATWG `URL` to resolve `entry` relative to.                  |
| `opts?`     | `NodeResolveOptions` | —       | Resolve options forwarded to the underlying resolution algorithm. |

**Returns** `Resolver` — A `Resolver` that yields the candidate resolutions for `entry`.

Types [#types-3]

NodeResolveOptions [#noderesolveoptions]

```ts
interface NodeResolveOptions {
  host?: string
  hosts?: string[]
  builtinProtocol?: string
  builtins?: Builtins
  conditions?: Conditions
  extensions?: string[]
  linked?: boolean
  linkedProtocol?: string
  matchedConditions?: string[]
  resolutions?: ResolutionsMap
}
```

See also [#see-also]

* Builds on `bare-addon-resolve`, `bare-mime`, `bare-module-lexer`, and `bare-module-resolve`.
* It's the engine behind [`bare-pack`](/reference/modules/bare-modules) — a low-level building block; use `bare-pack` to produce a bundle, and reach for this directly only when building tooling on top of the graph.
* The step generators exposed on `traverse` (`traverse.module`, `traverse.package`, `traverse.preresolved`, `traverse.imports`, `traverse.addons`, and `traverse.assets`) are subject to change between minor releases; if using them directly, specify a tilde range (for example `~1.2.3`) when declaring the dependency. See the [repository README](https://github.com/holepunchto/bare-module-traverse) for each step generator.
* [Bare modules](/reference/modules/bare-modules) — the full `bare-*` catalog.
* [Bare runtime API](/reference/bare/runtime) — the runtime these modules extend.


# bare-module



<mark style={{ backgroundColor: '#7dde9a', padding: '2px 8px', borderRadius: '4px', fontSize: '0.85em', fontWeight: 500 }}>
  stable
</mark>

[`bare-module`](https://github.com/holepunchto/bare-module) — Module support for JavaScript. It is a native addon and requires Bare `>=1.29.4`.

```sh
npm i bare-module
```

Usage [#usage]

A module is loaded by its WHATWG `URL`. The source may be read through the module's protocol or passed in directly:

```js
const Module = require('bare-module')

// Load a module directly from source, without it existing on disk.
const foo = await Module.load(
  new URL('file:///foo.js'),
  'module.exports = function add (a, b) { return a + b }'
)

foo.exports(2, 3)
// 5
```

To resolve and load specifiers relative to a directory, as `require()` does, create a `require()` bound to a parent URL. The default protocol has no backing store of its own and cannot read from the file system, so pass a protocol that serves the source:

```js
const Module = require('bare-module')

const require = Module.createRequire('file:///directory/', { protocol })

// Resolves and loads `file:///directory/foo.js`, reading it through `protocol`.
const foo = require('./foo.js')
```

The same machinery backs the `require()` and `import` available to modules as they run; see CommonJS modules and ECMAScript modules for what each exposes.

API [#api]

Module [#module]

new Module(url: URL) [#new-moduleurl-url]

**Parameters**

| Parameter | Type  | Default | Description                              |
| --------- | ----- | ------- | ---------------------------------------- |
| `url`     | `URL` | —       | The WHATWG `URL` identifying the module. |

builtins: Builtins [#builtins-builtins]

A map of builtin module specifiers mapped to the loaded module.

cache: Cache [#cache-cache]

A cache of loaded modules for this module. Defaults to `Module.cache`.

conditions: Conditions [#conditions-conditions]

An array of conditions used to resolve dependencies while loading the module. See [Conditional exports](https://github.com/holepunchto/bare-module#conditional-exports) for possible values.

defaultType: number [#defaulttype-number]

The assumed type of a module without a `type` using an ambiguous extension, such as `.js`. See `Module.constants.types` for possible values.

dirname: string [#dirname-string]

The directory portion of `module.url`.

exports: unknown [#exports-unknown]

The exports from the module.

filename: string [#filename-string]

The file portion of `module.url`.

id: string [#id-string]

imports: ImportsMap [#imports-importsmap]

The import map when the module was loaded.

main: Module [#main-module]

The module representing the entry script where the program was launched.

Module.asset(specifier: string, parentURL: URL, opts?: Options): URL [#moduleassetspecifier-string-parenturl-url-opts-options-url]

Get the asset URL by resolving `specifier` relative to `parentURL`. `specifier` is a string and `parentURL` is a WHATWG `URL`.

**Parameters**

| Parameter   | Type                  | Default | Description                                          |
| ----------- | --------------------- | ------- | ---------------------------------------------------- |
| `specifier` | `string`              | —       | The asset specifier to resolve.                      |
| `parentURL` | `URL`                 | —       | The WHATWG `URL` to resolve `specifier` relative to. |
| `opts?`     | [`Options`](#options) | —       | Resolution options.                                  |

**Returns** `URL` — The WHATWG `URL` of the resolved asset.

**Throws**

* `ASSET_NOT_FOUND` — no asset matching `specifier` could be found relative to `parentURL`.
* `TypeError` — `specifier` is not a string.

Module.builtinModules: Module[] [#modulebuiltinmodules-module]

Always an empty array; provided for Node.js compatibility.

Module.cache: Cache [#modulecache-cache]

Module.constants [#moduleconstants]

```ts
Module.constants: {
  states: {
    EVALUATED: number
    SYNTHESIZED: number
    RUN: number
  }
  types: {
    SCRIPT: number
    MODULE: number
    JSON: number
    BUNDLE: number
    ADDON: number
    BINARY: number
    TEXT: number
    ASSET: number
  }
}
```

Constants describing module states (`EVALUATED`, `SYNTHESIZED`, `RUN`) and module types (`SCRIPT`, `MODULE`, `JSON`, `BUNDLE`, `ADDON`, `BINARY`, `TEXT`, `ASSET`).

Module.createRequire(parentURL: string | URL, opts?: CreateRequireOptions): Require [#modulecreaterequireparenturl-string--url-opts-createrequireoptions-require]

Create a preconfigured `require()` bound to `parentURL`, so specifiers resolve and load relative to it.

**Parameters**

| Parameter   | Type                                            | Default | Description                                                                             |
| ----------- | ----------------------------------------------- | ------- | --------------------------------------------------------------------------------------- |
| `parentURL` | `string` \| `URL`                               | —       | The parent URL that the returned `require()` resolves and loads specifiers relative to. |
| `opts?`     | [`CreateRequireOptions`](#createrequireoptions) | —       | Options for the created `require()`, such as its `protocol` and `cache`.                |

**Returns** [`Require`](#require) — A `require()` bound to `parentURL`, with `main`, `cache`, `resolve`, `addon`, and `asset` attached.

Module.isBuiltin(): boolean [#moduleisbuiltin-boolean]

Always returns `false`; provided for Node.js compatibility.

Module.load(url: URL, opts: LoadOptions): Module [#moduleloadurl-url-opts-loadoptions-module]

Load a module with the provided `url`. `url` is a WHATWG `URL`. If provided, the `source` will be passed to the matching `extension` for the `url`.

Overloads:

```ts
Module.load(url: URL, opts: LoadOptions): Module
Module.load(url: URL, source?: Buffer | string | Bundle | null, opts?: LoadOptions): Module
```

**Parameters**

| Parameter | Type                          | Default | Description                                                                                     |
| --------- | ----------------------------- | ------- | ----------------------------------------------------------------------------------------------- |
| `url`     | `URL`                         | —       | The WHATWG `URL` of the module to load.                                                         |
| `opts`    | [`LoadOptions`](#loadoptions) | —       | Load options; may carry a `source` to load directly instead of reading it through the protocol. |

**Returns** `Module` — The loaded `Module`, reusing the cached instance if `url` was already loaded.

**Throws**

* `TYPE_INCOMPATIBLE` — a module is already cached for `url` with a type incompatible with the requested `type`.

Module.protocol: Protocol [#moduleprotocol-protocol]

The `ModuleProtocol` class for resolving, reading and loading modules. See [Protocols](https://github.com/holepunchto/bare-module#protocols) for usage.

Module.resolve(specifier: string, parentURL: URL, opts?: ResolveOptions): URL [#moduleresolvespecifier-string-parenturl-url-opts-resolveoptions-url]

Resolve the module `specifier` relative to the `parentURL`. `specifier` is a string and `parentURL` is a WHATWG `URL`.

**Parameters**

| Parameter   | Type                                | Default | Description                                          |
| ----------- | ----------------------------------- | ------- | ---------------------------------------------------- |
| `specifier` | `string`                            | —       | The module specifier to resolve.                     |
| `parentURL` | `URL`                               | —       | The WHATWG `URL` to resolve `specifier` relative to. |
| `opts?`     | [`ResolveOptions`](#resolveoptions) | —       | Resolution options.                                  |

**Returns** `URL` — The WHATWG `URL` that `specifier` resolves to.

**Throws**

* `MODULE_NOT_FOUND` — no module matching `specifier` could be found relative to `parentURL`.
* `TypeError` — `specifier` is not a string.

path: string [#path-string]

protocol: Protocol [#protocol-protocol]

The `ModuleProtocol` class for resolving, reading and loading modules. See [Protocols](https://github.com/holepunchto/bare-module#protocols) for usage.

resolutions: ResolutionsMap [#resolutions-resolutionsmap]

A map of preresolved imports with keys being serialized parent URLs and values being `"imports"` maps.

type: number [#type-number]

The type of the module. See `Module.constants.types` for possible values.

url: URL [#url-url]

The WHATWG `URL` identifier of the module.

ModuleProtocol [#moduleprotocol]

new ModuleProtocol(methods?: Partial<ModuleProtocol>, context?: ModuleProtocol) [#new-moduleprotocolmethods-partialmoduleprotocol-context-moduleprotocol]

Defines how modules are resolved, read and loaded; custom protocols can serve modules from outside the file system, such as a `Hyperdrive` or a `bare-bundle`.

**Parameters**

| Parameter  | Type                      | Default | Description                                                                                                      |
| ---------- | ------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------- |
| `methods?` | `Partial<ModuleProtocol>` | —       | Protocol method overrides; any of `preresolve`, `postresolve`, `resolve`, `exists`, `read`, `addon`, or `asset`. |
| `context?` | `ModuleProtocol`          | —       | An existing protocol to fall back to for any method not provided in `methods`.                                   |

addon(url: URL): URL [#addonurl-url-url]

Post-process URLs for addons before `postresolve()`.

**Parameters**

| Parameter | Type  | Default | Description                               |
| --------- | ----- | ------- | ----------------------------------------- |
| `url`     | `URL` | —       | The resolved addon `URL` to post-process. |

asset(url: URL): URL [#asseturl-url-url]

Post-process URLs for assets before `postresolve()`.

**Parameters**

| Parameter | Type  | Default | Description                               |
| --------- | ----- | ------- | ----------------------------------------- |
| `url`     | `URL` | —       | The resolved asset `URL` to post-process. |

exists(url: URL, type: number): boolean [#existsurl-url-type-number-boolean]

Return whether the URL exists.

**Parameters**

| Parameter | Type     | Default | Description                                                  |
| --------- | -------- | ------- | ------------------------------------------------------------ |
| `url`     | `URL`    | —       | The `URL` to check for existence.                            |
| `type`    | `number` | —       | The module type being probed (see `Module.constants.types`). |

extend(methods: Partial<ModuleProtocol>): ModuleProtocol [#extendmethods-partialmoduleprotocol-moduleprotocol]

Create a new protocol that uses this protocol as its context, overriding the given `methods`.

**Parameters**

| Parameter | Type                      | Default | Description                                     |
| --------- | ------------------------- | ------- | ----------------------------------------------- |
| `methods` | `Partial<ModuleProtocol>` | —       | Protocol method overrides for the new protocol. |

**Returns** `ModuleProtocol` — A new `ModuleProtocol` that uses this protocol as its context, with `methods` overriding.

postresolve(url: URL): URL [#postresolveurl-url-url]

Process the resolved URL; can be used to convert file paths, etc.

**Parameters**

| Parameter | Type  | Default | Description                         |
| --------- | ----- | ------- | ----------------------------------- |
| `url`     | `URL` | —       | The resolved `URL` to post-process. |

**Returns** `URL` — The (possibly transformed) resolved `URL`.

preresolve(specifier: string, parentURL: URL): string [#preresolvespecifier-string-parenturl-url-string]

Preprocess the `specifier` and `parentURL` before the resolve algorithm is called.

**Parameters**

| Parameter   | Type     | Default | Description                                      |
| ----------- | -------- | ------- | ------------------------------------------------ |
| `specifier` | `string` | —       | The module specifier being resolved.             |
| `parentURL` | `URL`    | —       | The `URL` the specifier is resolved relative to. |

**Returns** `string` — The (possibly rewritten) specifier to pass into the resolve algorithm.

read(url: URL): Buffer | string | null [#readurl-url-buffer--string--null]

Return the source code of a URL, represented as a string or buffer.

**Parameters**

| Parameter | Type  | Default | Description        |
| --------- | ----- | ------- | ------------------ |
| `url`     | `URL` | —       | The `URL` to read. |

**Returns** `Buffer` | `string` | `null` — The source of `url` as a `Buffer` or `string`, or `null` if it does not exist.

resolve(specifier: string, parentURL: URL, imports: ImportsMap): URL [#resolvespecifier-string-parenturl-url-imports-importsmap-url]

Resolve the `specifier` to a URL.

**Parameters**

| Parameter   | Type         | Default | Description                                     |
| ----------- | ------------ | ------- | ----------------------------------------------- |
| `specifier` | `string`     | —       | The module specifier to resolve.                |
| `parentURL` | `URL`        | —       | The `URL` to resolve `specifier` relative to.   |
| `imports`   | `ImportsMap` | —       | The `"imports"` map to apply during resolution. |

Types [#types]

Attributes [#attributes]

```ts
interface Attributes {
  type: Lowercase<keyof typeof constants.types>
}
```

Import attributes instructing how a module should be loaded.

Cache [#cache]

```ts
interface Cache {
}
```

A map of module URL `href`s to loaded modules.

Options [#options]

```ts
interface Options {
  attributes?: Attributes
  builtins?: Builtins
  cache?: Cache
  conditions?: Conditions
  defaultType?: number
  imports?: ImportsMap
  main?: Module
  protocol?: Protocol
  referrer?: Module
  resolutions?: ResolutionsMap
  type?: number
}
```

LoadOptions [#loadoptions]

```ts
interface LoadOptions {
  isDynamicImport?: boolean
  isImport?: boolean
  attributes?: Attributes
  builtins?: Builtins
  cache?: Cache
  conditions?: Conditions
  defaultType?: number
  imports?: ImportsMap
  main?: Module
  protocol?: Protocol
  referrer?: Module
  resolutions?: ResolutionsMap
  type?: number
}
```

ResolveOptions [#resolveoptions]

```ts
interface ResolveOptions {
  isImport?: boolean
  attributes?: Attributes
  builtins?: Builtins
  cache?: Cache
  conditions?: Conditions
  defaultType?: number
  imports?: ImportsMap
  main?: Module
  protocol?: Protocol
  referrer?: Module
  resolutions?: ResolutionsMap
  type?: number
}
```

CreateRequireOptions [#createrequireoptions]

```ts
interface CreateRequireOptions {
  module?: Module
  attributes?: Attributes
  builtins?: Builtins
  cache?: Cache
  conditions?: Conditions
  defaultType?: number
  imports?: ImportsMap
  main?: Module
  protocol?: Protocol
  referrer?: Module
  resolutions?: ResolutionsMap
  type?: number
}
```

RequireOptions [#requireoptions]

```ts
interface RequireOptions {
  with?: Attributes
}
```

Options for `require()`; `with` holds the import attributes.

RequireAddon [#requireaddon]

```ts
interface RequireAddon {
  host: string
  resolve: (specifier: string, parentURL?: URL) => unknown
}
```

The `require.addon` function: imports addon modules, with `host` and `resolve` attached.

Require [#require]

```ts
interface Require {
  main: Module
  cache: Cache
  resolve: (specifier: string, parentURL?: URL) => string
  addon: RequireAddon
  asset: (specifier: string, parentURL?: URL) => string
}
```

The function returned by `Module.createRequire()`: resolves and loads modules relative to its parent URL, with `main`, `cache`, `resolve`, `addon`, and `asset` attached.

Packages [#packages]

A package is a directory with a `package.json` file.

Fields [#fields]

"name" [#name]

```json
{
  "name": "my-package"
}
```

The name of the package. This is used for [addon resolution](https://github.com/holepunchto/bare-addon-resolve#algorithm), [self-referencing](#self-referencing), and importing packages by name.

"version" [#version]

```json
{
  "version": "1.2.3"
}
```

The current version of the package. This is used for [addon resolution](https://github.com/holepunchto/bare-addon-resolve#algorithm).

"type" [#type]

```json
{
  "type": "module"
}
```

The module format used for `.js` files. If not defined, `.js` files are interpreted as CommonJS. If set to `"module"`, `.js` files are instead interpreted as ES modules.

"exports" [#exports]

```json
{
  "exports": {
    ".": "./index.js"
  }
}
```

The entry points of the package. If defined, only the modules explicitly exported by the package may be imported when importing the package by name.

Subpath exports [#subpath-exports]

A package may define more than one entry point by declaring several subpaths with the main export being `"."`:

```json
{
  "exports": {
    ".": "./index.js",
    "./submodule": "./lib/submodule.js"
  }
}
```

When importing the package by name, `require('my-package')` will resolve to `<modules>/my-package/index.js` whereas `require('my-package/submodule')` will resolve to `<modules>/my-package/lib/submodule.js`.

Conditional exports [#conditional-exports]

Conditional exports allow packages to provide different exports for different conditions, such as the loading method the importing module uses (for example `require()` vs `import`):

```json
{
  "exports": {
    ".": {
      "import": "./index.mjs",
      "require": "./index.cjs"
    }
  }
}
```

When importing the package by name, `require('my-package')` will resolve to `<modules>/my-package/index.cjs` whereas `import 'my-package'` will resolve to `<modules>/my-package/index.mjs`.

Similarly, conditional exports can be used to provide different entry points for different runtimes:

```json
{
  "exports": {
    ".": {
      "bare": "./bare.js",
      "node": "./node.js"
    }
  }
}
```

To provide a fallback for when no other conditions match, the `"default"` condition can be declared:

```json
{
  "exports": {
    ".": {
      "bare": "./bare.js",
      "node": "./node.js",
      "default": "./fallback.js"
    }
  }
}
```

The following conditions are supported, listed in order from most specific to least specific as conditions should be defined:

| Condition      | Description                                                                                                                         |
| :------------- | :---------------------------------------------------------------------------------------------------------------------------------- |
| `"import"`     | Matches when the package is loaded via `import` or `import()`.                                                                      |
| `"require"`    | Matches when the package is loaded via `require()`.                                                                                 |
| `"asset"`      | Matches when the package is loaded via `require.asset()`.                                                                           |
| `"addon"`      | Matches when the package is loaded via `require.addon()`.                                                                           |
| `"bare"`       | Matches for any [Bare](https://github.com/holepunchto/bare) environment.                                                            |
| `"node"`       | Matches for any Node.js environment.                                                                                                |
| `"<platform>"` | Matches when equal to `Bare.platform`. See [`Bare.platform`](https://github.com/holepunchto/bare#bareplatform) for possible values. |
| `"<arch>"`     | Matches when equal to `Bare.arch`. See [`Bare.arch`](https://github.com/holepunchto/bare#barearch) for possible values.             |
| `"simulator"`  | Matches when Bare was compiled for a simulator.                                                                                     |
| `"default"`    | The fallback that always matches. This condition should always be last.                                                             |

Export conditions are evaluated in the order they are defined in the `"exports"` field. This means that less specific conditionals defined first will override more specific conditions define later. For example, the following will always call `./fallback.js` because `"default"` always matches and is defined first.

```json
{
  "exports": {
    ".": {
      "default": "./fallback.js",
      "bare": "./bare.js"
    }
  }
}
```

This is why the general rule is that conditions should be from most specific to least specific when defined.

Self-referencing [#self-referencing]

Within a package, exports defined in the `"exports"` field can be referenced by importing the package by name. For example, given the following `package.json`...

```json
{
  "name": "my-package",
  "exports": {
    ".": "./index.js",
    "./submodule": "./lib/submodule.js"
  }
}
```

...any module within `my-package` may reference these entry points using either `require('my-package')` or `require('my-package/submodule')`.

Exports sugar [#exports-sugar]

If a package defines only a single export, `"."`, it may leave out the subpath entirely:

```json
{
  "exports": "./index.js"
}
```

"imports" [#imports]

A private mapping for import specifiers within the package itself. Similar to `"exports"`, the `"imports"` field can be used to conditional import other packages within the package. But unlike `"exports"`, `"imports"` permits mapping to external packages.

The rules are otherwise analogous to the [`"exports"`](#conditional-exports) field.

Subpath imports [#subpath-imports]

Just like exports, subpaths can be used when importing a module internally.

```json
{
  "imports": {
    ".": "./index.js",
    "./submodule": "./lib/submodule.js"
  }
}
```

Conditional imports [#conditional-imports]

Adding conditional imports allows importing different packages based on the configured conditions. As an example:

```json
{
  "imports": {
    "bar": {
      "require": "./baz.cjs",
      "import": "./baz.mjs"
    }
  }
}
```

When importing the package `bar` as `require('bar')` will resolve to `./baz.cjs`, but when importing with `import('bar')` will resolve to `./baz.mjs`.

To provide a fallback for when no other conditions are met, the `"default"` condition can be configured like so:

```json
{
  "imports": {
    "bar": {
      "require": "./baz.cjs",
      "asset": "./baz.txt",
      "default": "./baz.mjs"
    }
  }
}
```

The following conditions are supported, listed in order from most specific to least specific as conditions should be defined:

| Condition      | Description                                                                                                                         |
| :------------- | :---------------------------------------------------------------------------------------------------------------------------------- |
| `"import"`     | Matches when the package is loaded via `import` or `import()`.                                                                      |
| `"require"`    | Matches when the package is loaded via `require()`.                                                                                 |
| `"asset"`      | Matches when the package is loaded via `require.asset()`.                                                                           |
| `"addon"`      | Matches when the package is loaded via `require.addon()`.                                                                           |
| `"bare"`       | Matches for any [Bare](https://github.com/holepunchto/bare) environment.                                                            |
| `"node"`       | Matches for any Node.js environment.                                                                                                |
| `"<platform>"` | Matches when equal to `Bare.platform`. See [`Bare.platform`](https://github.com/holepunchto/bare#bareplatform) for possible values. |
| `"<arch>"`     | Matches when equal to `Bare.arch`. See [`Bare.arch`](https://github.com/holepunchto/bare#barearch) for possible values.             |
| `"simulator"`  | Matches when Bare was compiled for a simulator.                                                                                     |
| `"default"`    | The fallback that always matches. This condition should always be last.                                                             |

The general rule is that conditions should be from most specific to least specific when defined.

# Prefix [#-prefix]

All import maps are private to the package and allow mapping to external packages. Entries in `"imports"` may start with `#` to disambiguate from external packages, but it is not required unlike in Node.js.

"engines" [#engines]

```json
{
  "engines": {
    "bare": ">=1.0.5"
  }
}
```

The `"engines"` field defines the engine requirements of the package. During module resolution, the versions declared by `Bare.versions` will be tested against the requirements declared by the package and resolution fail if they're not satisfied.

See also [#see-also]

* Builds on `bare-bundle`, `bare-module-lexer`, `bare-module-resolve`, `bare-path`, `bare-type-stripper`, and `bare-url`.
* [`bare-module-resolve`](/reference/bare/modules/bare-module-resolve) and [`bare-module-traverse`](/reference/bare/modules/bare-module-traverse) — the resolution and traversal algorithms underneath.
* [Bare runtime API](/reference/bare/runtime#bareaddon) — `Bare.Addon`, the native-addon loader `require.addon` builds on.
* [Bare modules](/reference/modules/bare-modules) — the full `bare-*` catalog.
* [Bare runtime API](/reference/bare/runtime) — the runtime these modules extend.


# bare-net



<mark style={{ backgroundColor: '#7dde9a', padding: '2px 8px', borderRadius: '4px', fontSize: '0.85em', fontWeight: 500 }}>
  stable
</mark>

[`bare-net`](https://github.com/holepunchto/bare-net) — TCP and IPC servers and clients for JavaScript.

```sh
npm i bare-net
```

Usage [#usage]

```js
const net = require('bare-net')

const server = net.createServer()
server.on('connection', (socket) => socket.on('data', console.log))
server.listen(() => console.log('server is up'))

const { port } = server.address()
const socket = net.createConnection(port)
socket.write('hello world')
```

API [#api]

NetSocket [#netsocket]

new NetSocket(opts?: NetOptions) [#new-netsocketopts-netoptions]

Create a `NetSocket`.

**Parameters**

| Parameter | Type                        | Default | Description                                                                                    |
| --------- | --------------------------- | ------- | ---------------------------------------------------------------------------------------------- |
| `opts?`   | [`NetOptions`](#netoptions) | —       | Options; `readBufferSize` defaults to `65536`, and `allowHalfOpen` and `eagerOpen` to `false`. |

connect(path: string, opts?: PipeConnectOptions, onconnect?: () => void): this [#connectpath-string-opts-pipeconnectoptions-onconnect---void-this]

Connect the socket to a `path` over IPC, or to a `port`/`host` over TCP.

Overloads:

```ts
connect(path: string, opts?: PipeConnectOptions, onconnect?: () => void): this
connect(path: string, onconnect: () => void): this
connect(port: number, host?: string, opts?: TCPSocketConnectOptions, onconnect?: () => void): this
connect(port: number, host: string, onconnect: () => void): this
connect(port: number, onconnect: () => void): this
connect(opts: NetSocketConnectOptions, onconnect?: () => void): this
```

**Parameters**

| Parameter    | Type                 | Default | Description                                                                                                                          |
| ------------ | -------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `path`       | `string`             | —       | The path to connect to over IPC.                                                                                                     |
| `opts?`      | `PipeConnectOptions` | —       | Connection options passed to the underlying socket; `path`, `port`, and `host` may be given here instead of as positional arguments. |
| `onconnect?` | `() => void`         | —       | Called once when the socket emits `'connect'`.                                                                                       |

connecting: boolean [#connecting-boolean]

`true` while the underlying socket is in the process of connecting.

localAddress: string [#localaddress-string]

Local IP address the socket is connected on, if connected over TCP.

localFamily: string [#localfamily-string]

Local IP address family, if connected over TCP.

localPort: number [#localport-number]

Local port the socket is connected on, if connected over TCP.

pending: boolean [#pending-boolean]

`true` if the socket hasn't been assigned an underlying TCP or IPC socket yet.

readyState: 'open' | 'readOnly' | 'writeOnly' | 'opening' [#readystate-open--readonly--writeonly--opening]

Current connection state of the socket.

NetSocket.ref(): this [#netsocketref-this]

Reference the socket, keeping the event loop alive while it is open.

remoteAddress: string [#remoteaddress-string]

Remote IP address the socket is connected to, if connected over TCP.

remoteFamily: string [#remotefamily-string]

Remote IP address family, if connected over TCP.

remotePort: number [#remoteport-number]

Remote port the socket is connected to, if connected over TCP.

setKeepAlive(enable?: boolean, delay?: number): this [#setkeepaliveenable-boolean-delay-number-this]

Enable or disable TCP keep-alive on the underlying socket.

Overloads:

```ts
setKeepAlive(enable?: boolean, delay?: number): this
setKeepAlive(delay: number): this
```

**Parameters**

| Parameter | Type      | Default | Description                                                                  |
| --------- | --------- | ------- | ---------------------------------------------------------------------------- |
| `enable?` | `boolean` | —       | Whether to enable keep-alive.                                                |
| `delay?`  | `number`  | —       | The initial delay in milliseconds before the first keep-alive probe is sent. |

setNoDelay(enable?: boolean): this [#setnodelayenable-boolean-this]

Enable or disable Nagle's algorithm on the underlying socket.

**Parameters**

| Parameter | Type      | Default | Description                                                            |
| --------- | --------- | ------- | ---------------------------------------------------------------------- |
| `enable?` | `boolean` | —       | When `true` (the default), data is sent immediately without buffering. |

setTimeout(ms: number, ontimeout?: () => void): this [#settimeoutms-number-ontimeout---void-this]

Set the socket's inactivity timeout.

**Parameters**

| Parameter    | Type         | Default | Description                                                              |
| ------------ | ------------ | ------- | ------------------------------------------------------------------------ |
| `ms`         | `number`     | —       | The inactivity timeout in milliseconds; pass `0` to disable the timeout. |
| `ontimeout?` | `() => void` | —       | Called once when the socket emits `'timeout'`.                           |

timeout: number [#timeout-number]

The socket's current inactivity timeout, in milliseconds.

NetSocket.unref(): this [#netsocketunref-this]

Unreference the socket, allowing the event loop to exit while it is open.

NetServer [#netserver]

new NetServer(opts?: NetOptions, onconnection?: (socket: NetSocket) => void) [#new-netserveropts-netoptions-onconnection-socket-netsocket--void]

Create a `NetServer`, optionally registering a `connection` listener.

Overloads:

```ts
new NetServer(opts?: NetOptions, onconnection?: (socket: NetSocket) => void)
new NetServer(onconnection: (socket: NetSocket) => void)
```

**Parameters**

| Parameter       | Type                          | Default | Description                                                                                                                         |
| --------------- | ----------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `opts?`         | [`NetOptions`](#netoptions)   | —       | Options applied to each accepted socket; `readBufferSize` defaults to `65536`, and `allowHalfOpen` and `pauseOnConnect` to `false`. |
| `onconnection?` | `(socket: NetSocket) => void` | —       | Called on each `'connection'` event.                                                                                                |

address(): string | TCPSocketAddress | null [#address-string--tcpsocketaddress--null]

Returns the address the server is listening on, or `null` if it isn't listening.

close(onclose: (err?: Error) => void): this [#closeonclose-err-error--void-this]

Stop the server from accepting new connections.

**Parameters**

| Parameter | Type                    | Default | Description                                  |
| --------- | ----------------------- | ------- | -------------------------------------------- |
| `onclose` | `(err?: Error) => void` | —       | Called once when the server emits `'close'`. |

listen [#listen]

```ts
listen(path: string, backlog?: number, opts?: PipeServerListenOptions, onlistening?: () => void): this
```

Start the server listening on a `path` over IPC, or a `port`/`host` over TCP.

**Parameters**

| Parameter      | Type                      | Default | Description                                             |
| -------------- | ------------------------- | ------- | ------------------------------------------------------- |
| `path`         | `string`                  | —       | The path to listen on over IPC.                         |
| `backlog?`     | `number`                  | —       | The maximum length of the queue of pending connections. |
| `opts?`        | `PipeServerListenOptions` | —       | —                                                       |
| `onlistening?` | `() => void`              | —       | Called once when the server emits `'listening'`.        |

listening: boolean [#listening-boolean]

`true` if the server is currently listening for connections.

NetServer.ref(): this [#netserverref-this]

Reference the server, keeping the event loop alive while it is listening.

NetServer.unref(): this [#netserverunref-this]

Unreference the server, allowing the event loop to exit while it is listening.

Functions [#functions]

createConnection [#createconnection]

```ts
createConnection(path: string, opts?: NetOptions & PipeConnectOptions, onconnect?: () => void): NetSocket
```

Create a `NetSocket` and connect it over IPC if a `path` is given, otherwise over TCP.

**Parameters**

| Parameter    | Type                              | Default | Description                                                                                               |
| ------------ | --------------------------------- | ------- | --------------------------------------------------------------------------------------------------------- |
| `path`       | `string`                          | —       | The path to connect to over IPC.                                                                          |
| `opts?`      | `NetOptions & PipeConnectOptions` | —       | Options for the socket and connection; if `path` is set the socket connects over IPC, otherwise over TCP. |
| `onconnect?` | `() => void`                      | —       | Called when the connection is established.                                                                |

createServer(opts?: NetOptions, onconnection?: (socket: NetSocket) => void): NetServer [#createserveropts-netoptions-onconnection-socket-netsocket--void-netserver]

Create a `NetServer`, optionally registering a `connection` listener.

Overloads:

```ts
createServer(opts?: NetOptions, onconnection?: (socket: NetSocket) => void): NetServer
createServer(onconnection: (socket: NetSocket) => void): NetServer
```

**Parameters**

| Parameter       | Type                          | Default | Description                                                                                                                         |
| --------------- | ----------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `opts?`         | [`NetOptions`](#netoptions)   | —       | Options applied to each accepted socket; `readBufferSize` defaults to `65536`, and `allowHalfOpen` and `pauseOnConnect` to `false`. |
| `onconnection?` | `(socket: NetSocket) => void` | —       | Called on each `'connection'` event.                                                                                                |

isIP(host: string): IPFamily | 0 [#isiphost-string-ipfamily--0]

**Parameters**

| Parameter | Type     | Default | Description |
| --------- | -------- | ------- | ----------- |
| `host`    | `string` | —       | —           |

isIPv4(host: string): boolean [#isipv4host-string-boolean]

**Parameters**

| Parameter | Type     | Default | Description |
| --------- | -------- | ------- | ----------- |
| `host`    | `string` | —       | —           |

isIPv6(host: string): boolean [#isipv6host-string-boolean]

**Parameters**

| Parameter | Type     | Default | Description |
| --------- | -------- | ------- | ----------- |
| `host`    | `string` | —       | —           |

Constants and variables [#constants-and-variables]

constants [#constants]

```ts
constants: {
  type: { TCP: 1; IPC: 2 }
  state: { UNREFED: number; BINDING: number; BOUND: number }
}
```

Connection type and internal state flags used by sockets and servers.

Types [#types]

NetOptions [#netoptions]

```ts
interface NetOptions {
  allowHalfOpen?: boolean
  eagerOpen?: boolean
  readBufferSize?: number
}
```

Options accepted when constructing a `NetSocket` or `NetServer`.

NetSocketEvents [#netsocketevents]

```ts
interface NetSocketEvents {
  connect: []
  data: [data: unknown]
  end: []
  readable: []
  piping: [dest: Writable]
  close: []
  error: [err: Error]
  drain: []
  finish: []
  pipe: [src: Readable]
}
```

Events emitted by a `NetSocket`, extending the underlying duplex stream's events.

NetSocketConnectOptions [#netsocketconnectoptions]

```ts
interface NetSocketConnectOptions {
  path?: string
  lookup?: DNSLookup
  host?: string
  keepAlive?: boolean
  keepAliveInitialDelay?: boolean
  noDelay?: boolean
  port?: number
  timeout?: number
  family?: `IPv${IPFamily}` | IPFamily | 0
  hints?: number
  all?: boolean
}
```

NetServerEvents [#netserverevents]

```ts
interface NetServerEvents {
  close: []
  connection: [socket: NetSocket]
  error: [err: Error]
  listening: []
}
```

Events emitted by a `NetServer`.

NetServerListenOptions [#netserverlistenoptions]

```ts
interface NetServerListenOptions {
  path?: string
  backlog?: number
  lookup?: DNSLookup
  host?: string
  port?: number
  family?: `IPv${IPFamily}` | IPFamily | 0
  hints?: number
  all?: boolean
}
```

Classes [#classes]

errors [#errors]

```ts
class errors {
  code: string
}
```

bare-net/constants [#bare-netconstants]

Constants and variables [#constants-and-variables-1]

constants.constants [#constantsconstants]

```ts
constants: {
  type: { TCP: 1; IPC: 2 }
  state: { UNREFED: number; BINDING: number; BOUND: number }
}
```

Connection type and internal state flags used by sockets and servers.

bare-net/errors [#bare-neterrors]

Classes [#classes-1]

NetError [#neterror]

```ts
class NetError {
  code: string
}
```

See also [#see-also]

* Builds on `bare-events`, `bare-pipe`, `bare-stream`, and `bare-tcp`.
* [Bare modules](/reference/modules/bare-modules) — the full `bare-*` catalog.
* [Bare runtime API](/reference/bare/runtime) — the runtime these modules extend.


# bare-os



<mark style={{ backgroundColor: '#7dde9a', padding: '2px 8px', borderRadius: '4px', fontSize: '0.85em', fontWeight: 500 }}>
  stable
</mark>

[`bare-os`](https://github.com/holepunchto/bare-os) exposes operating-system information and process utilities for [Bare](/reference/bare/runtime), closely mirroring the Node.js `os` module so most Node code ports directly.

Mirrors the Node.js [`os`](https://nodejs.org/api/os.html) module.

```sh
npm i bare-os
```

Usage [#usage]

```js
const os = require('bare-os')

console.log(os.platform()) // 'darwin', 'linux', 'win32', ...
console.log(os.arch()) // 'arm64', 'x64', ...
console.log(os.homedir())
console.log(os.tmpdir())
console.log(os.hostname())
console.log(os.networkInterfaces())
```

API [#api]

System and platform [#system-and-platform]

platform(): 'android' | 'darwin' | 'ios' | 'linux' | 'win32' [#platform-android--darwin--ios--linux--win32]

Returns the operating system platform as a string. Possible values include `'android'`, `'darwin'`, `'ios'`, `'linux'`, and `'win32'`.

arch(): 'arm' | 'arm64' | 'ia32' | 'x64' [#arch-arm--arm64--ia32--x64]

Returns the CPU architecture as a string. Possible values include `'arm'`, `'arm64'`, `'ia32'`, and `'x64'`.

type(): string [#type-string]

Returns the operating system name as returned by `uname(3)`.

version(): string [#version-string]

Returns the operating system version.

release(): string [#release-string]

Returns the operating system release.

machine(): string [#machine-string]

Returns the machine type as a string.

endianness(): 'LE' | 'BE' [#endianness-le--be]

Returns `'LE'` on little-endian systems and `'BE'` on big-endian systems.

availableParallelism(): number [#availableparallelism-number]

Returns the number of logical CPU cores available to the process.

Process and scheduling [#process-and-scheduling]

pid(): number [#pid-number]

Returns the process ID.

ppid(): number [#ppid-number]

Returns the parent process ID.

cwd(): string [#cwd-string]

Returns the current working directory.

chdir(dir: string): void [#chdirdir-string-void]

Changes the current working directory to `dir`.

**Parameters**

| Parameter | Type     | Default | Description                                              |
| --------- | -------- | ------- | -------------------------------------------------------- |
| `dir`     | `string` | —       | Path of the directory to make the new working directory. |

**Throws**

* Thrown with the underlying system error code (for example `ENOENT`) when `dir` does not exist or cannot be entered.

execPath(): string [#execpath-string]

Returns the absolute path of the executable that started the process.

kill(pid: number, signal?: string | number): void [#killpid-number-signal-string--number-void]

Sends `signal` to the process identified by `pid`. `signal` can be a string or a number. Defaults to `'SIGTERM'`.

**Parameters**

| Parameter | Type                 | Default | Description                                                                                                           |
| --------- | -------------------- | ------- | --------------------------------------------------------------------------------------------------------------------- |
| `pid`     | `number`             | —       | Process id to signal.                                                                                                 |
| `signal?` | `string` \| `number` | —       | Signal name or number to send (default `'SIGTERM'`); `0` probes for the process's existence without sending a signal. |

**Throws**

* `UNKNOWN_SIGNAL` — Thrown as an `OSError` when `signal` is a string that is not a recognized signal name.
* Thrown with the underlying system error code (for example `ESRCH`) when `pid` does not identify a running process.

getProcessTitle(): string [#getprocesstitle-string]

Returns the current process title.

setProcessTitle(title: unknown): void [#setprocesstitletitle-unknown-void]

Sets the process title. `title` is coerced to a string and must be shorter than 256 characters.

**Parameters**

| Parameter | Type      | Default | Description                                                |
| --------- | --------- | ------- | ---------------------------------------------------------- |
| `title`   | `unknown` | —       | New process title; coerced to a string if not already one. |

**Throws**

* `TITLE_OVERFLOW` — Thrown as an `OSError` when the process title is 256 characters or longer.

getPriority(pid?: number): number [#getprioritypid-number-number]

Returns the scheduling priority of the process specified by `pid`. Defaults to `0`, meaning the current process.

**Parameters**

| Parameter | Type     | Default | Description                                                 |
| --------- | -------- | ------- | ----------------------------------------------------------- |
| `pid?`    | `number` | —       | Process id to query; defaults to `0` (the current process). |

setPriority(priority: number): void [#setprioritypriority-number-void]

Sets the scheduling priority of the process specified by `pid`. If `pid` is omitted, the priority of the current process is set.

Overloads:

```ts
setPriority(priority: number): void
setPriority(pid: number, priority: number): void
```

**Parameters**

| Parameter  | Type     | Default | Description                                                             |
| ---------- | -------- | ------- | ----------------------------------------------------------------------- |
| `priority` | `number` | —       | Nice value to set (the current process, when called with one argument). |

Users and network [#users-and-network]

userInfo(uid?: number): UserInfo [#userinfouid-number-userinfo]

Returns information about a current user. The `uid` value defaults to the current effective uid.

**Parameters**

| Parameter | Type     | Default | Description                                                |
| --------- | -------- | ------- | ---------------------------------------------------------- |
| `uid?`    | `number` | —       | User ID to look up; defaults to the current effective uid. |

groupInfo(gid?: number): GroupInfo | null [#groupinfogid-number-groupinfo--null]

Returns information about a group. The `gid` value defaults to the effective group ID of the calling process.

**Parameters**

| Parameter | Type     | Default | Description                                                                     |
| --------- | -------- | ------- | ------------------------------------------------------------------------------- |
| `gid?`    | `number` | —       | Group ID to look up; defaults to the effective group ID of the calling process. |

**Returns** [`GroupInfo`](#groupinfo) | `null` — `null` on platforms that do not support group lookups (for example, Windows).

hostname(): string [#hostname-string]

Returns the hostname of the operating system.

networkInterfaces(): Record<string, NetworkInterface[]> [#networkinterfaces-recordstring-networkinterface]

Returns an object containing network interfaces that have been assigned a network address. Each key on the returned object identifies a network interface.

Memory and CPU [#memory-and-cpu]

cpus [#cpus]

```ts
cpus(): {
  model: string
  speed: number
  times: {
    user: number
    nice: number
    sys: number
    idle: number
    irq: number
  }
}[]
```

Returns an array of objects describing each logical CPU core.

cpuUsage(previous?: CpuUsage): CpuUsage [#cpuusageprevious-cpuusage-cpuusage]

Returns an object with `user` and `system` properties, each representing CPU time in microseconds. If `previous` is provided, the returned values are relative to it.

**Parameters**

| Parameter   | Type                    | Default | Description                                                        |
| ----------- | ----------------------- | ------- | ------------------------------------------------------------------ |
| `previous?` | [`CpuUsage`](#cpuusage) | —       | A previous `CpuUsage` snapshot to compute a relative diff against. |

threadCpuUsage(previous?: CpuUsage): CpuUsage [#threadcpuusageprevious-cpuusage-cpuusage]

Like `os.cpuUsage()` but for the current thread only.

**Parameters**

| Parameter   | Type                    | Default | Description                                                                                  |
| ----------- | ----------------------- | ------- | -------------------------------------------------------------------------------------------- |
| `previous?` | [`CpuUsage`](#cpuusage) | —       | A previous `CpuUsage` snapshot (from `threadCpuUsage()`) to compute a relative diff against. |

resourceUsage [#resourceusage]

```ts
resourceUsage(): {
  userCPUTime: number
  systemCPUTime: number
  maxRSS: number
  sharedMemorySize: number
  unsharedDataSize: number
  unsharedStackSize: number
  minorPageFault: number
  majorPageFault: number
  swappedOut: number
  fsRead: number
  fsWrite: number
  ipcSent: number
  ipcReceived: number
  signalsCount: number
  voluntaryContextSwitches: number
  involuntaryContextSwitches: number
}
```

Returns an object describing the resource usage of the current process.

memoryUsage [#memoryusage]

```ts
memoryUsage(): {
  rss: number
  heapTotal: number
  heapUsed: number
  external: number
}
```

Returns an object describing the memory usage of the process.

freemem(): number [#freemem-number]

Returns the amount of free system memory in bytes.

totalmem(): number [#totalmem-number]

Returns the total amount of system memory in bytes.

availableMemory(): number [#availablememory-number]

Returns an estimate of the amount of memory available for the process in bytes.

constrainedMemory(): number [#constrainedmemory-number]

Returns the amount of memory available to the process under resource constraints, such as cgroups.

uptime(): number [#uptime-number]

Returns the system uptime in seconds.

loadavg(): ArrayLike<number> [#loadavg-arraylikenumber]

Returns an array containing the 1, 5, and 15 minute load averages.

Directories [#directories]

tmpdir(): string [#tmpdir-string]

Returns the operating system's default directory for temporary files.

homedir(): string [#homedir-string]

Returns the home directory of the current user.

Environment variables [#environment-variables]

getEnvKeys(): string[] [#getenvkeys-string]

Returns an array of the names of all environment variables.

getEnv(name: string): string | undefined [#getenvname-string-string--undefined]

Returns the value of the environment variable `name`, or `undefined` if it is not set.

**Parameters**

| Parameter | Type     | Default | Description                               |
| --------- | -------- | ------- | ----------------------------------------- |
| `name`    | `string` | —       | Name of the environment variable to read. |

hasEnv(name: string): boolean [#hasenvname-string-boolean]

Returns `true` if the environment variable `name` is set, otherwise `false`.

**Parameters**

| Parameter | Type     | Default | Description                                |
| --------- | -------- | ------- | ------------------------------------------ |
| `name`    | `string` | —       | Name of the environment variable to check. |

setEnv(name: string, value: string): void [#setenvname-string-value-string-void]

Sets the environment variable `name` to `value`.

**Parameters**

| Parameter | Type     | Default | Description                                  |
| --------- | -------- | ------- | -------------------------------------------- |
| `name`    | `string` | —       | Name of the environment variable to set.     |
| `value`   | `string` | —       | Value to assign to the environment variable. |

unsetEnv(name: string): void [#unsetenvname-string-void]

Removes the environment variable `name`.

**Parameters**

| Parameter | Type     | Default | Description                                 |
| --------- | -------- | ------- | ------------------------------------------- |
| `name`    | `string` | —       | Name of the environment variable to remove. |

Constants [#constants]

EOL: '\r\n' | '\n' [#eol-rn--n]

The platform-specific end-of-line marker: `'\r\n'` on Windows, `'\n'` everywhere else.

devNull: '\\\\.\\nul' | '/dev/null' [#devnull-nul--devnull]

The platform-specific path to the null device: `'\\.\nul'` on Windows, `'/dev/null'` everywhere else.

constants [#constants-1]

```ts
constants: {
  signals: Record<string, number>
  errnos: Record<string, number>
  priority: Record<string, number>
}
```

An object of signal, error-number, and process-priority constants.

errors [#errors]

```ts
class errors {
  code: string
}
```

Types [#types]

NetworkInterface [#networkinterface]

```ts
interface NetworkInterface {
  address: string
  netmask: string
  family: 'IPv4' | 'IPv6'
  cidr: string
  mac: string
  internal: boolean
  scopeid?: number
}
```

UserInfo [#userinfo]

```ts
interface UserInfo {
  uid: number
  gid: number
  username: string
  homedir: string
  shell: string | null
}
```

GroupInfo [#groupinfo]

```ts
interface GroupInfo {
  groupname: string
  gid: number
  members: string[]
}
```

CpuUsage [#cpuusage]

```ts
interface CpuUsage {
  user: number
  system: number
}
```

bare-os/constants [#bare-osconstants]

Constants and variables [#constants-and-variables]

constants.constants [#constantsconstants]

```ts
constants: {
  signals: Record<string, number>
  errnos: Record<string, number>
  priority: Record<string, number>
}
```

An object of signal, error-number, and process-priority constants.

bare-os/errors [#bare-oserrors]

Classes [#classes]

OSError [#oserror]

```ts
class OSError {
  code: string
}
```

See also [#see-also]

* [`bare-process`](/reference/bare/modules/bare-process) — process-level control that complements these OS utilities.
* The higher-level `bare-env` wraps `getEnv`/`setEnv`/etc. into a `process.env`-style object.
* [Bare runtime API](/reference/bare/runtime) — `Bare.platform` and `Bare.arch` for compile-time identifiers.
* [Bare modules](/reference/modules/bare-modules) — the full `bare-*` catalog.
* [Bare runtime API](/reference/bare/runtime) — the runtime these modules extend.


# bare-pack



<mark style={{ backgroundColor: '#7dde9a', padding: '2px 8px', borderRadius: '4px', fontSize: '0.85em', fontWeight: 500 }}>
  stable
</mark>

[`bare-pack`](https://github.com/holepunchto/bare-pack) — Bundle packing for Bare.

```sh
npm i bare-pack
```

Usage [#usage]

```js
const pack = require('bare-pack')

async function readModule(url) {
  // Read `url` if it exists, otherwise `null`
}

async function* listPrefix(url) {
  // Yield URLs that have `url` as a prefix. The list may be empty.
}

const bundle = await pack(new URL('file:///directory/file.js'), readModule, listPrefix)
```

API [#api]

Functions [#functions]

pack [#pack]

```ts
pack(entry: URL, opts: PackOptions, readModule: ReadModuleCallback, listPrefix: ListPrefixCallback | null, writeFile: WriteFileCallback): Promise<Bundle>
```

Bundle the module graph rooted at `url`, which must be a WHATWG `URL` instance. `readModule` is called with a `URL` instance for every module to be read and must either return the module source, if it exists, or `null`. `listPrefix` is called with a `URL` instance of every prefix to be listed and must yield `URL` instances that have the specified `URL` as a prefix. If not provided, prefixes won't be bundled. `writeFile` is called for every addon or asset that should be offloaded rather than embedded; see the [Offloading section of the README](https://github.com/holepunchto/bare-pack#offloading). When `writeFile` is provided, `listPrefix` must be passed positionally (or as `null`).

**Parameters**

| Parameter    | Type                                                  | Default | Description                                                                                                                                                                                                                                                                                             |
| ------------ | ----------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `entry`      | `URL`                                                 | —       | The root of the module graph to bundle; must be a WHATWG `URL` instance (typically a `file:` URL).                                                                                                                                                                                                      |
| `opts`       | [`PackOptions`](#packoptions)                         | —       | Packing options, extending [`TraverseOptions`](/reference/bare/modules/bare-module-traverse) from `bare-module-traverse`. Adds `concurrency`, `base` (the URL that offloaded file paths are made relative to), and `offload` (whether to write addons and/or assets to disk instead of embedding them). |
| `readModule` | [`ReadModuleCallback`](#readmodulecallback)           | —       | Called with a `URL` for every module in the graph; returns the module source as a `Buffer` or string, or `null` if it does not exist.                                                                                                                                                                   |
| `listPrefix` | [`ListPrefixCallback`](#listprefixcallback) \| `null` | —       | Called with a `URL` for every prefix to list; yields the `URL`s that have it as a prefix. Pass `null` (or omit) to skip prefix bundling.                                                                                                                                                                |
| `writeFile`  | [`WriteFileCallback`](#writefilecallback)             | —       | Called for each addon or asset to offload rather than embed, receiving the file `URL` and its source. See the [Offloading section of the README](https://github.com/holepunchto/bare-pack#offloading).                                                                                                  |

**Returns** `Promise<Bundle>` — a promise that resolves to the packed [`bare-bundle`](https://github.com/holepunchto/bare-bundle) `Bundle`, with all statically resolvable imports preresolved.

Types [#types]

PackOptions [#packoptions]

```ts
interface PackOptions {
  concurrency?: number
  base?: URL | string
  offload?: boolean | { addons?: boolean; assets?: boolean }
  defaultType?: number
  aliases?: Record<string, AliasableExtension>
  resolve?: (entry: Import, parentURL: URL, opts?: ResolveOptions) => Resolver
  builtinProtocol?: string
  builtins?: Builtins
  conditions?: Conditions
  extensions?: string[]
  host?: string
  hosts?: string[]
  linked?: boolean
  linkedProtocol?: string
  matchedConditions?: string[]
  resolutions?: ResolutionsMap
}
```

ReadModuleCallback [#readmodulecallback]

```ts
interface ReadModuleCallback {
}
```

ListPrefixCallback [#listprefixcallback]

```ts
interface ListPrefixCallback {
}
```

WriteFileCallback [#writefilecallback]

```ts
interface WriteFileCallback {
}
```

CLI [#cli]

bare-pack [flags] <entry> [#bare-pack-flags-entry]

Bundle the module graph rooted at `<entry>`. If `--out` is provided, the bundle will be written to the specified file. Otherwise, the bundle will be written to `stdout`.

Flags include:

```console
--version|-v
--base <path>
--out|-o <path>
--builtins <path>
--imports <path>
--defer <specifier>
--linked
--offload
--offload-addons
--offload-assets
--format|-f
--encoding|-e
--host <host>
--help|-h
```

Host [#host]

By default, the bundle will be created for the host platform and architecture. To instead create a bundle for a different system, pass the `--host` flags.

```console
bare-pack --host <platform>[-<arch>[-<environment>]] index.js
```

The `--host` flag may be specified multiple times to create a combined bundle for multiple systems.

> \[!TIP]
> Most often you'll use one of the possible values of [`Bare.Addon.host`](https://github.com/holepunchto/bare#addonhost). Omitting the architecture and environment is also valid; `--host ios` will create a bundle for iOS with no architecture specific code, for example, whereas `--host ios-arm64-simulator` will create a bundle specifically for iOS ARM64 simulators.

Linking [#linking]

If your runtime environment dynamically links native addons ahead of time using [https://github.com/holepunchto/bare-link](https://github.com/holepunchto/bare-link), pass the `--linked` flag to ensure that addons resolve to `linked:` specifiers instead of `file:` prebuilds. This will mostly always be necessary when targeting mobile as both iOS and Android require native code to be linked ahead of time rather than loaded at runtime from disk.

```console
bare-pack --linked index.js
```

`index.js`

```js
const addon = require.addon()
```

`package.json`

```json
{
  "name": "addon",
  "version": "1.0.0",
  "addon": true
}
```

`require.addon()` will then resolve to `linked:addon.1.0.0.framework/addon.1.0.0` on macOS and iOS, `linked:libaddon.1.0.0.so` on Linux and Android, and `linked:addon-1.0.0.dll` on Windows.

See [`example/addon`](example/addon) for the full example.

Builtins [#builtins]

If your runtime environment includes builtin modules or statically embeds native addons, pass the `--builtins` flag and point it at a module exporting the list of builtins.

```console
bare-pack --builtins builtins.json index.js
```

`index.js`

```js
const addon = require('addon')
```

`package.json`

```json
{
  "name": "builtin",
  "version": "1.0.0",
  "dependencies": {
    "addon": "file:../addon"
  }
}
```

To treat both the `addon` JavaScript module and native addon as being provided by the runtime environment, do:

`builtins.json`

```json
["addon"]
```

To instead bundle the `addon` JavaScript module and only treat the native addon as being provided by the runtime environment, do:

`builtins.json`

```json
[{ "addon": "addon" }]
```

See [`example/builtin`](example/builtin) for the full example.

Offloading [#offloading]

To keep addons and assets out of the bundle and write them to disk alongside `--out` instead, pass `--offload` (or `--offload-addons` / `--offload-assets` for a single kind). `--out` is required.

```console
bare-pack --offload --out ./dist/index.bundle index.js
```

Each offloaded file is written at the directory of `--out`, mirroring its path relative to `--base`. The bundle's resolution for the file becomes `/../<path-relative-to-base>`, so when the bundle is later mounted (for example at `./dist/index.bundle/`) the resolution points to the file's location next to the bundle. If `--out` happens to be inside `--base`, the file is not rewritten on disk.

Format [#format]

The bundle format to use will be inferred from the `--out` flag if specified and can also be set directly using the `--format` and `--encoding` flags.

```console
bare-pack --format <bundle.cjs|bundle.mjs|bundle.json|bundle> --encoding <utf8|base64|ascii|hex|utf16le> index.js
```

| Format        | Extensions                  | Description                       |
| ------------- | --------------------------- | --------------------------------- |
| `bundle.cjs`  | `.bundle.js`, `.bundle.cjs` | CommonJS wrapper for a `.bundle`  |
| `bundle.mjs`  | `.bundle.mjs`               | ES module wrapper for a `.bundle` |
| `bundle.json` | `.bundle.json`              | JSON wrapper for a `.bundle`      |
| `bundle`      | `.bundle`, `.*`             | Raw `.bundle`                     |

The default encoding is `utf8` for all text formats. Use `base64` or `hex` if combining a text format with native addons or binary assets.

See also [#see-also]

* Builds on `bare-bundle`, `bare-bundle-id`, `bare-fs`, `bare-module-traverse`, and `bare-path`.
* [Bare modules](/reference/modules/bare-modules) — the full `bare-*` catalog.
* [Bare runtime API](/reference/bare/runtime) — the runtime these modules extend.


# bare-path



<mark style={{ backgroundColor: '#7dde9a', padding: '2px 8px', borderRadius: '4px', fontSize: '0.85em', fontWeight: 500 }}>
  stable
</mark>

[`bare-path`](https://github.com/holepunchto/bare-path) — Path manipulation library for JavaScript. It is a native addon.

Mirrors the Node.js [`path`](https://nodejs.org/api/path.html) module.

```sh
npm i bare-path
```

Usage [#usage]

```js
const path = require('bare-path')

path.join('foo', 'bar') // foo/bar on posix, foo\bar on windows
```

API [#api]

Joining and resolving [#joining-and-resolving]

path.join(...paths: string[]): string [#pathjoinpaths-string-string]

Joins all given path segments using the platform-specific separator, then normalizes the result.

**Parameters**

| Parameter | Type       | Default | Description                                             |
| --------- | ---------- | ------- | ------------------------------------------------------- |
| `paths`   | `string[]` | —       | The path segments to join together, in the order given. |

**Throws**

* `TypeError` — thrown if any path segment is not a string.

path.resolve(...args: string[]): string [#pathresolveargs-string-string]

Resolves a sequence of paths or path segments into an absolute path.

**Parameters**

| Parameter | Type       | Default | Description                                                                                       |
| --------- | ---------- | ------- | ------------------------------------------------------------------------------------------------- |
| `args`    | `string[]` | —       | The path segments to resolve, processed from right to left until an absolute path is constructed. |

**Returns** `string` — Falls back to the current working directory (or that of the resolved drive, on Windows) if none of the given segments is absolute.

**Throws**

* `TypeError` — thrown if any path segment is not a string.

path.normalize(path: string): string [#pathnormalizepath-string-string]

Normalizes `path`, resolving `.` and `..` segments.

**Parameters**

| Parameter | Type     | Default | Description            |
| --------- | -------- | ------- | ---------------------- |
| `path`    | `string` | —       | The path to normalize. |

**Throws**

* `TypeError` — thrown if `path` is not a string.

path.relative(from: string, to: string): string [#pathrelativefrom-string-to-string-string]

Returns the relative path from `from` to `to`.

**Parameters**

| Parameter | Type     | Default | Description                                 |
| --------- | -------- | ------- | ------------------------------------------- |
| `from`    | `string` | —       | The path to resolve the relative path from. |
| `to`      | `string` | —       | The path to resolve the relative path to.   |

**Returns** `string` — Both `from` and `to` are resolved to absolute paths before comparing, and an empty string is returned if they resolve to the same path.

**Throws**

* `TypeError` — thrown if `from` or `to` is not a string.

Inspecting paths [#inspecting-paths]

path.basename(path: string, suffix?: string): string [#pathbasenamepath-string-suffix-string-string]

Returns the last portion of `path`, similar to the Unix `basename` command.

**Parameters**

| Parameter | Type     | Default | Description                                                                     |
| --------- | -------- | ------- | ------------------------------------------------------------------------------- |
| `path`    | `string` | —       | The path to extract the last portion from.                                      |
| `suffix?` | `string` | —       | An optional suffix to remove from the end of the result, if it matches exactly. |

**Returns** `string` — An empty string if `suffix` equals `path` exactly.

**Throws**

* `TypeError` — thrown if `path`, or a defined `suffix`, is not a string.

path.dirname(path: string): string [#pathdirnamepath-string-string]

Returns the directory name of `path`, similar to the Unix `dirname` command.

**Parameters**

| Parameter | Type     | Default | Description                                  |
| --------- | -------- | ------- | -------------------------------------------- |
| `path`    | `string` | —       | The path to extract the directory name from. |

**Throws**

* `TypeError` — thrown if `path` is not a string.

path.extname(path: string): string [#pathextnamepath-string-string]

Returns the extension of `path`, from the last `.` to the end of the string.

**Parameters**

| Parameter | Type     | Default | Description                             |
| --------- | -------- | ------- | --------------------------------------- |
| `path`    | `string` | —       | The path to extract the extension from. |

**Returns** `string` — An empty string if `path` has no `.` in its last segment, or if that segment's only `.` is its first character (for example a dotfile).

**Throws**

* `TypeError` — thrown if `path` is not a string.

path.isAbsolute(path: string): boolean [#pathisabsolutepath-string-boolean]

Returns `true` if `path` is an absolute path.

**Parameters**

| Parameter | Type     | Default | Description       |
| --------- | -------- | ------- | ----------------- |
| `path`    | `string` | —       | The path to test. |

**Returns** `boolean` — On Windows, a drive-qualified path such as `C:\foo` is also absolute; on POSIX, only paths starting with `/` are absolute.

**Throws**

* `TypeError` — thrown if `path` is not a string.

path.toNamespacedPath(path: string): string [#pathtonamespacedpathpath-string-string]

Converts `path` to a namespace-prefixed path on Windows; returns `path` unchanged on POSIX.

**Parameters**

| Parameter | Type     | Default | Description          |
| --------- | -------- | ------- | -------------------- |
| `path`    | `string` | —       | The path to convert. |

**Returns** `string` — On Windows, resolves `path` and prefixes UNC paths with `\\?\UNC\` and drive-letter paths with `\\?\`; other paths (including non-string input) are returned unchanged.

Platform variants and separators [#platform-variants-and-separators]

path.sep: '/' | '\\' [#pathsep---]

The platform-specific path segment separator: `\` on Windows, `/` elsewhere.

path.delimiter: ':' | ';' [#pathdelimiter---]

The platform-specific path delimiter: `;` on Windows, `:` elsewhere.

path.posix [#pathposix]

The POSIX-specific implementation of the `path` methods.

path.win32 [#pathwin32]

The Windows-specific implementation of the `path` methods.

See also [#see-also]

* [Bare modules](/reference/modules/bare-modules) — the full `bare-*` catalog.
* [Bare runtime API](/reference/bare/runtime) — the runtime these modules extend.


# bare-pipe



<mark style={{ backgroundColor: '#7dde9a', padding: '2px 8px', borderRadius: '4px', fontSize: '0.85em', fontWeight: 500 }}>
  stable
</mark>

[`bare-pipe`](https://github.com/holepunchto/bare-pipe) — Native I/O pipes for JavaScript. It is a native addon and requires Bare `>=1.16.0`.

```sh
npm i bare-pipe
```

Usage [#usage]

```js
const Pipe = require('bare-pipe')

const stdout = new Pipe(1)

stdout.write('Hello world!\n')
```

API [#api]

Pipe [#pipe]

new Pipe(path: string | number, opts?: PipeOptions) [#new-pipepath-string--number-opts-pipeoptions]

Create a new pipe. If `path` is a number, it is treated as a file descriptor to open. If it is a string, it is treated as a path to connect to.

Overloads:

```ts
new Pipe(path: string | number, opts?: PipeOptions)
new Pipe(opts?: PipeOptions)
```

**Parameters**

| Parameter | Type                          | Default | Description                                                                                                                                                              |
| --------- | ----------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `path`    | `string` \| `number`          | —       | A file descriptor to open (number), or a path to connect to (string).                                                                                                    |
| `opts?`   | [`PipeOptions`](#pipeoptions) | —       | Options; `readBufferSize` defaults to `65536`, `allowHalfOpen` and `eagerOpen` to `true`, and `ipc` to `false` (set `ipc: true` to enable handle passing over the pipe). |

accept<T extends IPCAcceptable>(target: T): T [#acceptt-extends-ipcacceptabletarget-t-t]

Accept a pending handle into `target`. `target` must implement the [`IPCAcceptable`](#ipcacceptable) protocol. Call this synchronously from the `'handle'` event listener.

**Parameters**

| Parameter | Type | Default | Description                                                                                                                                       |
| --------- | ---- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `target`  | `T`  | —       | The object to accept the pending handle into; must implement the `IPCAcceptable` protocol. Call synchronously from the `'handle'` event listener. |

**Returns** `T` — `target`, for chaining the accepted handle into an expression.

**Throws**

* `INVALID_IPC_TARGET` — `target` does not implement the IPC handle protocol.

connect(path: string, opts?: PipeConnectOptions, onconnect?: () => void): this [#connectpath-string-opts-pipeconnectoptions-onconnect---void-this]

Connect the pipe to `path`. `onconnect` is called when the connection is established.

Overloads:

```ts
connect(path: string, opts?: PipeConnectOptions, onconnect?: () => void): this
connect(path: string, onconnect: () => void): this
connect(opts: PipeConnectOptions, onconnect?: () => void): this
```

**Parameters**

| Parameter    | Type                                        | Default | Description                                                         |
| ------------ | ------------------------------------------- | ------- | ------------------------------------------------------------------- |
| `path`       | `string`                                    | —       | The path to connect to.                                             |
| `opts?`      | [`PipeConnectOptions`](#pipeconnectoptions) | —       | Options; `path` may be given here instead of as the first argument. |
| `onconnect?` | `() => void`                                | —       | Called when the connection is established.                          |

**Throws**

* `PIPE_ALREADY_CONNECTED` — the pipe is already connecting or connected.

connecting: boolean [#connecting-boolean]

Whether the pipe is currently connecting.

open(fd: number, opts?: { fd?: number }, onconnect?: () => void): this [#openfd-number-opts--fd-number--onconnect---void-this]

Open the pipe on the given file descriptor.

Overloads:

```ts
open(fd: number, opts?: { fd?: number }, onconnect?: () => void): this
open(fd: number, onconnect: () => void): this
open(opts: { fd: number }, onconnect?: () => void): this
```

**Parameters**

| Parameter    | Type              | Default | Description                                  |
| ------------ | ----------------- | ------- | -------------------------------------------- |
| `fd`         | `number`          | —       | The file descriptor to open the pipe on.     |
| `opts?`      | `{ fd?: number }` | —       | —                                            |
| `onconnect?` | `() => void`      | —       | Called once when the pipe emits `'connect'`. |

pending: boolean [#pending-boolean]

Whether the pipe has not yet connected.

Pipe.constants [#pipeconstants]

```ts
Pipe.constants: {
  state: {
    CONNECTING: number
    CONNECTED: number
    BINDING: number
    BOUND: number
    READING: number
    CLOSING: number
    READABLE: number
    WRITABLE: number
    UNREFED: number
  }
  handle: {
    NAMED_PIPE: number
    TCP: number
    UDP: number
  }
}
```

Object containing internal state constants and handle type constants.

Pipe.createConnection [#pipecreateconnection]

```ts
Pipe.createConnection(path: string, opts?: CreateConnectionOptions, onconnect?: () => void): Pipe
```

Create a new pipe and connect it to `path`. Shorthand for `new Pipe(options).connect(path, options, onconnect)`.

**Parameters**

| Parameter    | Type                                                  | Default | Description                                                    |
| ------------ | ----------------------------------------------------- | ------- | -------------------------------------------------------------- |
| `path`       | `string`                                              | —       | The path to connect to.                                        |
| `opts?`      | [`CreateConnectionOptions`](#createconnectionoptions) | —       | Options passed to both the `Pipe` constructor and `connect()`. |
| `onconnect?` | `() => void`                                          | —       | Called when the connection is established.                     |

Pipe.createServer(opts?: PipeServerOptions, onconnection?: () => void): PipeServer [#pipecreateserveropts-pipeserveroptions-onconnection---void-pipeserver]

Create a new pipe server. The server extends [`EventEmitter`](https://github.com/holepunchto/bare-events).

**Parameters**

| Parameter       | Type                                      | Default | Description                                                                                                                                                |
| --------------- | ----------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `opts?`         | [`PipeServerOptions`](#pipeserveroptions) | —       | Options applied to each incoming pipe; `readBufferSize` defaults to `65536`, `allowHalfOpen` to `true`, `pauseOnConnect` to `false`, and `ipc` to `false`. |
| `onconnection?` | `() => void`                              | —       | Called on each `'connection'` event.                                                                                                                       |

Pipe.pipe(): [read: number, write: number] [#pipepipe-read-number-write-number]

**Returns** `[read: number, write: number]` — A `[read, write]` pair of file descriptors connected to each other.

readyState: 'open' | 'readOnly' | 'writeOnly' | 'opening' [#readystate-open--readonly--writeonly--opening]

The current state of the pipe. One of `'open'`, `'readOnly'`, `'writeOnly'`, or `'opening'`.

Pipe.ref(): this [#piperef-this]

Ref the pipe, preventing the process from exiting.

Pipe.unref(): this [#pipeunref-this]

Unref the pipe, allowing the process to exit.

write [#write]

```ts
write(chunk: Buffer | string, encoding: BufferEncoding, handle?: IPCAcceptable, cb?: (err: Error | null) => void): boolean
```

Write `chunk` to the pipe. If `handle` is given and the pipe was created with `ipc: true`, the handle is transferred to the receiver alongside the chunk. `handle` must implement the [`IPCAcceptable`](#ipcacceptable) protocol.

**Parameters**

| Parameter  | Type                              | Default | Description                                                                                                                                                               |
| ---------- | --------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `chunk`    | `Buffer` \| `string`              | —       | The data to write.                                                                                                                                                        |
| `encoding` | `BufferEncoding`                  | —       | The encoding of `chunk` when it is a string.                                                                                                                              |
| `handle?`  | [`IPCAcceptable`](#ipcacceptable) | —       | A handle to transfer to the receiver alongside the chunk; requires the pipe to have been created with `ipc: true` and `handle` to implement the `IPCAcceptable` protocol. |
| `cb?`      | `(err: Error \| null) => void`    | —       | Called when the chunk has been processed.                                                                                                                                 |

PipeServer [#pipeserver]

new PipeServer(opts?: PipeServerOptions, onconnection?: () => void) [#new-pipeserveropts-pipeserveroptions-onconnection---void]

Overloads:

```ts
new PipeServer(opts?: PipeServerOptions, onconnection?: () => void)
new PipeServer(onconnection: () => void)
```

**Parameters**

| Parameter       | Type                                      | Default | Description                                                                                                                                                |
| --------------- | ----------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `opts?`         | [`PipeServerOptions`](#pipeserveroptions) | —       | Options applied to each incoming pipe; `readBufferSize` defaults to `65536`, `allowHalfOpen` to `true`, `pauseOnConnect` to `false`, and `ipc` to `false`. |
| `onconnection?` | `() => void`                              | —       | Called on each `'connection'` event.                                                                                                                       |

address(): string | null [#address-string--null]

**Returns** `string` | `null` — The bound path, or `null` if the server is not listening.

close(onclose?: (err?: Error) => void): this [#closeonclose-err-error--void-this]

Close the server. No new connections will be accepted. The server emits `close` after all existing connections have ended.

**Parameters**

| Parameter  | Type                    | Default | Description                                                                             |
| ---------- | ----------------------- | ------- | --------------------------------------------------------------------------------------- |
| `onclose?` | `(err?: Error) => void` | —       | Called once when the server emits `'close'`, after all existing connections have ended. |

listen [#listen]

```ts
listen(path: string, backlog?: number, opts?: PipeServerListenOptions, onlistening?: () => void): this
```

Start listening for connections on `path`. `backlog` defaults to `511`.

**Parameters**

| Parameter      | Type                                                  | Default | Description                                                                |
| -------------- | ----------------------------------------------------- | ------- | -------------------------------------------------------------------------- |
| `path`         | `string`                                              | —       | The path to listen on.                                                     |
| `backlog?`     | `number`                                              | —       | The maximum length of the queue of pending connections (default `511`).    |
| `opts?`        | [`PipeServerListenOptions`](#pipeserverlistenoptions) | —       | `path` and `backlog` may be given here instead of as positional arguments. |
| `onlistening?` | `() => void`                                          | —       | Called once when the server emits `'listening'`.                           |

**Throws**

* `SERVER_ALREADY_LISTENING` — the server is already listening.
* `SERVER_IS_CLOSED` — the server has been closed.

listening: boolean [#listening-boolean]

Whether the server is listening.

PipeServer.ref(): this [#pipeserverref-this]

Ref the pipe, preventing the process from exiting.

PipeServer.unref(): this [#pipeserverunref-this]

Unref the pipe, allowing the process to exit.

Types [#types]

CreateConnectionOptions [#createconnectionoptions]

```ts
interface CreateConnectionOptions {
  allowHalfOpen?: boolean
  eagerOpen?: boolean
  ipc?: boolean
  readBufferSize?: number
  path?: string
}
```

IPCAcceptable [#ipcacceptable]

```ts
interface IPCAcceptable {
}
```

PipeEvents [#pipeevents]

```ts
interface PipeEvents {
  connect: []
  handle: [type: number]
  data: [data: unknown]
  end: []
  readable: []
  piping: [dest: Writable]
  close: []
  error: [err: Error]
  drain: []
  finish: []
  pipe: [src: Readable]
}
```

PipeOptions [#pipeoptions]

```ts
interface PipeOptions {
  allowHalfOpen?: boolean
  eagerOpen?: boolean
  ipc?: boolean
  readBufferSize?: number
}
```

PipeConnectOptions [#pipeconnectoptions]

```ts
interface PipeConnectOptions {
  path?: string
}
```

PipeServerEvents [#pipeserverevents]

```ts
interface PipeServerEvents {
  close: []
  connection: [pipe: Pipe]
  error: [err: Error]
  listening: []
}
```

PipeServerOptions [#pipeserveroptions]

```ts
interface PipeServerOptions {
  allowHalfOpen?: boolean
  ipc?: boolean
  pauseOnConnect?: boolean
  readBufferSize?: number
}
```

PipeServerListenOptions [#pipeserverlistenoptions]

```ts
interface PipeServerListenOptions {
  path?: string
  backlog?: number
}
```

Classes [#classes]

PipeError [#pipeerror]

```ts
class PipeError {
  code: string
}
```

bare-pipe/constants [#bare-pipeconstants]

Constants and variables [#constants-and-variables]

constants [#constants]

```ts
constants: {
  state: {
    CONNECTING: number
    CONNECTED: number
    BINDING: number
    BOUND: number
    READING: number
    CLOSING: number
    READABLE: number
    WRITABLE: number
    UNREFED: number
  }
  handle: {
    NAMED_PIPE: number
    TCP: number
    UDP: number
  }
}
```

Object containing internal state constants and handle type constants.

bare-pipe/errors [#bare-pipeerrors]

Classes [#classes-1]

errors.PipeError [#errorspipeerror]

IPC handle passing [#ipc-handle-passing]

Pipes created with `ipc: true` can transfer libuv handles (named pipes, TCP sockets, UDP sockets) to a peer alongside the byte stream. The peer receives a `'handle'` event for each transferred handle, in arrival order, before the corresponding `'data'` event.

Sender:

```js
const left = new Pipe(fd, { ipc: true })
const socket = tcp.createConnection(port)

socket.on('connect', () => {
  left.write(Buffer.from('here'), socket)
})
```

Receiver:

```js
const right = new Pipe(fd, { ipc: true })

right.on('handle', (type) => {
  if (type === Pipe.constants.handle.TCP) {
    const socket = new tcp.Socket()
    right.accept(socket)
    socket.on('data', console.log)
  }
})
```

IPCAcceptable protocol [#ipcacceptable-protocol]

Any object passed to `pipe.accept(target)` or `pipe.write(chunk, handle, ...)` must implement two well-known symbols:

```js
const ipcHandle = Symbol.for('bare.ipc.handle')
const ipcAccept = Symbol.for('bare.ipc.accept')

class MyTarget {
  get [ipcHandle]() {
    return this._handle // An ArrayBuffer backing a libuv `uv_*_t` struct
  }

  [ipcAccept]() {
    // Optional: Called synchronously after the handle has been transferred
  }
}
```

* `Symbol.for('bare.ipc.handle')` (required): A getter returning the underlying libuv handle (typically an `ArrayBuffer` whose first bytes are a `uv_stream_t` / `uv_udp_t`).
* `Symbol.for('bare.ipc.accept')` (optional): A method invoked synchronously after the handle has been transferred. Use it to initialize per-handle state (for example address lookup).

`Pipe`, `bare-tcp`'s `Socket`, and any compatible package implement this protocol natively, so a `bare-tcp` socket can be passed and received via `bare-pipe` IPC without any glue code.

TypeScript users can import the `IPCAcceptable` interface from `bare-pipe` to type the protocol.

See also [#see-also]

* Builds on `bare-events` and `bare-stream`.
* [`bare-subprocess`](/reference/bare/modules/bare-subprocess) — uses pipes for child-process stdio.
* [Bare modules](/reference/modules/bare-modules) — the full `bare-*` catalog.
* [Bare runtime API](/reference/bare/runtime) — the runtime these modules extend.


# bare-posix



<mark style={{ backgroundColor: '#7dde9a', padding: '2px 8px', borderRadius: '4px', fontSize: '0.85em', fontWeight: 500 }}>
  stable
</mark>

[`bare-posix`](https://github.com/holepunchto/bare-posix) — POSIX-specific bindings for Bare. It is a native addon.

```sh
npm i bare-posix
```

API [#api]

Functions [#functions]

getgid(): number [#getgid-number]

Returns the real group ID of the calling process.

setgid(id: number | string): void [#setgidid-number--string-void]

Set the real group ID of the calling process. Accepts a numeric ID or a group name, resolved via `getgrnam`.

**Parameters**

| Parameter | Type                 | Default | Description                                                                          |
| --------- | -------------------- | ------- | ------------------------------------------------------------------------------------ |
| `id`      | `number` \| `string` | —       | The group to switch to: a numeric group ID, or a group name resolved via `getgrnam`. |

**Throws**

* On platforms without POSIX support (android, win32), throws `Error: Platform not supported`.

getegid(): number [#getegid-number]

Returns the effective group ID of the calling process.

setegid(id: number | string): void [#setegidid-number--string-void]

Set the effective group ID of the calling process. Accepts a numeric ID or a group name, resolved via `getgrnam`.

**Parameters**

| Parameter | Type                 | Default | Description                                                                          |
| --------- | -------------------- | ------- | ------------------------------------------------------------------------------------ |
| `id`      | `number` \| `string` | —       | The group to switch to: a numeric group ID, or a group name resolved via `getgrnam`. |

**Throws**

* On platforms without POSIX support (android, win32), throws `Error: Platform not supported`.

getuid(): number [#getuid-number]

Returns the real user ID of the calling process.

setuid(id: number | string): void [#setuidid-number--string-void]

Set the real user ID of the calling process. Accepts a numeric ID or a username, resolved via `getpwnam`.

**Parameters**

| Parameter | Type                 | Default | Description                                                                      |
| --------- | -------------------- | ------- | -------------------------------------------------------------------------------- |
| `id`      | `number` \| `string` | —       | The user to switch to: a numeric user ID, or a username resolved via `getpwnam`. |

**Throws**

* On platforms without POSIX support (android, win32), throws `Error: Platform not supported`.

geteuid(): number [#geteuid-number]

Returns the effective user ID of the calling process.

seteuid(id: number | string): void [#seteuidid-number--string-void]

Set the effective user ID of the calling process. Accepts a numeric ID or a username, resolved via `getpwnam`.

**Parameters**

| Parameter | Type                 | Default | Description                                                                      |
| --------- | -------------------- | ------- | -------------------------------------------------------------------------------- |
| `id`      | `number` \| `string` | —       | The user to switch to: a numeric user ID, or a username resolved via `getpwnam`. |

**Throws**

* On platforms without POSIX support (android, win32), throws `Error: Platform not supported`.

getgroups(): number[] [#getgroups-number]

Returns the supplementary group IDs of the calling process.

getgrnam(name: string): Group | null [#getgrnamname-string-group--null]

Look up a group by name, returning its `Group` record or `null` if it doesn't exist.

**Parameters**

| Parameter | Type     | Default | Description                |
| --------- | -------- | ------- | -------------------------- |
| `name`    | `string` | —       | The group name to look up. |

**Returns** [`Group`](#group) | `null` — The matching `Group` record, or `null` if no such group exists.

getpwnam(name: string): Passwd | null [#getpwnamname-string-passwd--null]

Look up a user by name, returning its `Passwd` record or `null` if it doesn't exist.

**Parameters**

| Parameter | Type     | Default | Description               |
| --------- | -------- | ------- | ------------------------- |
| `name`    | `string` | —       | The user name to look up. |

**Returns** [`Passwd`](#passwd) | `null` — The matching `Passwd` record, or `null` if no such user exists.

Types [#types]

Group [#group]

```ts
interface Group {
  groupname: string
  passwd: string
  gid: number
  members: string[]
}
```

A POSIX group record, as returned by `getgrnam`.

Passwd [#passwd]

```ts
interface Passwd {
  username: string
  passwd: string
  uid: number
  gid: number
  gecos: string
  homedir: string
  shell: string
}
```

A POSIX user record, as returned by `getpwnam`.

See also [#see-also]

* [`bare-os`](/reference/bare/modules/bare-os) — portable OS utilities, including `userInfo` / `groupInfo`.
* [Bare modules](/reference/modules/bare-modules) — the full `bare-*` catalog.
* [Bare runtime API](/reference/bare/runtime) — the runtime these modules extend.


# bare-process



<mark style={{ backgroundColor: '#7dde9a', padding: '2px 8px', borderRadius: '4px', fontSize: '0.85em', fontWeight: 500 }}>
  stable
</mark>

[`bare-process`](https://github.com/holepunchto/bare-process) — Node.js-compatible process control for Bare.

Mirrors the Node.js [`process`](https://nodejs.org/api/process.html) module.

```sh
npm i bare-process
```

Usage [#usage]

```js
const process = require('bare-process')

process.exit()
```

To make the `process` object globally available, do:

```js
require('bare-process/global')
```

API [#api]

Types [#types]

ProcessEvents [#processevents]

```ts
interface ProcessEvents {
  beforeExit: [code: number]
  exit: [code: number]
  idle: []
  resume: []
  suspend: [linger: number]
  uncaughtException: [err: unknown]
  unhandledRejection: [reason: unknown, promise: Promise<unknown>]
  SIGBREAK: []
  SIGHUP: []
  SIGINT: []
  SIGPIPE: []
  SIGTERM: []
  SIGWINCH: []
}
```

Events emitted by `process`.

Process [#process]

```ts
interface Process<M extends ProcessEvents = ProcessEvents> {
  readonly stdin: typeof stdio.in
  readonly stdout: typeof stdio.out
  readonly stderr: typeof stdio.err
  readonly arch: ReturnType<typeof os.arch>
  readonly argv: string[]
  readonly env: Record<string, string>
  readonly execArgv: string[]
  readonly execPath: string
  readonly hrtime: typeof hrtime
  readonly pid: number
  readonly platform: ReturnType<typeof os.platform>
  readonly ppid: number
  readonly version: string
  readonly versions: Record<string, string>
  exitCode: number
  title: string
  exit(code?: number): never
  suspend(): void
  resume(): void
  cwd(): string
  chdir(dir: string): string
  kill(pid: number, signal?: string | number): void
  uptime(): number
  abort: typeof abort
  cpuUsage: typeof os.cpuUsage
  threadCpuUsage: typeof os.threadCpuUsage
  resourceUsage: typeof os.resourceUsage
  availableMemory: typeof os.availableMemory
  constrainedMemory: typeof os.constrainedMemory
  memoryUsage: typeof os.memoryUsage
  getgid: typeof posix.getgid
  setgid: typeof posix.setgid
  getegid: typeof posix.getegid
  setegid: typeof posix.setegid
  getuid: typeof posix.getuid
  setuid: typeof posix.setuid
  geteuid: typeof posix.geteuid
  seteuid: typeof posix.seteuid
  getgroups: typeof posix.getgroups
  nextTick<T extends unknown[]>(cb: (...args: T) => unknown, ...args: T): void
  addListener<E extends keyof M, R>(name: E, fn: EventHandler<M[E], R>): this
  addOnceListener<E extends keyof M, R>(name: E, fn: EventHandler<M[E], R>): this
  prependListener<E extends keyof M, R>(name: E, fn: EventHandler<M[E], R>): this
  prependOnceListener<E extends keyof M, R>(name: E, fn: EventHandler<M[E], R>): this
  removeListener<E extends keyof M, R>(name: E, fn: EventHandler<M[E], R>): this
  removeAllListeners<E extends keyof M>(name?: E): this
  on<E extends keyof M, R>(name: E, fn: EventHandler<M[E], R>): this
  once<E extends keyof M, R>(name: E, fn: EventHandler<M[E], R>): this
  off<E extends keyof M, R>(name: E, fn: EventHandler<M[E], R>): this
  emit<E extends keyof M>(name: E, ...args: M[E]): boolean
  listeners<E extends keyof M, R>(name: E): EventHandler<M[E], R>
  rawListeners<E extends keyof M, R>(name: E): EventHandler<M[E], R>[]
  eventNames(): (keyof M)[]
  listenerCount<E extends keyof M>(name: E): number
  getMaxListeners(): number
  setMaxListeners(n: number): void
}
```

Alias for the type of the global `process` object.

bare-process/global [#bare-processglobal]

Types [#types-1]

global.Process [#globalprocess]

```ts
type Process = typeof process
```

Alias for the type of the global `process` object.

See also [#see-also]

* Builds on `bare-abort`, `bare-env`, `bare-events`, `bare-hrtime`, `bare-os`, `bare-posix`, `bare-signals`, and `bare-stdio`.
* [Bare modules](/reference/modules/bare-modules) — the full `bare-*` catalog.
* [Bare runtime API](/reference/bare/runtime) — the runtime these modules extend.


# bare-prom-client



<mark style={{ backgroundColor: '#7dde9a', padding: '2px 8px', borderRadius: '4px', fontSize: '0.85em', fontWeight: 500 }}>
  stable
</mark>

[`bare-prom-client`](https://github.com/holepunchto/bare-prom-client) — Client for prometheus.

```sh
npm i bare-prom-client
```

Usage [#usage]

See example folder for a sample usage. The library does not bundle any web
framework. To expose the metrics, respond to Prometheus's scrape requests with
the result of `await registry.metrics()`.

Usage with Node.js's cluster module [#usage-with-nodejss-cluster-module]

Node.js's `cluster` module spawns multiple processes and hands off socket
connections to those workers. Returning metrics from a worker's local registry
will only reveal that individual worker's metrics, which is generally
undesirable. To solve this, you can aggregate all of the workers' metrics in the
master process. See `example/cluster.js` for an example.

Default metrics use sensible aggregation methods. (Note, however, that the event
loop lag mean and percentiles are averaged, which is not perfectly accurate.)
Custom metrics are summed across workers by default. To use a different
aggregation method, set the `aggregator` property in the metric config to one of
'sum', 'first', 'min', 'max', 'average' or 'omit'. (See `lib/metrics/version.js`
for an example.)

If you need to expose metrics about an individual worker, you can include a
value that is unique to the worker (such as the worker ID or process ID) in a
label. (See `example/server.js` for an example using
`worker_${cluster.worker.id}` as a label value.)

Metrics are aggregated from the global registry by default. To use a different
registry, call
`client.AggregatorRegistry.setRegistries(registryOrArrayOfRegistries)` from the
worker processes.

API [#api]

Registry [#registry]

clear(): void [#clear-void]

Remove all metrics from the registry

contentType: BoundRegistryContentType [#contenttype-boundregistrycontenttype]

Gets the Content-Type of the metrics for use in the response headers.

getMetricsAsArray(): MetricObject[] [#getmetricsasarray-metricobject]

Get all metrics as objects

**Returns** [`MetricObject[]`](#metricobject) — All registered metrics as plain objects.

getMetricsAsJSON(): Promise<MetricObjectWithValues<MetricValue<string>>[]> [#getmetricsasjson-promisemetricobjectwithvaluesmetricvaluestring]

Get all metrics as objects

**Returns** `Promise<MetricObjectWithValues<MetricValue<string>>[]>` — A promise resolving to all registered metrics as objects, each with its current values.

getSingleMetric<T extends string>(name: string): Metric<T> | undefined [#getsinglemetrict-extends-stringname-string-metrict--undefined]

Get a single metric

**Parameters**

| Parameter | Type     | Default | Description            |
| --------- | -------- | ------- | ---------------------- |
| `name`    | `string` | —       | The name of the metric |

**Returns** `Metric<T> | undefined` — The registered metric named `name`, or `undefined` if none is registered.

getSingleMetricAsString(name: string): Promise<string> [#getsinglemetricasstringname-string-promisestring]

Get a string representation of a single metric by name

**Parameters**

| Parameter | Type     | Default | Description            |
| --------- | -------- | ------- | ---------------------- |
| `name`    | `string` | —       | The name of the metric |

**Returns** `Promise<string>` — A promise resolving to the exposition-format string for the named metric.

metrics(): Promise<string> [#metrics-promisestring]

Get string representation for all metrics

**Returns** `Promise<string>` — A promise resolving to the exposition-format string for all registered metrics.

registerMetric<T extends string>(metric: Metric<T>): void [#registermetrict-extends-stringmetric-metrict-void]

Register metric to register

**Parameters**

| Parameter | Type        | Default | Description               |
| --------- | ----------- | ------- | ------------------------- |
| `metric`  | `Metric<T>` | —       | Metric to add to register |

Registry.merge(registers: Registry[]): Registry [#registrymergeregisters-registry-registry]

Merge registers

**Parameters**

| Parameter   | Type         | Default | Description                              |
| ----------- | ------------ | ------- | ---------------------------------------- |
| `registers` | `Registry[]` | —       | The registers you want to merge together |

**Returns** `Registry` — A new `Registry` containing the metrics of every registry in `registers`.

Registry.OPENMETRICS_CONTENT_TYPE: OpenMetricsContentType [#registryopenmetrics_content_type-openmetricscontenttype]

HTTP OpenMetrics Content-Type for metrics response headers.

Registry.PROMETHEUS_CONTENT_TYPE: PrometheusContentType [#registryprometheus_content_type-prometheuscontenttype]

HTTP Prometheus Content-Type for metrics response headers.

removeSingleMetric(name: string): void [#removesinglemetricname-string-void]

Remove a single metric

**Parameters**

| Parameter | Type     | Default | Description                      |
| --------- | -------- | ------- | -------------------------------- |
| `name`    | `string` | —       | The name of the metric to remove |

resetMetrics(): void [#resetmetrics-void]

Reset all metrics in the registry

setContentType(contentType: BoundRegistryContentType): void [#setcontenttypecontenttype-boundregistrycontenttype-void]

Set the content type of a registry. Used to change between Prometheus and
OpenMetrics versions.

**Parameters**

| Parameter     | Type                       | Default | Description              |
| ------------- | -------------------------- | ------- | ------------------------ |
| `contentType` | `BoundRegistryContentType` | —       | The type of the registry |

setDefaultLabels(labels: object): void [#setdefaultlabelslabels-object-void]

Set static labels to every metric emitted by this registry

**Parameters**

| Parameter | Type     | Default | Description                                                                         |
| --------- | -------- | ------- | ----------------------------------------------------------------------------------- |
| `labels`  | `object` | —       | Name/value pairs, for example `{ defaultLabel: 'value', anotherLabel: 'value 2' }`. |

AggregatorRegistry [#aggregatorregistry]

AggregatorRegistry.aggregate [#aggregatorregistryaggregate]

```ts
AggregatorRegistry.aggregate<T extends RegistryContentType>(metricsArr: Array<object>): Registry<T>
```

Creates a new Registry instance from an array of metrics that were
created by `registry.getMetricsAsJSON()`. Metrics are aggregated using
the method specified by their `aggregator` property, or by summation if
`aggregator` is undefined.

**Parameters**

| Parameter    | Type            | Default | Description                                                               |
| ------------ | --------------- | ------- | ------------------------------------------------------------------------- |
| `metricsArr` | `Array<object>` | —       | Array of metrics, each of which created by `registry.getMetricsAsJSON()`. |

**Returns** `Registry<T>` — aggregated registry.

AggregatorRegistry.setRegistries [#aggregatorregistrysetregistries]

```ts
AggregatorRegistry.setRegistries(regs: | Array<
					Registry<PrometheusContentType> | Registry<OpenMetricsContentType>
			  >
			| Registry<PrometheusContentType>
			| Registry<OpenMetricsContentType>): void
```

Sets the registry or registries to be aggregated. Call from workers to
use a registry/registries other than the default global registry.

**Parameters**

| Parameter | Type                                                                                                                                                     | Default | Description                              |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ---------------------------------------- |
| `regs`    | `\| Array< Registry<PrometheusContentType> \| Registry<OpenMetricsContentType> > \| Registry<PrometheusContentType> \| Registry<OpenMetricsContentType>` | —       | Registry or registries to be aggregated. |

clusterMetrics(): Promise<string> [#clustermetrics-promisestring]

Gets aggregated metrics for all workers.

**Returns** `Promise<string>` — Promise that resolves with the aggregated
metrics.

Counter [#counter]

new Counter(configuration: CounterConfiguration<T>) [#new-counterconfiguration-counterconfigurationt]

Counters go up, and reset when the process restarts (for example requests served, errors seen).

**Parameters**

| Parameter       | Type                      | Default | Description                                                              |
| --------------- | ------------------------- | ------- | ------------------------------------------------------------------------ |
| `configuration` | `CounterConfiguration<T>` | —       | Configuration when creating a Counter metric. Name and Help is required. |

Counter.Internal [#counterinternal]

```ts
interface Internal {
  inc(value?: number): void
}
```

Counter.get(): Promise<MetricObjectWithValues<MetricValue<T>>> [#counterget-promisemetricobjectwithvaluesmetricvaluet]

Get counter metric object

**Returns** `Promise<MetricObjectWithValues<MetricValue<T>>>` — A promise resolving to the counter's current value as a metric object.

Counter.inc(labels: LabelValues<T>, value?: number): void [#counterinclabels-labelvaluest-value-number-void]

Increment for given labels

Overloads:

```ts
inc(labels: LabelValues<T>, value?: number): void
inc(value?: number): void
inc(incData: IncreaseDataWithExemplar<T>): void
```

**Parameters**

| Parameter | Type             | Default | Description                       |
| --------- | ---------------- | ------- | --------------------------------- |
| `labels`  | `LabelValues<T>` | —       | Object with label keys and values |
| `value?`  | `number`         | —       | The number to increment with      |

labels(...values: string[]): Counter.Internal [#labelsvalues-string-counterinternal]

Return the child for given labels

Overloads:

```ts
labels(...values: string[]): Counter.Internal
labels(labels: LabelValues<T>): Counter.Internal
```

**Parameters**

| Parameter | Type       | Default | Description  |
| --------- | ---------- | ------- | ------------ |
| `values`  | `string[]` | —       | Label values |

**Returns** `Counter.Internal` — Configured counter with given labels

Counter.remove(...values: string[]): void [#counterremovevalues-string-void]

Remove metrics for the given label values

Overloads:

```ts
remove(...values: string[]): void
remove(labels: LabelValues<T>): void
```

**Parameters**

| Parameter | Type       | Default | Description  |
| --------- | ---------- | ------- | ------------ |
| `values`  | `string[]` | —       | Label values |

Counter.reset(): void [#counterreset-void]

Reset counter values

Gauge [#gauge]

new Gauge(configuration: GaugeConfiguration<T>) [#new-gaugeconfiguration-gaugeconfigurationt]

Gauges are similar to Counters but a Gauge's value can be decreased (for example in-flight requests, queue depth).

**Parameters**

| Parameter       | Type                    | Default | Description                                                            |
| --------------- | ----------------------- | ------- | ---------------------------------------------------------------------- |
| `configuration` | `GaugeConfiguration<T>` | —       | Configuration when creating a Gauge metric. Name and Help is mandatory |

dec(labels: LabelValues<T>, value?: number): void [#declabels-labelvaluest-value-number-void]

Decrement gauge

Overloads:

```ts
dec(labels: LabelValues<T>, value?: number): void
dec(value?: number): void
```

**Parameters**

| Parameter | Type             | Default | Description                       |
| --------- | ---------------- | ------- | --------------------------------- |
| `labels`  | `LabelValues<T>` | —       | Object with label keys and values |
| `value?`  | `number`         | —       | Value to decrement with           |

Gauge.Internal [#gaugeinternal]

```ts
interface Internal<T extends string> {
  inc(value?: number): void
  dec(value?: number): void
  set(value: number): void
  setToCurrentTime(): void
  startTimer(): (labels?: LabelValues<T>) => number
}
```

Gauge.get(): Promise<MetricObjectWithValues<MetricValue<T>>> [#gaugeget-promisemetricobjectwithvaluesmetricvaluet]

Get gauge metric object

**Returns** `Promise<MetricObjectWithValues<MetricValue<T>>>` — A promise resolving to the gauge's current value as a metric object.

Gauge.inc(labels: LabelValues<T>, value?: number): void [#gaugeinclabels-labelvaluest-value-number-void]

Increment gauge for given labels

Overloads:

```ts
inc(labels: LabelValues<T>, value?: number): void
inc(value?: number): void
```

**Parameters**

| Parameter | Type             | Default | Description                       |
| --------- | ---------------- | ------- | --------------------------------- |
| `labels`  | `LabelValues<T>` | —       | Object with label keys and values |
| `value?`  | `number`         | —       | The value to increment with       |

labels(...values: string[]): Gauge.Internal<T> [#labelsvalues-string-gaugeinternalt]

Return the child for given labels

Overloads:

```ts
labels(...values: string[]): Gauge.Internal<T>
labels(labels: LabelValues<T>): Gauge.Internal<T>
```

**Parameters**

| Parameter | Type       | Default | Description  |
| --------- | ---------- | ------- | ------------ |
| `values`  | `string[]` | —       | Label values |

**Returns** `Gauge.Internal<T>` — Configured gauge with given labels

Gauge.remove(...values: string[]): void [#gaugeremovevalues-string-void]

Remove metrics for the given label values

Overloads:

```ts
remove(...values: string[]): void
remove(labels: LabelValues<T>): void
```

**Parameters**

| Parameter | Type       | Default | Description  |
| --------- | ---------- | ------- | ------------ |
| `values`  | `string[]` | —       | Label values |

Gauge.reset(): void [#gaugereset-void]

Reset gauge values

set(labels: LabelValues<T>, value: number): void [#setlabels-labelvaluest-value-number-void]

Set gauge value for labels

Overloads:

```ts
set(labels: LabelValues<T>, value: number): void
set(value: number): void
```

**Parameters**

| Parameter | Type             | Default | Description                       |
| --------- | ---------------- | ------- | --------------------------------- |
| `labels`  | `LabelValues<T>` | —       | Object with label keys and values |
| `value`   | `number`         | —       | The value to set                  |

setToCurrentTime(labels?: LabelValues<T>): void [#settocurrenttimelabels-labelvaluest-void]

Set gauge value to current epoch time in seconds

**Parameters**

| Parameter | Type             | Default | Description                       |
| --------- | ---------------- | ------- | --------------------------------- |
| `labels?` | `LabelValues<T>` | —       | Object with label keys and values |

Gauge.startTimer(labels?: LabelValues<T>): (labels?: LabelValues<T>) => number [#gaugestarttimerlabels-labelvaluest-labels-labelvaluest--number]

Start a timer. Calling the returned function will set the gauge's value
to the observed duration in seconds.

**Parameters**

| Parameter | Type             | Default | Description                       |
| --------- | ---------------- | ------- | --------------------------------- |
| `labels?` | `LabelValues<T>` | —       | Object with label keys and values |

**Returns** `(labels?: LabelValues<T>) => number` — Function to invoke when timer should be stopped. The value it
returns is the timed duration.

Histogram [#histogram]

new Histogram(configuration: HistogramConfiguration<T>) [#new-histogramconfiguration-histogramconfigurationt]

Histograms track sizes and frequency of events (for example request durations).

**Parameters**

| Parameter       | Type                        | Default | Description                                                           |
| --------------- | --------------------------- | ------- | --------------------------------------------------------------------- |
| `configuration` | `HistogramConfiguration<T>` | —       | Configuration when creating the Histogram. Name and Help is mandatory |

Histogram.get(): Promise<MetricObjectWithValues<MetricValueWithName<T>>> [#histogramget-promisemetricobjectwithvaluesmetricvaluewithnamet]

Get histogram metric object

**Returns** `Promise<MetricObjectWithValues<MetricValueWithName<T>>>` — A promise resolving to the histogram's current buckets and counts as a metric object.

Histogram.Config [#histogramconfig]

```ts
interface Config {
  buckets?: number[]
}
```

Histogram.Internal [#histograminternal]

```ts
interface Internal<T extends string> {
  observe(value: number): void
  startTimer(): (labels?: LabelValues<T>) => void
}
```

labels(...values: string[]): Histogram.Internal<T> [#labelsvalues-string-histograminternalt]

Return the child for given labels

Overloads:

```ts
labels(...values: string[]): Histogram.Internal<T>
labels(labels: LabelValues<T>): Histogram.Internal<T>
```

**Parameters**

| Parameter | Type       | Default | Description  |
| --------- | ---------- | ------- | ------------ |
| `values`  | `string[]` | —       | Label values |

**Returns** `Histogram.Internal<T>` — Configured histogram with given labels

Histogram.observe(value: number): void [#histogramobservevalue-number-void]

Observe value

Overloads:

```ts
observe(value: number): void
observe(labels: LabelValues<T>, value: number): void
observe(observeData: ObserveDataWithExemplar<T>): void
```

**Parameters**

| Parameter | Type     | Default | Description          |
| --------- | -------- | ------- | -------------------- |
| `value`   | `number` | —       | The value to observe |

Histogram.remove(...values: string[]): void [#histogramremovevalues-string-void]

Remove metrics for the given label values

Overloads:

```ts
remove(...values: string[]): void
remove(labels: LabelValues<T>): void
```

**Parameters**

| Parameter | Type       | Default | Description  |
| --------- | ---------- | ------- | ------------ |
| `values`  | `string[]` | —       | Label values |

Histogram.reset(): void [#histogramreset-void]

Reset histogram values

Histogram.startTimer(labels?: LabelValues<T>): (labels?: LabelValues<T>) => number [#histogramstarttimerlabels-labelvaluest-labels-labelvaluest--number]

Start a timer. Calling the returned function will observe the duration in
seconds in the histogram.

Overloads:

```ts
startTimer(labels?: LabelValues<T>): (labels?: LabelValues<T>) => number
startTimer(labels?: LabelValues<T>, exemplarLabels?: LabelValues<T>): (labels?: LabelValues<T>, exemplarLabels?: LabelValues<T>) => number
```

**Parameters**

| Parameter | Type             | Default | Description                       |
| --------- | ---------------- | ------- | --------------------------------- |
| `labels?` | `LabelValues<T>` | —       | Object with label keys and values |

**Returns** `(labels?: LabelValues<T>) => number` — Function to invoke when timer should be stopped. The value it
returns is the timed duration.

zero(labels: LabelValues<T>): void [#zerolabels-labelvaluest-void]

Initialize the metrics for the given combination of labels to zero

**Parameters**

| Parameter | Type             | Default | Description                                              |
| --------- | ---------------- | ------- | -------------------------------------------------------- |
| `labels`  | `LabelValues<T>` | —       | Object with label keys and values to initialize to zero. |

Summary [#summary]

new Summary(configuration: SummaryConfiguration<T>) [#new-summaryconfiguration-summaryconfigurationt]

Summaries calculate percentiles of observed values.

**Parameters**

| Parameter       | Type                      | Default | Description                                                            |
| --------------- | ------------------------- | ------- | ---------------------------------------------------------------------- |
| `configuration` | `SummaryConfiguration<T>` | —       | Configuration when creating Summary metric. Name and Help is mandatory |

Summary.get(): Promise<MetricObjectWithValues<MetricValueWithName<T>>> [#summaryget-promisemetricobjectwithvaluesmetricvaluewithnamet]

Get summary metric object

**Returns** `Promise<MetricObjectWithValues<MetricValueWithName<T>>>` — A promise resolving to the summary's current percentiles as a metric object.

labels(...values: string[]): Summary.Internal<T> [#labelsvalues-string-summaryinternalt]

Return the child for given labels

Overloads:

```ts
labels(...values: string[]): Summary.Internal<T>
labels(labels: LabelValues<T>): Summary.Internal<T>
```

**Parameters**

| Parameter | Type       | Default | Description  |
| --------- | ---------- | ------- | ------------ |
| `values`  | `string[]` | —       | Label values |

**Returns** `Summary.Internal<T>` — Configured summary with given labels

Summary.observe(value: number): void [#summaryobservevalue-number-void]

Observe value in summary

Overloads:

```ts
observe(value: number): void
observe(labels: LabelValues<T>, value: number): void
```

**Parameters**

| Parameter | Type     | Default | Description          |
| --------- | -------- | ------- | -------------------- |
| `value`   | `number` | —       | The value to observe |

Summary.remove(...values: string[]): void [#summaryremovevalues-string-void]

Remove metrics for the given label values

Overloads:

```ts
remove(...values: string[]): void
remove(labels: LabelValues<T>): void
```

**Parameters**

| Parameter | Type       | Default | Description  |
| --------- | ---------- | ------- | ------------ |
| `values`  | `string[]` | —       | Label values |

Summary.reset(): void [#summaryreset-void]

Reset all values in the summary

Summary.startTimer(labels?: LabelValues<T>): (labels?: LabelValues<T>) => number [#summarystarttimerlabels-labelvaluest-labels-labelvaluest--number]

Start a timer. Calling the returned function will observe the duration in
seconds in the summary.

**Parameters**

| Parameter | Type             | Default | Description                       |
| --------- | ---------------- | ------- | --------------------------------- |
| `labels?` | `LabelValues<T>` | —       | Object with label keys and values |

**Returns** `(labels?: LabelValues<T>) => number` — Function to invoke when timer should be stopped

Summary.Config [#summaryconfig]

```ts
interface Config {
  percentiles?: number[]
}
```

Summary.Internal [#summaryinternal]

```ts
interface Internal<T extends string> {
  observe(value: number): void
  startTimer(): (labels?: LabelValues<T>) => number
}
```

Pushgateway [#pushgateway]

new Pushgateway(url: string, options?: any, registry?: Registry<T>) [#new-pushgatewayurl-string-options-any-registry-registryt]

**Parameters**

| Parameter   | Type          | Default | Description                                                              |
| ----------- | ------------- | ------- | ------------------------------------------------------------------------ |
| `url`       | `string`      | —       | Complete url to the Pushgateway. If port is needed append url with :port |
| `options?`  | `any`         | —       | Options                                                                  |
| `registry?` | `Registry<T>` | —       | Registry                                                                 |

delete(params: Pushgateway.Parameters): Promise<{ resp?: unknown; body?: unknown }> [#deleteparams-pushgatewayparameters-promise-resp-unknown-body-unknown-]

Delete all metrics for jobName

**Parameters**

| Parameter | Type                     | Default | Description     |
| --------- | ------------------------ | ------- | --------------- |
| `params`  | `Pushgateway.Parameters` | —       | Push parameters |

**Returns** `Promise<{ resp?: unknown; body?: unknown }>` — A promise resolving with the Pushgateway HTTP response and body.

push(params: Pushgateway.Parameters): Promise<{ resp?: unknown; body?: unknown }> [#pushparams-pushgatewayparameters-promise-resp-unknown-body-unknown-]

Overwrite all metric (using PUT to Pushgateway)

**Parameters**

| Parameter | Type                     | Default | Description     |
| --------- | ------------------------ | ------- | --------------- |
| `params`  | `Pushgateway.Parameters` | —       | Push parameters |

**Returns** `Promise<{ resp?: unknown; body?: unknown }>` — A promise resolving with the Pushgateway HTTP response and body.

pushAdd(params: Pushgateway.Parameters): Promise<{ resp?: unknown; body?: unknown }> [#pushaddparams-pushgatewayparameters-promise-resp-unknown-body-unknown-]

Add metric and overwrite old ones

**Parameters**

| Parameter | Type                     | Default | Description     |
| --------- | ------------------------ | ------- | --------------- |
| `params`  | `Pushgateway.Parameters` | —       | Push parameters |

**Returns** `Promise<{ resp?: unknown; body?: unknown }>` — A promise resolving with the Pushgateway HTTP response and body.

Pushgateway.Parameters [#pushgatewayparameters]

```ts
interface Parameters {
  jobName: string
  groupings?: {
			[key: string]: string;
		}
}
```

Functions [#functions]

linearBuckets(start: number, width: number, count: number): number[] [#linearbucketsstart-number-width-number-count-number-number]

Create an array with equal spacing between the elements

**Parameters**

| Parameter | Type     | Default | Description                      |
| --------- | -------- | ------- | -------------------------------- |
| `start`   | `number` | —       | The first value in the array     |
| `width`   | `number` | —       | The spacing between the elements |
| `count`   | `number` | —       | The number of items in array     |

**Returns** `number[]` — An array with the requested number of elements

exponentialBuckets(start: number, factor: number, count: number): number[] [#exponentialbucketsstart-number-factor-number-count-number-number]

Create an array that grows exponentially

**Parameters**

| Parameter | Type     | Default | Description                  |
| --------- | -------- | ------- | ---------------------------- |
| `start`   | `number` | —       | The first value in the array |
| `factor`  | `number` | —       | The exponential factor       |
| `count`   | `number` | —       | The number of items in array |

**Returns** `number[]` — An array with the requested number of elements

validateMetricName(name: string): boolean [#validatemetricnamename-string-boolean]

Validate a metric name

**Parameters**

| Parameter | Type     | Default | Description          |
| --------- | -------- | ------- | -------------------- |
| `name`    | `string` | —       | The name to validate |

**Returns** `boolean` — True if the metric name is valid, false if not

Constants and variables [#constants-and-variables]

register: Registry [#register-registry]

The register that contains all metrics

contentType: RegistryContentType [#contenttype-registrycontenttype]

HTTP Content-Type for metrics response headers for the default registry,
defaults to Prometheus text format.

prometheusContentType: PrometheusContentType [#prometheuscontenttype-prometheuscontenttype]

HTTP Prometheus Content-Type for metrics response headers.

openMetricsContentType: OpenMetricsContentType [#openmetricscontenttype-openmetricscontenttype]

HTTP OpenMetrics Content-Type for metrics response headers.

MetricType [#metrictype]

```ts
enum MetricType {
	Counter,
	Gauge,
	Histogram,
	Summary,
}
```

collectDefaultMetrics [#collectdefaultmetrics]

```ts
collectDefaultMetrics: {
	/**
	 * Configure default metrics
	 * @param config Configuration object for default metrics collector
	 */
	<T extends RegistryContentType>(
		config?: DefaultMetricsCollectorConfiguration<T>,
	): void;
	/** All available default metrics */
	metricsList: string[];
}
```

Types [#types]

Charset [#charset]

```ts
type Charset = 'utf-8'
```

PrometheusMIME [#prometheusmime]

```ts
type PrometheusMIME = 'text/plain'
```

PrometheusMetricsVersion [#prometheusmetricsversion]

```ts
type PrometheusMetricsVersion = '0.0.4'
```

OpenMetricsMIME [#openmetricsmime]

```ts
type OpenMetricsMIME = 'application/openmetrics-text'
```

OpenMetricsVersion [#openmetricsversion]

```ts
type OpenMetricsVersion = '1.0.0'
```

OpenMetricsContentType [#openmetricscontenttype]

```ts
type OpenMetricsContentType = `${OpenMetricsMIME}; version=${OpenMetricsVersion}; charset=${Charset}`
```

PrometheusContentType [#prometheuscontenttype]

```ts
type PrometheusContentType = `${PrometheusMIME}; version=${PrometheusMetricsVersion}; charset=${Charset}`
```

RegistryContentType [#registrycontenttype]

```ts
type RegistryContentType = | PrometheusContentType
	| OpenMetricsContentType
```

Collector [#collector]

```ts
type Collector = () => void
```

Metric [#metric]

```ts
type Metric<T extends string = string> = | Counter<T>
	| Gauge<T>
	| Summary<T>
	| Histogram<T>
```

General metric type

Aggregator [#aggregator]

```ts
type Aggregator = 'omit' | 'sum' | 'first' | 'min' | 'max' | 'average'
```

Aggregation methods, used for aggregating metrics in a Node.js cluster.

CollectFunction [#collectfunction]

```ts
type CollectFunction<T> = (this: T) => void | Promise<void>
```

MetricObject [#metricobject]

```ts
interface MetricObject {
  name: string
  help: string
  type: MetricType
  aggregator: Aggregator
  collect: CollectFunction<any>
}
```

MetricObjectWithValues [#metricobjectwithvalues]

```ts
interface MetricObjectWithValues<T extends MetricValue<string>> {
  values: T[]
  name: string
  help: string
  type: MetricType
  aggregator: Aggregator
  collect: CollectFunction<any>
}
```

MetricValue [#metricvalue]

```ts
type MetricValue<T extends string> = {
	value: number;
	labels: LabelValues<T>;
}
```

MetricValueWithName [#metricvaluewithname]

```ts
type MetricValueWithName<T extends string> = MetricValue<T> & {
	metricName?: string;
}
```

LabelValues [#labelvalues]

```ts
type LabelValues<T extends string> = Partial<Record<T, string | number>>
```

MetricConfiguration [#metricconfiguration]

```ts
interface MetricConfiguration<T extends string> {
  name: string
  help: string
  labelNames?: T[] | readonly T[]
  registers?: (
		| Registry<PrometheusContentType>
		| Registry<OpenMetricsContentType>
	)[]
  aggregator?: Aggregator
  collect?: CollectFunction<any>
  enableExemplars?: boolean
}
```

CounterConfiguration [#counterconfiguration]

```ts
interface CounterConfiguration<T extends string> {
  collect?: CollectFunction<Counter<T>>
  name: string
  help: string
  labelNames?: T[] | readonly T[]
  registers?: (
		| Registry<PrometheusContentType>
		| Registry<OpenMetricsContentType>
	)[]
  aggregator?: Aggregator
  enableExemplars?: boolean
}
```

IncreaseDataWithExemplar [#increasedatawithexemplar]

```ts
interface IncreaseDataWithExemplar<T extends string> {
  value?: number
  labels?: LabelValues<T>
  exemplarLabels?: LabelValues<T>
}
```

ObserveDataWithExemplar [#observedatawithexemplar]

```ts
interface ObserveDataWithExemplar<T extends string> {
  value: number
  labels?: LabelValues<T>
  exemplarLabels?: LabelValues<T>
}
```

GaugeConfiguration [#gaugeconfiguration]

```ts
interface GaugeConfiguration<T extends string> {
  collect?: CollectFunction<Gauge<T>>
  name: string
  help: string
  labelNames?: T[] | readonly T[]
  registers?: (
		| Registry<PrometheusContentType>
		| Registry<OpenMetricsContentType>
	)[]
  aggregator?: Aggregator
  enableExemplars?: boolean
}
```

HistogramConfiguration [#histogramconfiguration]

```ts
interface HistogramConfiguration<T extends string> {
  buckets?: number[]
  collect?: CollectFunction<Histogram<T>>
  name: string
  help: string
  labelNames?: T[] | readonly T[]
  registers?: (
		| Registry<PrometheusContentType>
		| Registry<OpenMetricsContentType>
	)[]
  aggregator?: Aggregator
  enableExemplars?: boolean
}
```

SummaryConfiguration [#summaryconfiguration]

```ts
interface SummaryConfiguration<T extends string> {
  percentiles?: number[]
  maxAgeSeconds?: number
  ageBuckets?: number
  pruneAgedBuckets?: boolean
  compressCount?: number
  collect?: CollectFunction<Summary<T>>
  name: string
  help: string
  labelNames?: T[] | readonly T[]
  registers?: (
		| Registry<PrometheusContentType>
		| Registry<OpenMetricsContentType>
	)[]
  aggregator?: Aggregator
  enableExemplars?: boolean
}
```

DefaultMetricsCollectorConfiguration [#defaultmetricscollectorconfiguration]

```ts
interface DefaultMetricsCollectorConfiguration<T extends RegistryContentType> {
  register?: Registry<T>
  prefix?: string
  gcDurationBuckets?: number[]
  eventLoopMonitoringPrecision?: number
  labels?: object
}
```

See also [#see-also]

* Builds on `bare-fs`, `bare-http1`, `bare-https`, `bare-performance`, `bare-process`, `bare-url`, `bare-utils`, `bare-v8`, and `bare-zlib`.
* It's pure JavaScript, modelled on and API-compatible with the Node.js [`prom-client`](https://github.com/siimon/prom-client) package.
* [Bare modules](/reference/modules/bare-modules) — the full `bare-*` catalog.
* [Bare runtime API](/reference/bare/runtime) — the runtime these modules extend.


# bare-querystring



<mark style={{ backgroundColor: '#7dde9a', padding: '2px 8px', borderRadius: '4px', fontSize: '0.85em', fontWeight: 500 }}>
  stable
</mark>

[`bare-querystring`](https://github.com/holepunchto/bare-querystring) — URL query strings utilities.

```sh
npm i bare-querystring
```

Usage [#usage]

```js
const querystring = require('bare-querystring')

querystring.decode('name=ferret') // `{ name: "ferret" }`

querystring.encode({ name: 'ferret' }) // `name=ferret`
```

API [#api]

Functions [#functions]

parse(input: string, separator?: string, delimiter?: string): Record<string, string | string[]> [#parseinput-string-separator-string-delimiter-string-recordstring-string--string]

Parse a query string into an object, splitting pairs on `separator` (default `&`) and key/value on `delimiter` (default `=`). `+` decodes to a space, keys and values are percent-decoded, and repeated keys collect into an array.

**Parameters**

| Parameter    | Type     | Default | Description                                                    |
| ------------ | -------- | ------- | -------------------------------------------------------------- |
| `input`      | `string` | —       | Query string to parse.                                         |
| `separator?` | `string` | —       | Substring that separates key/value pairs (default `'&'`).      |
| `delimiter?` | `string` | —       | Substring that separates a key from its value (default `'='`). |

**Returns** `Record<string, string | string[]>` — An object (with a `null` prototype) mapping decoded keys to decoded values; repeated keys collect into an array.

decode(input: string, separator?: string, delimiter?: string): Record<string, string | string[]> [#decodeinput-string-separator-string-delimiter-string-recordstring-string--string]

Alias for `parse`.

**Parameters**

| Parameter    | Type     | Default | Description                                                    |
| ------------ | -------- | ------- | -------------------------------------------------------------- |
| `input`      | `string` | —       | Query string to parse.                                         |
| `separator?` | `string` | —       | Substring that separates key/value pairs (default `'&'`).      |
| `delimiter?` | `string` | —       | Substring that separates a key from its value (default `'='`). |

**Returns** `Record<string, string | string[]>` — The parsed parameters, exactly as `parse` returns them.

stringify(params: {}, separator?: string, delimiter?: string): string [#stringifyparams--separator-string-delimiter-string-string]

Serialize an object into a query string, joining pairs with `separator` (default `&`) and key/value with `delimiter` (default `=`). Array values produce one pair per element.

**Parameters**

| Parameter    | Type     | Default | Description                                                                                        |
| ------------ | -------- | ------- | -------------------------------------------------------------------------------------------------- |
| `params`     | `{}`     | —       | Object whose enumerable entries become key/value pairs; array values produce one pair per element. |
| `separator?` | `string` | —       | Substring used to join key/value pairs (default `'&'`).                                            |
| `delimiter?` | `string` | —       | Substring used to join a key to its value (default `'='`).                                         |

**Returns** `string` — The percent-encoded query string.

encode(params: {}, separator?: string, delimiter?: string): string [#encodeparams--separator-string-delimiter-string-string]

Alias for `stringify`.

**Parameters**

| Parameter    | Type     | Default | Description                                                                                        |
| ------------ | -------- | ------- | -------------------------------------------------------------------------------------------------- |
| `params`     | `{}`     | —       | Object whose enumerable entries become key/value pairs; array values produce one pair per element. |
| `separator?` | `string` | —       | Substring used to join key/value pairs (default `'&'`).                                            |
| `delimiter?` | `string` | —       | Substring used to join a key to its value (default `'='`).                                         |

**Returns** `string` — The percent-encoded query string, exactly as `stringify` returns it.

See also [#see-also]

* [Bare modules](/reference/modules/bare-modules) — the full `bare-*` catalog.
* [Bare runtime API](/reference/bare/runtime) — the runtime these modules extend.


# bare-readline



<mark style={{ backgroundColor: '#7dde9a', padding: '2px 8px', borderRadius: '4px', fontSize: '0.85em', fontWeight: 500 }}>
  stable
</mark>

[`bare-readline`](https://github.com/holepunchto/bare-readline) — Line editing for interactive CLIs with command history.

Mirrors the Node.js [`readline`](https://nodejs.org/api/readline.html) module.

```sh
npm i bare-readline
```

Usage [#usage]

```js
const readline = require('bare-readline')

const rl = readline.createInterface({
  input: stream,
  output: stream
})

rl.on('data', (line) => {
  console.log(line)
  rl.prompt()
}).prompt()
```

API [#api]

Readline [#readline]

new Readline(opts?: ReadlineOptions) [#new-readlineopts-readlineoptions]

Create a `Readline` interface over an input and output stream.

**Parameters**

| Parameter | Type                                  | Default | Description                                                                                                                               |
| --------- | ------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `opts?`   | [`ReadlineOptions`](#readlineoptions) | —       | Options; `input` and `output` are the streams to read from and render to, `prompt` defaults to `'> '`, and `crlfDelay` defaults to `100`. |

clearLine(): string [#clearline-string]

Clear the current input line from the output and reset the line buffer and cursor, returning the cleared line.

**Returns** `string` — the input line that was cleared, before the buffer and cursor were reset.

close(): void [#close-void]

Stop listening for input and end the stream.

cursor: number [#cursor-number]

The current cursor position within the input line.

getPrompt(): string [#getprompt-string]

Returns the current prompt string.

**Returns** `string` — the current prompt string.

input: Readable [#input-readable]

The readable stream that keystrokes are read from.

line: string [#line-string]

The current, in-progress input line.

output: Writable [#output-writable]

The writable stream that the prompt and line edits are rendered to.

prompt(): void [#prompt-void]

Render the prompt and current input line to the output.

Readline.constants: { EOL: string } [#readlineconstants--eol-string-]

Constants used by `Readline`, including the end-of-line sequence.

Readline.createInterface(opts?: ReadlineOptions): Readline [#readlinecreateinterfaceopts-readlineoptions-readline]

Create a `Readline` interface over an input and output stream.

**Parameters**

| Parameter | Type                                  | Default | Description                                                                                                                               |
| --------- | ------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `opts?`   | [`ReadlineOptions`](#readlineoptions) | —       | Options; `input` and `output` are the streams to read from and render to, `prompt` defaults to `'> '`, and `crlfDelay` defaults to `100`. |

setPrompt(prompt: string): void [#setpromptprompt-string-void]

Set the prompt string written before the input line.

**Parameters**

| Parameter | Type     | Default | Description                                      |
| --------- | -------- | ------- | ------------------------------------------------ |
| `prompt`  | `string` | —       | The prompt string written before the input line. |

write(data: string): void [#writedata-string-void]

Write data directly to the output stream.

**Parameters**

| Parameter | Type     | Default | Description                             |
| --------- | -------- | ------- | --------------------------------------- |
| `data`    | `string` | —       | The data to write to the output stream. |

Types [#types]

ReadlineOptions [#readlineoptions]

```ts
interface ReadlineOptions {
  crlfDelay?: number
  input?: Readable
  output?: Writable
  prompt?: string
}
```

Options accepted when constructing a `Readline` interface.

ReadlineEvents [#readlineevents]

```ts
interface ReadlineEvents {
  data: [line: string]
  history: [history: string[]]
  line: [line: string]
  end: []
  readable: []
  piping: [dest: Writable]
  close: []
  error: [err: Error]
}
```

Events emitted by a `Readline` interface.

See also [#see-also]

* Builds on `bare-ansi-escapes` and `bare-stream`.
* [Bare modules](/reference/modules/bare-modules) — the full `bare-*` catalog.
* [Bare runtime API](/reference/bare/runtime) — the runtime these modules extend.


# bare-realm



<mark style={{ backgroundColor: '#7dde9a', padding: '2px 8px', borderRadius: '4px', fontSize: '0.85em', fontWeight: 500 }}>
  stable
</mark>

[`bare-realm`](https://github.com/holepunchto/bare-realm) — Realm support for Bare. It is a native addon and requires Bare `>=1.5.0`.

```sh
npm i bare-realm
```

Usage [#usage]

```js
const Realm = require('bare-realm')

const realm = new Realm()

realm.evaluate('globalThis.foo = 42')
// 42

typeof globalThis.foo
// undefined
```

API [#api]

Realm [#realm]

evaluate(code: string, options?: EvaluateOptions): any [#evaluatecode-string-options-evaluateoptions-any]

Evaluate `code` in the realm's isolated global scope and return its completion value. The realm has its own `globalThis`, so assignments to globals made by `code` do not leak into the caller's environment.

**Parameters**

| Parameter  | Type                                  | Default | Description                                                                                                                                     |
| ---------- | ------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `code`     | `string`                              | —       | The JavaScript source to evaluate.                                                                                                              |
| `options?` | [`EvaluateOptions`](#evaluateoptions) | —       | Options. `filename` is the script name used in stack traces (default `'<anonymous>'`); `offset` shifts the reported line numbers (default `0`). |

**Returns** `any` — The completion value of `code`.

Types [#types]

EvaluateOptions [#evaluateoptions]

```ts
interface EvaluateOptions {
  filename?: string
  offset?: number
}
```

See also [#see-also]

* [Bare modules](/reference/modules/bare-modules) — the full `bare-*` catalog.
* [Bare runtime API](/reference/bare/runtime) — the runtime these modules extend.


# bare-rpc



<mark style={{ backgroundColor: '#7dde9a', padding: '2px 8px', borderRadius: '4px', fontSize: '0.85em', fontWeight: 500 }}>
  stable
</mark>

[`bare-rpc`](https://github.com/holepunchto/bare-rpc) — librpc ABI compatible RPC for Bare.

```sh
npm i bare-rpc
```

Usage [#usage]

```js
import RPC from 'bare-rpc'

// On one end
const rpc = new RPC(stream, (req) => {
  if (req.command === 42) {
    console.log(req.data.toString()) // ping
    req.reply('pong')
  }
})

// On the other end
const req = rpc.request(42)
req.send('ping')

const replyBuffer = await req.reply()
console.log(replyBuffer.toString()) // pong
```

API [#api]

RPC [#rpc]

new RPC(stream: Duplex, onrequest: (req: RPCIncomingRequest) => void | Promise<void>) [#new-rpcstream-duplex-onrequest-req-rpcincomingrequest--void--promisevoid]

Create an RPC instance using a duplex `stream`. `onrequest` is an optional callback run when a remote request is received. This is where processing and responding to an RPC request happens. `onrequest` receives a `RPCIncomingRequest` as an argument.

**Parameters**

| Parameter   | Type                                                 | Default | Description                                                                                                                                                                              |
| ----------- | ---------------------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `stream`    | `Duplex`                                             | —       | The duplex stream to frame RPC messages over, identifying each method by a unique command number — an IPC pipe, a TCP socket, or a [Bare Kit](/reference/bare/bare-kit) worklet channel. |
| `onrequest` | `(req: RPCIncomingRequest) => void \| Promise<void>` | —       | Callback run for each incoming request or event, receiving an `RPCIncomingRequest` (or `RPCIncomingEvent`) to inspect and `reply()` to. Defaults to a no-op.                             |

event(command: number): RPCOutgoingEvent [#eventcommand-number-rpcoutgoingevent]

Create an outgoing event for `command`. Events are one-way: unlike `request()` they carry no id and expect no reply, so the remote end receives them as an `RPCIncomingEvent`.

**Parameters**

| Parameter | Type     | Default | Description                                                                        |
| --------- | -------- | ------- | ---------------------------------------------------------------------------------- |
| `command` | `number` | —       | A unique number identifying the event; the remote end differentiates events by it. |

**Returns** `RPCOutgoingEvent` — an `RPCOutgoingEvent`; call `send()` on it to dispatch the one-way event.

idle: boolean [#idle-boolean]

Whether there are no requests or responses currently in flight. Useful for determining when it is safe to tear down the underlying stream.

request(command: number): RPCOutgoingRequest [#requestcommand-number-rpcoutgoingrequest]

Create a request for `command`. `command` is a unique number that should be used to differentiate different requests on the remote end.

**Parameters**

| Parameter | Type     | Default | Description                                                                            |
| --------- | -------- | ------- | -------------------------------------------------------------------------------------- |
| `command` | `number` | —       | A unique number identifying the request; the remote end differentiates requests by it. |

**Returns** `RPCOutgoingRequest` — an `RPCOutgoingRequest`; call `send()` on it to dispatch the request and `await reply()` for the response.

RPCIncomingEvent [#rpcincomingevent]

new RPCIncomingEvent(rpc: RPC, command: number, data: Buffer) [#new-rpcincomingeventrpc-rpc-command-number-data-buffer]

**Parameters**

| Parameter | Type     | Default | Description                                 |
| --------- | -------- | ------- | ------------------------------------------- |
| `rpc`     | `RPC`    | —       | The `RPC` instance the event arrived on.    |
| `command` | `number` | —       | The command number the event was sent with. |
| `data`    | `Buffer` | —       | The payload buffer sent with the event.     |

RPCIncomingEvent.command: number [#rpcincomingeventcommand-number]

The command that the request was created with. A command is a unique number.

RPCIncomingEvent.data: Buffer | null [#rpcincomingeventdata-buffer--null]

The data buffer sent with the request.

RPCIncomingEvent.rpc: RPC [#rpcincomingeventrpc-rpc]

RPCOutgoingEvent [#rpcoutgoingevent]

new RPCOutgoingEvent(rpc: RPC, command: number) [#new-rpcoutgoingeventrpc-rpc-command-number]

**Parameters**

| Parameter | Type     | Default | Description                              |
| --------- | -------- | ------- | ---------------------------------------- |
| `rpc`     | `RPC`    | —       | The `RPC` instance to send the event on. |
| `command` | `number` | —       | The command number to send.              |

RPCOutgoingEvent.command: number [#rpcoutgoingeventcommand-number]

The command that the request was created with. A command is a unique number.

RPCOutgoingEvent.rpc: RPC [#rpcoutgoingeventrpc-rpc]

RPCOutgoingEvent.send(data?: Buffer | string | null, encoding?: BufferEncoding): void [#rpcoutgoingeventsenddata-buffer--string--null-encoding-bufferencoding-void]

Send the request with the provided `data`. `data` can be a buffer or a string which will be encoded using `encoding`.

**Parameters**

| Parameter   | Type                           | Default | Description                                                                                  |
| ----------- | ------------------------------ | ------- | -------------------------------------------------------------------------------------------- |
| `data?`     | `Buffer` \| `string` \| `null` | —       | The payload to send: a `Buffer`, or a string encoded using `encoding`. Omit to send no data. |
| `encoding?` | `BufferEncoding`               | —       | The encoding used when `data` is a string (defaults to `utf8`).                              |

**Throws**

* `ALREADY_SENT` — the event has already been sent.

RPCOutgoingEvent.sent: boolean [#rpcoutgoingeventsent-boolean]

A boolean for whether the request has been sent.

RPCIncomingRequest [#rpcincomingrequest]

new RPCIncomingRequest(rpc: RPC, id: number, command: number, data: Buffer) [#new-rpcincomingrequestrpc-rpc-id-number-command-number-data-buffer]

**Parameters**

| Parameter | Type     | Default | Description                                                   |
| --------- | -------- | ------- | ------------------------------------------------------------- |
| `rpc`     | `RPC`    | —       | The `RPC` instance the request arrived on.                    |
| `id`      | `number` | —       | The request id, used to correlate the reply with the request. |
| `command` | `number` | —       | The command number the request was sent with.                 |
| `data`    | `Buffer` | —       | The payload buffer sent with the request.                     |

RPCIncomingRequest.command: number [#rpcincomingrequestcommand-number]

The command that the request was created with. A command is a unique number.

createRequestStream(opts?: ReadableOptions): RPCIncomingStream [#createrequeststreamopts-readableoptions-rpcincomingstream]

Create a [`Readable`](https://github.com/mafintosh/streamx#readable-stream) stream for receiving the request's streamed data.

**Parameters**

| Parameter | Type              | Default | Description                                                                                         |
| --------- | ----------------- | ------- | --------------------------------------------------------------------------------------------------- |
| `opts?`   | `ReadableOptions` | —       | Options for the returned [`Readable`](https://github.com/mafintosh/streamx#readable-stream) stream. |

**Throws**

* `ALREADY_RECEIVED` — the request has already been received.

createResponseStream(opts?: WritableOptions): RPCOutgoingStream [#createresponsestreamopts-writableoptions-rpcoutgoingstream]

Create a [`Writable`](https://github.com/mafintosh/streamx#writable-stream) stream for sending the streamed reply to the request.

**Parameters**

| Parameter | Type              | Default | Description                                                                                         |
| --------- | ----------------- | ------- | --------------------------------------------------------------------------------------------------- |
| `opts?`   | `WritableOptions` | —       | Options for the returned [`Writable`](https://github.com/mafintosh/streamx#writable-stream) stream. |

**Throws**

* `ALREADY_SENT` — a response has already been sent for this request.

RPCIncomingRequest.data: Buffer | null [#rpcincomingrequestdata-buffer--null]

The data buffer sent with the request.

RPCIncomingRequest.id: number [#rpcincomingrequestid-number]

RPCIncomingRequest.received: boolean [#rpcincomingrequestreceived-boolean]

A boolean for whether the request has received a reply.

reply(data?: Buffer | string | null, encoding?: BufferEncoding): void [#replydata-buffer--string--null-encoding-bufferencoding-void]

Send a reply to the request. `data` may be a buffer or a string encoded using `encoding`.

**Parameters**

| Parameter   | Type                           | Default | Description                                                                                  |
| ----------- | ------------------------------ | ------- | -------------------------------------------------------------------------------------------- |
| `data?`     | `Buffer` \| `string` \| `null` | —       | The payload to send: a `Buffer`, or a string encoded using `encoding`. Omit to send no data. |
| `encoding?` | `BufferEncoding`               | —       | The encoding used when `data` is a string (defaults to `utf8`).                              |

**Throws**

* `ALREADY_SENT` — a response has already been sent for this request.

RPCIncomingRequest.rpc: RPC [#rpcincomingrequestrpc-rpc]

RPCIncomingRequest.sent: boolean [#rpcincomingrequestsent-boolean]

A boolean for whether the request has been sent.

RPCOutgoingRequest [#rpcoutgoingrequest]

new RPCOutgoingRequest(rpc: RPC, id: number, command: number) [#new-rpcoutgoingrequestrpc-rpc-id-number-command-number]

**Parameters**

| Parameter | Type     | Default | Description                                                   |
| --------- | -------- | ------- | ------------------------------------------------------------- |
| `rpc`     | `RPC`    | —       | The `RPC` instance to send the request on.                    |
| `id`      | `number` | —       | The request id, used to correlate the reply with the request. |
| `command` | `number` | —       | The command number to send.                                   |

RPCOutgoingRequest.command: number [#rpcoutgoingrequestcommand-number]

The command that the request was created with. A command is a unique number.

createRequestStream(opts?: WritableOptions): RPCOutgoingStream [#createrequeststreamopts-writableoptions-rpcoutgoingstream]

Create a [`Writable`](https://github.com/mafintosh/streamx#writable-stream) stream for sending data with the request.

**Parameters**

| Parameter | Type              | Default | Description                                                                                         |
| --------- | ----------------- | ------- | --------------------------------------------------------------------------------------------------- |
| `opts?`   | `WritableOptions` | —       | Options for the returned [`Writable`](https://github.com/mafintosh/streamx#writable-stream) stream. |

**Throws**

* `ALREADY_SENT` — the request has already been sent.

createResponseStream(opts?: ReadableOptions): RPCIncomingStream [#createresponsestreamopts-readableoptions-rpcincomingstream]

Create a [`Readable`](https://github.com/mafintosh/streamx#readable-stream) stream for receiving data in reply to the request.

**Parameters**

| Parameter | Type              | Default | Description                                                                                         |
| --------- | ----------------- | ------- | --------------------------------------------------------------------------------------------------- |
| `opts?`   | `ReadableOptions` | —       | Options for the returned [`Readable`](https://github.com/mafintosh/streamx#readable-stream) stream. |

**Throws**

* `ALREADY_RECEIVED` — the response has already been received.

RPCOutgoingRequest.id: number [#rpcoutgoingrequestid-number]

RPCOutgoingRequest.received: boolean [#rpcoutgoingrequestreceived-boolean]

A boolean for whether the request has received a reply.

reply(encoding?: BufferEncoding): Promise<Buffer | string | null> [#replyencoding-bufferencoding-promisebuffer--string--null]

Await the reply from the remote end to the request. `encoding` can be defined for decoding the response `data` buffer back into a string.

**Parameters**

| Parameter   | Type             | Default | Description                                                                                            |
| ----------- | ---------------- | ------- | ------------------------------------------------------------------------------------------------------ |
| `encoding?` | `BufferEncoding` | —       | If given, decodes the reply payload to a string using this encoding; omit to receive the raw `Buffer`. |

**Returns** `Promise<Buffer | string | null>` — a promise that resolves with the remote end's reply payload, or rejects with the channel's teardown error if it closes before a reply arrives.

**Throws**

* `ALREADY_RECEIVED` — a reply is already being received for this request.

RPCOutgoingRequest.rpc: RPC [#rpcoutgoingrequestrpc-rpc]

RPCOutgoingRequest.send(data?: Buffer | string | null, encoding?: BufferEncoding): void [#rpcoutgoingrequestsenddata-buffer--string--null-encoding-bufferencoding-void]

Send the request with the provided `data`. `data` can be a buffer or a string which will be encoded using `encoding`.

**Parameters**

| Parameter   | Type                           | Default | Description                                                                                  |
| ----------- | ------------------------------ | ------- | -------------------------------------------------------------------------------------------- |
| `data?`     | `Buffer` \| `string` \| `null` | —       | The payload to send: a `Buffer`, or a string encoded using `encoding`. Omit to send no data. |
| `encoding?` | `BufferEncoding`               | —       | The encoding used when `data` is a string (defaults to `utf8`).                              |

**Throws**

* `ALREADY_SENT` — the request has already been sent.

RPCOutgoingRequest.sent: boolean [#rpcoutgoingrequestsent-boolean]

A boolean for whether the request has been sent.

RPCIncomingStream [#rpcincomingstream]

RPCIncomingStream [#rpcincomingstream-1]

```ts
new RPCIncomingStream(rpc: RPC, request: RPCIncomingRequest | RPCOutgoingRequest, type: typeof constants.type.REQUEST | typeof constants.type.RESPONSE, opts?: ReadableOptions)
```

**Parameters**

| Parameter | Type                                                                | Default | Description                                                                                                              |
| --------- | ------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------ |
| `rpc`     | `RPC`                                                               | —       | The `RPC` instance the stream belongs to.                                                                                |
| `request` | `RPCIncomingRequest` \| `RPCOutgoingRequest`                        | —       | The request the stream carries data for.                                                                                 |
| `type`    | `typeof constants.type.REQUEST` \| `typeof constants.type.RESPONSE` | —       | Whether the stream carries the request body (`constants.type.REQUEST`) or the response body (`constants.type.RESPONSE`). |
| `opts?`   | `ReadableOptions`                                                   | —       | Options for the underlying [`Readable`](https://github.com/mafintosh/streamx#readable-stream) stream.                    |

RPCOutgoingStream [#rpcoutgoingstream]

RPCOutgoingStream [#rpcoutgoingstream-1]

```ts
new RPCOutgoingStream(rpc: RPC, request: RPCIncomingRequest | RPCOutgoingRequest, type: typeof constants.type.REQUEST | typeof constants.type.RESPONSE, opts?: WritableOptions)
```

**Parameters**

| Parameter | Type                                                                | Default | Description                                                                                                              |
| --------- | ------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------ |
| `rpc`     | `RPC`                                                               | —       | The `RPC` instance the stream belongs to.                                                                                |
| `request` | `RPCIncomingRequest` \| `RPCOutgoingRequest`                        | —       | The request the stream carries data for.                                                                                 |
| `type`    | `typeof constants.type.REQUEST` \| `typeof constants.type.RESPONSE` | —       | Whether the stream carries the request body (`constants.type.REQUEST`) or the response body (`constants.type.RESPONSE`). |
| `opts?`   | `WritableOptions`                                                   | —       | Options for the underlying [`Writable`](https://github.com/mafintosh/streamx#writable-stream) stream.                    |

bare-rpc/errors [#bare-rpcerrors]

RPCError [#rpcerror]

RPCError.ALREADY_RECEIVED(msg: string): RPCError [#rpcerroralready_receivedmsg-string-rpcerror]

**Parameters**

| Parameter | Type     | Default | Description |
| --------- | -------- | ------- | ----------- |
| `msg`     | `string` | —       | —           |

RPCError.ALREADY_SENT(msg: string): RPCError [#rpcerroralready_sentmsg-string-rpcerror]

**Parameters**

| Parameter | Type     | Default | Description |
| --------- | -------- | ------- | ----------- |
| `msg`     | `string` | —       | —           |

RPCError.CHANNEL_CLOSED(msg: string): RPCError [#rpcerrorchannel_closedmsg-string-rpcerror]

**Parameters**

| Parameter | Type     | Default | Description |
| --------- | -------- | ------- | ----------- |
| `msg`     | `string` | —       | —           |

RPCError.UNKNOWN_MESSAGE(msg: string): RPCError [#rpcerrorunknown_messagemsg-string-rpcerror]

**Parameters**

| Parameter | Type     | Default | Description |
| --------- | -------- | ------- | ----------- |
| `msg`     | `string` | —       | —           |

See also [#see-also]

* Builds on `bare-stream`.
* Pairs with [`hyperschema`](https://github.com/holepunchto/hyperschema) and [`compact-encoding`](/reference/helpers/compact-encoding) to generate typed message codecs.
* It's pure JavaScript. For the end-to-end pattern with generated types, see [Type a native RPC bridge](/how-to/run-on-native/type-a-native-rpc-bridge).
* [Bare modules](/reference/modules/bare-modules) — the full `bare-*` catalog.
* [Bare runtime API](/reference/bare/runtime) — the runtime these modules extend.


# bare-sdl



[`bare-sdl`](https://github.com/holepunchto/bare-sdl) provides [SDL](https://www.libsdl.org/) bindings for [Bare](/reference/bare/runtime)—native windowing, GPU-accelerated 2D rendering, input, and audio. It's a native addon and requires Bare `>=1.14.0`. This page is an overview of the main classes; see the [repository README](https://github.com/holepunchto/bare-sdl) for constructors, enums, and the full surface.

```sh
npm i bare-sdl
```

API overview [#api-overview]

Windowing and rendering [#windowing-and-rendering]

* **`Window`**— a native window. `window.destroy()` tears it down.
* **`Renderer`**— a GPU-accelerated 2D renderer for a window: `renderer.clear()`, `renderer.texture(texture)`, `renderer.present()`, `renderer.destroy()`.
* **`Texture`**— a renderable image: `texture.update(buffer, pitch)`, `texture.destroy()`.

Input [#input]

* **`Event`**— an input event with a `type` and, for keyboard events, `event.key` (including `event.key.scancode`).
* **`Poller`**— pumps the event queue: `poller.poll(event)` fills an `Event` with the next pending event.

Audio [#audio]

* **`AudioDevice`**— a playback or recording device. Instance members include `name`, `format`, `isPlaybackDevice`, `isPhysicalDevice`, `isPaused`, and `gain`, plus `bindStream(stream)`, `unbindStream(stream)`, `pause()`, `resume()`, and `close()`. Static helpers enumerate devices and formats: `AudioDevice.playbackDevices()`, `AudioDevice.recordingDevices()`, `AudioDevice.defaultPlaybackDevice([spec])`, `AudioDevice.defaultRecordingDevice([spec])`, `AudioDevice.playbackDeviceFormats()`, and `AudioDevice.recordingDeviceFormats()`.
* **`AudioStream`**— an audio stream you bind to an `AudioDevice` with `bindStream(stream)`.

Video [#video]

* **`Camera`**— a video capture device; see the [repository README](https://github.com/holepunchto/bare-sdl) for its surface.

See also [#see-also]

* [Bare modules](/reference/modules/bare-modules)—the full `bare-*` catalog, including media codecs.
* [`bare-stream`](/reference/bare/modules/bare-stream)—the streams bound to audio devices.
* [Bare runtime API](/reference/bare/runtime)—the runtime these bindings run on.


# bare-semver



<mark style={{ backgroundColor: '#7dde9a', padding: '2px 8px', borderRadius: '4px', fontSize: '0.85em', fontWeight: 500 }}>
  stable
</mark>

[`bare-semver`](https://github.com/holepunchto/bare-semver) — Minimal semantic versioning library for Bare.

```sh
npm i bare-semver
```

Usage [#usage]

```js
const semver = require('bare-semver')

const version = semver.Version.parse('1.2.3-alpha.1+build.42')

console.log(version.major) // 1
console.log(version.minor) // 2
console.log(version.patch) // 3

const satisfied = semver.satisfies('1.2.3', '>=1.0.0 <2.0.0')

console.log(satisfied) // true
```

API [#api]

errors [#errors]

errors.INVALID_RANGE(msg: string, fn?: Function): SemVerError [#errorsinvalid_rangemsg-string-fn-function-semvererror]

**Parameters**

| Parameter | Type       | Default | Description                                                                                               |
| --------- | ---------- | ------- | --------------------------------------------------------------------------------------------------------- |
| `msg`     | `string`   | —       | The error message.                                                                                        |
| `fn?`     | `Function` | —       | Optional function to omit from the top of the generated stack trace, passed to `Error.captureStackTrace`. |

**Returns** `SemVerError` — A `SemVerError` with `code` set to `'INVALID_RANGE'`, for the caller to throw.

errors.INVALID_VERSION(msg: string, fn?: Function): SemVerError [#errorsinvalid_versionmsg-string-fn-function-semvererror]

**Parameters**

| Parameter | Type       | Default | Description                                                                                               |
| --------- | ---------- | ------- | --------------------------------------------------------------------------------------------------------- |
| `msg`     | `string`   | —       | The error message.                                                                                        |
| `fn?`     | `Function` | —       | Optional function to omit from the top of the generated stack trace, passed to `Error.captureStackTrace`. |

**Returns** `SemVerError` — A `SemVerError` with `code` set to `'INVALID_VERSION'`, for the caller to throw.

Version [#version]

Version [#version-1]

```ts
new Version(major: number, minor: number, patch: number, opts?: { prerelease?: string[]; build?: string[] })
```

Create a new version with the given `major`, `minor`, and `patch` components.

**Parameters**

| Parameter | Type                                          | Default | Description                                                                    |
| --------- | --------------------------------------------- | ------- | ------------------------------------------------------------------------------ |
| `major`   | `number`                                      | —       | The major version number.                                                      |
| `minor`   | `number`                                      | —       | The minor version number.                                                      |
| `patch`   | `number`                                      | —       | The patch version number.                                                      |
| `opts?`   | `{ prerelease?: string[]; build?: string[] }` | —       | Optional `prerelease` and `build` tag arrays; each defaults to an empty array. |

build: string[] [#build-string]

An array of build metadata tags.

compare(version: Version): boolean [#compareversion-version-boolean]

Compare `version` with `other`, returning `1` if `version` is greater, `-1` if less, or `0` if equal. Comparison follows the Semantic Versioning 2.0.0 specification, including prerelease precedence rules.

**Parameters**

| Parameter | Type      | Default | Description                     |
| --------- | --------- | ------- | ------------------------------- |
| `version` | `Version` | —       | The version to compare against. |

major: number [#major-number]

The major version number.

minor: number [#minor-number]

The minor version number.

patch: number [#patch-number]

The patch version number.

prerelease: string[] [#prerelease-string]

An array of prerelease tags.

Version.toString(): string [#versiontostring-string]

Return the string representation of `version`.

Version.compare(a: Version, b: Version): number [#versioncomparea-version-b-version-number]

**Parameters**

| Parameter | Type      | Default | Description |
| --------- | --------- | ------- | ----------- |
| `a`       | `Version` | —       | —           |
| `b`       | `Version` | —       | —           |

Version.parse(input: string): Version [#versionparseinput-string-version]

Parse a semantic version string into a `Version` instance.

**Parameters**

| Parameter | Type     | Default | Description                  |
| --------- | -------- | ------- | ---------------------------- |
| `input`   | `string` | —       | The version string to parse. |

**Throws**

* `INVALID_VERSION` — `input` is not a valid version string.

Comparator [#comparator]

new Comparator(operator: number, version: Version) [#new-comparatoroperator-number-version-version]

Create a new comparator with the given `operator` constant and `version`.

**Parameters**

| Parameter  | Type      | Default | Description                                                              |
| ---------- | --------- | ------- | ------------------------------------------------------------------------ |
| `operator` | `number`  | —       | One of the `constants` operator values (`EQ`, `LT`, `LTE`, `GT`, `GTE`). |
| `version`  | `Version` | —       | The version the comparator matches against.                              |

operator: number [#operator-number]

The comparison operator constant.

Comparator.test(version: Version): boolean [#comparatortestversion-version-boolean]

Test whether `version` satisfies the comparator.

**Parameters**

| Parameter | Type      | Default | Description                                 |
| --------- | --------- | ------- | ------------------------------------------- |
| `version` | `Version` | —       | The version to test against the comparator. |

**Returns** `boolean` — `true` if `version` satisfies the comparator's operator and version, `false` otherwise.

Comparator.toString(): string [#comparatortostring-string]

Return the string representation of the comparator (operator and version), for example `>=1.2.3`.

version: Version [#version-version]

The `Version` instance to compare against.

Range [#range]

new Range(comparators?: Comparator[][]) [#new-rangecomparators-comparator]

Create a new range from a two-dimensional array of `Comparator` instances. Each inner array represents a set of comparators joined by intersection, and the outer array represents the union of those sets.

**Parameters**

| Parameter      | Type             | Default | Description                                                                                                                                                             |
| -------------- | ---------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `comparators?` | `Comparator[][]` | —       | Two-dimensional array of comparator sets: the outer array is a union (OR) of inner arrays, each an intersection (AND); defaults to an empty range that matches nothing. |

comparators: Comparator[][] [#comparators-comparator]

The two-dimensional array of `Comparator` instances.

Range.parse(input: string): Range [#rangeparseinput-string-range]

Parse a range string into a `Range` instance. Supports comparison operators (`<`, `<=`, `>`, `>=`, `=`), partial versions, and logical OR (`||`).

**Parameters**

| Parameter | Type     | Default | Description                |
| --------- | -------- | ------- | -------------------------- |
| `input`   | `string` | —       | The range string to parse. |

**Throws**

* `INVALID_VERSION` — `input` is not valid range syntax (reported via the `INVALID_VERSION` code — `INVALID_RANGE` is not currently thrown by the parser).

Range.test(version: Version): boolean [#rangetestversion-version-boolean]

Test whether `version` satisfies the range.

**Parameters**

| Parameter | Type      | Default | Description                            |
| --------- | --------- | ------- | -------------------------------------- |
| `version` | `Version` | —       | The version to test against the range. |

**Returns** `boolean` — `true` if `version` satisfies any comparator set in the range, `false` otherwise.

Range.toString(): string [#rangetostring-string]

Return the string representation of the range, for example `>=1.2.3 <2.0.0`.

Functions [#functions]

satisfies(version: Version, range: Range): boolean [#satisfiesversion-version-range-range-boolean]

Test whether `version` satisfies `range`. Both `version` and `range` may be strings, in which case they will be parsed.

**Parameters**

| Parameter | Type      | Default | Description                                            |
| --------- | --------- | ------- | ------------------------------------------------------ |
| `version` | `Version` | —       | The version to test, or a version string to parse.     |
| `range`   | `Range`   | —       | The range to test against, or a range string to parse. |

**Returns** `boolean` — `true` if `version` matches `range`, `false` otherwise.

**Throws**

* `INVALID_VERSION` — `version` or `range` is a string that fails to parse.

Constants and variables [#constants-and-variables]

constants: { EQ: 1; LT: 2; LTE: 3; GT: 4; GTE: 5 } [#constants--eq-1-lt-2-lte-3-gt-4-gte-5-]

An object containing the comparison operator constants.

See also [#see-also]

* Beyond comparison operators, `Range.parse()` also supports caret ranges (`^1.2.3`), tilde ranges (`~1.2.3` or `~>1.2.3`), X-ranges and wildcards (`1.2.x`, `1.*`, `*`), and hyphen ranges (`1.2.3 - 2.3.4`).
* It's pure JavaScript and underpins Bare's module/addon resolution.
* [`bare-module-resolve`](/reference/bare/modules/bare-module-resolve) — uses semver ranges during resolution.
* [Bare modules](/reference/modules/bare-modules) — the full `bare-*` catalog.
* [Bare runtime API](/reference/bare/runtime) — the runtime these modules extend.


# bare-sidecar



<mark style={{ backgroundColor: '#7dde9a', padding: '2px 8px', borderRadius: '4px', fontSize: '0.85em', fontWeight: 500 }}>
  stable
</mark>

[`bare-sidecar`](https://github.com/holepunchto/bare-sidecar) — Start and manage Bare sidecar processes from Node.js and Electron.

```sh
npm i bare-sidecar
```

Usage [#usage]

In the host process:

```js
const Sidecar = require('bare-sidecar')

const sidecar = new Sidecar(require.resolve('./entry'))

sidecar
  .on('exit', (code, status) => {
    // The sidecar process exited
  })
  .on('data', (data) => {
    // Received data from the sidecar over IPC
  })
  .write('Hello sidecar')
```

In the sidecar entry (`entry.js`), the IPC channel is available as a stream on `Bare.IPC`:

```js
Bare.IPC.on('data', (data) => Bare.IPC.write(data))
```

API [#api]

Sidecar [#sidecar]

new Sidecar(entry: string, args?: string[], opts?: SidecarOptions) [#new-sidecarentry-string-args-string-opts-sidecaroptions]

Spawn a bundled Bare runtime running `entry` and return a `Sidecar`. `entry` is the path to the module to run, typically resolved with `require.resolve()`. `args` is an array of additional command line arguments passed to the process. `options` is reserved for future use.

Overloads:

```ts
new Sidecar(entry: string, args?: string[], opts?: SidecarOptions)
new Sidecar(entry: string, opts?: SidecarOptions)
```

**Parameters**

| Parameter | Type                                | Default | Description                                                                               |
| --------- | ----------------------------------- | ------- | ----------------------------------------------------------------------------------------- |
| `entry`   | `string`                            | —       | Path to the module the sidecar process runs, typically resolved with `require.resolve()`. |
| `args?`   | `string[]`                          | —       | Additional command-line arguments passed to the process (default `[]`).                   |
| `opts?`   | [`SidecarOptions`](#sidecaroptions) | —       | Reserved for future use.                                                                  |

stderr: Pipe | null [#stderr-pipe--null]

The readable standard error stream of the underlying process.

stdin: Pipe | null [#stdin-pipe--null]

The writable standard input stream of the underlying process.

stdout: Pipe | null [#stdout-pipe--null]

The readable standard output stream of the underlying process.

Types [#types]

SidecarEvents [#sidecarevents]

```ts
interface SidecarEvents {
  exit: [code: number | null, signalCode: string | null]
  data: [data: unknown]
  end: []
  readable: []
  piping: [dest: Writable]
  close: []
  error: [err: Error]
  drain: []
  finish: []
  pipe: [src: Readable]
}
```

SidecarOptions [#sidecaroptions]

```ts
interface SidecarOptions {
}
```

See also [#see-also]

* Builds on `bare-fs`, `bare-module`, `bare-path`, `bare-pipe`, `bare-stream`, `bare-subprocess`, and `bare-url`.
* The instance extends a duplex stream: writing to it sends data to the sidecar over its IPC channel, data received from the sidecar is emitted as `'data'` events, and destroying the stream kills the sidecar process.
* The `'close'` event is emitted after the sidecar process has exited and its underlying stream has been destroyed.
* [`bare-subprocess`](/reference/bare/modules/bare-subprocess) — the lower-level process API.
* [One core, many platforms](/explanation/bare-on-native) — running a Bare core beside a host.
* [Bare modules](/reference/modules/bare-modules) — the full `bare-*` catalog.
* [Bare runtime API](/reference/bare/runtime) — the runtime these modules extend.


# bare-signals



<mark style={{ backgroundColor: '#7dde9a', padding: '2px 8px', borderRadius: '4px', fontSize: '0.85em', fontWeight: 500 }}>
  stable
</mark>

[`bare-signals`](https://github.com/holepunchto/bare-signals) — Native signal handling for JavaScript. It is a native addon and requires Bare `>=1.7.0`.

```sh
npm i bare-signals
```

Usage [#usage]

```js
const Signal = require('bare-signals')

const sigint = new Signal('SIGINT')

sigint.on('signal', () => console.log('SIGINT caught')).start()
```

API [#api]

Signal [#signal]

new Signal(signum: number | string) [#new-signalsignum-number--string]

Create a `Signal` for `signum`, given as a signal number or name such as `'SIGINT'`. Throws if `signum` is a string that names an unknown signal.

**Parameters**

| Parameter | Type                 | Default | Description                                                                  |
| --------- | -------------------- | ------- | ---------------------------------------------------------------------------- |
| `signum`  | `number` \| `string` | —       | The signal to handle, given as a signal number or a name such as `'SIGINT'`. |

**Throws**

* `UNKNOWN_SIGNAL` — `signum` is a string that does not name a known signal.

close(): Promise<void> [#close-promisevoid]

Close the signal, releasing its underlying handle. Returns a promise that resolves once the `close` event has fired.

Signal.ref(): this [#signalref-this]

Ref the signal, keeping the event loop alive while it is active.

Signal.constants: Record<string, number> [#signalconstants-recordstring-number]

The map of known signal names to signal numbers.

start(): this [#start-this]

Start listening for the signal, emitting `signal` when it is received. Throws if the signal has been closed.

**Throws**

* `SIGNAL_CLOSED` — the signal has been closed.

stop(): this [#stop-this]

Stop listening for the signal.

Signal.unref(): this [#signalunref-this]

Unref the signal, allowing the event loop to exit even while it is active.

SignalEmitter [#signalemitter]

SignalEmitter.ref(): this [#signalemitterref-this]

Ref all currently tracked signals, keeping the event loop alive.

SignalEmitter.unref(): this [#signalemitterunref-this]

Unref all currently tracked signals, allowing the event loop to exit.

Classes [#classes]

SignalError [#signalerror]

```ts
class SignalError {
  code: string
}
```

An error thrown by `bare-signals`, such as for an unknown signal name or an operation on a closed signal.

See also [#see-also]

* Builds on `bare-events`.
* [Bare modules](/reference/modules/bare-modules) — the full `bare-*` catalog.
* [Bare runtime API](/reference/bare/runtime) — the runtime these modules extend.


# bare-sqlite-vector



<mark style={{ backgroundColor: '#7dde9a', padding: '2px 8px', borderRadius: '4px', fontSize: '0.85em', fontWeight: 500 }}>
  stable
</mark>

[`bare-sqlite-vector`](https://github.com/holepunchto/bare-sqlite-vector) — SQLite Vector bindings for Bare. It is a native addon.

```sh
npm i bare-sqlite-vector
```

Usage [#usage]

```js
const { DatabaseSync } = require('bare-sqlite')
const vector = require('bare-sqlite-vector')

const db = new DatabaseSync(':memory:')
vector.register(db)

db.exec(`
  CREATE TABLE points (id INTEGER PRIMARY KEY, v BLOB);
  INSERT INTO points (v) VALUES (vector_as_f32('[1.0, 0.0, 0.0, 0.0]'));
  INSERT INTO points (v) VALUES (vector_as_f32('[0.0, 1.0, 0.0, 0.0]'));
`)

db.prepare("SELECT vector_init('points', 'v', 'type=FLOAT32,dimension=4,distance=L2')").get()

const rows = db
  .prepare(
    "SELECT rowid, distance FROM vector_full_scan('points', 'v', vector_as_f32('[0.9, 0.1, 0.0, 0.0]'), 2)"
  )
  .all()
```

API [#api]

Functions [#functions]

register(db: DatabaseSync): void [#registerdb-databasesync-void]

Register the vector extension's SQL functions and virtual table modules on the given `bare-sqlite` connection. `db` must be an open `DatabaseSync` instance from `bare-sqlite`.

**Parameters**

| Parameter | Type           | Default | Description                                                                                                         |
| --------- | -------------- | ------- | ------------------------------------------------------------------------------------------------------------------- |
| `db`      | `DatabaseSync` | —       | An open `DatabaseSync` connection from `bare-sqlite` to register the vector functions and virtual table modules on. |

**Throws**

* `DATABASE_NOT_OPEN` — `db` is not open.

See also [#see-also]

* Builds on `bare-sqlite`.
* [Bare modules](/reference/modules/bare-modules) — the full `bare-*` catalog.
* [Bare runtime API](/reference/bare/runtime) — the runtime these modules extend.


# bare-sqlite



<mark style={{ backgroundColor: '#7dde9a', padding: '2px 8px', borderRadius: '4px', fontSize: '0.85em', fontWeight: 500 }}>
  stable
</mark>

[`bare-sqlite`](https://github.com/holepunchto/bare-sqlite) — SQLite bindings for Bare. It is a native addon.

```sh
npm i bare-sqlite
```

Usage [#usage]

```js
const { DatabaseSync } = require('bare-sqlite')

const db = new DatabaseSync(':memory:')

db.exec(`
  CREATE TABLE books (id INTEGER PRIMARY KEY, title TEXT);
  INSERT INTO books (title) VALUES ('Dune'), ('Foundation');
`)

for (const row of db.prepare('SELECT id, title FROM books').iterate()) {
  console.log(row)
}

db.close()
```

API [#api]

DatabaseSync [#databasesync]

new DatabaseSync(location: string, opts?: SQLiteDatabaseSync.Options) [#new-databasesynclocation-string-opts-sqlitedatabasesyncoptions]

Open a SQLite database. `location` is a path to a database file, or `':memory:'` for an in-memory database.

**Parameters**

| Parameter  | Type                         | Default | Description                                                                                                                                                                                                                                                                                                                                                                                                     |
| ---------- | ---------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `location` | `string`                     | —       | Path to the database file, or `':memory:'` for an in-memory database.                                                                                                                                                                                                                                                                                                                                           |
| `opts?`    | `SQLiteDatabaseSync.Options` | —       | Options. `open` opens the database immediately (default `true`); `readOnly` opens it read-only (default `false`); `enableForeignKeyConstraints` enforces foreign keys (default `true`); `enableDoubleQuotedStringLiterals` permits double-quoted string literals (default `false`); `allowExtension` permits loading extensions (default `false`); `timeout` is the busy-timeout in milliseconds (default `0`). |

close(): void [#close-void]

Close the database. Throws if not open. Prepared statements that are still reachable from JavaScript remain valid until they are finalized; the underlying connection is released once the last statement is gone.

**Throws**

* `DATABASE_NOT_OPEN` — the database is not open.

createTagStore(maxSize?: number): TagStore [#createtagstoremaxsize-number-tagstore]

Create an LRU cache of prepared statements keyed on the SQL string produced by a tagged template. `maxSize` defaults to `1000`. The returned store exposes `sql.all`, `sql.get`, `sql.iterate`, and `sql.run` as tag functions; placeholder values are bound positionally.

**Parameters**

| Parameter  | Type     | Default | Description                                                                                                    |
| ---------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------- |
| `maxSize?` | `number` | —       | Maximum number of cached prepared statements before the least-recently-used entry is evicted (default `1000`). |

**Returns** `TagStore` — A `TagStore` exposing `all`, `get`, `iterate`, and `run` as tagged-template functions.

**Throws**

* `DATABASE_NOT_OPEN` — the database is not open.
* `INVALID_ARGUMENT` — `maxSize` is not a positive integer.

DatabaseSync.Options [#databasesyncoptions]

```ts
interface Options {
  open?: boolean
  readOnly?: boolean
  enableForeignKeyConstraints?: boolean
  enableDoubleQuotedStringLiterals?: boolean
  allowExtension?: boolean
  timeout?: number
}
```

enableLoadExtension(allow: boolean): void [#enableloadextensionallow-boolean-void]

Toggle extension loading at runtime. Useful for enabling extension loading during setup and disabling it before running user-supplied SQL. Throws if `allowExtension` was not enabled at construction.

**Parameters**

| Parameter | Type      | Default | Description                                                      |
| --------- | --------- | ------- | ---------------------------------------------------------------- |
| `allow`   | `boolean` | —       | When `true`, enable extension loading; when `false`, disable it. |

**Throws**

* `DATABASE_NOT_OPEN` — the database is not open.
* `LOAD_EXTENSION_DISABLED` — `allowExtension` was not enabled at construction.

exec(sql: string): void [#execsql-string-void]

Execute one or more SQL statements without returning rows. `sql` may contain multiple statements separated by `;`.

**Parameters**

| Parameter | Type     | Default | Description                                              |
| --------- | -------- | ------- | -------------------------------------------------------- |
| `sql`     | `string` | —       | One or more SQL statements to execute, separated by `;`. |

**Throws**

* `DATABASE_NOT_OPEN` — the database is not open.

isOpen: boolean [#isopen-boolean]

`true` if the database is currently open, `false` otherwise.

loadExtension(path: string, entryPoint?: string | null): void [#loadextensionpath-string-entrypoint-string--null-void]

Load an SQLite extension from `path`. `entryPoint` is the C initialization function name; when omitted, SQLite derives it from the filename. Throws if `allowExtension` was not enabled at construction.

**Parameters**

| Parameter     | Type               | Default | Description                                                                                                |
| ------------- | ------------------ | ------- | ---------------------------------------------------------------------------------------------------------- |
| `path`        | `string`           | —       | Path to the shared library implementing the SQLite extension.                                              |
| `entryPoint?` | `string` \| `null` | —       | Name of the C initialization function to call; when omitted (`null`), SQLite derives it from the filename. |

**Throws**

* `DATABASE_NOT_OPEN` — the database is not open.
* `LOAD_EXTENSION_DISABLED` — `allowExtension` was not enabled at construction.

open(): void [#open-void]

Open the database. Throws if already open. Useful when the database was constructed with `open: false`.

**Throws**

* `DATABASE_ALREADY_OPEN` — the database is already open.

prepare(sql: string): StatementSync [#preparesql-string-statementsync]

Compile `sql` into a prepared statement. The returned `StatementSync` can be reused with different parameter values.

**Parameters**

| Parameter | Type     | Default | Description                                            |
| --------- | -------- | ------- | ------------------------------------------------------ |
| `sql`     | `string` | —       | The SQL to compile into a reusable prepared statement. |

**Returns** `StatementSync` — A `StatementSync` that can be reused with different parameter values.

**Throws**

* `DATABASE_NOT_OPEN` — the database is not open.

StatementSync [#statementsync]

StatementSync.all [#statementsyncall]

```ts
all<T extends SQLiteStatementSync.Row = SQLiteStatementSync.Row>(...params: SQLiteStatementSync.Parameters): T[]
```

Execute the statement and return all rows as an array of objects keyed by column name.

**Parameters**

| Parameter | Type                             | Default | Description                                                                                                                                                  |
| --------- | -------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `params`  | `SQLiteStatementSync.Parameters` | —       | Values to bind to the statement placeholders. An optional leading plain object binds named parameters; the remaining arguments bind positional placeholders. |

**Returns** `T[]` — All result rows, as an array of objects keyed by column name.

columns(): SQLiteStatementSync.Column[] [#columns-sqlitestatementsynccolumn]

Return an array describing the statement's result columns.

**Returns** `SQLiteStatementSync.Column[]` — An array describing the statement result columns.

expandedSQL: string | null [#expandedsql-string--null]

The SQL with bound parameter values substituted in, or `null` if SQLite couldn't expand it.

StatementSync.get [#statementsyncget]

```ts
get<T extends SQLiteStatementSync.Row = SQLiteStatementSync.Row>(...params: SQLiteStatementSync.Parameters): T | undefined
```

Execute the statement and return the first row, or `undefined` if there are no rows.

**Parameters**

| Parameter | Type                             | Default | Description                                                                                                                                                  |
| --------- | -------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `params`  | `SQLiteStatementSync.Parameters` | —       | Values to bind to the statement placeholders. An optional leading plain object binds named parameters; the remaining arguments bind positional placeholders. |

**Returns** `T` | `undefined` — The first result row, or `undefined` if the query produced no rows.

StatementSync.iterate [#statementsynciterate]

```ts
iterate<T extends SQLiteStatementSync.Row = SQLiteStatementSync.Row>(...params: SQLiteStatementSync.Parameters): IterableIterator<T>
```

Execute the statement and return an iterator that yields result rows one at a time as objects keyed by column name.

**Parameters**

| Parameter | Type                             | Default | Description                                                                                                                                                  |
| --------- | -------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `params`  | `SQLiteStatementSync.Parameters` | —       | Values to bind to the statement placeholders. An optional leading plain object binds named parameters; the remaining arguments bind positional placeholders. |

**Returns** `IterableIterator<T>` — An iterator that yields result rows one at a time as objects keyed by column name.

run(...params: SQLiteStatementSync.Parameters): SQLiteStatementSync.RunResult [#runparams-sqlitestatementsyncparameters-sqlitestatementsyncrunresult]

Execute the statement and return a result object with `changes` (the number of rows modified) and `lastInsertRowid`.

**Parameters**

| Parameter | Type                             | Default | Description                                                                                                                                                  |
| --------- | -------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `params`  | `SQLiteStatementSync.Parameters` | —       | Values to bind to the statement placeholders. An optional leading plain object binds named parameters; the remaining arguments bind positional placeholders. |

**Returns** `SQLiteStatementSync.RunResult` — A result object with `changes` (the number of rows modified) and `lastInsertRowid`.

setAllowBareNamedParameters(allow: boolean): void [#setallowbarenamedparametersallow-boolean-void]

When `true` (the default), named-parameter lookup falls back to the bare key when the sigil-prefixed key (`':foo'`) is not found. When `false`, only sigil-prefixed keys are considered.

**Parameters**

| Parameter | Type      | Default | Description                                                                                                                                                          |
| --------- | --------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `allow`   | `boolean` | —       | When `true` (the default), named-parameter lookup falls back to the bare key when the sigil-prefixed key is not found; when `false`, only sigil-prefixed keys match. |

setAllowUnknownNamedParameters(allow: boolean): void [#setallowunknownnamedparametersallow-boolean-void]

When `false` (the default), passing a named-parameters object with keys that don't correspond to any placeholder throws `INVALID_ARGUMENT`. When `true`, extras are silently ignored.

**Parameters**

| Parameter | Type      | Default | Description                                                                                             |
| --------- | --------- | ------- | ------------------------------------------------------------------------------------------------------- |
| `allow`   | `boolean` | —       | When `false` (the default), unknown named-parameter keys throw; when `true`, they are silently ignored. |

setReadBigInts(enabled: boolean): void [#setreadbigintsenabled-boolean-void]

When `true`, `INTEGER` columns are returned as `BigInt` rather than `Number`. `changes` and `lastInsertRowid` from `stmt.run()` are returned as `BigInt` too. Default is `false`.

**Parameters**

| Parameter | Type      | Default | Description                                                                                                                                        |
| --------- | --------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `enabled` | `boolean` | —       | When `true`, `INTEGER` columns (and the `changes`/`lastInsertRowid` from `run()`) are returned as `BigInt` rather than `Number` (default `false`). |

sourceSQL: string [#sourcesql-string]

The original SQL string that the statement was compiled from.

StatementSync.BindValue [#statementsyncbindvalue]

```ts
type BindValue = | null
    | undefined
    | number
    | bigint
    | string
    | ArrayBuffer
    | ArrayBufferView
```

StatementSync.Column [#statementsynccolumn]

```ts
interface Column {
  column: string | null
  name: string | null
  database: string | null
  table: string | null
  type: string | null
}
```

StatementSync.NamedParameters [#statementsyncnamedparameters]

```ts
type NamedParameters = Record<string, BindValue>
```

StatementSync.Parameters [#statementsyncparameters]

```ts
type Parameters = [NamedParameters, ...BindValue[]] | BindValue[]
```

StatementSync.Row [#statementsyncrow]

```ts
type Row = Record<string, Value>
```

StatementSync.RunResult [#statementsyncrunresult]

```ts
interface RunResult {
  changes: number | bigint
  lastInsertRowid: number | bigint
}
```

StatementSync.Value [#statementsyncvalue]

```ts
type Value = null | number | bigint | string | Buffer
```

StatementSync.values [#statementsyncvalues]

```ts
values<T extends SQLiteStatementSync.Value[] = SQLiteStatementSync.Value[]>(...params: SQLiteStatementSync.Parameters): T[]
```

Execute the statement and return all rows as an array of value tuples, one per row, in the order given by `stmt.columns()`. Cheaper than `stmt.all()` when column names aren't needed.

**Parameters**

| Parameter | Type                             | Default | Description                                                                                                                                                  |
| --------- | -------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `params`  | `SQLiteStatementSync.Parameters` | —       | Values to bind to the statement placeholders. An optional leading plain object binds named parameters; the remaining arguments bind positional placeholders. |

**Returns** `T[]` — All result rows, as an array of value tuples ordered by `columns()`.

TagStore [#tagstore]

TagStore.all [#tagstoreall]

```ts
all<T extends StatementSync.Row = StatementSync.Row>(strings: readonly string[], ...params: StatementSync.BindValue[]): T[]
```

Execute the statement and return all rows as an array of objects keyed by column name.

**Parameters**

| Parameter | Type                        | Default | Description                                                                                        |
| --------- | --------------------------- | ------- | -------------------------------------------------------------------------------------------------- |
| `strings` | `readonly string[]`         | —       | The template string parts (the `strings` array of a tagged template).                              |
| `params`  | `StatementSync.BindValue[]` | —       | The interpolated template values, bound positionally to the placeholders between the string parts. |

**Returns** `T[]` — All result rows, as an array of objects keyed by column name.

capacity: number [#capacity-number]

The maximum number of statements the cache holds before evicting the least-recently-used entry.

clear(): void [#clear-void]

Evict all cached prepared statements.

db: DatabaseSync [#db-databasesync]

The `DatabaseSync` this store prepares statements against.

TagStore.get [#tagstoreget]

```ts
get<T extends StatementSync.Row = StatementSync.Row>(strings: readonly string[], ...params: StatementSync.BindValue[]): T | undefined
```

Execute the statement and return the first row, or `undefined` if there are no rows.

**Parameters**

| Parameter | Type                        | Default | Description                                                                                        |
| --------- | --------------------------- | ------- | -------------------------------------------------------------------------------------------------- |
| `strings` | `readonly string[]`         | —       | The template string parts (the `strings` array of a tagged template).                              |
| `params`  | `StatementSync.BindValue[]` | —       | The interpolated template values, bound positionally to the placeholders between the string parts. |

**Returns** `T` | `undefined` — The first result row, or `undefined` if the query produced no rows.

TagStore.iterate [#tagstoreiterate]

```ts
iterate<T extends StatementSync.Row = StatementSync.Row>(strings: readonly string[], ...params: StatementSync.BindValue[]): IterableIterator<T>
```

Execute the statement and return an iterator that yields result rows one at a time as objects keyed by column name.

**Parameters**

| Parameter | Type                        | Default | Description                                                                                        |
| --------- | --------------------------- | ------- | -------------------------------------------------------------------------------------------------- |
| `strings` | `readonly string[]`         | —       | The template string parts (the `strings` array of a tagged template).                              |
| `params`  | `StatementSync.BindValue[]` | —       | The interpolated template values, bound positionally to the placeholders between the string parts. |

**Returns** `IterableIterator<T>` — An iterator that yields result rows one at a time as objects keyed by column name.

run(strings: readonly string[], ...params: StatementSync.BindValue[]): StatementSync.RunResult [#runstrings-readonly-string-params-statementsyncbindvalue-statementsyncrunresult]

Execute the statement and return a result object with `changes` (the number of rows modified) and `lastInsertRowid`.

**Parameters**

| Parameter | Type                        | Default | Description                                                                                        |
| --------- | --------------------------- | ------- | -------------------------------------------------------------------------------------------------- |
| `strings` | `readonly string[]`         | —       | The template string parts (the `strings` array of a tagged template).                              |
| `params`  | `StatementSync.BindValue[]` | —       | The interpolated template values, bound positionally to the placeholders between the string parts. |

**Returns** `StatementSync.RunResult` — A result object with `changes` (the number of rows modified) and `lastInsertRowid`.

size: number [#size-number]

The number of prepared statements currently cached.

TagStore.values [#tagstorevalues]

```ts
values<T extends StatementSync.Value[] = StatementSync.Value[]>(strings: readonly string[], ...params: StatementSync.BindValue[]): T[]
```

Execute the statement and return all rows as an array of value tuples, one per row, in the order given by `stmt.columns()`. Cheaper than `stmt.all()` when column names aren't needed.

**Parameters**

| Parameter | Type                        | Default | Description                                                                                        |
| --------- | --------------------------- | ------- | -------------------------------------------------------------------------------------------------- |
| `strings` | `readonly string[]`         | —       | The template string parts (the `strings` array of a tagged template).                              |
| `params`  | `StatementSync.BindValue[]` | —       | The interpolated template values, bound positionally to the placeholders between the string parts. |

**Returns** `T[]` — All result rows, as an array of value tuples ordered by `columns()`.

Classes [#classes]

errors [#errors]

```ts
class errors {
  code: string
}
```

See also [#see-also]

* [Bare modules](/reference/modules/bare-modules) — the full `bare-*` catalog.
* [Bare runtime API](/reference/bare/runtime) — the runtime these modules extend.


# bare-stdio



<mark style={{ backgroundColor: '#7dde9a', padding: '2px 8px', borderRadius: '4px', fontSize: '0.85em', fontWeight: 500 }}>
  stable
</mark>

[`bare-stdio`](https://github.com/holepunchto/bare-stdio) — Standard input/output streams for Bare. It is a native addon.

```sh
npm i bare-stdio
```

Usage [#usage]

```js
const stdio = require('bare-stdio')

// Write to stdout
stdio.out.write('Hello, World!\n')

// Write to stderr
stdio.err.write('An error occurred\n')

// Read from stdin
stdio.in.on('data', (data) => {
  console.log('Received:', data.toString())
})
```

API [#api]

Constants and variables [#constants-and-variables]

io: IO [#io-io]

The standard I/O streams: `in` — a readable stream for standard input (fd `0`), `out` — a writable stream for standard output (fd `1`), and `err` — a writable stream for standard error (fd `2`). Each is created lazily on first access: a `bare-tty` stream if the file descriptor is a terminal, a `bare-pipe` `Pipe` if it's a pipe, otherwise a `bare-fs` stream.

Types [#types]

IO [#io]

```ts
interface IO {
  readonly in: TTYReadStream | Pipe | FileReadStream
  readonly out: TTYWriteStream | Pipe | FileWriteStream
  readonly err: TTYWriteStream | Pipe | FileWriteStream
}
```

See also [#see-also]

* Builds on `bare-fs`, `bare-pipe`, and `bare-tty`.
* [Bare modules](/reference/modules/bare-modules) — the full `bare-*` catalog.
* [Bare runtime API](/reference/bare/runtime) — the runtime these modules extend.


# bare-stow



<mark style={{ backgroundColor: '#7dde9a', padding: '2px 8px', borderRadius: '4px', fontSize: '0.85em', fontWeight: 500 }}>
  stable
</mark>

[`bare-stow`](https://github.com/holepunchto/bare-stow) — Module bundling and harness generation for Bare.

```sh
npm i bare-stow
```

Usage [#usage]

Given an entry module `core.js` that exports a `start` function receiving the IPC stream and an optional `ready` callback. The function may optionally return (or resolve to) a function that runs before the bundle exits:

```js
module.exports = async function start(ipc, ready) {
  ipc.on('data', (data) => {
    // Handle messages from the host.
  })

  // Optionally call `ready()` to signal readiness early. Otherwise it is
  // signaled automatically when `start()` resolves.
  ready()

  return async function stop() {
    // Clean up before the bundle exits.
  }
}
```

The `ipc` argument is a duplex byte stream. Anything written to it is delivered to the host, and `'data'` events fire when the host writes back.

Stow it for the `bare-sidecar` target:

```js
const stow = require('bare-stow')

const entry = new URL('file:///app/core.js')
const out = new URL('file:///app/out/index.js')

for await (const artifact of stow(entry, 'bare-sidecar', out)) {
  console.log(artifact.url.href)
}
```

Or equivalently from the command line:

```console
$ bare-stow --target bare-sidecar --out ./out/index.js ./core.js
```

This writes the harness to `out` and the bundle alongside it. The harness can then be required from the host and booted with `start()`. The harness awaits the worker's `ready` signal before resolving, so by the time `start()` returns the bundle is up:

```js
const harness = require('/app/out/index.js')

const { ipc } = await harness.start()

ipc.write(Buffer.from('hello from the host'))

ipc.on('exit', (code) => {
  console.log('bundle exited with', code)
})

// Request a graceful shutdown.
ipc.destroy()
```

API [#api]

Functions [#functions]

stow [#stow]

```ts
stow(entry: URL | string, target: Target | TargetName, out: URL | string, opts?: StowOptions): AsyncGenerator<StowArtifact>
```

Bundle the module graph rooted at `entry` for `target`, writing a harness plus bundle to `out`.

**Parameters**

| Parameter | Type                                | Default | Description                                                                                                                                                       |
| --------- | ----------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `entry`   | `URL` \| `string`                   | —       | The entry module to bundle, as a `file:` URL or path string.                                                                                                      |
| `target`  | [`Target`](#target) \| `TargetName` | —       | The bundling target: a `Target` object, or a target name resolved to one (the built-in `bare-sidecar` and `bare-worker`, or a `bare-stow-target-<name>` package). |
| `out`     | `URL` \| `string`                   | —       | The path to write the harness to, as a `file:` URL or path string; the bundle is written alongside it.                                                            |
| `opts?`   | [`StowOptions`](#stowoptions)       | —       | Options; see [`StowOptions`](#stowoptions).                                                                                                                       |

**Returns** `AsyncGenerator<StowArtifact>` — An async generator that yields each written artifact's `url` as it is produced — the harness first, then the bundle, then any offloaded addon or asset files.

**Throws**

* The `target` argument is missing.
* The `out` argument is missing.
* A host in `opts.hosts` is not supported by the resolved target.

Types [#types]

stow.RPCName [#stowrpcname]

```ts
type RPCName = 'bare-rpc'
```

stow.TargetName [#stowtargetname]

```ts
type TargetName = 'bare-sidecar' | 'bare-worker'
```

Target [#target]

```ts
interface Target {
  name: string
  linked: boolean
  offload: boolean | { addons?: boolean; assets?: boolean }
  format: 'bundle' | 'bundle.cjs' | 'bundle.mjs' | 'bundle.json'
  encoding: string | null
  extension: string
  module?: 'esm' | 'cjs'
  hosts: string[]
  generate(context: TargetContext): Artifact[]
}
```

A bundling target, such as `bare-sidecar` or `bare-worker`, describing how to package and boot a bundle on a given host runtime.

TargetContext [#targetcontext]

```ts
interface TargetContext {
  bundleSpecifier: string
  ipc: string
  rpc: string
  module: 'esm' | 'cjs'
  client: RPCClient | null
}
```

The context passed to a target's `generate()`, describing the bundle to embed and the RPC wiring to splice in.

RPC [#rpc]

```ts
interface RPC {
  name: string
  generate(context: RPCContext): Artifact[]
}
```

An RPC library adapter that generates the wiring code spliced into a stowed bundle's harness or entry shim.

RPCContext [#rpccontext]

```ts
interface RPCContext {
  ipc: string
  rpc: string
  module: 'esm' | 'cjs'
  role: 'client' | 'server'
}
```

The context passed to an RPC adapter's `generate()`.

RPCClient [#rpcclient]

```ts
interface RPCClient {
  source: string
  type: string
}
```

The resolved client RPC wiring, carrying both the runtime source to splice into the harness and the type declaration to splice into the harness's `.d.ts`.

Artifact [#artifact]

```ts
interface Artifact {
  extension?: string
  source: string
}
```

A single generated source artifact, such as a harness or a type declaration.

StowOptions [#stowoptions]

```ts
interface StowOptions {
  client?: RPC | RPCName
  server?: RPC | RPCName
  resolveTarget?(name: string): Target
  resolveRPC?(name: string): RPC
  concurrency?: number
  base?: URL | string
  defaultType?: number
  builtinProtocol?: string
  builtins?: Builtins
  conditions?: Conditions
  extensions?: string[]
  host?: string
  hosts?: string[]
  linkedProtocol?: string
  matchedConditions?: string[]
  resolutions?: ResolutionsMap
}
```

Options for `stow()`.

StowArtifact [#stowartifact]

```ts
interface StowArtifact {
  url: URL
}
```

An artifact written by `stow()`, yielded once its file has been written.

bare-stow/protocol [#bare-stowprotocol]

Protocol [#protocol]

new Protocol(stream: Duplex) [#new-protocolstream-duplex]

Attach a `Protocol` to the given underlying duplex byte `stream`.

**Parameters**

| Parameter | Type     | Default | Description                                                                             |
| --------- | -------- | ------- | --------------------------------------------------------------------------------------- |
| `stream`  | `Duplex` | —       | The underlying duplex byte stream to multiplex the control and user-data channels over. |

send(type: string, payload?: object): Promise<void> [#sendtype-string-payload-object-promisevoid]

Send a control frame of `type` with an optional JSON-serializable `payload`.

**Parameters**

| Parameter  | Type     | Default | Description                                                                           |
| ---------- | -------- | ------- | ------------------------------------------------------------------------------------- |
| `type`     | `string` | —       | The control frame type, for example `'ready'`, `'exit'`, `'error'`, or `'terminate'`. |
| `payload?` | `object` | —       | An optional JSON-serializable payload carried with the frame.                         |

Functions [#functions-1]

attach(stream: Duplex): Protocol [#attachstream-duplex-protocol]

Attach a `Protocol` to `stream`, an underlying duplex byte stream.

**Parameters**

| Parameter | Type     | Default | Description                                       |
| --------- | -------- | ------- | ------------------------------------------------- |
| `stream`  | `Duplex` | —       | Any duplex byte stream to attach the protocol to. |

**Returns** `Protocol` — A `Protocol` multiplexing control and user-data frames over `stream`.

Constants and variables [#constants-and-variables]

CONTROL: number [#control-number]

The frame type marker identifying a control-channel frame.

USER: number [#user-number]

The frame type marker identifying a user-data-channel frame.

Types [#types-1]

ProtocolEvents [#protocolevents]

```ts
interface ProtocolEvents {
  ready: []
  terminate: []
  exit: [code: number]
  data: [data: unknown]
  end: []
  readable: []
  piping: [dest: Writable]
  close: []
  error: [err: Error]
  drain: []
  finish: []
  pipe: [src: Readable]
}
```

The events emitted by a `Protocol`, in addition to the standard duplex stream events.

bare-stow/host [#bare-stowhost]

IPC [#ipc]

new IPC(stream: Duplex) [#new-ipcstream-duplex]

Wrap the host side of a stowed bundle's transport `stream`.

**Parameters**

| Parameter | Type     | Default | Description                                                            |
| --------- | -------- | ------- | ---------------------------------------------------------------------- |
| `stream`  | `Duplex` | —       | The host side of a stowed bundle's transport (any duplex byte stream). |

ready: Promise<void> [#ready-promisevoid]

A promise that resolves once the worker has signaled ready, and rejects if the worker errors before then.

terminate(): Promise<number | undefined> [#terminate-promisenumber--undefined]

Send a `terminate` control frame to the worker and resolve with its exit code once it exits.

**Returns** `Promise<number | undefined>` — The worker's exit `code` once it exits.

Functions [#functions-2]

wrap(stream: Duplex): IPC [#wrapstream-duplex-ipc]

Wrap the host side of a stowed bundle's transport `stream`, returning an `IPC` handle with lifecycle helpers layered on top of the `Protocol`.

**Parameters**

| Parameter | Type     | Default | Description                                                            |
| --------- | -------- | ------- | ---------------------------------------------------------------------- |
| `stream`  | `Duplex` | —       | The host side of a stowed bundle's transport (any duplex byte stream). |

**Returns** `IPC` — An `IPC` handle wrapping `stream`, with the `ready` promise and `terminate()` layered on top of `Protocol`.

Protocol [#protocol-1]

The harness multiplexes a control channel and a user data channel over the underlying binary duplex stream. The `ipc` returned from `start()` is itself a duplex stream carrying the user data; control frames ride alongside it on the same handle. RPC libraries (such as `bare-rpc`) bind to `ipc` just like a raw stream.

Control frames signal lifecycle events:

| Direction      | Type        | Payload              |
| :------------- | :---------- | :------------------- |
| Worker -> Host | `ready`     | -                    |
| Worker -> Host | `exit`      | `{ code }`           |
| Worker -> Host | `error`     | `{ message, stack }` |
| Host -> Worker | `terminate` | -                    |

An incoming `error` frame destroys the local `ipc` with the carried error, surfacing it as a normal stream `error` event. Other control frames emit a regular event named after the type.

The `ipc` handle exposes the lifecycle as events and methods on the same duplex:

* `ipc.ready`: A promise that resolves once the worker has signaled ready. Rejects if the worker errors before ready.
* `ipc.on('exit', code)`: Emitted when the worker signals exit. `code` carries the exit code.
* `ipc.on('error', err)`: Emitted when the worker reports a fault, or when the underlying transport errors. Either way the `ipc` is destroyed.
* `ipc.on('close')`: Emitted when the underlying transport closes.
* `ipc.destroy()`: Standard stream destroy. Sends a `terminate` control frame to the worker and waits for the underlying transport to close.
* `ipc.terminate()`: Like `destroy()` but resolves with the worker's exit code.

The framing layer is also exported directly for embedders that bring their own transport:

```js
const protocol = require('bare-stow/protocol')

const ipc = protocol.attach(stream) // Any duplex byte stream
ipc.write(Buffer.from('payload')) // User data
ipc.send('ready') // Control frame
ipc.on('exit', () => {
  /* ... */
})
```

The host helper layers the lifecycle promise and `terminate` method on top of the protocol:

```js
const { wrap } = require('bare-stow/host')

const ipc = wrap(stream) // Any duplex byte stream
await ipc.ready
```

CLI [#cli]

bare-stow [flags] <entry> [#bare-stow-flags-entry]

Stow the module graph rooted at `<entry>`, writing the harness and bundle to the path given by `--out`.

```console
--version|-v
--target <name>
--client <name>
--server <name>
--base <path>
--out|-o <path>
--builtins <path>
--imports <path>
--defer <specifier>
--host <name>
--help|-h
```

--target <name> [#--target-name]

The target runtime. Required. The built-in `bare-sidecar` and `bare-worker` are resolved directly; any other `<name>` is loaded from its `bare-stow-target-<name>` package, or from `<name>` itself as a full module specifier, resolved from the working directory.

--client <name> and --server <name> [#--client-name-and---server-name]

The RPC library to wire into the harness (`--client`) or the bundle entry shim (`--server`). The built-in `bare-rpc` is resolved directly; any other `<name>` is loaded from its `bare-stow-rpc-<name>` package, or from `<name>` itself as a full module specifier, resolved from the working directory.

--builtins <path> and --imports <path> [#--builtins-path-and---imports-path]

Paths to JavaScript or JSON files exporting a list of builtin module names and a map of global import overrides respectively. Forwarded to `bare-pack`.

--defer <specifier> [#--defer-specifier]

A module specifier whose resolution should be deferred. May be passed multiple times.

--host <name> [#--host-name]

A host triple to build for. Must be a subset of the host triples supported by the target. May be passed multiple times. Defaults to all host triples supported by the target.

See also [#see-also]

* Builds on `bare-bundle`, `bare-bundle-id`, `bare-fs`, `bare-module-lexer`, `bare-module-traverse`, `bare-pack`, `bare-path`, `bare-stream`, and `bare-type-stripper`.
* [Bare modules](/reference/modules/bare-modules) — the full `bare-*` catalog.
* [Bare runtime API](/reference/bare/runtime) — the runtime these modules extend.


# bare-stream



<mark style={{ backgroundColor: '#7dde9a', padding: '2px 8px', borderRadius: '4px', fontSize: '0.85em', fontWeight: 500 }}>
  stable
</mark>

[`bare-stream`](https://github.com/holepunchto/bare-stream) — Streaming data for JavaScript.

Mirrors the Node.js [`stream`](https://nodejs.org/api/stream.html) module.

```sh
npm i bare-stream
```

Usage [#usage]

```js
const { Readable } = require('bare-stream')

const stream = new Readable({
  read(size) {
    // Push data, then push `null` to signal the end
    this.push('hello')
    this.push('world')
    this.push(null)
  }
})

stream.on('data', (data) => console.log(data))
```

API [#api]

Stream basics [#stream-basics]

_destroy(err: Error | null, cb: StreamCallback): void [#_destroyerr-error--null-cb-streamcallback-void]

**Parameters**

| Parameter | Type                                | Default | Description                                                                  |
| --------- | ----------------------------------- | ------- | ---------------------------------------------------------------------------- |
| `err`     | `Error` \| `null`                   | —       | The error the stream is being destroyed with, or `null` for a clean destroy. |
| `cb`      | [`StreamCallback`](#streamcallback) | —       | Called with an error, or `null` on success.                                  |

_open(cb: StreamCallback): void [#_opencb-streamcallback-void]

**Parameters**

| Parameter | Type                                | Default | Description                                             |
| --------- | ----------------------------------- | ------- | ------------------------------------------------------- |
| `cb`      | [`StreamCallback`](#streamcallback) | —       | Called with an error, or `null`, once opening finishes. |

_predestroy(): void [#_predestroy-void]

destroy(err?: Error | null): void [#destroyerr-error--null-void]

**Parameters**

| Parameter | Type              | Default | Description                                                                    |
| --------- | ----------------- | ------- | ------------------------------------------------------------------------------ |
| `err?`    | `Error` \| `null` | —       | The error to destroy the stream with; omit or pass `null` for a clean destroy. |

destroyed: boolean [#destroyed-boolean]

destroying: boolean [#destroying-boolean]

readable: boolean [#readable-boolean]

writable: boolean [#writable-boolean]

Stream utilities [#stream-utilities]

Stream.addAbortSignal<S extends Stream>(signal: AbortSignal, stream: S): S [#streamaddabortsignals-extends-streamsignal-abortsignal-stream-s-s]

Destroy `stream` when `signal` aborts, using `signal.reason` as the destruction error. Returns `stream`.

**Parameters**

| Parameter | Type          | Default | Description                                        |
| --------- | ------------- | ------- | -------------------------------------------------- |
| `signal`  | `AbortSignal` | —       | The `AbortSignal` that destroys `stream` on abort. |
| `stream`  | `S`           | —       | The stream to destroy when `signal` aborts.        |

Stream.duplexPair(opts?: DuplexOptions): [Duplex, Duplex] [#streamduplexpairopts-duplexoptions-duplex-duplex]

Create a pair of linked `Duplex` streams. Data written to `a` is readable from `b` and vice versa. `options` are passed to each side.

**Parameters**

| Parameter | Type                              | Default | Description                      |
| --------- | --------------------------------- | ------- | -------------------------------- |
| `opts?`   | [`DuplexOptions`](#duplexoptions) | —       | Passed to both ends of the pair. |

Stream.finished(stream: Stream, opts: { cleanup?: boolean }, cb: StreamCallback): () => void [#streamfinishedstream-stream-opts--cleanup-boolean--cb-streamcallback---void]

Invoke `cb` once `stream` is no longer readable or writable, or has errored. Returns a function that detaches the listeners.

Overloads:

```ts
Stream.finished(stream: Stream, opts: { cleanup?: boolean }, cb: StreamCallback): () => void
Stream.finished(stream: Stream, cb: StreamCallback): () => void
```

**Parameters**

| Parameter | Type                                | Default | Description                                                               |
| --------- | ----------------------------------- | ------- | ------------------------------------------------------------------------- |
| `stream`  | `Stream`                            | —       | The stream to wait on.                                                    |
| `opts`    | `{ cleanup?: boolean }`             | —       | Set `cleanup: true` to detach the listeners automatically once `cb` runs. |
| `cb`      | [`StreamCallback`](#streamcallback) | —       | Called with an error, or `null`, once `stream` finishes.                  |

Stream.getStreamError(stream: Stream, opts?: { all?: boolean }): Error | null [#streamgetstreamerrorstream-stream-opts--all-boolean--error--null]

Return the error a stream was destroyed with, or `null`.

**Parameters**

| Parameter | Type                | Default | Description            |
| --------- | ------------------- | ------- | ---------------------- |
| `stream`  | `Stream`            | —       | The stream to inspect. |
| `opts?`   | `{ all?: boolean }` | —       | —                      |

Stream.isDisturbed(stream: Stream): boolean [#streamisdisturbedstream-stream-boolean]

**Parameters**

| Parameter | Type     | Default | Description         |
| --------- | -------- | ------- | ------------------- |
| `stream`  | `Stream` | —       | The stream to test. |

Stream.isEnded(stream: Stream): boolean [#streamisendedstream-stream-boolean]

**Parameters**

| Parameter | Type     | Default | Description         |
| --------- | -------- | ------- | ------------------- |
| `stream`  | `Stream` | —       | The stream to test. |

Stream.isErrored(stream: Stream): boolean [#streamiserroredstream-stream-boolean]

**Parameters**

| Parameter | Type     | Default | Description         |
| --------- | -------- | ------- | ------------------- |
| `stream`  | `Stream` | —       | The stream to test. |

Stream.isFinished(stream: Stream): boolean [#streamisfinishedstream-stream-boolean]

**Parameters**

| Parameter | Type     | Default | Description         |
| --------- | -------- | ------- | ------------------- |
| `stream`  | `Stream` | —       | The stream to test. |

Stream.isReadable(stream: Stream): boolean [#streamisreadablestream-stream-boolean]

**Parameters**

| Parameter | Type     | Default | Description         |
| --------- | -------- | ------- | ------------------- |
| `stream`  | `Stream` | —       | The stream to test. |

Stream.isStream(stream: unknown): stream is Stream [#streamisstreamstream-unknown-stream-is-stream]

**Parameters**

| Parameter | Type      | Default | Description         |
| --------- | --------- | ------- | ------------------- |
| `stream`  | `unknown` | —       | The stream to test. |

Stream.isWritable(stream: Stream): boolean [#streamiswritablestream-stream-boolean]

Return `true` if `stream` is writable.

**Parameters**

| Parameter | Type     | Default | Description         |
| --------- | -------- | ------- | ------------------- |
| `stream`  | `Stream` | —       | The stream to test. |

Stream.pipeline<S extends Writable>(streams: Pipeline<S>, cb?: StreamCallback): S [#streampipelines-extends-writablestreams-pipelines-cb-streamcallback-s]

Pipe a series of streams together, propagating errors and cleaning up on completion. `streams` is a `Readable` source, zero or more `Duplex` transforms, and a `Writable` destination. Returns the destination stream. `cb` is called when the pipeline finishes or errors.

Overloads:

```ts
Stream.pipeline<S extends Writable>(streams: Pipeline<S>, cb?: StreamCallback): S
Stream.pipeline<S extends Writable>(...args: Pipeline<S>): S
Stream.pipeline<S extends Writable>(...args: [...Pipeline<S>, cb: StreamCallback]): S
```

**Parameters**

| Parameter | Type                                | Default | Description                                                                          |
| --------- | ----------------------------------- | ------- | ------------------------------------------------------------------------------------ |
| `streams` | `Pipeline<S>`                       | —       | A `Readable` source, zero or more `Duplex` transforms, and a `Writable` destination. |
| `cb?`     | [`StreamCallback`](#streamcallback) | —       | Called with an error, or `null`, once the pipeline finishes or errors.               |

Readable streams [#readable-streams]

new Readable(opts?: ReadableOptions) [#new-readableopts-readableoptions]

A readable stream.

**Parameters**

| Parameter | Type                                  | Default | Description |
| --------- | ------------------------------------- | ------- | ----------- |
| `opts?`   | [`ReadableOptions`](#readableoptions) | —       | —           |

_read(size: number): void [#_readsize-number-void]

**Parameters**

| Parameter | Type     | Default | Description |
| --------- | -------- | ------- | ----------- |
| `size`    | `number` | —       | —           |

Readable.closed: boolean [#readableclosed-boolean]

`true` when the stream is no longer readable.

Readable.errored: Error | null [#readableerrored-error--null]

The error the stream was destroyed with, or `null`.

pause(): this [#pause-this]

pipe<S extends Writable>(dest: S, cb?: StreamCallback): S [#pipes-extends-writabledest-s-cb-streamcallback-s]

**Parameters**

| Parameter | Type                                | Default | Description                                 |
| --------- | ----------------------------------- | ------- | ------------------------------------------- |
| `dest`    | `S`                                 | —       | The destination stream to write into.       |
| `cb?`     | [`StreamCallback`](#streamcallback) | —       | Called with an error, or `null` on success. |

push(data: unknown | null, encoding?: BufferEncoding): boolean [#pushdata-unknown--null-encoding-bufferencoding-boolean]

Push `data` into the stream's internal buffer. If `data` is a string, it is encoded to a `Buffer` using `encoding`, defaulting to `'utf8'`. Push `null` to signal the end of the stream.

**Parameters**

| Parameter   | Type                | Default | Description                                                                   |
| ----------- | ------------------- | ------- | ----------------------------------------------------------------------------- |
| `data`      | `unknown` \| `null` | —       | Data to add to the buffer, or `null` to end the stream.                       |
| `encoding?` | `BufferEncoding`    | —       | Encoding used to convert a string `data` to a `Buffer`; defaults to `'utf8'`. |

read(): unknown | null [#read-unknown--null]

Readable.from [#readablefrom]

```ts
Readable.from(data: unknown | unknown[] | AsyncIterable<unknown>, opts?: ReadableOptions): Readable
```

Create a readable stream from `data`, which may be a value, an array of values, or an async iterable.

**Parameters**

| Parameter | Type                                             | Default | Description                                               |
| --------- | ------------------------------------------------ | ------- | --------------------------------------------------------- |
| `data`    | `unknown \| unknown[] \| AsyncIterable<unknown>` | —       | A value, array of values, or async iterable to read from. |
| `opts?`   | [`ReadableOptions`](#readableoptions)            | —       | —                                                         |

Readable.fromWeb(readableStream: ReadableStream, opts?: ReadableFromWebOptions): Readable [#readablefromwebreadablestream-readablestream-opts-readablefromweboptions-readable]

Convert a web `ReadableStream` into a `Readable`.

**Parameters**

| Parameter        | Type                                                | Default | Description                                                                               |
| ---------------- | --------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------- |
| `readableStream` | `ReadableStream`                                    | —       | The web `ReadableStream` to convert.                                                      |
| `opts?`          | [`ReadableFromWebOptions`](#readablefromweboptions) | —       | Options for the conversion; supports `encoding` and `signal`, matching `ReadableOptions`. |

Readable.isBackpressured(rs: Readable): boolean [#readableisbackpressuredrs-readable-boolean]

**Parameters**

| Parameter | Type       | Default | Description          |
| --------- | ---------- | ------- | -------------------- |
| `rs`      | `Readable` | —       | The stream to check. |

Readable.isPaused(rs: Readable): boolean [#readableispausedrs-readable-boolean]

**Parameters**

| Parameter | Type       | Default | Description          |
| --------- | ---------- | ------- | -------------------- |
| `rs`      | `Readable` | —       | The stream to check. |

Readable.toWeb(readable: Readable, opts?: ReadableToWebOptions): ReadableStream [#readabletowebreadable-readable-opts-readabletoweboptions-readablestream]

Convert a `Readable` into a web `ReadableStream`.

**Parameters**

| Parameter  | Type                                            | Default | Description                                                                                                             |
| ---------- | ----------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------- |
| `readable` | `Readable`                                      | —       | The `Readable` to convert.                                                                                              |
| `opts?`    | [`ReadableToWebOptions`](#readabletoweboptions) | —       | Options for the conversion; `strategy` is a custom queuing strategy passed through to the `ReadableStream` constructor. |

resume(): this [#resume-this]

setEncoding(encoding: BufferEncoding): void [#setencodingencoding-bufferencoding-void]

**Parameters**

| Parameter  | Type             | Default | Description                                      |
| ---------- | ---------------- | ------- | ------------------------------------------------ |
| `encoding` | `BufferEncoding` | —       | Encoding used to decode emitted data to strings. |

unshift(data: unknown | null, encoding?: BufferEncoding): boolean [#unshiftdata-unknown--null-encoding-bufferencoding-boolean]

Like `stream.push()` but prepends `data` to the internal buffer so it is read before any already buffered data.

**Parameters**

| Parameter   | Type                | Default | Description                                                                   |
| ----------- | ------------------- | ------- | ----------------------------------------------------------------------------- |
| `data`      | `unknown` \| `null` | —       | Data to prepend to the buffer, or `null` to end the stream.                   |
| `encoding?` | `BufferEncoding`    | —       | Encoding used to convert a string `data` to a `Buffer`; defaults to `'utf8'`. |

Writable streams [#writable-streams]

new Writable(opts?: WritableOptions) [#new-writableopts-writableoptions]

A writable stream.

**Parameters**

| Parameter | Type                                  | Default | Description |
| --------- | ------------------------------------- | ------- | ----------- |
| `opts?`   | [`WritableOptions`](#writableoptions) | —       | —           |

_final(cb: StreamCallback): void [#_finalcb-streamcallback-void]

**Parameters**

| Parameter | Type                                | Default | Description                                 |
| --------- | ----------------------------------- | ------- | ------------------------------------------- |
| `cb`      | [`StreamCallback`](#streamcallback) | —       | Called with an error, or `null` on success. |

_write(data: unknown, encoding: StreamEncoding, cb: StreamCallback): void [#_writedata-unknown-encoding-streamencoding-cb-streamcallback-void]

**Parameters**

| Parameter  | Type                                | Default | Description                                              |
| ---------- | ----------------------------------- | ------- | -------------------------------------------------------- |
| `data`     | `unknown`                           | —       | The chunk to write.                                      |
| `encoding` | `StreamEncoding`                    | —       | Encoding of `data`, or `'buffer'` if it is not a string. |
| `cb`       | [`StreamCallback`](#streamcallback) | —       | Called with an error, or `null` on success.              |

_writev(batch: { chunk: unknown; encoding: StreamEncoding }[], cb: StreamCallback): void [#_writevbatch--chunk-unknown-encoding-streamencoding--cb-streamcallback-void]

**Parameters**

| Parameter | Type                                             | Default | Description                                                   |
| --------- | ------------------------------------------------ | ------- | ------------------------------------------------------------- |
| `batch`   | `{ chunk: unknown; encoding: StreamEncoding }[]` | —       | Queued chunks to write, each with its `chunk` and `encoding`. |
| `cb`      | [`StreamCallback`](#streamcallback)              | —       | Called with an error, or `null` on success.                   |

Writable.closed: boolean [#writableclosed-boolean]

`true` when the stream is no longer writable.

cork(): void [#cork-void]

end(cb?: StreamCallback): this [#endcb-streamcallback-this]

Signal that no more data will be written. If `data` is provided it is written first. The optional `cb` is called once the stream has finished.

Overloads:

```ts
end(cb?: StreamCallback): this
end(data: unknown, encoding?: BufferEncoding, cb?: StreamCallback): this
end(data: unknown, cb?: StreamCallback): this
```

**Parameters**

| Parameter | Type                                | Default | Description                                                    |
| --------- | ----------------------------------- | ------- | -------------------------------------------------------------- |
| `cb?`     | [`StreamCallback`](#streamcallback) | —       | Called with an error, or `null`, once the stream has finished. |

Writable.errored: Error | null [#writableerrored-error--null]

The error the stream was destroyed with, or `null`.

uncork(): void [#uncork-void]

Writable.drained(ws: Writable): Promise<boolean> [#writabledrainedws-writable-promiseboolean]

Returns a promise that resolves once the stream has drained.

**Parameters**

| Parameter | Type       | Default | Description            |
| --------- | ---------- | ------- | ---------------------- |
| `ws`      | `Writable` | —       | The stream to wait on. |

Writable.fromWeb(writableStream: WritableStream, opts?: WritableFromWebOptions): Writable [#writablefromwebwritablestream-writablestream-opts-writablefromweboptions-writable]

Convert a web `WritableStream` into a `Writable`.

**Parameters**

| Parameter        | Type                                                | Default | Description                                                                |
| ---------------- | --------------------------------------------------- | ------- | -------------------------------------------------------------------------- |
| `writableStream` | `WritableStream`                                    | —       | The web `WritableStream` to convert.                                       |
| `opts?`          | [`WritableFromWebOptions`](#writablefromweboptions) | —       | Options for the conversion; supports `signal`, matching `WritableOptions`. |

Writable.isBackpressured(ws: Writable): boolean [#writableisbackpressuredws-writable-boolean]

**Parameters**

| Parameter | Type       | Default | Description          |
| --------- | ---------- | ------- | -------------------- |
| `ws`      | `Writable` | —       | The stream to check. |

Writable.toWeb(writable: Writable): WritableStream [#writabletowebwritable-writable-writablestream]

Convert a `Writable` into a web `WritableStream`.

**Parameters**

| Parameter  | Type       | Default | Description                |
| ---------- | ---------- | ------- | -------------------------- |
| `writable` | `Writable` | —       | The `Writable` to convert. |

write(data: unknown, encoding?: BufferEncoding, cb?: StreamCallback): boolean [#writedata-unknown-encoding-bufferencoding-cb-streamcallback-boolean]

Write `data` to the stream. If `data` is a string, it is encoded using `encoding`, defaulting to `'utf8'`. Returns `false` if the stream is backpressured. The optional `cb` is called once the write has drained.

Overloads:

```ts
write(data: unknown, encoding?: BufferEncoding, cb?: StreamCallback): boolean
write(data: unknown, cb?: StreamCallback): boolean
```

**Parameters**

| Parameter   | Type                                | Default | Description                                                                   |
| ----------- | ----------------------------------- | ------- | ----------------------------------------------------------------------------- |
| `data`      | `unknown`                           | —       | Data to write. If a string, it is encoded using `encoding`.                   |
| `encoding?` | `BufferEncoding`                    | —       | Encoding used to convert a string `data` to a `Buffer`; defaults to `'utf8'`. |
| `cb?`       | [`StreamCallback`](#streamcallback) | —       | Called with an error, or `null`, once the write has drained.                  |

Duplex and Transform streams [#duplex-and-transform-streams]

new Duplex(opts?: DuplexOptions) [#new-duplexopts-duplexoptions]

A stream that is both readable and writable. Accepts the combined options of `Readable` and `Writable`.

**Parameters**

| Parameter | Type                              | Default | Description |
| --------- | --------------------------------- | ------- | ----------- |
| `opts?`   | [`DuplexOptions`](#duplexoptions) | —       | —           |

Duplex.fromWeb [#duplexfromweb]

```ts
Duplex.fromWeb({ readable: ReadableStream, writable: Writable }, opts?: DuplexFromWebOptions): Readable
```

Convert a pair of web `ReadableStream` and `WritableStream` into a `Duplex`.

**Parameters**

| Parameter                                          | Type                                            | Default | Description                                                                                                   |
| -------------------------------------------------- | ----------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------- |
| `{ readable: ReadableStream, writable: Writable }` | `any`                                           | —       | Options for the conversion; combines the `Readable` and `Writable` conversion options (`encoding`, `signal`). |
| `opts?`                                            | [`DuplexFromWebOptions`](#duplexfromweboptions) | —       | Options for the conversion; combines the `Readable` and `Writable` conversion options (`encoding`, `signal`). |

Duplex.toWeb(readable: Readable, opts?: ReadableToWebOptions): ReadableStream [#duplextowebreadable-readable-opts-readabletoweboptions-readablestream]

**Parameters**

| Parameter  | Type                                            | Default | Description |
| ---------- | ----------------------------------------------- | ------- | ----------- |
| `readable` | `Readable`                                      | —       | —           |
| `opts?`    | [`ReadableToWebOptions`](#readabletoweboptions) | —       | —           |

new Transform(opts?: TransformOptions) [#new-transformopts-transformoptions]

A duplex stream where output is computed from input.

**Parameters**

| Parameter | Type                                    | Default | Description |
| --------- | --------------------------------------- | ------- | ----------- |
| `opts?`   | [`TransformOptions`](#transformoptions) | —       | —           |

_flush(cb: StreamCallback): void [#_flushcb-streamcallback-void]

**Parameters**

| Parameter | Type                                | Default | Description                                              |
| --------- | ----------------------------------- | ------- | -------------------------------------------------------- |
| `cb`      | [`StreamCallback`](#streamcallback) | —       | Called with an error, or `null`, once flushing finishes. |

_transform(data: unknown, encoding: StreamEncoding, cb: StreamCallback): void [#_transformdata-unknown-encoding-streamencoding-cb-streamcallback-void]

**Parameters**

| Parameter  | Type                                | Default | Description                                              |
| ---------- | ----------------------------------- | ------- | -------------------------------------------------------- |
| `data`     | `unknown`                           | —       | The chunk to transform.                                  |
| `encoding` | `StreamEncoding`                    | —       | Encoding of `data`, or `'buffer'` if it is not a string. |
| `cb`       | [`StreamCallback`](#streamcallback) | —       | Called with an error, or `null` on success.              |

Events [#events]

StreamEvents [#streamevents]

```ts
interface StreamEvents {
  close: []
  error: [err: Error]
}
```

ReadableEvents [#readableevents]

```ts
interface ReadableEvents {
  data: [data: unknown]
  end: []
  readable: []
  piping: [dest: Writable]
  close: []
  error: [err: Error]
}
```

WritableEvents [#writableevents]

```ts
interface WritableEvents {
  drain: []
  finish: []
  pipe: [src: Readable]
  close: []
  error: [err: Error]
}
```

DuplexEvents [#duplexevents]

```ts
interface DuplexEvents {
  data: [data: unknown]
  end: []
  readable: []
  piping: [dest: Writable]
  close: []
  error: [err: Error]
  drain: []
  finish: []
  pipe: [src: Readable]
}
```

TransformEvents [#transformevents]

```ts
interface TransformEvents {
  data: [data: unknown]
  end: []
  readable: []
  piping: [dest: Writable]
  close: []
  error: [err: Error]
  drain: []
  finish: []
  pipe: [src: Readable]
}
```

Options [#options]

StreamOptions [#streamoptions]

```ts
interface StreamOptions<S extends Stream = Stream> {
  eagerOpen?: boolean
  signal?: AbortSignal
  open?(this: S, cb: StreamCallback): void
  predestroy?(this: S): void
  destroy?(this: S, err: Error | null, cb: StreamCallback): void
}
```

ReadableOptions [#readableoptions]

```ts
interface ReadableOptions<S extends Readable = Readable> {
  encoding?: BufferEncoding
  highWaterMark?: number
  read?(this: S, size: number): void
  eagerOpen?: boolean
  signal?: AbortSignal
  open?(this: S, cb: StreamCallback): void
  predestroy?(this: S): void
  destroy?(this: S, err: Error | null, cb: StreamCallback): void
}
```

WritableOptions [#writableoptions]

```ts
interface WritableOptions<S extends Writable = Writable> {
  write?(this: S, data: unknown, encoding: StreamEncoding, cb: StreamCallback): void
  writev?(this: S, batch: { chunk: unknown; encoding: StreamEncoding }[], cb: StreamCallback): void
  final?(this: S, cb: StreamCallback): void
  eagerOpen?: boolean
  signal?: AbortSignal
  open?(this: S, cb: StreamCallback): void
  predestroy?(this: S): void
  destroy?(this: S, err: Error | null, cb: StreamCallback): void
}
```

DuplexOptions [#duplexoptions]

```ts
interface DuplexOptions<S extends Duplex = Duplex> {
  encoding?: BufferEncoding
  highWaterMark?: number
  read?(this: S, size: number): void
  eagerOpen?: boolean
  signal?: AbortSignal
  open?(this: S, cb: StreamCallback): void
  predestroy?(this: S): void
  destroy?(this: S, err: Error | null, cb: StreamCallback): void
  write?(this: S, data: unknown, encoding: StreamEncoding, cb: StreamCallback): void
  writev?(this: S, batch: { chunk: unknown; encoding: StreamEncoding }[], cb: StreamCallback): void
  final?(this: S, cb: StreamCallback): void
}
```

TransformOptions [#transformoptions]

```ts
interface TransformOptions<S extends Transform = Transform> {
  transform?(this: S, data: unknown, encoding: StreamEncoding, cb: StreamCallback): void
  flush?(this: S, cb: StreamCallback): void
  encoding?: BufferEncoding
  highWaterMark?: number
  read?(this: S, size: number): void
  eagerOpen?: boolean
  signal?: AbortSignal
  open?(this: S, cb: StreamCallback): void
  predestroy?(this: S): void
  destroy?(this: S, err: Error | null, cb: StreamCallback): void
  write?(this: S, data: unknown, encoding: StreamEncoding, cb: StreamCallback): void
  writev?(this: S, batch: { chunk: unknown; encoding: StreamEncoding }[], cb: StreamCallback): void
  final?(this: S, cb: StreamCallback): void
}
```

Types [#types]

StreamCallback [#streamcallback]

```ts
interface StreamCallback {
}
```

ReadableFromWebOptions [#readablefromweboptions]

```ts
interface ReadableFromWebOptions {
  encoding?: BufferEncoding
  signal?: AbortSignal
}
```

ReadableToWebOptions [#readabletoweboptions]

```ts
interface ReadableToWebOptions {
  strategy?: CustomQueuingStrategy
}
```

WritableFromWebOptions [#writablefromweboptions]

```ts
interface WritableFromWebOptions {
  signal?: AbortSignal
}
```

DuplexFromWebOptions [#duplexfromweboptions]

```ts
interface DuplexFromWebOptions {
  encoding?: BufferEncoding
  signal?: AbortSignal
}
```

bare-stream/web [#bare-streamweb]

ReadableStreamDefaultReader [#readablestreamdefaultreader]

new ReadableStreamDefaultReader(stream: ReadableStream) [#new-readablestreamdefaultreaderstream-readablestream]

A reader over a `ReadableStream`, exposing `closed`, `read()`, `releaseLock()`, and `cancel([reason])`.

**Parameters**

| Parameter | Type             | Default | Description                        |
| --------- | ---------------- | ------- | ---------------------------------- |
| `stream`  | `ReadableStream` | —       | The `ReadableStream` to read from. |

ReadableStreamDefaultReader.cancel(reason?: unknown): Promise<void> [#readablestreamdefaultreadercancelreason-unknown-promisevoid]

**Parameters**

| Parameter | Type      | Default | Description                                                                                            |
| --------- | --------- | ------- | ------------------------------------------------------------------------------------------------------ |
| `reason?` | `unknown` | —       | Reason for the cancellation, passed to the stream's `destroy()`; defaults to a `TypeError` if omitted. |

ReadableStreamDefaultReader.closed: Promise<void> [#readablestreamdefaultreaderclosed-promisevoid]

read(): Promise<{ value: unknown; done: boolean }> [#read-promise-value-unknown-done-boolean-]

**Returns** `Promise<{ value: unknown; done: boolean }>` — Resolves with the next chunk as `{ value, done: false }`, or `{ value: undefined, done: true }` once the stream ends; rejects with the stream's error if the stream is errored.

ReadableStreamDefaultReader.releaseLock(): void [#readablestreamdefaultreaderreleaselock-void]

ReadableStreamDefaultController [#readablestreamdefaultcontroller]

new ReadableStreamDefaultController(stream: ReadableStream) [#new-readablestreamdefaultcontrollerstream-readablestream]

The controller passed to `start` and `pull`, exposing `desiredSize`, `enqueue(data)`, `close()`, and `error([err])`.

**Parameters**

| Parameter | Type             | Default | Description                                  |
| --------- | ---------------- | ------- | -------------------------------------------- |
| `stream`  | `ReadableStream` | —       | The `ReadableStream` the controller manages. |

close(): void [#close-void]

ReadableStreamDefaultController.desiredSize: number [#readablestreamdefaultcontrollerdesiredsize-number]

ReadableStreamDefaultController.enqueue(data: unknown): void [#readablestreamdefaultcontrollerenqueuedata-unknown-void]

**Parameters**

| Parameter | Type      | Default | Description           |
| --------- | --------- | ------- | --------------------- |
| `data`    | `unknown` | —       | The chunk to enqueue. |

ReadableStreamDefaultController.error(error?: unknown): void [#readablestreamdefaultcontrollererrorerror-unknown-void]

**Parameters**

| Parameter | Type      | Default | Description                           |
| --------- | --------- | ------- | ------------------------------------- |
| `error?`  | `unknown` | —       | The error to destroy the stream with. |

ReadableStream [#readablestream]

new ReadableStream(underlyingSource?: UnderlyingSource, queuingStrategy?: CustomQueuingStrategy) [#new-readablestreamunderlyingsource-underlyingsource-queuingstrategy-customqueuingstrategy]

A web readable stream. `underlyingSource` may provide `start`, `pull`, and `cancel` methods, or be an existing `streamx` stream to wrap. `queuingStrategy` defaults to a `CountQueuingStrategy`.

**Parameters**

| Parameter           | Type                    | Default | Description                                                                                    |
| ------------------- | ----------------------- | ------- | ---------------------------------------------------------------------------------------------- |
| `underlyingSource?` | `UnderlyingSource`      | —       | May provide `start`, `pull`, and `cancel` methods, or be an existing `streamx` stream to wrap. |
| `queuingStrategy?`  | `CustomQueuingStrategy` | —       | Defaults to a `CountQueuingStrategy` if omitted.                                               |

ReadableStream.cancel(reason?: unknown): Promise<void> [#readablestreamcancelreason-unknown-promisevoid]

**Parameters**

| Parameter | Type      | Default | Description                                                                                            |
| --------- | --------- | ------- | ------------------------------------------------------------------------------------------------------ |
| `reason?` | `unknown` | —       | Reason for the cancellation, passed to the stream's `destroy()`; defaults to a `TypeError` if omitted. |

getReader(): ReadableStreamDefaultReader [#getreader-readablestreamdefaultreader]

Acquire a `ReadableStreamDefaultReader`. Throws if the stream is already locked.

**Throws**

* `TypeError` — thrown if the stream already has an active reader (`locked` is `true`).

ReadableStream.locked: boolean [#readablestreamlocked-boolean]

pipeTo(destination: WritableStream): Promise<void> [#pipetodestination-writablestream-promisevoid]

Pipe the stream to a `WritableStream`, returning a promise that resolves once piping completes.

**Parameters**

| Parameter     | Type             | Default | Description                        |
| ------------- | ---------------- | ------- | ---------------------------------- |
| `destination` | `WritableStream` | —       | The `WritableStream` to pipe into. |

ReadableStream.from(iterable: unknown | unknown[] | AsyncIterable<unknown>): ReadableStream [#readablestreamfromiterable-unknown--unknown--asynciterableunknown-readablestream]

Create a `ReadableStream` from an iterable or async iterable.

**Parameters**

| Parameter  | Type                                             | Default | Description                                               |
| ---------- | ------------------------------------------------ | ------- | --------------------------------------------------------- |
| `iterable` | `unknown \| unknown[] \| AsyncIterable<unknown>` | —       | A value, array of values, or async iterable to read from. |

tee(): [ReadableStream, ReadableStream] [#tee-readablestream-readablestream]

Split the stream into two independent `ReadableStream` branches.

QueuingStrategy [#queuingstrategy]

new QueuingStrategy(opts?: QueuingStrategyOptions) [#new-queuingstrategyopts-queuingstrategyoptions]

**Parameters**

| Parameter | Type                     | Default | Description |
| --------- | ------------------------ | ------- | ----------- |
| `opts?`   | `QueuingStrategyOptions` | —       | —           |

highWaterMark: number [#highwatermark-number]

size(chunk: unknown): number [#sizechunk-unknown-number]

**Parameters**

| Parameter | Type      | Default | Description           |
| --------- | --------- | ------- | --------------------- |
| `chunk`   | `unknown` | —       | The chunk to measure. |

WritableStreamDefaultWriter [#writablestreamdefaultwriter]

new WritableStreamDefaultWriter(stream: WritableStream) [#new-writablestreamdefaultwriterstream-writablestream]

A writer over a `WritableStream`, exposing `desiredSize`, `closed`, `ready`, `write(chunk)`, `releaseLock()`, `close()`, and `abort([reason])`.

**Parameters**

| Parameter | Type             | Default | Description                       |
| --------- | ---------------- | ------- | --------------------------------- |
| `stream`  | `WritableStream` | —       | The `WritableStream` to write to. |

WritableStreamDefaultWriter.abort(reason?: unknown): Promise<void> [#writablestreamdefaultwriterabortreason-unknown-promisevoid]

**Parameters**

| Parameter | Type      | Default | Description                                                                                     |
| --------- | --------- | ------- | ----------------------------------------------------------------------------------------------- |
| `reason?` | `unknown` | —       | Reason for the abort, passed to the stream's `destroy()`; defaults to a `TypeError` if omitted. |

WritableStreamDefaultWriter.close(): Promise<void> [#writablestreamdefaultwriterclose-promisevoid]

**Returns** `Promise<void>` — Resolves once the stream has finished closing.

WritableStreamDefaultWriter.closed: Promise<void> [#writablestreamdefaultwriterclosed-promisevoid]

WritableStreamDefaultWriter.desiredSize: number [#writablestreamdefaultwriterdesiredsize-number]

ready: Promise<void> [#ready-promisevoid]

WritableStreamDefaultWriter.releaseLock(): void [#writablestreamdefaultwriterreleaselock-void]

write(chunk: unknown): Promise<void> [#writechunk-unknown-promisevoid]

**Parameters**

| Parameter | Type      | Default | Description         |
| --------- | --------- | ------- | ------------------- |
| `chunk`   | `unknown` | —       | The chunk to write. |

**Returns** `Promise<void>` — Resolves once `chunk` has been written and the stream has drained; rejects with the stream's error if the stream is or becomes errored.

WritableStreamDefaultController [#writablestreamdefaultcontroller]

new WritableStreamDefaultController(stream: WritableStream) [#new-writablestreamdefaultcontrollerstream-writablestream]

The controller passed to `start` and `write`, exposing `error([err])`.

**Parameters**

| Parameter | Type             | Default | Description                                  |
| --------- | ---------------- | ------- | -------------------------------------------- |
| `stream`  | `WritableStream` | —       | The `WritableStream` the controller manages. |

error(err?: unknown): void [#errorerr-unknown-void]

**Parameters**

| Parameter | Type      | Default | Description                           |
| --------- | --------- | ------- | ------------------------------------- |
| `err?`    | `unknown` | —       | The error to destroy the stream with. |

WritableStream [#writablestream]

new WritableStream(underlyingSink?: UnderlyingSink, queuingStrategy?: CustomQueuingStrategy) [#new-writablestreamunderlyingsink-underlyingsink-queuingstrategy-customqueuingstrategy]

A web writable stream. `underlyingSink` may provide `start`, `write`, `close`, and `abort` methods, or be an existing `streamx` stream to wrap.

**Parameters**

| Parameter          | Type                    | Default | Description                                                                                             |
| ------------------ | ----------------------- | ------- | ------------------------------------------------------------------------------------------------------- |
| `underlyingSink?`  | `UnderlyingSink`        | —       | May provide `start`, `write`, `close`, and `abort` methods, or be an existing `streamx` stream to wrap. |
| `queuingStrategy?` | `CustomQueuingStrategy` | —       | —                                                                                                       |

WritableStream.abort(reason?: unknown): Promise<void> [#writablestreamabortreason-unknown-promisevoid]

**Parameters**

| Parameter | Type      | Default | Description                                                                                     |
| --------- | --------- | ------- | ----------------------------------------------------------------------------------------------- |
| `reason?` | `unknown` | —       | Reason for the abort, passed to the stream's `destroy()`; defaults to a `TypeError` if omitted. |

WritableStream.close(): Promise<void> [#writablestreamclose-promisevoid]

**Returns** `Promise<void>` — Resolves once the stream has finished closing.

getWriter(): WritableStreamDefaultWriter [#getwriter-writablestreamdefaultwriter]

Acquire a `WritableStreamDefaultWriter`. Throws if the stream is already locked.

**Throws**

* `TypeError` — thrown if the stream already has an active writer (`locked` is `true`).

WritableStream.locked: boolean [#writablestreamlocked-boolean]

TransformStreamDefaultController [#transformstreamdefaultcontroller]

new TransformStreamDefaultController(stream: TransformStream) [#new-transformstreamdefaultcontrollerstream-transformstream]

The controller passed to `start`, `transform`, and `flush`, exposing `desiredSize`, `enqueue(data)`, `error([err])`, and `terminate()`.

**Parameters**

| Parameter | Type              | Default | Description                                   |
| --------- | ----------------- | ------- | --------------------------------------------- |
| `stream`  | `TransformStream` | —       | The `TransformStream` the controller manages. |

TransformStreamDefaultController.desiredSize: number [#transformstreamdefaultcontrollerdesiredsize-number]

TransformStreamDefaultController.enqueue(data: unknown): void [#transformstreamdefaultcontrollerenqueuedata-unknown-void]

**Parameters**

| Parameter | Type      | Default | Description           |
| --------- | --------- | ------- | --------------------- |
| `data`    | `unknown` | —       | The chunk to enqueue. |

TransformStreamDefaultController.error(error?: unknown): void [#transformstreamdefaultcontrollererrorerror-unknown-void]

**Parameters**

| Parameter | Type      | Default | Description                           |
| --------- | --------- | ------- | ------------------------------------- |
| `error?`  | `unknown` | —       | The error to destroy the stream with. |

terminate(): void [#terminate-void]

TransformStream [#transformstream]

TransformStream [#transformstream-1]

```ts
new TransformStream(transformer?: Transformer, writableStrategy?: CustomQueuingStrategy, readableStrategy?: CustomQueuingStrategy)
```

A web transform stream. `transformer` may provide `start`, `transform`, and `flush` methods. Exposes `readable` and `writable` properties.

**Parameters**

| Parameter           | Type                    | Default | Description                                            |
| ------------------- | ----------------------- | ------- | ------------------------------------------------------ |
| `transformer?`      | `Transformer`           | —       | May provide `start`, `transform`, and `flush` methods. |
| `writableStrategy?` | `CustomQueuingStrategy` | —       | —                                                      |
| `readableStrategy?` | `CustomQueuingStrategy` | —       | —                                                      |

readable: ReadableStream [#readable-readablestream]

writable: WritableStream [#writable-writablestream]

Functions [#functions]

isReadableStream(value: unknown): value is ReadableStream [#isreadablestreamvalue-unknown-value-is-readablestream]

**Parameters**

| Parameter | Type      | Default | Description        |
| --------- | --------- | ------- | ------------------ |
| `value`   | `unknown` | —       | The value to test. |

isReadableStreamErrored(stream: ReadableStream): boolean [#isreadablestreamerroredstream-readablestream-boolean]

**Parameters**

| Parameter | Type             | Default | Description         |
| --------- | ---------------- | ------- | ------------------- |
| `stream`  | `ReadableStream` | —       | The stream to test. |

isReadableStreamDisturbed(stream: ReadableStream): boolean [#isreadablestreamdisturbedstream-readablestream-boolean]

**Parameters**

| Parameter | Type             | Default | Description         |
| --------- | ---------------- | ------- | ------------------- |
| `stream`  | `ReadableStream` | —       | The stream to test. |

isWritableStream(value: unknown): value is WritableStream [#iswritablestreamvalue-unknown-value-is-writablestream]

**Parameters**

| Parameter | Type      | Default | Description        |
| --------- | --------- | ------- | ------------------ |
| `value`   | `unknown` | —       | The value to test. |

isTransformStream(value: unknown): value is TransformStream [#istransformstreamvalue-unknown-value-is-transformstream]

Return `true` if `value` is a web `TransformStream`.

**Parameters**

| Parameter | Type      | Default | Description        |
| --------- | --------- | ------- | ------------------ |
| `value`   | `unknown` | —       | The value to test. |

Types [#types-1]

UnderlyingSource [#underlyingsource]

```ts
interface UnderlyingSource<S extends ReadableStream = ReadableStream> {
  start?(this: S, controller: ReadableStreamDefaultController): void
  pull?(this: S, controller: ReadableStreamDefaultController): void
  cancel?(this: S, reason?: unknown): void
}
```

CustomQueuingStrategy [#customqueuingstrategy]

```ts
interface CustomQueuingStrategy {
  highWaterMark?: number
  size?: (chunk: unknown) => number
}
```

QueuingStrategyOptions [#queuingstrategyoptions]

```ts
interface QueuingStrategyOptions {
  highWaterMark?: number
}
```

UnderlyingSink [#underlyingsink]

```ts
interface UnderlyingSink<S extends WritableStream = WritableStream> {
  start?(this: S, controller: WritableStreamDefaultController): void
  write?(this: S, chunk: unknown, controller: WritableStreamDefaultController): void
  close?(this: S): void
  abort?(this: S, reason?: unknown): void
}
```

Transformer [#transformer]

```ts
interface Transformer<S extends TransformStream = TransformStream> {
  start?(this: S, controller: TransformStreamDefaultController): void
  transform?(this: S, chunk: unknown, controller: TransformStreamDefaultController): void
  flush?(this: S, controller: TransformStreamDefaultController): void
}
```

Classes [#classes]

CountQueuingStrategy [#countqueuingstrategy]

```ts
class CountQueuingStrategy {
}
```

ByteLengthQueuingStrategy [#bytelengthqueuingstrategy]

```ts
class ByteLengthQueuingStrategy {
}
```

See also [#see-also]

* It's pure JavaScript and underpins much of the `bare-*` ecosystem—[`bare-fs`](/reference/bare/modules/bare-fs), [`bare-tcp`](/reference/bare/modules/bare-tcp), and others return its streams.
* [Bare modules](/reference/modules/bare-modules) — the full `bare-*` catalog.
* [Bare runtime API](/reference/bare/runtime) — the runtime these modules extend.


# bare-string-decoder



<mark style={{ backgroundColor: '#7dde9a', padding: '2px 8px', borderRadius: '4px', fontSize: '0.85em', fontWeight: 500 }}>
  stable
</mark>

[`bare-string-decoder`](https://github.com/holepunchto/bare-string-decoder) — `string_decoder` shim for Bare.

```sh
npm i bare-string-decoder
```

API [#api]

StringDecoder [#stringdecoder]

new StringDecoder(encoding: BufferEncoding) [#new-stringdecoderencoding-bufferencoding]

Create a `StringDecoder` for the given `encoding`.

**Parameters**

| Parameter  | Type             | Default | Description                                                                                             |
| ---------- | ---------------- | ------- | ------------------------------------------------------------------------------------------------------- |
| `encoding` | `BufferEncoding` | —       | The character encoding the bytes are decoded from (a `BufferEncoding` such as `'utf8'` or `'utf16le'`). |

end(buffer: string | Buffer): string [#endbuffer-string--buffer-string]

Decode any remaining buffered bytes together with `buffer` and return the resulting string, flushing incomplete sequences.

**Parameters**

| Parameter | Type                 | Default | Description                                                                            |
| --------- | -------------------- | ------- | -------------------------------------------------------------------------------------- |
| `buffer`  | `string` \| `Buffer` | —       | A final chunk of bytes to decode together with any bytes buffered from previous calls. |

**Returns** `string` — The decoded string, including any bytes buffered from previous calls.

write(buffer: string | Buffer): string [#writebuffer-string--buffer-string]

Decode `buffer` and return the resulting string, retaining any trailing incomplete multi-byte sequence to be completed by a subsequent call.

**Parameters**

| Parameter | Type                 | Default | Description          |
| --------- | -------------------- | ------- | -------------------- |
| `buffer`  | `string` \| `Buffer` | —       | The bytes to decode. |

**Returns** `string` — The decoded string, excluding any trailing incomplete multi-byte sequence, which is buffered for the next call.

See also [#see-also]

* [Bare modules](/reference/modules/bare-modules) — the full `bare-*` catalog.
* [Bare runtime API](/reference/bare/runtime) — the runtime these modules extend.


# bare-structured-clone



<mark style={{ backgroundColor: '#7dde9a', padding: '2px 8px', borderRadius: '4px', fontSize: '0.85em', fontWeight: 500 }}>
  stable
</mark>

[`bare-structured-clone`](https://github.com/holepunchto/bare-structured-clone) — Structured cloning algorithm for JavaScript. It is a native addon and requires Bare `>=1.2.0`.

```sh
npm i bare-structured-clone
```

Usage [#usage]

```js
const structuredClone = require('bare-structured-clone')

const copy = structuredClone({ hello: 'world' })

const buffer = new ArrayBuffer(4)
const transferred = structuredClone(buffer, { transfer: [buffer] })
```

To install `structuredClone` as a global, require the `global` submodule:

```js
require('bare-structured-clone/global')

const copy = structuredClone({ hello: 'world' })
```

API [#api]

DataCloneError [#datacloneerror]

DataCloneError.DataCloneError.ALREADY_TRANSFERRED(msg: string): DataCloneError [#datacloneerrordatacloneerroralready_transferredmsg-string-datacloneerror]

**Parameters**

| Parameter | Type     | Default | Description        |
| --------- | -------- | ------- | ------------------ |
| `msg`     | `string` | —       | The error message. |

**Returns** `DataCloneError` — A new `DataCloneError` with code `ALREADY_TRANSFERRED`.

DataCloneError.DataCloneError.INVALID_INTERFACE(msg: string): DataCloneError [#datacloneerrordatacloneerrorinvalid_interfacemsg-string-datacloneerror]

**Parameters**

| Parameter | Type     | Default | Description        |
| --------- | -------- | ------- | ------------------ |
| `msg`     | `string` | —       | The error message. |

**Returns** `DataCloneError` — A new `DataCloneError` with code `INVALID_INTERFACE`.

DataCloneError.DataCloneError.INVALID_REFERENCE(msg: string): DataCloneError [#datacloneerrordatacloneerrorinvalid_referencemsg-string-datacloneerror]

**Parameters**

| Parameter | Type     | Default | Description        |
| --------- | -------- | ------- | ------------------ |
| `msg`     | `string` | —       | The error message. |

**Returns** `DataCloneError` — A new `DataCloneError` with code `INVALID_REFERENCE`.

DataCloneError.DataCloneError.INVALID_VERSION(msg: string): DataCloneError [#datacloneerrordatacloneerrorinvalid_versionmsg-string-datacloneerror]

**Parameters**

| Parameter | Type     | Default | Description        |
| --------- | -------- | ------- | ------------------ |
| `msg`     | `string` | —       | The error message. |

**Returns** `DataCloneError` — A new `DataCloneError` with code `INVALID_VERSION`.

DataCloneError.DataCloneError.UNSERIALIZABLE_TYPE(msg: string): DataCloneError [#datacloneerrordatacloneerrorunserializable_typemsg-string-datacloneerror]

**Parameters**

| Parameter | Type     | Default | Description        |
| --------- | -------- | ------- | ------------------ |
| `msg`     | `string` | —       | The error message. |

**Returns** `DataCloneError` — A new `DataCloneError` with code `UNSERIALIZABLE_TYPE`.

DataCloneError.DataCloneError.UNTRANSFERABLE_TYPE(msg: string): DataCloneError [#datacloneerrordatacloneerroruntransferable_typemsg-string-datacloneerror]

**Parameters**

| Parameter | Type     | Default | Description        |
| --------- | -------- | ------- | ------------------ |
| `msg`     | `string` | —       | The error message. |

**Returns** `DataCloneError` — A new `DataCloneError` with code `UNTRANSFERABLE_TYPE`.

Functions [#functions]

structuredClone [#structuredclone]

```ts
structuredClone<T extends SerializableValue | TransferableValue>(value: T, opts?: StructuredCloneOptions): T
```

Clone `value` by serializing and then deserializing it. `opts` may include a `transfer` list and an `interfaces` list.

**Parameters**

| Parameter | Type                                                | Default | Description                                                      |
| --------- | --------------------------------------------------- | ------- | ---------------------------------------------------------------- |
| `value`   | `T`                                                 | —       | The value to clone.                                              |
| `opts?`   | [`StructuredCloneOptions`](#structuredcloneoptions) | —       | Options carrying the optional `transfer` and `interfaces` lists. |

**Returns** `T` — A deep copy of `value`, with any transferred objects detached from the original.

**Throws**

* `UNSERIALIZABLE_TYPE` — `value`, or a value it references, is of a type that cannot be serialized (for example a function, a symbol, or a detached `ArrayBuffer`).
* `UNTRANSFERABLE_TYPE` — a value in the `transfer` list cannot be transferred.
* `ALREADY_TRANSFERRED` — a value in the `transfer` list has already been transferred.
* `INVALID_INTERFACE` — a serializable or transferable value has an interface that is not present in the `interfaces` list.

structuredClone.deserialize [#structuredclonedeserialize]

```ts
structuredClone.deserialize<T extends SerializableValue>(serialized: SerializedValue, interfaces?: (SerializableConstructor | TransferableConstructor)[]): T
```

**Parameters**

| Parameter     | Type                                                     | Default | Description                                                                                         |
| ------------- | -------------------------------------------------------- | ------- | --------------------------------------------------------------------------------------------------- |
| `serialized`  | `SerializedValue`                                        | —       | A value previously produced by `serialize`.                                                         |
| `interfaces?` | `(SerializableConstructor \| TransferableConstructor)[]` | —       | Serializable and transferable constructors to recognize when deserializing custom platform objects. |

**Returns** `T` — The value reconstructed from `serialized`.

structuredClone.deserializeWithTransfer [#structuredclonedeserializewithtransfer]

```ts
structuredClone.deserializeWithTransfer<T extends SerializableValue | TransferableValue>(serialized: SerializedTransfer, interfaces?: (SerializableConstructor | TransferableConstructor)[]): T
```

**Parameters**

| Parameter     | Type                                                     | Default | Description                                                                                         |
| ------------- | -------------------------------------------------------- | ------- | --------------------------------------------------------------------------------------------------- |
| `serialized`  | [`SerializedTransfer`](#serializedtransfer)              | —       | A value previously produced by `serializeWithTransfer`.                                             |
| `interfaces?` | `(SerializableConstructor \| TransferableConstructor)[]` | —       | Serializable and transferable constructors to recognize when deserializing custom platform objects. |

**Returns** `T` — The value reconstructed from `serialized`, with its transferred objects re-attached.

structuredClone.serialize [#structuredcloneserialize]

```ts
structuredClone.serialize(value: SerializableValue, forStorage?: boolean, interfaces?: (SerializableConstructor | TransferableConstructor)[]): SerializedValue
```

**Parameters**

| Parameter     | Type                                                     | Default | Description                                                                                       |
| ------------- | -------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------- |
| `value`       | `SerializableValue`                                      | —       | The value to serialize.                                                                           |
| `forStorage?` | `boolean`                                                | —       | Whether the serialized form will be persisted rather than sent across a boundary immediately.     |
| `interfaces?` | `(SerializableConstructor \| TransferableConstructor)[]` | —       | Serializable and transferable constructors to recognize when serializing custom platform objects. |

**Returns** `SerializedValue` — A serialized representation of `value`.

structuredClone.serializeWithTransfer [#structuredcloneserializewithtransfer]

```ts
structuredClone.serializeWithTransfer(value: SerializableValue | TransferableValue, transferList?: TransferableValue[], interfaces?: (SerializableConstructor | TransferableConstructor)[]): SerializedTransfer
```

**Parameters**

| Parameter       | Type                                                     | Default | Description                                                                                                 |
| --------------- | -------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------- |
| `value`         | `SerializableValue` \| `TransferableValue`               | —       | The value to serialize.                                                                                     |
| `transferList?` | `TransferableValue[]`                                    | —       | Transferable objects to include in the transfer list; each is detached from the original after serializing. |
| `interfaces?`   | `(SerializableConstructor \| TransferableConstructor)[]` | —       | Serializable and transferable constructors to recognize when serializing custom platform objects.           |

**Returns** [`SerializedTransfer`](#serializedtransfer) — A serialized representation of `value`, plus its transfer list.

Constants and variables [#constants-and-variables]

structuredClone.constants [#structuredcloneconstants]

```ts
structuredClone.constants: {
  VERSION: number

  type: {
    // Primitive types
    UNDEFINED: 0
    NULL: 1
    TRUE: 2
    FALSE: 3
    NUMBER: 4
    BIGINT: 5
    STRING: 6

    // Builtin objects
    DATE: 7
    REGEXP: 8
    ERROR: 9

    // Builtin binary data objects
    ARRAYBUFFER: 10
    RESIZABLEARRAYBUFFER: 11
    SHAREDARRAYBUFFER: 12
    GROWABLESHAREDARRAYBUFFER: 13
    TYPEDARRAY: 14
    DATAVIEW: 15

    // Builtin composite objects
    MAP: 16
    SET: 17
    ARRAY: 18
    OBJECT: 19

    // Object references
    REFERENCE: 20

    // Object transfers
    TRANSFER: 21

    // Platform objects
    URL: 22
    BUFFER: 23
    EXTERNAL: 24
    SERIALIZABLE: 25
    TRANSFERABLE: 26

    typedarray: {
      UINT8ARRAY: 1
      UINT8CLAMPEDARRAY: 2
      INT8ARRAY: 3
      UINT16ARRAY: 4
      INT16ARRAY: 5
      UINT32ARRAY: 6
      INT32ARRAY: 7
      BIGUINT64ARRAY: 8
      BIGINT64ARRAY: 9
      FLOAT16ARRAY: 12
      FLOAT32ARRAY: 10
      FLOAT64ARRAY: 11
    }

    error: {
      AGGREGATE: 1
      EVAL: 2
      RANGE: 3
      REFERENCE: 4
      SYNTAX: 5
      TYPE: 6
      URI: 7
    }
  }
}
```

Numeric tags used in serialized values. Also available as `require('bare-structured-clone/constants')`.

structuredClone.symbols [#structuredclonesymbols]

```ts
structuredClone.symbols: {
  readonly serialize: unique symbol
  readonly deserialize: unique symbol
  readonly detach: unique symbol
  readonly attach: unique symbol
  readonly interface: unique symbol
}
```

Types [#types]

structuredClone.SerializableValue [#structuredcloneserializablevalue]

```ts
type SerializableValue = | undefined
  | null
  | boolean
  | number
  | bigint
  | string
  | Date
  | RegExp
  | Error
  | ArrayBuffer
  | SharedArrayBuffer
  | Uint8Array
  | Uint8ClampedArray
  | Int8Array
  | Uint16Array
  | Int16Array
  | Uint32Array
  | Int32Array
  | BigUint64Array
  | BigInt64Array
  | Float16Array
  | Float32Array
  | Float64Array
  | DataView
  | Map<SerializableValue, SerializableValue>
  | Set<SerializableValue>
  | SerializableValue[]
  | { [key: string | number]: SerializableValue }
  | URL
  | Buffer
  | Serializable
```

structuredClone.TransferableValue [#structuredclonetransferablevalue]

```ts
type TransferableValue = ArrayBuffer | Transferable
```

StructuredCloneOptions [#structuredcloneoptions]

```ts
interface StructuredCloneOptions {
  transfer: TransferableValue[]
  interfaces: (SerializableConstructor | TransferableConstructor)[]
}
```

SerializableConstructor [#serializableconstructor]

```ts
interface SerializableConstructor<T = unknown> {
}
```

TransferableConstructor [#transferableconstructor]

```ts
interface TransferableConstructor<T = unknown> {
}
```

SerializedTransfer [#serializedtransfer]

```ts
interface SerializedTransfer {
  type: typeof constants.type.TRANSFER
  transfers: (
    | SerializedArrayBufferTransfer
    | SerializedResizableArrayBufferTransfer
    | SerializedTransferableTransfer
  )[]
  value: SerializedValue
}
```

SerializedArrayBufferTransfer [#serializedarraybuffertransfer]

```ts
interface SerializedArrayBufferTransfer {
  type: typeof constants.type.ARRAYBUFFER
  id: number
  backingStore: ArrayBuffer
}
```

SerializedResizableArrayBufferTransfer [#serializedresizablearraybuffertransfer]

```ts
interface SerializedResizableArrayBufferTransfer {
  type: typeof constants.type.RESIZABLEARRAYBUFFER
  id: number
  backingStore: ArrayBuffer
  maxByteLength: number
}
```

SerializedTransferableTransfer [#serializedtransferabletransfer]

```ts
interface SerializedTransferableTransfer {
  type: typeof constants.type.TRANSFERABLE
  id: number
  interface: number
  value: SerializedValue
}
```

Classes [#classes]

Serializable [#serializable]

```ts
class Serializable {
}
```

Base class for a custom serializable type. A subclass implements `[symbols.serialize](forStorage)`, returning the `SerializableValue` to serialize, and a static `[symbols.deserialize](serialized)`, returning a new instance reconstructed from it. The subclass's constructor must be registered via the `interfaces` option on both ends of the clone.

Transferable [#transferable]

```ts
class Transferable {
  detached: boolean
}
```

Base class for a custom transferable type. A subclass implements `[symbols.detach]()`, releasing ownership and returning the `SerializableValue` to serialize, and a static `[symbols.attach](serialized)`, returning a new instance that takes ownership of `serialized`. The base `[symbols.detach]()` implementation sets `detached` to `true`; a subclass should call `super[symbols.detach]()` after releasing its own state. The subclass's constructor must be registered via the `interfaces` option on both ends of the clone.

bare-structured-clone/constants [#bare-structured-cloneconstants]

Constants and variables [#constants-and-variables-1]

constants [#constants]

```ts
constants: {
  VERSION: number

  type: {
    // Primitive types
    UNDEFINED: 0
    NULL: 1
    TRUE: 2
    FALSE: 3
    NUMBER: 4
    BIGINT: 5
    STRING: 6

    // Builtin objects
    DATE: 7
    REGEXP: 8
    ERROR: 9

    // Builtin binary data objects
    ARRAYBUFFER: 10
    RESIZABLEARRAYBUFFER: 11
    SHAREDARRAYBUFFER: 12
    GROWABLESHAREDARRAYBUFFER: 13
    TYPEDARRAY: 14
    DATAVIEW: 15

    // Builtin composite objects
    MAP: 16
    SET: 17
    ARRAY: 18
    OBJECT: 19

    // Object references
    REFERENCE: 20

    // Object transfers
    TRANSFER: 21

    // Platform objects
    URL: 22
    BUFFER: 23
    EXTERNAL: 24
    SERIALIZABLE: 25
    TRANSFERABLE: 26

    typedarray: {
      UINT8ARRAY: 1
      UINT8CLAMPEDARRAY: 2
      INT8ARRAY: 3
      UINT16ARRAY: 4
      INT16ARRAY: 5
      UINT32ARRAY: 6
      INT32ARRAY: 7
      BIGUINT64ARRAY: 8
      BIGINT64ARRAY: 9
      FLOAT16ARRAY: 12
      FLOAT32ARRAY: 10
      FLOAT64ARRAY: 11
    }

    error: {
      AGGREGATE: 1
      EVAL: 2
      RANGE: 3
      REFERENCE: 4
      SYNTAX: 5
      TYPE: 6
      URI: 7
    }
  }
}
```

Numeric tags used in serialized values. Also available as `require('bare-structured-clone/constants')`.

bare-structured-clone/errors [#bare-structured-cloneerrors]

DataCloneError [#datacloneerror-1]

DataCloneError.DataCloneError.ALREADY_TRANSFERRED(msg: string): DataCloneError [#datacloneerrordatacloneerroralready_transferredmsg-string-datacloneerror-1]

**Parameters**

| Parameter | Type     | Default | Description        |
| --------- | -------- | ------- | ------------------ |
| `msg`     | `string` | —       | The error message. |

**Returns** `DataCloneError` — A new `DataCloneError` with code `ALREADY_TRANSFERRED`.

DataCloneError.DataCloneError.INVALID_INTERFACE(msg: string): DataCloneError [#datacloneerrordatacloneerrorinvalid_interfacemsg-string-datacloneerror-1]

**Parameters**

| Parameter | Type     | Default | Description        |
| --------- | -------- | ------- | ------------------ |
| `msg`     | `string` | —       | The error message. |

**Returns** `DataCloneError` — A new `DataCloneError` with code `INVALID_INTERFACE`.

DataCloneError.DataCloneError.INVALID_REFERENCE(msg: string): DataCloneError [#datacloneerrordatacloneerrorinvalid_referencemsg-string-datacloneerror-1]

**Parameters**

| Parameter | Type     | Default | Description        |
| --------- | -------- | ------- | ------------------ |
| `msg`     | `string` | —       | The error message. |

**Returns** `DataCloneError` — A new `DataCloneError` with code `INVALID_REFERENCE`.

DataCloneError.DataCloneError.INVALID_VERSION(msg: string): DataCloneError [#datacloneerrordatacloneerrorinvalid_versionmsg-string-datacloneerror-1]

**Parameters**

| Parameter | Type     | Default | Description        |
| --------- | -------- | ------- | ------------------ |
| `msg`     | `string` | —       | The error message. |

**Returns** `DataCloneError` — A new `DataCloneError` with code `INVALID_VERSION`.

DataCloneError.DataCloneError.UNSERIALIZABLE_TYPE(msg: string): DataCloneError [#datacloneerrordatacloneerrorunserializable_typemsg-string-datacloneerror-1]

**Parameters**

| Parameter | Type     | Default | Description        |
| --------- | -------- | ------- | ------------------ |
| `msg`     | `string` | —       | The error message. |

**Returns** `DataCloneError` — A new `DataCloneError` with code `UNSERIALIZABLE_TYPE`.

DataCloneError.DataCloneError.UNTRANSFERABLE_TYPE(msg: string): DataCloneError [#datacloneerrordatacloneerroruntransferable_typemsg-string-datacloneerror-1]

**Parameters**

| Parameter | Type     | Default | Description        |
| --------- | -------- | ------- | ------------------ |
| `msg`     | `string` | —       | The error message. |

**Returns** `DataCloneError` — A new `DataCloneError` with code `UNTRANSFERABLE_TYPE`.

See also [#see-also]

* Builds on `bare-buffer`, `bare-type`, and `bare-url`.
* [`bare-channel`](/reference/bare/modules/bare-channel) and [`bare-broadcast-channel`](/reference/bare/modules/bare-broadcast-channel) — inter-thread messaging built on this.
* [Bare modules](/reference/modules/bare-modules) — the full `bare-*` catalog.
* [Bare runtime API](/reference/bare/runtime) — the runtime these modules extend.


# bare-subprocess



<mark style={{ backgroundColor: '#7dde9a', padding: '2px 8px', borderRadius: '4px', fontSize: '0.85em', fontWeight: 500 }}>
  stable
</mark>

[`bare-subprocess`](https://github.com/holepunchto/bare-subprocess) — Native process spawning for JavaScript. It is a native addon and requires Bare `>=1.7.0`.

```sh
npm i bare-subprocess
```

Usage [#usage]

```js
const { spawn } = require('bare-subprocess')

const subprocess = spawn('echo', ['hello', 'world'], {
  stdio: 'inherit'
})

subprocess.on('exit', () => console.log('done'))
```

API [#api]

Subprocess [#subprocess]

channel: SubprocessChannel [#channel-subprocesschannel]

The `SubprocessChannel` instance backing the IPC channel, or `undefined` when no channel exists. For `serialization: 'binary'`, this is always `undefined`.

Subprocess.connected: boolean [#subprocessconnected-boolean]

`true` while an IPC channel exists between parent and child.

Subprocess.disconnect(): void [#subprocessdisconnect-void]

Close the IPC channel. A `'disconnect'` event is emitted once the channel is fully closed.

exitCode: number | null [#exitcode-number--null]

The exit code of the child, or `null` if the child has not exited or was terminated by a signal.

kill(signum?: number): void [#killsignum-number-void]

Send a signal to the child. `signum` may be a signal number or a name (for example `'SIGTERM'`). Defaults to `SIGTERM`.

**Parameters**

| Parameter | Type     | Default | Description                                                                                  |
| --------- | -------- | ------- | -------------------------------------------------------------------------------------------- |
| `signum?` | `number` | —       | Signal to send, as a signal number or name (for example `'SIGTERM'`); defaults to `SIGTERM`. |

**Throws**

* `UNKNOWN_SIGNAL` — thrown if `signum` is a string that isn't a recognized signal name.

killed: boolean [#killed-boolean]

`true` if `subprocess.kill()` has been called, otherwise `false`.

pid: number [#pid-number]

The process ID of the child.

ref(): void [#ref-void]

Reference the subprocess and its stdio pipes against the event loop.

Subprocess.send(message: unknown, handle?: unknown, cb?: (err: Error | null) => void): boolean [#subprocesssendmessage-unknown-handle-unknown-cb-err-error--null--void-boolean]

Send `message` to the child over the IPC channel. `handle` may be a `bare-pipe` `Pipe` or a `bare-tcp` `Socket` to transfer ownership of along with the message. `callback` is invoked with `(err)` after the message has been written.

Overloads:

```ts
send(message: unknown, handle?: unknown, cb?: (err: Error | null) => void): boolean
send(message: unknown, cb: (err: Error | null) => void): boolean
```

**Parameters**

| Parameter | Type                           | Default | Description                                                                                                 |
| --------- | ------------------------------ | ------- | ----------------------------------------------------------------------------------------------------------- |
| `message` | `unknown`                      | —       | The value to send to the child over the IPC channel.                                                        |
| `handle?` | `unknown`                      | —       | A `bare-pipe` `Pipe` or `bare-tcp` `Socket` to transfer to the child along with `message`.                  |
| `cb?`     | `(err: Error \| null) => void` | —       | Called with `(err)` once `message` has been written, or with an error if there is no connected IPC channel. |

**Returns** `boolean` — `false` if the subprocess has no IPC channel or it has disconnected (`cb`, if given, is then invoked asynchronously with an error); otherwise the underlying pipe write result.

signalCode: string | null [#signalcode-string--null]

The name of the signal the child was terminated with, or `null`.

spawnargs: string[] [#spawnargs-string]

The arguments the child was spawned with.

spawnfile: string [#spawnfile-string]

The file that was spawned.

stderr: Pipe | null [#stderr-pipe--null]

Convenience accessor for `subprocess.stdio[2]`.

stdin: Pipe | null [#stdin-pipe--null]

Convenience accessor for `subprocess.stdio[0]`.

stdio: (Pipe | null)[] [#stdio-pipe--null]

An array of `bare-pipe` instances corresponding to the configured stdio slots. Slots configured as `'inherit'`, `'ignore'`, or backed by an inherited fd are `null`.

stdout: Pipe | null [#stdout-pipe--null]

Convenience accessor for `subprocess.stdio[1]`.

unref(): void [#unref-void]

Unreference the subprocess and its stdio pipes against the event loop.

Functions [#functions]

spawn(file: string, args?: string[] | null, opts?: SpawnOptions): Subprocess [#spawnfile-string-args-string--null-opts-spawnoptions-subprocess]

Spawn `file` as a new subprocess with the given `args`. Returns a `Subprocess` instance. `args` may be `null` or omitted to spawn with no arguments. If `args` is omitted, the second argument is treated as `options`.

Overloads:

```ts
spawn(file: string, args?: string[] | null, opts?: SpawnOptions): Subprocess
spawn(file: string, opts?: SpawnOptions): Subprocess
```

Synchronous form: `spawnSync(file: string, args?: string[] | null, opts?: SpawnSyncOptions): SpawnSyncResult`

**Parameters**

| Parameter | Type                            | Default | Description                                                                                                                     |
| --------- | ------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `file`    | `string`                        | —       | The executable to spawn; a string path or a `file://` URL.                                                                      |
| `args?`   | `string[]` \| `null`            | —       | Arguments to pass to `file`; may be `null` or omitted to spawn with none. If omitted, the second argument is treated as `opts`. |
| `opts?`   | [`SpawnOptions`](#spawnoptions) | —       | Options controlling the environment, stdio, and behavior of the new subprocess; see `SpawnOptions`.                             |

**Throws**

* `UNKNOWN_SERIALIZATION_MODE` — thrown if `opts.serialization` is not `'json'`, `'advanced'`, or `'binary'`.
* `IPC_CHANNEL_ALREADY_DEFINED` — thrown if `opts.stdio` requests more than one `'ipc'` slot.

Constants and variables [#constants-and-variables]

constants: Record<string, number> [#constants-recordstring-number]

Types [#types]

SubprocessChannel [#subprocesschannel]

```ts
interface SubprocessChannel {
  readonly connected: boolean
  send(message: unknown, handle?: unknown, cb?: (err: Error | null) => void): boolean
  disconnect(): void
  ref(): this
  unref(): this
}
```

SubprocessEvents [#subprocessevents]

```ts
interface SubprocessEvents {
  exit: [code: number | null, signalCode: string | null]
  message: [message: unknown, handle: unknown]
  disconnect: []
  error: [err: Error]
}
```

IO [#io]

```ts
type IO = 'inherit' | 'pipe' | 'overlapped' | 'ignore' | 'ipc'
```

SerializationMode [#serializationmode]

```ts
type SerializationMode = 'json' | 'advanced' | 'binary'
```

SpawnOptions [#spawnoptions]

```ts
interface SpawnOptions {
  cwd?: string
  stdio?: [stdin?: IO, stdout?: IO, stderr?: IO, ...fds: IO[]] | IO | null
  shell?: boolean | string
  detached?: boolean
  uid?: number
  gid?: number
  env?: Record<string, string>
  windowsHide?: boolean
  windowsVerbatimArguments?: boolean
  serialization?: SerializationMode
}
```

SpawnSyncOptions [#spawnsyncoptions]

```ts
interface SpawnSyncOptions {
  input?: string | Buffer
  maxBuffer?: number
  cwd?: string
  stdio?: [stdin?: IO, stdout?: IO, stderr?: IO, ...fds: IO[]] | IO | null
  shell?: boolean | string
  detached?: boolean
  uid?: number
  gid?: number
  env?: Record<string, string>
  windowsHide?: boolean
  windowsVerbatimArguments?: boolean
  serialization?: SerializationMode
}
```

SpawnSyncResult [#spawnsyncresult]

```ts
interface SpawnSyncResult {
  output: (Buffer | null)[] | null
  pid: number
  signal: number
  status: number
  stdout: Buffer | null
  stderr: Buffer | null
  error?: Error
}
```

Classes [#classes]

errors [#errors]

```ts
class errors {
  code: string
}
```

bare-subprocess/constants [#bare-subprocessconstants]

Constants and variables [#constants-and-variables-1]

signals: Record<string, number> [#signals-recordstring-number]

bare-subprocess/errors [#bare-subprocesserrors]

Classes [#classes-1]

SubprocessError [#subprocesserror]

```ts
class SubprocessError {
  code: string
}
```

bare-subprocess/parent [#bare-subprocessparent]

SubprocessParentChannel [#subprocessparentchannel]

new SubprocessParentChannel() [#new-subprocessparentchannel]

**Throws**

* `NO_IPC_CHANNEL` — thrown if the `BARE_CHANNEL_FD` environment variable is not set.
* `UNKNOWN_SERIALIZATION_MODE` — thrown if `BARE_CHANNEL_SERIALIZATION_MODE` is set to something other than `'json'` or `'advanced'`.

SubprocessParentChannel.connected: boolean [#subprocessparentchannelconnected-boolean]

`true` while an IPC channel exists between parent and child.

SubprocessParentChannel.disconnect(): void [#subprocessparentchanneldisconnect-void]

Close the IPC channel. A `'disconnect'` event is emitted once the channel is fully closed.

ref(): this [#ref-this]

Reference the subprocess and its stdio pipes against the event loop.

SubprocessParentChannel.send(message: unknown, handle?: unknown, cb?: (err: Error | null) => void): boolean [#subprocessparentchannelsendmessage-unknown-handle-unknown-cb-err-error--null--void-boolean]

Send `message` to the child over the IPC channel. `handle` may be a `bare-pipe` `Pipe` or a `bare-tcp` `Socket` to transfer ownership of along with the message. `callback` is invoked with `(err)` after the message has been written.

Overloads:

```ts
send(message: unknown, handle?: unknown, cb?: (err: Error | null) => void): boolean
send(message: unknown, cb: (err: Error | null) => void): boolean
```

**Parameters**

| Parameter | Type                           | Default | Description                                                                                           |
| --------- | ------------------------------ | ------- | ----------------------------------------------------------------------------------------------------- |
| `message` | `unknown`                      | —       | The value to send to the parent process over the IPC channel.                                         |
| `handle?` | `unknown`                      | —       | A `bare-pipe` `Pipe` or `bare-tcp` `Socket` to transfer to the parent along with `message`.           |
| `cb?`     | `(err: Error \| null) => void` | —       | Called with `(err)` once `message` has been written, or with an error if the channel is disconnected. |

**Returns** `boolean` — `false` if the channel is disconnected (`cb`, if given, is then invoked asynchronously with a `CHANNEL_DISCONNECTED` error); otherwise the underlying pipe write result.

unref(): this [#unref-this]

Unreference the subprocess and its stdio pipes against the event loop.

Types [#types-1]

SubprocessParentChannelEvents [#subprocessparentchannelevents]

```ts
interface SubprocessParentChannelEvents {
  message: [message: unknown, handle: unknown]
  disconnect: []
  error: [err: Error]
}
```

See also [#see-also]

* Builds on `bare-env`, `bare-events`, `bare-os`, `bare-pipe`, `bare-structured-clone`, `bare-tcp`, and `bare-url`.
* It's a native addon and requires Bare `>=1.7.0`; it's available on desktop (Windows, macOS, Linux).
* [Bare modules](/reference/modules/bare-modules) — the full `bare-*` catalog.
* [Bare runtime API](/reference/bare/runtime) — the runtime these modules extend.


# bare-system-logger



<mark style={{ backgroundColor: '#7dde9a', padding: '2px 8px', borderRadius: '4px', fontSize: '0.85em', fontWeight: 500 }}>
  stable
</mark>

[`bare-system-logger`](https://github.com/holepunchto/bare-system-logger) — System logger for Bare. It is a native addon.

```sh
npm i bare-system-logger
```

Usage [#usage]

```js
const SystemLog = require('bare-system-logger')

const log = new SystemLog()

log.info('Hello %s', 'world!')
```

API [#api]

Classes [#classes]

SystemLog [#systemlog]

```ts
class SystemLog {
}
```

A logger that writes formatted messages to the native OS system log, at `debug`, `info`, `warn`, `error`, and `fatal` severity levels.

See also [#see-also]

* Builds on `bare-logger`.
* [Bare modules](/reference/modules/bare-modules) — the full `bare-*` catalog.
* [Bare runtime API](/reference/bare/runtime) — the runtime these modules extend.


# bare-tcp



<mark style={{ backgroundColor: '#7dde9a', padding: '2px 8px', borderRadius: '4px', fontSize: '0.85em', fontWeight: 500 }}>
  stable
</mark>

[`bare-tcp`](https://github.com/holepunchto/bare-tcp) — Native TCP sockets for JavaScript. It is a native addon and requires Bare `>=1.16.0`.

Mirrors the Node.js [`net`](https://nodejs.org/api/net.html) module.

```sh
npm i bare-tcp
```

Usage [#usage]

```js
const tcp = require('bare-tcp')

const server = tcp.createServer()
server.on('connection', (socket) => socket.on('data', console.log))
server.listen(() => console.log('server is up'))

const { port } = server.address()
const socket = tcp.createConnection(port)
socket.write('hello world')
```

API [#api]

TCPSocket [#tcpsocket]

new TCPSocket(opts?: TCPSocketOptions) [#new-tcpsocketopts-tcpsocketoptions]

Create a new TCP socket.

**Parameters**

| Parameter | Type                                    | Default | Description                                                                                   |
| --------- | --------------------------------------- | ------- | --------------------------------------------------------------------------------------------- |
| `opts?`   | [`TCPSocketOptions`](#tcpsocketoptions) | —       | Options; `readBufferSize` defaults to `65536`, and `allowHalfOpen` and `eagerOpen` to `true`. |

connect [#connect]

```ts
connect(port: number, host?: string, opts?: TCPSocketConnectOptions, onconnect?: () => void): this
```

Connect the socket to `port` on `host`. If `host` is not provided, it defaults to `'localhost'`. `onconnect` is called when the connection is established.

**Parameters**

| Parameter    | Type                                                  | Default | Description                                                                                                                    |
| ------------ | ----------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `port`       | `number`                                              | —       | The port to connect to.                                                                                                        |
| `host?`      | `string`                                              | —       | The host to connect to; defaults to `'localhost'`.                                                                             |
| `opts?`      | [`TCPSocketConnectOptions`](#tcpsocketconnectoptions) | —       | Connection options; if `host` is a hostname it is resolved with `opts.lookup`, which defaults to `dns.lookup` from `bare-dns`. |
| `onconnect?` | `() => void`                                          | —       | Called when the connection is established.                                                                                     |

**Throws**

* `SOCKET_ALREADY_CONNECTED` — the socket is already connecting or connected.
* `INVALID_PORT` — `port` is not an integer between 0 and 65535.

connecting: boolean [#connecting-boolean]

Whether the socket is currently connecting.

localAddress: string [#localaddress-string]

The local IP address of the socket, if connected.

localFamily: string [#localfamily-string]

The local IP family (`'IPv4'` or `'IPv6'`), if connected.

localPort: number [#localport-number]

The local port of the socket, if connected.

open(fd: number, opts?: { fd?: number }, onconnect?: () => void): this [#openfd-number-opts--fd-number--onconnect---void-this]

Open the socket on the file descriptor of an existing TCP connection, emitting `'connect'` once open.

Overloads:

```ts
open(fd: number, opts?: { fd?: number }, onconnect?: () => void): this
open(fd: number, onconnect: () => void): this
open(opts: { fd: number }, onconnect?: () => void): this
```

**Parameters**

| Parameter    | Type              | Default | Description                                                              |
| ------------ | ----------------- | ------- | ------------------------------------------------------------------------ |
| `fd`         | `number`          | —       | The file descriptor of an existing TCP connection to open the socket on. |
| `opts?`      | `{ fd?: number }` | —       | `fd` may be given here instead of as the first argument.                 |
| `onconnect?` | `() => void`      | —       | Called once when the socket emits `'connect'`.                           |

pending: boolean [#pending-boolean]

Whether the socket has not yet connected.

readyState: 'open' | 'opening' [#readystate-open--opening]

The current state of the socket. Either `'open'` or `'opening'`.

TCPSocket.ref(): this [#tcpsocketref-this]

Ref the socket, preventing the process from exiting.

remoteAddress: string [#remoteaddress-string]

The remote IP address of the socket, if connected.

remoteFamily: string [#remotefamily-string]

The remote IP family (`'IPv4'` or `'IPv6'`), if connected.

remotePort: number [#remoteport-number]

The remote port of the socket, if connected.

setKeepAlive(enable?: boolean, delay?: number): this [#setkeepaliveenable-boolean-delay-number-this]

Enable or disable keep-alive. `delay` is the initial delay in milliseconds before the first keep-alive probe is sent.

Overloads:

```ts
setKeepAlive(enable?: boolean, delay?: number): this
setKeepAlive(delay: number): this
```

**Parameters**

| Parameter | Type      | Default | Description                                                                  |
| --------- | --------- | ------- | ---------------------------------------------------------------------------- |
| `enable?` | `boolean` | —       | Whether to enable keep-alive.                                                |
| `delay?`  | `number`  | —       | The initial delay in milliseconds before the first keep-alive probe is sent. |

setNoDelay(enable?: boolean): this [#setnodelayenable-boolean-this]

Enable or disable Nagle's algorithm. When `enable` is `true` (the default), data is sent immediately without buffering.

**Parameters**

| Parameter | Type      | Default | Description                                                            |
| --------- | --------- | ------- | ---------------------------------------------------------------------- |
| `enable?` | `boolean` | —       | When `true` (the default), data is sent immediately without buffering. |

setTimeout(ms: number, ontimeout?: () => void): this [#settimeoutms-number-ontimeout---void-this]

Set a timeout in milliseconds. When the socket is idle for `ms` milliseconds, a `timeout` event is emitted. Pass `0` to disable the timeout.

**Parameters**

| Parameter    | Type         | Default | Description                                                              |
| ------------ | ------------ | ------- | ------------------------------------------------------------------------ |
| `ms`         | `number`     | —       | The inactivity timeout in milliseconds; pass `0` to disable the timeout. |
| `ontimeout?` | `() => void` | —       | Called once when the socket emits `'timeout'`.                           |

timeout: number [#timeout-number]

The timeout in milliseconds, or `undefined` if no timeout is set.

TCPSocket.unref(): this [#tcpsocketunref-this]

Unref the socket, allowing the process to exit.

TCPServer [#tcpserver]

new TCPServer(opts?: TCPServerOptions, onconnection?: () => void) [#new-tcpserveropts-tcpserveroptions-onconnection---void]

Create a new TCP server. If `onconnection` is provided, it is added as a listener for the `connection` event.

Overloads:

```ts
new TCPServer(opts?: TCPServerOptions, onconnection?: () => void)
new TCPServer(onconnection: () => void)
```

**Parameters**

| Parameter       | Type                                    | Default | Description                                                                                                                                                            |
| --------------- | --------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `opts?`         | [`TCPServerOptions`](#tcpserveroptions) | —       | Options applied to each incoming socket; `readBufferSize` defaults to `65536`, `allowHalfOpen` to `true`, and `keepAlive`, `noDelay`, and `pauseOnConnect` to `false`. |
| `onconnection?` | `() => void`                            | —       | Called on each `'connection'` event.                                                                                                                                   |

address(): TCPSocketAddress [#address-tcpsocketaddress]

**Returns** [`TCPSocketAddress`](#tcpsocketaddress) — The bound address as `{ address, family, port }`, or `null` if the server is not listening.

close(onclose?: (err?: Error) => void): this [#closeonclose-err-error--void-this]

Close the server. No new connections will be accepted. The server emits `close` after all existing connections have ended.

**Parameters**

| Parameter  | Type                    | Default | Description                                                                             |
| ---------- | ----------------------- | ------- | --------------------------------------------------------------------------------------- |
| `onclose?` | `(err?: Error) => void` | —       | Called once when the server emits `'close'`, after all existing connections have ended. |

closing: boolean [#closing-boolean]

Whether the server is closing.

connections: Set<TCPSocket> [#connections-settcpsocket]

A `Set` of active connections.

listen [#listen]

```ts
listen(port?: number, host?: string, backlog?: number, opts?: TCPServerListenOptions, onlistening?: () => void): this
```

Start listening for connections on `port` and `host`. If `port` is `0`, an available port is assigned. If `host` is not provided, it defaults to `'localhost'`. `backlog` defaults to `511`.

**Parameters**

| Parameter      | Type                                                | Default | Description                                                                                                                                    |
| -------------- | --------------------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `port?`        | `number`                                            | —       | The port to listen on; if `0` (the default), an available port is assigned.                                                                    |
| `host?`        | `string`                                            | —       | The host to listen on; defaults to `'localhost'`.                                                                                              |
| `backlog?`     | `number`                                            | —       | The maximum length of the queue of pending connections (default `511`).                                                                        |
| `opts?`        | [`TCPServerListenOptions`](#tcpserverlistenoptions) | —       | Listen options; the positional arguments may be given here instead, and `lookup` (default `dns.lookup`) resolves `host` when it is a hostname. |
| `onlistening?` | `() => void`                                        | —       | Called once when the server emits `'listening'`.                                                                                               |

**Throws**

* `SERVER_ALREADY_LISTENING` — the server is already listening.
* `SERVER_IS_CLOSED` — the server has been closed.
* `INVALID_PORT` — `port` is not an integer between 0 and 65535.

listening: boolean [#listening-boolean]

Whether the server is listening.

maxConnections: number [#maxconnections-number]

The maximum number of concurrent connections; connections beyond it are destroyed and reported via the `'drop'` event. Defaults to `Infinity`.

TCPServer.ref(): this [#tcpserverref-this]

Ref the server, preventing the process from exiting.

TCPServer.unref(): this [#tcpserverunref-this]

Unref the server, allowing the process to exit.

Functions [#functions]

createConnection [#createconnection]

```ts
createConnection(port: number, host?: string, opts?: TCPSocketOptions & TCPSocketConnectOptions, onconnect?: () => void): TCPSocket
```

Create a new socket and connect it to `port` on `host`. Shorthand for `new tcp.Socket(options).connect(port, host, options, onconnect)`.

**Parameters**

| Parameter    | Type                                         | Default | Description                                                         |
| ------------ | -------------------------------------------- | ------- | ------------------------------------------------------------------- |
| `port`       | `number`                                     | —       | The port to connect to.                                             |
| `host?`      | `string`                                     | —       | The host to connect to; defaults to `'localhost'`.                  |
| `opts?`      | `TCPSocketOptions & TCPSocketConnectOptions` | —       | Options passed to both the `TCPSocket` constructor and `connect()`. |
| `onconnect?` | `() => void`                                 | —       | Called when the connection is established.                          |

createServer(opts?: TCPServerOptions, onconnection?: () => void): TCPServer [#createserveropts-tcpserveroptions-onconnection---void-tcpserver]

Create a new TCP server. `server` extends \<[https://github.com/holepunchto/bare-events>](https://github.com/holepunchto/bare-events>).

Overloads:

```ts
createServer(opts?: TCPServerOptions, onconnection?: () => void): TCPServer
createServer(onconnection: () => void): TCPServer
```

**Parameters**

| Parameter       | Type                                    | Default | Description                                                                                                                                                            |
| --------------- | --------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `opts?`         | [`TCPServerOptions`](#tcpserveroptions) | —       | Options applied to each incoming socket; `readBufferSize` defaults to `65536`, `allowHalfOpen` to `true`, and `keepAlive`, `noDelay`, and `pauseOnConnect` to `false`. |
| `onconnection?` | `() => void`                            | —       | Called on each `'connection'` event.                                                                                                                                   |

socketpair(): [first: number, second: number] [#socketpair-first-number-second-number]

Create a pair of connected sockets, returning their file descriptors.

**Returns** `[first: number, second: number]` — The file descriptors of the two connected sockets.

isIP(host: string): IPFamily | 0 [#isiphost-string-ipfamily--0]

Returns `4` if `host` is an IPv4 address, `6` if it is an IPv6 address, or `0` otherwise.

**Parameters**

| Parameter | Type     | Default | Description          |
| --------- | -------- | ------- | -------------------- |
| `host`    | `string` | —       | The string to check. |

isIPv4(host: string): boolean [#isipv4host-string-boolean]

Returns `true` if `host` is an IPv4 address.

**Parameters**

| Parameter | Type     | Default | Description          |
| --------- | -------- | ------- | -------------------- |
| `host`    | `string` | —       | The string to check. |

isIPv6(host: string): boolean [#isipv6host-string-boolean]

Returns `true` if `host` is an IPv6 address.

**Parameters**

| Parameter | Type     | Default | Description          |
| --------- | -------- | ------- | -------------------- |
| `host`    | `string` | —       | The string to check. |

Constants and variables [#constants-and-variables]

constants [#constants]

```ts
constants: {
  state: {
    CONNECTING: number
    CONNECTED: number
    BINDING: number
    BOUND: number
    READING: number
    CLOSING: number
    UNREFED: number
  }
}
```

Object containing internal state constants.

Types [#types]

IPFamily [#ipfamily]

```ts
type IPFamily = 4 | 6
```

TCPSocketAddress [#tcpsocketaddress]

```ts
interface TCPSocketAddress {
  address: string
  family: `IPv${IPFamily}`
  port: number
}
```

The address of a TCP socket, as `{ address, family, port }`.

TCPSocketEvents [#tcpsocketevents]

```ts
interface TCPSocketEvents {
  connect: []
  lookup: [err: Error | null, address: string | null, family: IPFamily | 0, host: string]
  timeout: [ms: number]
  data: [data: unknown]
  end: []
  readable: []
  piping: [dest: Writable]
  close: []
  error: [err: Error]
  drain: []
  finish: []
  pipe: [src: Readable]
}
```

Events emitted by a `TCPSocket`.

TCPSocketOptions [#tcpsocketoptions]

```ts
interface TCPSocketOptions {
  allowHalfOpen?: boolean
  eagerOpen?: boolean
  readBufferSize?: number
}
```

Options for a `TCPSocket`.

TCPSocketConnectOptions [#tcpsocketconnectoptions]

```ts
interface TCPSocketConnectOptions {
  lookup?: DNSLookup
  host?: string
  keepAlive?: boolean
  keepAliveInitialDelay?: boolean
  noDelay?: boolean
  port?: number
  timeout?: number
  family?: `IPv${IPFamily}` | IPFamily | 0
  hints?: number
  all?: boolean
}
```

Options for `connect()`.

TCPServerDropInfo [#tcpserverdropinfo]

```ts
interface TCPServerDropInfo {
  localAddress?: string
  localPort?: number
  localFamily?: string
  remoteAddress?: string
  remotePort?: number
  remoteFamily?: string
}
```

Details of a connection dropped because `maxConnections` was exceeded.

TCPServerEvents [#tcpserverevents]

```ts
interface TCPServerEvents {
  close: []
  connection: [socket: TCPSocket]
  drop: [info: TCPServerDropInfo]
  error: [err: Error]
  listening: []
  lookup: [err: Error | null, address: string | null, family: IPFamily | 0, host: string]
}
```

Events emitted by a `TCPServer`.

TCPServerOptions [#tcpserveroptions]

```ts
interface TCPServerOptions {
  allowHalfOpen?: number
  keepAlive?: boolean
  keepAliveInitialDelay?: boolean
  maxConnections?: number
  noDelay?: boolean
  pauseOnConnect?: boolean
  readBufferSize?: number
}
```

Options for a TCP server, applied to each incoming socket.

TCPServerListenOptions [#tcpserverlistenoptions]

```ts
interface TCPServerListenOptions {
  lookup?: DNSLookup
  backlog?: number
  host?: string
  port?: number
  family?: `IPv${IPFamily}` | IPFamily | 0
  hints?: number
  all?: boolean
}
```

Options for `listen()`.

Classes [#classes]

TCPError [#tcperror]

```ts
class TCPError {
  code: string
}
```

An error produced by `bare-tcp`; `code` identifies the failure.

See also [#see-also]

* Builds on `bare-dns`, `bare-events`, and `bare-stream`.
* Sockets are [`bare-stream`](/reference/bare/modules/bare-stream) duplex streams.
* [Bare modules](/reference/modules/bare-modules) — the full `bare-*` catalog.
* [Bare runtime API](/reference/bare/runtime) — the runtime these modules extend.


# bare-timers



<mark style={{ backgroundColor: '#7dde9a', padding: '2px 8px', borderRadius: '4px', fontSize: '0.85em', fontWeight: 500 }}>
  stable
</mark>

[`bare-timers`](https://github.com/holepunchto/bare-timers) — Native timers for Javascript. It is a native addon and requires Bare `>=1.7.0`.

Mirrors the Node.js [`timers`](https://nodejs.org/api/timers.html) module.

```sh
npm i bare-timers
```

Usage [#usage]

```js
const { setTimeout, clearTimeout } = require('bare-timers')
```

API [#api]

Functions [#functions]

setTimeout [#settimeout]

```ts
setTimeout<T extends unknown[]>(callback: (...args: T) => unknown, delay: number, ...args: T): Timeout
```

Schedule execution once after `delay` milliseconds, clamped to a minimum of 1ms.

**Parameters**

| Parameter  | Type                      | Default | Description                                                       |
| ---------- | ------------------------- | ------- | ----------------------------------------------------------------- |
| `callback` | `(...args: T) => unknown` | —       | The function to run after the delay.                              |
| `delay`    | `number`                  | —       | Milliseconds to wait before running; clamped to a minimum of `1`. |
| `args`     | `T`                       | —       | Additional arguments passed to `callback`.                        |

clearTimeout(timer: Timeout): void [#cleartimeouttimer-timeout-void]

Cancel a pending timeout, preventing it from firing.

**Parameters**

| Parameter | Type                  | Default | Description                   |
| --------- | --------------------- | ------- | ----------------------------- |
| `timer`   | [`Timeout`](#timeout) | —       | The timeout handle to cancel. |

setInterval [#setinterval]

```ts
setInterval<T extends unknown[]>(callback: (...args: T) => unknown, delay: number, ...args: T): Timeout
```

Schedule repeated execution every `delay` milliseconds, clamped to a minimum of 1ms.

**Parameters**

| Parameter  | Type                      | Default | Description                                             |
| ---------- | ------------------------- | ------- | ------------------------------------------------------- |
| `callback` | `(...args: T) => unknown` | —       | The function to run on each interval.                   |
| `delay`    | `number`                  | —       | Milliseconds between runs; clamped to a minimum of `1`. |
| `args`     | `T`                       | —       | Additional arguments passed to `callback`.              |

clearInterval(timer: Timeout): void [#clearintervaltimer-timeout-void]

Cancel a pending interval, preventing further firings.

**Parameters**

| Parameter | Type                  | Default | Description                    |
| --------- | --------------------- | ------- | ------------------------------ |
| `timer`   | [`Timeout`](#timeout) | —       | The interval handle to cancel. |

setImmediate<T extends unknown[]>(callback: (...args: T) => unknown, ...args: T): Immediate [#setimmediatet-extends-unknowncallback-args-t--unknown-args-t-immediate]

Schedule execution once at the end of the current event loop iteration.

**Parameters**

| Parameter  | Type                      | Default | Description                                                         |
| ---------- | ------------------------- | ------- | ------------------------------------------------------------------- |
| `callback` | `(...args: T) => unknown` | —       | The function to run at the end of the current event loop iteration. |
| `args`     | `T`                       | —       | Additional arguments passed to `callback`.                          |

clearImmediate(immediate: Immediate): void [#clearimmediateimmediate-immediate-void]

Cancel a pending immediate, preventing it from firing.

**Parameters**

| Parameter   | Type                      | Default | Description                     |
| ----------- | ------------------------- | ------- | ------------------------------- |
| `immediate` | [`Immediate`](#immediate) | —       | The immediate handle to cancel. |

Types [#types]

Task [#task]

```ts
interface Task {
  ref(): this
  unref(): this
  hasRef(): boolean
}
```

The base handle shared by `Timeout` and `Immediate`, controlling whether it keeps the event loop alive.

Timeout [#timeout]

```ts
interface Timeout {
  refresh(): this
  ref(): this
  unref(): this
  hasRef(): boolean
}
```

The handle returned by `setTimeout` and `setInterval`.

Immediate [#immediate]

```ts
interface Immediate {
  ref(): this
  unref(): this
  hasRef(): boolean
}
```

The handle returned by `setImmediate`.

bare-timers/promises [#bare-timerspromises]

Functions [#functions-1]

setTimeout<T>(delay?: number, value?: T, options?: TimeoutOptions): Promise<T> [#settimeouttdelay-number-value-t-options-timeoutoptions-promiset]

Schedule execution once after `delay` milliseconds, clamped to a minimum of 1ms.

**Parameters**

| Parameter  | Type             | Default | Description                                                                                                            |
| ---------- | ---------------- | ------- | ---------------------------------------------------------------------------------------------------------------------- |
| `delay?`   | `number`         | —       | Milliseconds to wait before running; clamped to a minimum of `1`.                                                      |
| `value?`   | `T`              | —       | The value the returned promise resolves with.                                                                          |
| `options?` | `TimeoutOptions` | —       | Options; `ref` defaults to `true` (set `false` to unref), and `signal` may be an `AbortSignal` that cancels the timer. |

setInterval<T>(delay?: number, value?: T, options?: TimeoutOptions): AsyncGenerator<T> [#setintervaltdelay-number-value-t-options-timeoutoptions-asyncgeneratort]

Schedule repeated execution every `delay` milliseconds, clamped to a minimum of 1ms.

**Parameters**

| Parameter  | Type             | Default | Description                                                                                                            |
| ---------- | ---------------- | ------- | ---------------------------------------------------------------------------------------------------------------------- |
| `delay?`   | `number`         | —       | Milliseconds between runs; clamped to a minimum of `1`.                                                                |
| `value?`   | `T`              | —       | The value yielded on each iteration.                                                                                   |
| `options?` | `TimeoutOptions` | —       | Options; `ref` defaults to `true` (set `false` to unref), and `signal` may be an `AbortSignal` that cancels the timer. |

setImmediate<T>(value?: T, options?: ImmediateOptions): Promsie<T> [#setimmediatetvalue-t-options-immediateoptions-promsiet]

Schedule execution once at the end of the current event loop iteration.

**Parameters**

| Parameter  | Type               | Default | Description                                                                                                            |
| ---------- | ------------------ | ------- | ---------------------------------------------------------------------------------------------------------------------- |
| `value?`   | `T`                | —       | The value the returned promise resolves with.                                                                          |
| `options?` | `ImmediateOptions` | —       | Options; `ref` defaults to `true` (set `false` to unref), and `signal` may be an `AbortSignal` that cancels the timer. |

Types [#types-1]

TaskOptions [#taskoptions]

```ts
interface TaskOptions {
  ref?: boolean
  signal?: AbortSignal
}
```

Shared options for the `bare-timers/promises` scheduling functions.

TimeoutOptions [#timeoutoptions]

```ts
interface TimeoutOptions {
  ref?: boolean
  signal?: AbortSignal
}
```

Options for `bare-timers/promises`' `setTimeout` and `setInterval`.

ImmediateOptions [#immediateoptions]

```ts
interface ImmediateOptions {
  ref?: boolean
  signal?: AbortSignal
}
```

Options for `bare-timers/promises`' `setImmediate`.

See also [#see-also]

* Inside Bare these functions are installed as globals, so most code calls them directly without importing anything.
* `delay` is floored to an integer. A `delay` that is less than `1`, `NaN`, non-numeric, or greater than `Number.MAX_SAFE_INTEGER` is clamped to `1` ms. (Node caps the maximum at `2147483647`; Bare's ceiling is `Number.MAX_SAFE_INTEGER`.)
* Passing `null`, `undefined`, or a non-object to `clearTimeout`/`clearInterval`/`clearImmediate` is a no-op, as is clearing a handle that has already fired or been cleared. All three delegate to the same routine, so any one can cancel any handle—but use the matching name for clarity.
* Every handle also implements `[Symbol.dispose]()`, so a `using timer = setTimeout(…)` declaration cancels the timer when the scope exits.
* The usual suspension pattern is to clear timers outright on `suspend`; `unref()` is the alternative for a timer that must keep running across the cycle—the same pattern [`bare-ipc`](/reference/bare/modules/bare-ipc#unref-this) uses for its channel.
* Hooks into the [Bare runtime](/reference/bare/runtime)'s lifecycle events (`idle`, `resume`, `wakeup`) to pause and restart the underlying native timer. The promise-based API integrates with `bare-abort-controller`—an optional peer dependency—for `signal`-based cancellation.
* `require('bare-timers').promises` is also reachable as the standalone `require('bare-timers/promises')`.
* [Bare modules](/reference/modules/bare-modules) — the full `bare-*` catalog.
* [Bare runtime API](/reference/bare/runtime) — the runtime these modules extend.


# bare-tls



<mark style={{ backgroundColor: '#7dde9a', padding: '2px 8px', borderRadius: '4px', fontSize: '0.85em', fontWeight: 500 }}>
  stable
</mark>

[`bare-tls`](https://github.com/holepunchto/bare-tls) — Transport Layer Security (TLS) streams for JavaScript. It is a native addon and requires Bare `>=1.7.0`.

Mirrors the Node.js [`tls`](https://nodejs.org/api/tls.html) module.

```sh
npm i bare-tls
```

Usage [#usage]

```js
const tls = require('bare-tls')
const fs = require('bare-fs')

const server = tls.createServer(
  {
    cert: fs.readFileSync('cert.pem'),
    key: fs.readFileSync('key.pem')
  },
  (socket) => {
    socket.on('data', (data) => socket.end('pong')).on('close', () => server.close())
  }
)

server.listen(8443)

const client = tls.connect({ port: 8443, host: 'localhost' })

client.on('data', (data) => console.log(data)).end('ping')
```

API [#api]

errors [#errors]

errors.from(err: Error): TLSError [#errorsfromerr-error-tlserror]

Create a `TLSError` from `err`, copying its message and code.

**Parameters**

| Parameter | Type    | Default | Description           |
| --------- | ------- | ------- | --------------------- |
| `err`     | `Error` | —       | The error to convert. |

TLSSocket [#tlssocket]

new TLSSocket(socket: Duplex, opts?: TLSSocketOptions) [#new-tlssocketsocket-duplex-opts-tlssocketoptions]

Wrap the duplex stream `socket` with TLS.

**Parameters**

| Parameter | Type                                    | Default | Description                                                                                                         |
| --------- | --------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------- |
| `socket`  | `Duplex`                                | —       | The duplex stream to wrap; it handles transport while the TLS socket handles encryption and decryption.             |
| `opts?`   | [`TLSSocketOptions`](#tlssocketoptions) | —       | Options; `rejectUnauthorized`, `eagerOpen`, and `allowHalfOpen` default to `true`, and `readBufferSize` to `65536`. |

**Throws**

* `TypeError` — `host` is missing for a client socket while `rejectUnauthorized` is `true`.
* `RangeError` — an ALPN protocol name is empty or longer than 255 bytes.

alpnProtocol: string | null [#alpnprotocol-string--null]

The negotiated ALPN protocol as a string, or `null` if no protocol was negotiated.

encrypted: true [#encrypted-true]

Always `true`.

socket: Duplex [#socket-duplex]

The underlying duplex stream.

Functions [#functions]

createServer(opts?: TLSSocketOptions, onconnection?: (socket: TLSSocket) => void): TLSNetServer [#createserveropts-tlssocketoptions-onconnection-socket-tlssocket--void-tlsnetserver]

Creates a TLS server that listens for TCP connections and wraps them with TLS. Incoming connections are emitted as `'connection'` events with a `tls.Socket` instance. Options are the same as `tls.Socket`, plus any options supported by \<[https://github.com/holepunchto/bare-net>](https://github.com/holepunchto/bare-net>).

**Parameters**

| Parameter       | Type                                    | Default | Description                                                                                                 |
| --------------- | --------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------- |
| `opts?`         | [`TLSSocketOptions`](#tlssocketoptions) | —       | Options applied to each incoming socket; the same as `TLSSocket`, plus any options supported by `bare-net`. |
| `onconnection?` | `(socket: TLSSocket) => void`           | —       | Called on each `'connection'` event.                                                                        |

createConnection [#createconnection]

```ts
createConnection(opts: TLSSocketOptions & { port: number; host?: string }, onconnect?: () => void): TLSSocket
```

Creates a TCP connection and wraps it with TLS. `opts` are passed to both the underlying TCP socket and `TLSSocket`. At minimum, `port` must be specified.

**Parameters**

| Parameter    | Type                                                 | Default | Description                                                                                                                |
| ------------ | ---------------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
| `opts`       | `TLSSocketOptions & { port: number; host?: string }` | —       | Options passed to both the underlying TCP socket and `TLSSocket`; `port` is required and `host` defaults to `'localhost'`. |
| `onconnect?` | `() => void`                                         | —       | Called when the connection is established.                                                                                 |

Constants and variables [#constants-and-variables]

constants [#constants]

```ts
constants: {
  state: {
    CONNECTED: number
    ATTACHED: number
  }
}
```

Internal state flags used by `TLSSocket`, such as `state.CONNECTED`.

Types [#types]

TLSSocketEvents [#tlssocketevents]

```ts
interface TLSSocketEvents {
  connect: []
  data: [data: unknown]
  end: []
  readable: []
  piping: [dest: Writable]
  close: []
  error: [err: Error]
  drain: []
  finish: []
  pipe: [src: Readable]
}
```

Events emitted by a `TLSSocket`.

TLSSocketOptions [#tlssocketoptions]

```ts
interface TLSSocketOptions {
  isServer?: boolean
  cert?: ArrayBufferView
  key?: ArrayBufferView
  host?: string
  rejectUnauthorized?: boolean
  ca?: ArrayBufferView
  alpnProtocols?: string[]
  eagerOpen?: boolean
  allowHalfOpen?: boolean
  readBufferSize?: number
}
```

Options for a `TLSSocket`.

TLSNetServerEvents [#tlsnetserverevents]

```ts
interface TLSNetServerEvents {
  listening: []
  connection: [socket: TLSSocket]
  error: [err: Error]
  close: []
}
```

Events emitted by a TLS server.

TLSNetServer [#tlsnetserver]

```ts
interface TLSNetServer {
  readonly listening: boolean
}
```

A TLS server over TCP; incoming connections are wrapped with TLS and emitted as `'connection'` events.

bare-tls/constants [#bare-tlsconstants]

Constants and variables [#constants-and-variables-1]

constants.constants [#constantsconstants]

```ts
constants: {
  state: {
    CONNECTED: number
    ATTACHED: number
  }
}
```

Internal state flags used by `TLSSocket`, such as `state.CONNECTED`.

bare-tls/errors [#bare-tlserrors]

TLSError [#tlserror]

TLSError.from(err: Error): TLSError [#tlserrorfromerr-error-tlserror]

Create a `TLSError` from `err`, copying its message and code.

**Parameters**

| Parameter | Type    | Default | Description           |
| --------- | ------- | ------- | --------------------- |
| `err`     | `Error` | —       | The error to convert. |

See also [#see-also]

* Builds on `bare-net` and `bare-stream`.
* [Bare modules](/reference/modules/bare-modules) — the full `bare-*` catalog.
* [Bare runtime API](/reference/bare/runtime) — the runtime these modules extend.


# bare-tty



<mark style={{ backgroundColor: '#7dde9a', padding: '2px 8px', borderRadius: '4px', fontSize: '0.85em', fontWeight: 500 }}>
  stable
</mark>

[`bare-tty`](https://github.com/holepunchto/bare-tty) — Native TTY streams for JavaScript. It is a native addon and requires Bare `>=1.16.0`.

Mirrors the Node.js [`tty`](https://nodejs.org/api/tty.html) module.

```sh
npm i bare-tty
```

Usage [#usage]

```js
const tty = require('bare-tty')

const stdout = new tty.WriteStream(1)

stdout.write('Hello world!\n')
```

API [#api]

ReadStream [#readstream]

new ReadStream(fd: number, opts?: ReadableOptions) [#new-readstreamfd-number-opts-readableoptions]

Create a `ReadStream` for the TTY file descriptor `fd`.

**Parameters**

| Parameter | Type              | Default | Description                                                                  |
| --------- | ----------------- | ------- | ---------------------------------------------------------------------------- |
| `fd`      | `number`          | —       | The file descriptor of the TTY.                                              |
| `opts?`   | `ReadableOptions` | —       | Options; `readBufferSize` defaults to `65536` and `allowHalfOpen` to `true`. |

ReadStream.fd: number [#readstreamfd-number]

The stream's underlying file descriptor.

ReadStream.isTTY: true [#readstreamistty-true]

Always `true`, identifying the stream as a TTY.

setMode(mode: number): this [#setmodemode-number-this]

Set the TTY mode directly, using one of the `constants.mode` values. Returns the stream.

**Parameters**

| Parameter | Type     | Default | Description                                              |
| --------- | -------- | ------- | -------------------------------------------------------- |
| `mode`    | `number` | —       | The TTY mode to set, one of the `constants.mode` values. |

setRawMode(mode: boolean): this [#setrawmodemode-boolean-this]

Enable or disable raw mode. In raw mode, input is delivered byte-by-byte without line buffering or special key processing. Returns the stream.

**Parameters**

| Parameter | Type      | Default | Description                                                  |
| --------- | --------- | ------- | ------------------------------------------------------------ |
| `mode`    | `boolean` | —       | `true` to enable raw mode, `false` to return to normal mode. |

WriteStream [#writestream]

new WriteStream(fd: number, opts?: WritableOptions) [#new-writestreamfd-number-opts-writableoptions]

Create a `WriteStream` for the TTY file descriptor `fd`.

**Parameters**

| Parameter | Type              | Default | Description                     |
| --------- | ----------------- | ------- | ------------------------------- |
| `fd`      | `number`          | —       | The file descriptor of the TTY. |
| `opts?`   | `WritableOptions` | —       | —                               |

columns: number [#columns-number]

The current number of columns in the TTY.

WriteStream.fd: number [#writestreamfd-number]

The stream's underlying file descriptor.

getWindowSize(): [width: number, height: number] [#getwindowsize-width-number-height-number]

Return the current TTY dimensions as `[width, height]`.

WriteStream.isTTY: true [#writestreamistty-true]

Always `true`, identifying the stream as a TTY.

rows: number [#rows-number]

The current number of rows in the TTY.

Functions [#functions]

isTTY(fd: number): boolean [#isttyfd-number-boolean]

Return whether `fd` refers to a TTY.

**Parameters**

| Parameter | Type     | Default | Description                   |
| --------- | -------- | ------- | ----------------------------- |
| `fd`      | `number` | —       | The file descriptor to check. |

Constants and variables [#constants-and-variables]

constants [#constants]

```ts
constants: {
  mode: { NORMAL: number; RAW: number; IO: number }
  state: { READING: number; CLOSING: number }
}
```

Native mode and internal state flags used by `ReadStream`/`WriteStream`, such as `mode.NORMAL` and `mode.RAW`.

See also [#see-also]

* Builds on `bare-events`, `bare-signals`, and `bare-stream`.
* [Bare modules](/reference/modules/bare-modules) — the full `bare-*` catalog.
* [Bare runtime API](/reference/bare/runtime) — the runtime these modules extend.


# bare-type-stripper



<mark style={{ backgroundColor: '#7dde9a', padding: '2px 8px', borderRadius: '4px', fontSize: '0.85em', fontWeight: 500 }}>
  stable
</mark>

[`bare-type-stripper`](https://github.com/holepunchto/bare-type-stripper) — Heuristic lexer for stripping TypeScript type syntax to produce plain JavaScript. It is a native addon.

```sh
npm i bare-type-stripper
```

Usage [#usage]

```js
const strip = require('bare-type-stripper')

strip(`
  const x: number = 1
  function f<T>(xs: T[]): T { return xs[0] }
`).toString()

// '
//   const x         = 1
//   function f   (xs   )    { return xs[0] }
// '
```

API [#api]

Functions [#functions]

strip(input: string | Buffer, encoding?: BufferEncoding, opts?: object): Buffer [#stripinput-string--buffer-encoding-bufferencoding-opts-object-buffer]

Strip TypeScript-only syntax from `input` and return plain JavaScript as a `Buffer`. Stripped regions are replaced with spaces (newlines preserved) so the output has the same byte length as the input, keeping stack traces and source positions aligned.

**Parameters**

| Parameter   | Type                 | Default | Description                                                                                                         |
| ----------- | -------------------- | ------- | ------------------------------------------------------------------------------------------------------------------- |
| `input`     | `string` \| `Buffer` | —       | The TypeScript source to strip, as a string or a `Buffer`.                                                          |
| `encoding?` | `BufferEncoding`     | —       | Encoding used to decode `input` when it is a string (default `'utf8'`); ignored when `input` is already a `Buffer`. |
| `opts?`     | `object`             | —       | An options object; currently unused.                                                                                |

**Throws**

* `TypeError` — `input` is neither a string nor a buffer.
* `SyntaxError` — the source contains non-erasable TypeScript syntax (`enum`/`const enum`, `namespace`/`module` with a body, parameter properties, or angle-bracket type assertions).

strip.lex [#striplex]

```ts
strip.lex(input: string | Buffer, encoding?: BufferEncoding, opts?: object): [start: number, end: number, flags?: number][]
```

**Parameters**

| Parameter   | Type                 | Default | Description |
| ----------- | -------------------- | ------- | ----------- |
| `input`     | `string` \| `Buffer` | —       | —           |
| `encoding?` | `BufferEncoding`     | —       | —           |
| `opts?`     | `object`             | —       | —           |

Constants and variables [#constants-and-variables]

strip.constants [#stripconstants]

```ts
strip.constants: {
    SEMI: number
    PAREN: number
    ERROR: number
  }
```

What gets stripped [#what-gets-stripped]

| Construct                 | Example                               |
| :------------------------ | :------------------------------------ |
| Type annotations          | `const x: number = 1`                 |
| Type aliases              | `type Foo = number`                   |
| Interfaces                | `interface Foo { x: number }`         |
| Type-only imports/exports | `import type { Foo } from 'mod'`      |
| Generics at declarations  | `function f<T>(x: T): T`              |
| Generics at call sites    | `foo<number>()`                       |
| Generic arrow functions   | `<T>(x: T) => x`                      |
| Type assertions           | `x as Foo`, `x satisfies Foo`         |
| Non-null assertion        | `obj!.foo`                            |
| Optional parameter marker | `function f(x?: T)`                   |
| Definite assignment       | `let x!: number`                      |
| Class member modifiers    | `public`, `private`, `readonly`, etc. |
| `implements` clauses      | `class C implements I`                |
| `declare` statements      | `declare const x: number`             |
| Overload signatures       | `function f(x: string): void`         |
| Abstract members          | `abstract foo(): void`                |

What is left alone [#what-is-left-alone]

* Decorators - they emit runtime code and are valid JavaScript syntax.

What throws [#what-throws]

Constructs with runtime semantics that a purely lexical stripper cannot reproduce are marked with the `ERROR` flag, and `strip()` throws a `SyntaxError` when it meets one:

* `enum` / `const enum` declarations - they emit a runtime object.
* `namespace` / `module` declarations with bodies - they emit runtime code.
* Parameter properties - `constructor(public x: number)` implies a `this.x = x` assignment that stripping the modifier would silently lose.
* Old-style angle-bracket type assertions (`<Foo>expr`) - indistinguishable from JSX, which is not supported.

Limitations [#limitations]

The stripper targets plain `.ts` sources; JSX (`.tsx`) is not supported and is reported as non-erasable syntax.

See also [#see-also]

* [Bare modules](/reference/modules/bare-modules) — the full `bare-*` catalog.
* [Bare runtime API](/reference/bare/runtime) — the runtime these modules extend.


# bare-type



<mark style={{ backgroundColor: '#7dde9a', padding: '2px 8px', borderRadius: '4px', fontSize: '0.85em', fontWeight: 500 }}>
  stable
</mark>

[`bare-type`](https://github.com/holepunchto/bare-type) — Cross-realm type predicates for Bare. It is a native addon and requires Bare `>=1.2.0`.

```sh
npm i bare-type
```

Usage [#usage]

```js
const type = require('bare-type')

if (type(123).isNumber()) {
  console.log(123, 'is a number')
}
```

API [#api]

Type [#type]

new Type(type: number) [#new-typetype-number]

**Parameters**

| Parameter | Type     | Default | Description |
| --------- | -------- | ------- | ----------- |
| `type`    | `number` | —       | —           |

isArguments(): boolean [#isarguments-boolean]

isArray(): boolean [#isarray-boolean]

isArrayBuffer(): boolean [#isarraybuffer-boolean]

isAsyncFunction(): boolean [#isasyncfunction-boolean]

isBigInt(): boolean [#isbigint-boolean]

isBigInt64Array(): boolean [#isbigint64array-boolean]

isBigUint64Array(): boolean [#isbiguint64array-boolean]

isBoolean(): boolean [#isboolean-boolean]

isDataView(): boolean [#isdataview-boolean]

isDate(): boolean [#isdate-boolean]

isError(): boolean [#iserror-boolean]

isExternal(): boolean [#isexternal-boolean]

isFloat16Array(): boolean [#isfloat16array-boolean]

isFloat32Array(): boolean [#isfloat32array-boolean]

isFloat64Array(): boolean [#isfloat64array-boolean]

isFunction(): boolean [#isfunction-boolean]

isGenerator(): boolean [#isgenerator-boolean]

isGeneratorFunction(): boolean [#isgeneratorfunction-boolean]

isInt16Array(): boolean [#isint16array-boolean]

isInt32(): boolean [#isint32-boolean]

isInt32Array(): boolean [#isint32array-boolean]

isInt8Array(): boolean [#isint8array-boolean]

isMap(): boolean [#ismap-boolean]

isModuleNamespace(): boolean [#ismodulenamespace-boolean]

isNull(): boolean [#isnull-boolean]

isNumber(): boolean [#isnumber-boolean]

isObject(): boolean [#isobject-boolean]

isPromise(): boolean [#ispromise-boolean]

isProxy(): boolean [#isproxy-boolean]

isRegExp(): boolean [#isregexp-boolean]

isSet(): boolean [#isset-boolean]

isSharedArrayBuffer(): boolean [#issharedarraybuffer-boolean]

isString(): boolean [#isstring-boolean]

isSymbol(): boolean [#issymbol-boolean]

isTypedArray(): boolean [#istypedarray-boolean]

isUint16Array(): boolean [#isuint16array-boolean]

isUint32(): boolean [#isuint32-boolean]

isUint32Array(): boolean [#isuint32array-boolean]

isUint8Array(): boolean [#isuint8array-boolean]

isUint8ClampedArray(): boolean [#isuint8clampedarray-boolean]

isUndefined(): boolean [#isundefined-boolean]

isWeakMap(): boolean [#isweakmap-boolean]

isWeakRef(): boolean [#isweakref-boolean]

isWeakSet(): boolean [#isweakset-boolean]

Functions [#functions]

type(value: unknown): Type [#typevalue-unknown-type]

Return a `Type` wrapping `value`, exposing `is*()` predicates to test its runtime type across realms.

**Parameters**

| Parameter | Type      | Default | Description                 |
| --------- | --------- | ------- | --------------------------- |
| `value`   | `unknown` | —       | The value to wrap and test. |

type.addTag(object: object, tag: Uint32Array): void [#typeaddtagobject-object-tag-uint32array-void]

**Parameters**

| Parameter | Type          | Default | Description |
| --------- | ------------- | ------- | ----------- |
| `object`  | `object`      | —       | —           |
| `tag`     | `Uint32Array` | —       | —           |

type.checkTag(object: object, tag: Uint32Array): boolean [#typechecktagobject-object-tag-uint32array-boolean]

**Parameters**

| Parameter | Type          | Default | Description |
| --------- | ------------- | ------- | ----------- |
| `object`  | `object`      | —       | —           |
| `tag`     | `Uint32Array` | —       | —           |

type.createTag(...components: number[]): Uint32Array [#typecreatetagcomponents-number-uint32array]

**Parameters**

| Parameter    | Type       | Default | Description |
| ------------ | ---------- | ------- | ----------- |
| `components` | `number[]` | —       | —           |

See also [#see-also]

* [Bare modules](/reference/modules/bare-modules) — the full `bare-*` catalog.
* [Bare runtime API](/reference/bare/runtime) — the runtime these modules extend.


# bare-union-bundle



[`bare-union-bundle`](https://github.com/holepunchto/bare-union-bundle) layers multiple [`bare-bundle`](/reference/modules/bare-modules) files into one **union bundle**, so modules resolve across a stack of bundles (for example, an app layer over a shared base). It's pure JavaScript, built on [`bare-module-traverse`](/reference/bare/modules/bare-module-traverse).

```sh
npm i bare-union-bundle
```

Usage [#usage]

```js
const UnionBundle = require('bare-union-bundle')

const b = UnionBundle.require('./0.bundle', './1.bundle', './2.bundle')

// load entrypoint.js from layer 1, unioning back to the project root
const mod = b.load(new URL('file:///root-of-project'), 'entrypoint.js', 1)
```

API [#api]

const b = new UnionBundle(bundles) · UnionBundle.require(...files) [#const-b--new-unionbundlebundles--unionbundlerequirefiles]

Create a union from in-memory `bundles`, or load and union bundle files.

const layer = await b.add(root, entrypoint[, opts]) [#const-layer--await-baddroot-entrypoint-opts]

Create a new layer bundle for `entrypoint` relative to `root`. Options:

```js
opts = {
  skipModules: true  // skip bundling dependencies under node_modules in root (boolean; default true)
}
```

Modules already referenced in the union's existing bundles are automatically skipped.

const bundle = b.checkout(index) [#const-bundle--bcheckoutindex]

Extract a single layer as a standalone bundle.

const mod = b.load(root, entrypoint, index[, opts]) [#const-mod--bloadroot-entrypoint-index-opts]

Load a module from layer `index`, resolving across the union back to `root`. Options:

```js
opts = {
  cache: require.cache,  // the module cache to load the entrypoint with (default require.cache)
  skipModules: true      // skip loading node_modules deps already in the cache (boolean; default true)
}
```

Related modules [#related-modules]

Builds on [`bare-bundle`](/reference/modules/bare-modules), [`bare-module`](/reference/bare/modules/bare-module), [`bare-module-traverse`](/reference/bare/modules/bare-module-traverse), and [`bare-fs`](/reference/bare/modules/bare-fs) (see [Bare modules](/reference/modules/bare-modules)).

See also [#see-also]

* [`bare-pack`](/reference/modules/bare-modules)—produces the bundles a union layers together.
* [`bare-module-traverse`](/reference/bare/modules/bare-module-traverse)—the traversal it uses to add layers.
* [Bare modules](/reference/modules/bare-modules)—the full `bare-*` catalog.


# bare-url



<mark style={{ backgroundColor: '#7dde9a', padding: '2px 8px', borderRadius: '4px', fontSize: '0.85em', fontWeight: 500 }}>
  stable
</mark>

[`bare-url`](https://github.com/holepunchto/bare-url) — WHATWG URL implementation for JavaScript. It is a native addon.

Mirrors the Node.js [`url`](https://nodejs.org/api/url.html) module.

```sh
npm i bare-url
```

Usage [#usage]

```js
const { URL, URLSearchParams } = require('bare-url')

const url = new URL('https://example.com/path?foo=bar#hash')

console.log(url.hostname) // 'example.com'
console.log(url.pathname) // '/path'
console.log(url.searchParams.get('foo')) // 'bar'
```

To register `URL` and `URLSearchParams` as globals:

```js
require('bare-url/global')
```

API [#api]

Constructing and parsing [#constructing-and-parsing]

new URL(input: string | URL, base?: string | URL) [#new-urlinput-string--url-base-string--url]

Parse `input` as a URL. If `base` is provided, `input` is resolved relative to `base`.

**Parameters**

| Parameter | Type              | Default | Description                                                   |
| --------- | ----------------- | ------- | ------------------------------------------------------------- |
| `input`   | `string` \| `URL` | —       | The URL string to parse.                                      |
| `base?`   | `string` \| `URL` | —       | A base URL that `input` is resolved relative to, if provided. |

**Throws**

* `INVALID_URL` — `input` is not a valid URL.

URL.parse(input: string, base?: string | URL): URL | null [#urlparseinput-string-base-string--url-url--null]

Parse `input` as a URL without throwing.

**Parameters**

| Parameter | Type              | Default | Description                                                   |
| --------- | ----------------- | ------- | ------------------------------------------------------------- |
| `input`   | `string`          | —       | The URL string to parse.                                      |
| `base?`   | `string` \| `URL` | —       | A base URL that `input` is resolved relative to, if provided. |

**Returns** `URL` | `null` — A `URL` instance if `input` parses successfully, or `null` on failure.

URL.canParse(input: string, base?: string | URL): boolean [#urlcanparseinput-string-base-string--url-boolean]

Return `true` if `input` can be parsed as a valid URL, optionally relative to `base`.

**Parameters**

| Parameter | Type              | Default | Description                                                   |
| --------- | ----------------- | ------- | ------------------------------------------------------------- |
| `input`   | `string`          | —       | The URL string to test.                                       |
| `base?`   | `string` \| `URL` | —       | A base URL that `input` is resolved relative to, if provided. |

Components [#components]

href: string [#href-string]

The full serialized URL string. Setting this property reparses the URL.

protocol: string [#protocol-string]

The URL scheme followed by `':'`, for example `'https:'`.

username: string [#username-string]

The username portion of the URL, or an empty string.

password: string [#password-string]

The password portion of the URL, or an empty string.

host: string [#host-string]

The hostname and port, for example `'example.com:8080'`.

hostname: string [#hostname-string]

The hostname without the port.

port: string [#port-string]

The port as a string, or an empty string if not present.

pathname: string [#pathname-string]

The path portion of the URL.

search: string [#search-string]

The query string including the leading `'?'`, or an empty string.

searchParams: URLSearchParams [#searchparams-urlsearchparams]

A `URLSearchParams` object for the query string. Mutations to the params are reflected in the URL.

hash: string [#hash-string]

The fragment including the leading `'#'`, or an empty string.

Converting to string [#converting-to-string]

URL.toString(): string [#urltostring-string]

Returns the serialized string form.

URL.toJSON(): string [#urltojson-string]

Returns the serialized string form. Suitable for JSON serialization.

File URL conversion [#file-url-conversion]

URL.fileURLToPath(url: URL | string): string [#urlfileurltopathurl-url--string-string]

Convert a `file:` URL to a platform-specific file path. `url` may be a `URL` instance or a string.

**Parameters**

| Parameter | Type              | Default | Description                                                  |
| --------- | ----------------- | ------- | ------------------------------------------------------------ |
| `url`     | `URL` \| `string` | —       | The `file:` URL to convert, as a `URL` instance or a string. |

**Throws**

* `INVALID_URL_SCHEME` — the URL does not use the `file:` protocol.
* `INVALID_FILE_URL_HOST` — (non-Windows) the URL has a host other than empty or `'localhost'`.
* `INVALID_FILE_URL_PATH` — the URL path contains an encoded path-separator or NUL character, or, on Windows, is not an absolute drive path.

URL.pathToFileURL(pathname: string): URL [#urlpathtofileurlpathname-string-url]

Convert a platform-specific file path to a `file:` URL.

**Parameters**

| Parameter  | Type     | Default | Description                                 |
| ---------- | -------- | ------- | ------------------------------------------- |
| `pathname` | `string` | —       | The platform-specific file path to convert. |

Type checks [#type-checks]

URL.isURL(value: unknown): value is URL [#urlisurlvalue-unknown-value-is-url]

Return `true` if `value` is a `URL` instance.

**Parameters**

| Parameter | Type      | Default | Description        |
| --------- | --------- | ------- | ------------------ |
| `value`   | `unknown` | —       | The value to test. |

URL.isURLSearchParams(value: unknown): value is URLSearchParams [#urlisurlsearchparamsvalue-unknown-value-is-urlsearchparams]

Return `true` if `value` is a `URLSearchParams` instance.

**Parameters**

| Parameter | Type      | Default | Description        |
| --------- | --------- | ------- | ------------------ |
| `value`   | `unknown` | —       | The value to test. |

Constructing search params [#constructing-search-params]

new URLSearchParams(init: string | Record<string, string> | Iterable<[string, string]>) [#new-urlsearchparamsinit-string--recordstring-string--iterablestring-string]

Create a new `URLSearchParams` instance. `init` may be a query string, an iterable of `[name, value]` pairs, or an object of key-value pairs.

**Parameters**

| Parameter | Type                                                             | Default | Description                                                                                                          |
| --------- | ---------------------------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------- |
| `init`    | `string \| Record<string, string> \| Iterable<[string, string]>` | —       | A query string, an iterable of `[name, value]` pairs, or an object of key-value pairs to initialize the params from. |

Reading and writing parameters [#reading-and-writing-parameters]

get(name: string): string | undefined [#getname-string-string--undefined]

Return the first value for `name`, or `null` if not present.

**Parameters**

| Parameter | Type     | Default | Description                    |
| --------- | -------- | ------- | ------------------------------ |
| `name`    | `string` | —       | The parameter name to look up. |

getAll(name: string): string[] [#getallname-string-string]

Return all values for `name` as an array.

**Parameters**

| Parameter | Type     | Default | Description                    |
| --------- | -------- | ------- | ------------------------------ |
| `name`    | `string` | —       | The parameter name to look up. |

has(name: string, value?: string): boolean [#hasname-string-value-string-boolean]

Return `true` if a pair with `name` exists. If `value` is provided, the pair must also match `value`.

**Parameters**

| Parameter | Type     | Default | Description                                       |
| --------- | -------- | ------- | ------------------------------------------------- |
| `name`    | `string` | —       | The parameter name to check.                      |
| `value?`  | `string` | —       | If provided, the pair must also match this value. |

append(name: string, value: string): void [#appendname-string-value-string-void]

Append a new `name`/`value` pair.

**Parameters**

| Parameter | Type     | Default | Description          |
| --------- | -------- | ------- | -------------------- |
| `name`    | `string` | —       | The parameter name.  |
| `value`   | `string` | —       | The parameter value. |

set(name: string, value: string): void [#setname-string-value-string-void]

Set the value for `name`, replacing any existing pairs with that name.

**Parameters**

| Parameter | Type     | Default | Description         |
| --------- | -------- | ------- | ------------------- |
| `name`    | `string` | —       | The parameter name. |
| `value`   | `string` | —       | The value to set.   |

delete(name: string, value?: string): void [#deletename-string-value-string-void]

Remove all pairs with `name`. If `value` is provided, only pairs with both the matching `name` and `value` are removed.

**Parameters**

| Parameter | Type     | Default | Description                                                   |
| --------- | -------- | ------- | ------------------------------------------------------------- |
| `name`    | `string` | —       | The parameter name to remove.                                 |
| `value?`  | `string` | —       | If provided, only pairs also matching this value are removed. |

size: number [#size-number]

The total number of search parameters.

Serializing search params [#serializing-search-params]

URLSearchParams.toString(): string [#urlsearchparamstostring-string]

Returns the serialized string form.

URLSearchParams.toJSON(): string [#urlsearchparamstojson-string]

Returns the serialized string form. Suitable for JSON serialization.

Search params type check [#search-params-type-check]

URLSearchParams.isURLSearchParams(value: unknown): value is URLSearchParams [#urlsearchparamsisurlsearchparamsvalue-unknown-value-is-urlsearchparams]

Return `true` if `value` is a `URLSearchParams` instance.

**Parameters**

| Parameter | Type      | Default | Description        |
| --------- | --------- | ------- | ------------------ |
| `value`   | `unknown` | —       | The value to test. |

Errors [#errors]

URLError [#urlerror]

```ts
class URLError {
  code: string
  input: string
}
```

bare-url/global [#bare-urlglobal]

Types [#types]

URLConstructor [#urlconstructor]

```ts
type URLConstructor = typeof url.URL
```

URLSearchParamsConstructor [#urlsearchparamsconstructor]

```ts
type URLSearchParamsConstructor = typeof url.URLSearchParams
```

See also [#see-also]

* Builds on `bare-path`.
* [`bare-path`](/reference/bare/modules/bare-path) — provides the platform-specific path handling used by `fileURLToPath`/`pathToFileURL`.
* [Bare modules](/reference/modules/bare-modules) — the full `bare-*` catalog.
* [Bare runtime API](/reference/bare/runtime) — the runtime these modules extend.


# bare-vm



<mark style={{ backgroundColor: '#7dde9a', padding: '2px 8px', borderRadius: '4px', fontSize: '0.85em', fontWeight: 500 }}>
  stable
</mark>

[`bare-vm`](https://github.com/holepunchto/bare-vm) — Isolated JavaScript contexts for Bare.

```sh
npm i bare-vm
```

Usage [#usage]

```js
const vm = require('bare-vm')

const context = vm.createContext()
vm.runInContext('x = 40; x += 2', context) // 42

vm.runInNewContext('x = 40; x += 2') // 42
```

API [#api]

Functions [#functions]

createContext(): Context [#createcontext-context]

Create and return a new isolated global context that code can be run in with `runInContext()`.

**Returns** [`Context`](#context) — A new isolated global context that code can be run in with `runInContext()`.

runInContext(code: string, context: Context, options?: RunOptions): unknown [#runincontextcode-string-context-context-options-runoptions-unknown]

Run `code` inside `context`, a context previously created with `createContext()`, and return the result.

**Parameters**

| Parameter  | Type                        | Default | Description                                                                                                                                                                                              |
| ---------- | --------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `code`     | `string`                    | —       | The JavaScript source to run.                                                                                                                                                                            |
| `context`  | [`Context`](#context)       | —       | A context previously created with `createContext()`.                                                                                                                                                     |
| `options?` | [`RunOptions`](#runoptions) | —       | Options. `filename` is the script name used in stack traces (default `'<anonymous>'`); `offset` shifts the reported line numbers (default `0`, also accepted as `lineOffset` for Node.js compatibility). |

**Returns** `unknown` — The completion value of `code`.

runInNewContext(code: string, options?: RunOptions): unknown [#runinnewcontextcode-string-options-runoptions-unknown]

Create a new context and run `code` inside it in one step, equivalent to calling `createContext()` followed by `runInContext()`.

**Parameters**

| Parameter  | Type                        | Default | Description                                                                                                                                                                                              |
| ---------- | --------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `code`     | `string`                    | —       | The JavaScript source to run.                                                                                                                                                                            |
| `options?` | [`RunOptions`](#runoptions) | —       | Options. `filename` is the script name used in stack traces (default `'<anonymous>'`); `offset` shifts the reported line numbers (default `0`, also accepted as `lineOffset` for Node.js compatibility). |

**Returns** `unknown` — The completion value of `code`.

Types [#types]

Context [#context]

```ts
interface Context {
}
```

RunOptions [#runoptions]

```ts
interface RunOptions {
  filename?: string
  offset?: number
}
```

See also [#see-also]

* Builds on `bare-realm`.
* [Bare modules](/reference/modules/bare-modules) — the full `bare-*` catalog.
* [Bare runtime API](/reference/bare/runtime) — the runtime these modules extend.


# bare-ws



<mark style={{ backgroundColor: '#7dde9a', padding: '2px 8px', borderRadius: '4px', fontSize: '0.85em', fontWeight: 500 }}>
  stable
</mark>

[`bare-ws`](https://github.com/holepunchto/bare-ws) — WebSocket library for JavaScript.

```sh
npm i bare-ws
```

Usage [#usage]

```js
const ws = require('bare-ws')

const server = new ws.Server({ port: 8080 }, (socket) => {
  socket.on('data', (data) => {
    console.log(data.toString())
  })
})

server.on('listening', () => {
  const socket = new ws.Socket({ port: 8080 })

  socket.write('Hello WebSocket')
})
```

API [#api]

Socket [#socket]

new Socket(opts: WebSocketOptions) [#new-socketopts-websocketoptions]

Open a WebSocket connection to `url`, or wrap an already-connected `opts.socket` when acting as the server side of a handshake.

Overloads:

```ts
new Socket(opts: WebSocketOptions)
new Socket(url: URL | string, opts?: WebSocketOptions)
```

**Parameters**

| Parameter | Type               | Default | Description                                                                                                |
| --------- | ------------------ | ------- | ---------------------------------------------------------------------------------------------------------- |
| `opts`    | `WebSocketOptions` | —       | Connection options: `host`/`hostname`, `port`, `path`, `secure`, or an already-connected `socket` to wrap. |

ping(data: unknown): void [#pingdata-unknown-void]

Send a WebSocket ping frame with `data` as its payload.

**Parameters**

| Parameter | Type      | Default | Description                                                         |
| --------- | --------- | ------- | ------------------------------------------------------------------- |
| `data`    | `unknown` | —       | The payload of the ping frame; a string is converted to a `Buffer`. |

**Throws**

* `NOT_CONNECTED` — the socket has not finished connecting.

pong(data: unknown): void [#pongdata-unknown-void]

Send a WebSocket pong frame with `data` as its payload.

**Parameters**

| Parameter | Type      | Default | Description                                                         |
| --------- | --------- | ------- | ------------------------------------------------------------------- |
| `data`    | `unknown` | —       | The payload of the pong frame; a string is converted to a `Buffer`. |

**Throws**

* `NOT_CONNECTED` — the socket has not finished connecting.

Socket.handshake(req: HTTPClientRequest, cb: (error: WebSocketError | null) => void): void [#sockethandshakereq-httpclientrequest-cb-error-websocketerror--null--void-void]

Perform the client side of the WebSocket opening handshake over `req`, calling `cb` with a `WebSocketError` if the server's response is invalid.

**Parameters**

| Parameter | Type                                      | Default | Description                                                                                           |
| --------- | ----------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------- |
| `req`     | `HTTPClientRequest`                       | —       | The outgoing HTTP request to upgrade; the WebSocket handshake headers are added to it.                |
| `cb`      | `(error: WebSocketError \| null) => void` | —       | Called once the server's response is validated, with a `WebSocketError` on failure, otherwise `null`. |

Socket.WebSocketEvents [#socketwebsocketevents]

```ts
interface WebSocketEvents {
  ping: [payload: unknown]
  pong: [payload: unknown]
  data: [data: unknown]
  end: []
  readable: []
  piping: [dest: Writable]
  close: []
  error: [err: Error]
  drain: []
  finish: []
  pipe: [src: Readable]
}
```

Socket.WebSocketOptions [#socketwebsocketoptions]

```ts
interface WebSocketOptions {
  host?: string
  hostname?: string
  path?: string
  port?: string | number
  secure?: boolean
  socket?: TCPSocket
}
```

`host`/`hostname` (an alias for `host`, for Node.js compatibility), `port`, and `path` address the connection. `secure` uses TLS (`wss:`) for the underlying connection when `true`. `socket` is an already-connected TCP socket to use instead of opening a new connection.

Server [#server]

new Server(onconnection: (socket: WebSocket, req: HTTPClientRequest) => void) [#new-serveronconnection-socket-websocket-req-httpclientrequest--void]

Create a server, optionally backed by `opts.server`, and emit `connection` for each successful WebSocket upgrade.

Overloads:

```ts
new Server(onconnection: (socket: WebSocket, req: HTTPClientRequest) => void)
new Server(opts?: WebSocketServerOptions, onconnection?: (socket: WebSocket, req: HTTPClientRequest) => void)
```

**Parameters**

| Parameter      | Type                                                  | Default | Description                          |
| -------------- | ----------------------------------------------------- | ------- | ------------------------------------ |
| `onconnection` | `(socket: WebSocket, req: HTTPClientRequest) => void` | —       | Called on each `'connection'` event. |

address(): TCPSocketAddress [#address-tcpsocketaddress]

Return the bound address of the underlying TCP server.

close(cb?: (err?: Error | null) => void): this [#closecb-err-error--null--void-this]

Stop the server from accepting new connections, calling `cb` once it has closed.

**Parameters**

| Parameter | Type                            | Default | Description                                   |
| --------- | ------------------------------- | ------- | --------------------------------------------- |
| `cb?`     | `(err?: Error \| null) => void` | —       | Called once the underlying server has closed. |

listening: boolean [#listening-boolean]

`true` once the underlying server is bound and accepting connections.

ref(): this [#ref-this]

Ref the underlying server so it keeps the event loop alive.

Server.handshake(req: HTTPClientRequest, cb: (err: WebSocketError | null) => void): void [#serverhandshakereq-httpclientrequest-cb-err-websocketerror--null--void-void]

Perform the server side of the WebSocket opening handshake for `req`, writing the `101` upgrade response on `socket` and calling `cb` with a `WebSocketError` on failure.

Overloads:

```ts
Server.handshake(req: HTTPClientRequest, cb: (err: WebSocketError | null) => void): void
Server.handshake(req: HTTPClientRequest, socket: TCPSocket, cb?: (err: WebSocketError | null) => void): void
Server.handshake(req: HTTPClientRequest, socket?: TCPSocket, head?: Buffer, cb?: (err: WebSocketError | null) => void): void
```

**Parameters**

| Parameter | Type                                    | Default | Description                                                                                       |
| --------- | --------------------------------------- | ------- | ------------------------------------------------------------------------------------------------- |
| `req`     | `HTTPClientRequest`                     | —       | The incoming upgrade request.                                                                     |
| `cb`      | `(err: WebSocketError \| null) => void` | —       | Called with a `WebSocketError` if the request is not a valid WebSocket upgrade, otherwise `null`. |

Server.WebSocketServerEvents [#serverwebsocketserverevents]

```ts
interface WebSocketServerEvents {
  connection: [socket: WebSocket, req: HTTPClientRequest]
  listening: []
  data: [data: unknown]
  end: []
  readable: []
  piping: [dest: Writable]
  close: []
  error: [err: Error]
  drain: []
  finish: []
  pipe: [src: Readable]
}
```

Server.WebSocketServerOptions [#serverwebsocketserveroptions]

```ts
interface WebSocketServerOptions {
  secure?: boolean
  IncomingMessage?: typeof HTTPIncomingMessage
  ServerResponse?: typeof HTTPServerResponse
}
```

`secure` creates an HTTPS-backed server, accepting `wss:` connections, when `true`.

unref(): this [#unref-this]

Unref the underlying server so it does not keep the event loop alive on its own.

bare-ws/global [#bare-wsglobal]

Types [#types]

WebSocketConstructor [#websocketconstructor]

```ts
type WebSocketConstructor = typeof ws.Socket
```

The type of the `Socket` class, used to type the global `WebSocket` constructor.

bare-ws/constants [#bare-wsconstants]

Constants and variables [#constants-and-variables]

EOL: string [#eol-string]

The line ending (`\r\n`) used when writing the handshake response.

EOF: string [#eof-string]

The blank-line terminator (`\r\n\r\n`) that ends the handshake response headers.

GUID: Buffer [#guid-buffer]

The WebSocket protocol's fixed GUID, concatenated with the `Sec-WebSocket-Key` to compute the `Sec-WebSocket-Accept` digest.

opcode [#opcode]

```ts
opcode: {
  CONTINUATION: number
  TEXT: number
  BINARY: number
  CLOSE: number
  PING: number
  PONG: number
}
```

The WebSocket frame opcodes (`CONTINUATION`, `TEXT`, `BINARY`, `CLOSE`, `PING`, `PONG`) as defined by RFC 6455.

status: { PROTOCOL_ERROR: number; MESSAGE_TOO_LARGE: number } [#status--protocol_error-number-message_too_large-number-]

WebSocket close status codes for protocol errors (`PROTOCOL_ERROR`) and oversized messages (`MESSAGE_TOO_LARGE`).

bare-ws/errors [#bare-wserrors]

WebSocketError [#websocketerror]

WebSocketError [#websocketerror-1]

```ts
new WebSocketError(msg: string, code: string, status: number, fn?: WebSocketError, cause?: unknown)
```

An error thrown for WebSocket protocol violations, carrying a `code` and a close `status`.

**Parameters**

| Parameter | Type             | Default | Description                                                                                               |
| --------- | ---------------- | ------- | --------------------------------------------------------------------------------------------------------- |
| `msg`     | `string`         | —       | The error message.                                                                                        |
| `code`    | `string`         | —       | The error code.                                                                                           |
| `status`  | `number`         | —       | The WebSocket close status associated with the error.                                                     |
| `fn?`     | `WebSocketError` | —       | Optional function to omit from the top of the generated stack trace, passed to `Error.captureStackTrace`. |
| `cause?`  | `unknown`        | —       | The underlying cause of the error, if any.                                                                |

WebSocketError.EXPECTED_CONTINUATION(msg?: string): WebSocketError [#websocketerrorexpected_continuationmsg-string-websocketerror]

A fragmented message's next frame was not a continuation frame.

**Parameters**

| Parameter | Type     | Default | Description        |
| --------- | -------- | ------- | ------------------ |
| `msg?`    | `string` | —       | The error message. |

**Returns** `WebSocketError` — A `WebSocketError` with `code` set to `'EXPECTED_CONTINUATION'`, for the caller to throw.

WebSocketError.EXPECTED_MASK(msg?: string): WebSocketError [#websocketerrorexpected_maskmsg-string-websocketerror]

A frame from a client was missing its required mask.

**Parameters**

| Parameter | Type     | Default | Description        |
| --------- | -------- | ------- | ------------------ |
| `msg?`    | `string` | —       | The error message. |

**Returns** `WebSocketError` — A `WebSocketError` with `code` set to `'EXPECTED_MASK'`, for the caller to throw.

WebSocketError.INCOMPLETE_FRAME(msg?: string, length?: number): WebSocketError [#websocketerrorincomplete_framemsg-string-length-number-websocketerror]

The buffered data does not yet contain a full frame.

**Parameters**

| Parameter | Type     | Default | Description                                                                                                  |
| --------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------ |
| `msg?`    | `string` | —       | The error message.                                                                                           |
| `length?` | `number` | —       | The total byte length the frame needs before it can be decoded, stored as the error `status` (default `-1`). |

**Returns** `WebSocketError` — A `WebSocketError` with `code` set to `'INCOMPLETE_FRAME'` and `status` set to `length`, for the caller to throw.

WebSocketError.INVALID_ACCEPT_HEADER(msg?: string): WebSocketError [#websocketerrorinvalid_accept_headermsg-string-websocketerror]

The `Sec-WebSocket-Accept` header in the server's handshake response did not match the expected digest.

**Parameters**

| Parameter | Type     | Default | Description        |
| --------- | -------- | ------- | ------------------ |
| `msg?`    | `string` | —       | The error message. |

**Returns** `WebSocketError` — A `WebSocketError` with `code` set to `'INVALID_ACCEPT_HEADER'`, for the caller to throw.

WebSocketError.INVALID_ENCODING(msg?: string): WebSocketError [#websocketerrorinvalid_encodingmsg-string-websocketerror]

Data was written with an encoding other than `buffer` or `utf8`.

**Parameters**

| Parameter | Type     | Default | Description        |
| --------- | -------- | ------- | ------------------ |
| `msg?`    | `string` | —       | The error message. |

**Returns** `WebSocketError` — A `WebSocketError` with `code` set to `'INVALID_ENCODING'`, for the caller to throw.

WebSocketError.INVALID_KEY_HEADER(msg?: string): WebSocketError [#websocketerrorinvalid_key_headermsg-string-websocketerror]

The `Sec-WebSocket-Key` header was missing or malformed.

**Parameters**

| Parameter | Type     | Default | Description        |
| --------- | -------- | ------- | ------------------ |
| `msg?`    | `string` | —       | The error message. |

**Returns** `WebSocketError` — A `WebSocketError` with `code` set to `'INVALID_KEY_HEADER'`, for the caller to throw.

WebSocketError.INVALID_OPCODE(msg?: string): WebSocketError [#websocketerrorinvalid_opcodemsg-string-websocketerror]

A frame was received with an opcode that is not `TEXT` or `BINARY`.

**Parameters**

| Parameter | Type     | Default | Description        |
| --------- | -------- | ------- | ------------------ |
| `msg?`    | `string` | —       | The error message. |

**Returns** `WebSocketError` — A `WebSocketError` with `code` set to `'INVALID_OPCODE'`, for the caller to throw.

WebSocketError.INVALID_PAYLOAD_LENGTH(msg?: string): WebSocketError [#websocketerrorinvalid_payload_lengthmsg-string-websocketerror]

A frame's payload length field was invalid.

**Parameters**

| Parameter | Type     | Default | Description        |
| --------- | -------- | ------- | ------------------ |
| `msg?`    | `string` | —       | The error message. |

**Returns** `WebSocketError` — A `WebSocketError` with `code` set to `'INVALID_PAYLOAD_LENGTH'`, for the caller to throw.

WebSocketError.INVALID_UPGRADE_HEADER(msg?: string): WebSocketError [#websocketerrorinvalid_upgrade_headermsg-string-websocketerror]

The `Upgrade` header was missing or not `websocket`.

**Parameters**

| Parameter | Type     | Default | Description        |
| --------- | -------- | ------- | ------------------ |
| `msg?`    | `string` | —       | The error message. |

**Returns** `WebSocketError` — A `WebSocketError` with `code` set to `'INVALID_UPGRADE_HEADER'`, for the caller to throw.

WebSocketError.INVALID_VERSION_HEADER(msg?: string): WebSocketError [#websocketerrorinvalid_version_headermsg-string-websocketerror]

The `Sec-WebSocket-Version` header was neither `8` nor `13`.

**Parameters**

| Parameter | Type     | Default | Description        |
| --------- | -------- | ------- | ------------------ |
| `msg?`    | `string` | —       | The error message. |

**Returns** `WebSocketError` — A `WebSocketError` with `code` set to `'INVALID_VERSION_HEADER'`, for the caller to throw.

WebSocketError.NETWORK_ERROR(msg: string, cause?: unknown): WebSocketError [#websocketerrornetwork_errormsg-string-cause-unknown-websocketerror]

The underlying HTTP request errored before the handshake completed.

**Parameters**

| Parameter | Type      | Default | Description           |
| --------- | --------- | ------- | --------------------- |
| `msg`     | `string`  | —       | The error message.    |
| `cause?`  | `unknown` | —       | The underlying error. |

**Returns** `WebSocketError` — A `WebSocketError` with `code` set to `'NETWORK_ERROR'`, for the caller to throw.

WebSocketError.NOT_CONNECTED(msg?: string): WebSocketError [#websocketerrornot_connectedmsg-string-websocketerror]

An operation, such as `ping()` or `pong()`, was attempted before the socket finished connecting.

**Parameters**

| Parameter | Type     | Default | Description        |
| --------- | -------- | ------- | ------------------ |
| `msg?`    | `string` | —       | The error message. |

**Returns** `WebSocketError` — A `WebSocketError` with `code` set to `'NOT_CONNECTED'`, for the caller to throw.

WebSocketError.UNEXPECTED_CONTINUATION(msg?: string): WebSocketError [#websocketerrorunexpected_continuationmsg-string-websocketerror]

A continuation frame was received without a preceding fragmented frame.

**Parameters**

| Parameter | Type     | Default | Description        |
| --------- | -------- | ------- | ------------------ |
| `msg?`    | `string` | —       | The error message. |

**Returns** `WebSocketError` — A `WebSocketError` with `code` set to `'UNEXPECTED_CONTINUATION'`, for the caller to throw.

WebSocketError.UNEXPECTED_CONTROL(msg?: string): WebSocketError [#websocketerrorunexpected_controlmsg-string-websocketerror]

A control frame was received while a fragmented message was in progress.

**Parameters**

| Parameter | Type     | Default | Description        |
| --------- | -------- | ------- | ------------------ |
| `msg?`    | `string` | —       | The error message. |

**Returns** `WebSocketError` — A `WebSocketError` with `code` set to `'UNEXPECTED_CONTROL'`, for the caller to throw.

WebSocketError.UNEXPECTED_RSV1(msg?: string): WebSocketError [#websocketerrorunexpected_rsv1msg-string-websocketerror]

A frame was received with the reserved RSV1 bit set.

**Parameters**

| Parameter | Type     | Default | Description        |
| --------- | -------- | ------- | ------------------ |
| `msg?`    | `string` | —       | The error message. |

**Returns** `WebSocketError` — A `WebSocketError` with `code` set to `'UNEXPECTED_RSV1'`, for the caller to throw.

WebSocketError.UNEXPECTED_RSV2(msg?: string): WebSocketError [#websocketerrorunexpected_rsv2msg-string-websocketerror]

A frame was received with the reserved RSV2 bit set.

**Parameters**

| Parameter | Type     | Default | Description        |
| --------- | -------- | ------- | ------------------ |
| `msg?`    | `string` | —       | The error message. |

**Returns** `WebSocketError` — A `WebSocketError` with `code` set to `'UNEXPECTED_RSV2'`, for the caller to throw.

WebSocketError.UNEXPECTED_RSV3(msg?: string): WebSocketError [#websocketerrorunexpected_rsv3msg-string-websocketerror]

A frame was received with the reserved RSV3 bit set.

**Parameters**

| Parameter | Type     | Default | Description        |
| --------- | -------- | ------- | ------------------ |
| `msg?`    | `string` | —       | The error message. |

**Returns** `WebSocketError` — A `WebSocketError` with `code` set to `'UNEXPECTED_RSV3'`, for the caller to throw.

See also [#see-also]

* Builds on `bare-crypto`, `bare-events`, `bare-http1`, `bare-https`, and `bare-stream`.
* It's pure JavaScript. Sockets are [`bare-stream`](/reference/bare/modules/bare-stream) duplex streams that perform the WebSocket handshake over an HTTP or HTTPS request.
* [`bare-tcp`](/reference/bare/modules/bare-tcp) — the socket layer WebSocket connections run over.
* [`bare-fetch`](/reference/bare/modules/bare-fetch) — a request/response HTTP client for the non-persistent case.
* [Bare modules](/reference/modules/bare-modules) — the full `bare-*` catalog.
* [Bare runtime API](/reference/bare/runtime) — the runtime these modules extend.


# bare-zlib



<mark style={{ backgroundColor: '#7dde9a', padding: '2px 8px', borderRadius: '4px', fontSize: '0.85em', fontWeight: 500 }}>
  stable
</mark>

[`bare-zlib`](https://github.com/holepunchto/bare-zlib) — Stream-based zlib bindings for JavaScript. It is a native addon.

Mirrors the Node.js [`zlib`](https://nodejs.org/api/zlib.html) module.

```sh
npm i bare-zlib
```

API [#api]

Zlib [#zlib]

Zlib.constants [#zlibconstants]

```ts
Zlib.constants: {
  Z_NO_FLUSH: number
  Z_PARTIAL_FLUSH: number
  Z_SYNC_FLUSH: number
  Z_FULL_FLUSH: number
  Z_FINISH: number
  Z_BLOCK: number
  Z_TREES: number

  Z_FILTERED: number
  Z_HUFFMAN_ONLY: number
  Z_RLE: number
  Z_FIXED: number
  Z_DEFAULT_STRATEGY: number

  Z_NO_COMPRESSION: number
  Z_BEST_SPEED: number
  Z_BEST_COMPRESSION: number
  Z_DEFAULT_COMPRESSION: number

  Z_MIN_CHUNK: number
  Z_MAX_CHUNK: number
  Z_DEFAULT_CHUNK: number

  Z_MIN_MEMLEVEL: number
  Z_MAX_MEMLEVEL: number
  Z_DEFAULT_MEMLEVEL: number

  Z_MIN_LEVEL: number
  Z_MAX_LEVEL: number
  Z_DEFAULT_LEVEL: number

  Z_MIN_WINDOWBITS: number
  Z_MAX_WINDOWBITS: number
  Z_DEFAULT_WINDOWBITS: number

  Z_OK: number
  Z_STREAM_END: number
  Z_NEED_DICT: number
  Z_ERRNO: number
  Z_STREAM_ERROR: number
  Z_DATA_ERROR: number
  Z_MEM_ERROR: number
  Z_BUF_ERROR: number
  Z_VERSION_ERROR: number
}
```

Zlib-related constants such as flush modes, compression levels, strategies, and chunk/window/memory-level bounds.

Zlib.createDeflate(opts?: ZlibOptions): Deflate [#zlibcreatedeflateopts-zliboptions-deflate]

Create and return a new `Deflate` stream for streaming zlib compression.

**Parameters**

| Parameter | Type                          | Default | Description                                           |
| --------- | ----------------------------- | ------- | ----------------------------------------------------- |
| `opts?`   | [`ZlibOptions`](#zliboptions) | —       | Options for the stream and the underlying zlib state. |

Zlib.createDeflateRaw(opts?: ZlibOptions): DeflateRaw [#zlibcreatedeflaterawopts-zliboptions-deflateraw]

Create and return a new `DeflateRaw` stream for streaming raw deflate compression, without a zlib header.

**Parameters**

| Parameter | Type                          | Default | Description                                           |
| --------- | ----------------------------- | ------- | ----------------------------------------------------- |
| `opts?`   | [`ZlibOptions`](#zliboptions) | —       | Options for the stream and the underlying zlib state. |

Zlib.createGunzip(opts?: ZlibOptions): Gunzip [#zlibcreategunzipopts-zliboptions-gunzip]

Create and return a new `Gunzip` stream for streaming gzip decompression.

**Parameters**

| Parameter | Type                          | Default | Description                                           |
| --------- | ----------------------------- | ------- | ----------------------------------------------------- |
| `opts?`   | [`ZlibOptions`](#zliboptions) | —       | Options for the stream and the underlying zlib state. |

Zlib.createGzip(opts?: ZlibOptions): Gzip [#zlibcreategzipopts-zliboptions-gzip]

Create and return a new `Gzip` stream for streaming gzip compression.

**Parameters**

| Parameter | Type                          | Default | Description                                           |
| --------- | ----------------------------- | ------- | ----------------------------------------------------- |
| `opts?`   | [`ZlibOptions`](#zliboptions) | —       | Options for the stream and the underlying zlib state. |

Zlib.createInflate(opts?: ZlibOptions): Inflate [#zlibcreateinflateopts-zliboptions-inflate]

Create and return a new `Inflate` stream for streaming zlib decompression.

**Parameters**

| Parameter | Type                          | Default | Description                                           |
| --------- | ----------------------------- | ------- | ----------------------------------------------------- |
| `opts?`   | [`ZlibOptions`](#zliboptions) | —       | Options for the stream and the underlying zlib state. |

Zlib.createInflateRaw(opts?: ZlibOptions): InflateRaw [#zlibcreateinflaterawopts-zliboptions-inflateraw]

Create and return a new `InflateRaw` stream for streaming raw deflate decompression, without a zlib header.

**Parameters**

| Parameter | Type                          | Default | Description                                           |
| --------- | ----------------------------- | ------- | ----------------------------------------------------- |
| `opts?`   | [`ZlibOptions`](#zliboptions) | —       | Options for the stream and the underlying zlib state. |

Zlib.deflate(buffer: ZlibInput, opts: ZlibOptions, cb: ZlibCallback): void [#zlibdeflatebuffer-zlibinput-opts-zliboptions-cb-zlibcallback-void]

Compress `buffer` with deflate, calling `cb` with the resulting `Buffer`.

Overloads:

```ts
Zlib.deflate(buffer: ZlibInput, opts: ZlibOptions, cb: ZlibCallback): void
Zlib.deflate(buffer: ZlibInput, cb: ZlibCallback): void
```

**Parameters**

| Parameter | Type                            | Default | Description                                                                  |
| --------- | ------------------------------- | ------- | ---------------------------------------------------------------------------- |
| `buffer`  | `ZlibInput`                     | —       | The data to compress.                                                        |
| `opts`    | [`ZlibOptions`](#zliboptions)   | —       | The zlib options to apply for this operation.                                |
| `cb`      | [`ZlibCallback`](#zlibcallback) | —       | Called with the resulting `Buffer`, or with an error if the operation fails. |

Zlib.deflateRaw(buffer: ZlibInput, opts: ZlibOptions, cb: ZlibCallback): void [#zlibdeflaterawbuffer-zlibinput-opts-zliboptions-cb-zlibcallback-void]

Compress `buffer` with raw deflate, without a zlib header, calling `cb` with the resulting `Buffer`.

Overloads:

```ts
Zlib.deflateRaw(buffer: ZlibInput, opts: ZlibOptions, cb: ZlibCallback): void
Zlib.deflateRaw(buffer: ZlibInput, cb: ZlibCallback): void
```

**Parameters**

| Parameter | Type                            | Default | Description                                                                  |
| --------- | ------------------------------- | ------- | ---------------------------------------------------------------------------- |
| `buffer`  | `ZlibInput`                     | —       | The data to compress.                                                        |
| `opts`    | [`ZlibOptions`](#zliboptions)   | —       | The zlib options to apply for this operation.                                |
| `cb`      | [`ZlibCallback`](#zlibcallback) | —       | Called with the resulting `Buffer`, or with an error if the operation fails. |

Zlib.deflateRawSync(buffer: ZlibInput, opts?: ZlibOptions): Buffer [#zlibdeflaterawsyncbuffer-zlibinput-opts-zliboptions-buffer]

Synchronously compress `buffer` with raw deflate, without a zlib header, and return the resulting `Buffer`.

**Parameters**

| Parameter | Type                          | Default | Description                                                |
| --------- | ----------------------------- | ------- | ---------------------------------------------------------- |
| `buffer`  | `ZlibInput`                   | —       | The data to compress; a string is converted to a `Buffer`. |
| `opts?`   | [`ZlibOptions`](#zliboptions) | —       | The zlib options to apply for this operation.              |

**Throws**

* `LIMIT_EXCEEDED` — the output exceeded `maxOutputLength`.
* `ZlibError` — the underlying zlib operation failed; `code` identifies the failure.

Zlib.deflateSync(buffer: ZlibInput, opts?: ZlibOptions): Buffer [#zlibdeflatesyncbuffer-zlibinput-opts-zliboptions-buffer]

Synchronously compress `buffer` with deflate and return the resulting `Buffer`.

**Parameters**

| Parameter | Type                          | Default | Description                                                |
| --------- | ----------------------------- | ------- | ---------------------------------------------------------- |
| `buffer`  | `ZlibInput`                   | —       | The data to compress; a string is converted to a `Buffer`. |
| `opts?`   | [`ZlibOptions`](#zliboptions) | —       | The zlib options to apply for this operation.              |

**Throws**

* `LIMIT_EXCEEDED` — the output exceeded `maxOutputLength`.
* `ZlibError` — the underlying zlib operation failed; `code` identifies the failure.

Zlib.gunzip(buffer: ZlibInput, opts: ZlibOptions, cb: ZlibCallback): void [#zlibgunzipbuffer-zlibinput-opts-zliboptions-cb-zlibcallback-void]

Decompress `buffer` as gzip, calling `cb` with the resulting `Buffer`.

Overloads:

```ts
Zlib.gunzip(buffer: ZlibInput, opts: ZlibOptions, cb: ZlibCallback): void
Zlib.gunzip(buffer: ZlibInput, cb: ZlibCallback): void
```

**Parameters**

| Parameter | Type                            | Default | Description                                                                  |
| --------- | ------------------------------- | ------- | ---------------------------------------------------------------------------- |
| `buffer`  | `ZlibInput`                     | —       | The data to decompress.                                                      |
| `opts`    | [`ZlibOptions`](#zliboptions)   | —       | The zlib options to apply for this operation.                                |
| `cb`      | [`ZlibCallback`](#zlibcallback) | —       | Called with the resulting `Buffer`, or with an error if the operation fails. |

Zlib.gunzipSync(buffer: ZlibInput, opts?: ZlibOptions): Buffer [#zlibgunzipsyncbuffer-zlibinput-opts-zliboptions-buffer]

Synchronously decompress `buffer` as gzip and return the resulting `Buffer`.

**Parameters**

| Parameter | Type                          | Default | Description                                                  |
| --------- | ----------------------------- | ------- | ------------------------------------------------------------ |
| `buffer`  | `ZlibInput`                   | —       | The data to decompress; a string is converted to a `Buffer`. |
| `opts?`   | [`ZlibOptions`](#zliboptions) | —       | The zlib options to apply for this operation.                |

**Throws**

* `LIMIT_EXCEEDED` — the output exceeded `maxOutputLength`.
* `ZlibError` — the underlying zlib operation failed; `code` (such as `DATA_ERROR`) identifies the failure.

Zlib.gzip(buffer: ZlibInput, opts: ZlibOptions, cb: ZlibCallback): void [#zlibgzipbuffer-zlibinput-opts-zliboptions-cb-zlibcallback-void]

Compress `buffer` as gzip, calling `cb` with the resulting `Buffer`.

Overloads:

```ts
Zlib.gzip(buffer: ZlibInput, opts: ZlibOptions, cb: ZlibCallback): void
Zlib.gzip(buffer: ZlibInput, cb: ZlibCallback): void
```

**Parameters**

| Parameter | Type                            | Default | Description                                                                  |
| --------- | ------------------------------- | ------- | ---------------------------------------------------------------------------- |
| `buffer`  | `ZlibInput`                     | —       | The data to compress.                                                        |
| `opts`    | [`ZlibOptions`](#zliboptions)   | —       | The zlib options to apply for this operation.                                |
| `cb`      | [`ZlibCallback`](#zlibcallback) | —       | Called with the resulting `Buffer`, or with an error if the operation fails. |

Zlib.gzipSync(buffer: ZlibInput, opts?: ZlibOptions): Buffer [#zlibgzipsyncbuffer-zlibinput-opts-zliboptions-buffer]

Synchronously compress `buffer` as gzip and return the resulting `Buffer`.

**Parameters**

| Parameter | Type                          | Default | Description                                                |
| --------- | ----------------------------- | ------- | ---------------------------------------------------------- |
| `buffer`  | `ZlibInput`                   | —       | The data to compress; a string is converted to a `Buffer`. |
| `opts?`   | [`ZlibOptions`](#zliboptions) | —       | The zlib options to apply for this operation.              |

**Throws**

* `LIMIT_EXCEEDED` — the output exceeded `maxOutputLength`.
* `ZlibError` — the underlying zlib operation failed; `code` identifies the failure.

Zlib.inflate(buffer: ZlibInput, opts: ZlibOptions, cb: ZlibCallback): void [#zlibinflatebuffer-zlibinput-opts-zliboptions-cb-zlibcallback-void]

Decompress `buffer` with inflate, calling `cb` with the resulting `Buffer`.

Overloads:

```ts
Zlib.inflate(buffer: ZlibInput, opts: ZlibOptions, cb: ZlibCallback): void
Zlib.inflate(buffer: ZlibInput, cb: ZlibCallback): void
```

**Parameters**

| Parameter | Type                            | Default | Description                                                                  |
| --------- | ------------------------------- | ------- | ---------------------------------------------------------------------------- |
| `buffer`  | `ZlibInput`                     | —       | The data to decompress.                                                      |
| `opts`    | [`ZlibOptions`](#zliboptions)   | —       | The zlib options to apply for this operation.                                |
| `cb`      | [`ZlibCallback`](#zlibcallback) | —       | Called with the resulting `Buffer`, or with an error if the operation fails. |

Zlib.inflateRaw(buffer: ZlibInput, opts: ZlibOptions, cb: ZlibCallback): void [#zlibinflaterawbuffer-zlibinput-opts-zliboptions-cb-zlibcallback-void]

Decompress `buffer` with raw inflate, without a zlib header, calling `cb` with the resulting `Buffer`.

Overloads:

```ts
Zlib.inflateRaw(buffer: ZlibInput, opts: ZlibOptions, cb: ZlibCallback): void
Zlib.inflateRaw(buffer: ZlibInput, cb: ZlibCallback): void
```

**Parameters**

| Parameter | Type                            | Default | Description                                                                  |
| --------- | ------------------------------- | ------- | ---------------------------------------------------------------------------- |
| `buffer`  | `ZlibInput`                     | —       | The data to decompress.                                                      |
| `opts`    | [`ZlibOptions`](#zliboptions)   | —       | The zlib options to apply for this operation.                                |
| `cb`      | [`ZlibCallback`](#zlibcallback) | —       | Called with the resulting `Buffer`, or with an error if the operation fails. |

Zlib.inflateRawSync(buffer: ZlibInput, opts?: ZlibOptions): Buffer [#zlibinflaterawsyncbuffer-zlibinput-opts-zliboptions-buffer]

Synchronously decompress `buffer` with raw inflate, without a zlib header, and return the resulting `Buffer`.

**Parameters**

| Parameter | Type                          | Default | Description                                                  |
| --------- | ----------------------------- | ------- | ------------------------------------------------------------ |
| `buffer`  | `ZlibInput`                   | —       | The data to decompress; a string is converted to a `Buffer`. |
| `opts?`   | [`ZlibOptions`](#zliboptions) | —       | The zlib options to apply for this operation.                |

**Throws**

* `LIMIT_EXCEEDED` — the output exceeded `maxOutputLength`.
* `ZlibError` — the underlying zlib operation failed; `code` (such as `DATA_ERROR`) identifies the failure.

Zlib.inflateSync(buffer: ZlibInput, opts?: ZlibOptions): Buffer [#zlibinflatesyncbuffer-zlibinput-opts-zliboptions-buffer]

Synchronously decompress `buffer` with inflate and return the resulting `Buffer`.

**Parameters**

| Parameter | Type                          | Default | Description                                                  |
| --------- | ----------------------------- | ------- | ------------------------------------------------------------ |
| `buffer`  | `ZlibInput`                   | —       | The data to decompress; a string is converted to a `Buffer`. |
| `opts?`   | [`ZlibOptions`](#zliboptions) | —       | The zlib options to apply for this operation.                |

**Throws**

* `LIMIT_EXCEEDED` — the output exceeded `maxOutputLength`.
* `ZlibError` — the underlying zlib operation failed; `code` (such as `DATA_ERROR`) identifies the failure.

Zlib.ZlibInput [#zlibzlibinput]

```ts
type ZlibInput = string | Buffer | Uint8Array
```

The input accepted by the one-shot functions: a string, `Buffer`, or `Uint8Array`.

ZlibStream [#zlibstream]

flush(mode?: number, cb?: ZlibFlushCallback): Promise<void> [#flushmode-number-cb-zlibflushcallback-promisevoid]

Flush queued data through the stream immediately using the given flush `mode`, resolving once it has drained.

Overloads:

```ts
flush(mode?: number, cb?: ZlibFlushCallback): Promise<void>
flush(cb: ZlibFlushCallback): Promise<void>
```

**Parameters**

| Parameter | Type                                      | Default | Description                                                                                        |
| --------- | ----------------------------------------- | ------- | -------------------------------------------------------------------------------------------------- |
| `mode?`   | `number`                                  | —       | The flush mode, from `constants` (default `Z_FULL_FLUSH`).                                         |
| `cb?`     | [`ZlibFlushCallback`](#zlibflushcallback) | —       | Called once the flush completes, for Node.js compatibility; the returned promise resolves as well. |

reset(): void [#reset-void]

Reset the underlying compressor or decompressor to its initial state.

**Throws**

* `STREAM_CLOSED` — the stream has already closed.

Deflate [#deflate]

new Deflate(opts?: ZlibOptions) [#new-deflateopts-zliboptions]

Create a `Deflate` stream with the given `opts`.

**Parameters**

| Parameter | Type                          | Default | Description                                           |
| --------- | ----------------------------- | ------- | ----------------------------------------------------- |
| `opts?`   | [`ZlibOptions`](#zliboptions) | —       | Options for the stream and the underlying zlib state. |

Inflate [#inflate]

new Inflate(opts?: ZlibOptions) [#new-inflateopts-zliboptions]

Create an `Inflate` stream with the given `opts`.

**Parameters**

| Parameter | Type                          | Default | Description                                           |
| --------- | ----------------------------- | ------- | ----------------------------------------------------- |
| `opts?`   | [`ZlibOptions`](#zliboptions) | —       | Options for the stream and the underlying zlib state. |

DeflateRaw [#deflateraw]

new DeflateRaw(opts?: ZlibOptions) [#new-deflaterawopts-zliboptions]

Create a `DeflateRaw` stream with the given `opts`.

**Parameters**

| Parameter | Type                          | Default | Description                                           |
| --------- | ----------------------------- | ------- | ----------------------------------------------------- |
| `opts?`   | [`ZlibOptions`](#zliboptions) | —       | Options for the stream and the underlying zlib state. |

InflateRaw [#inflateraw]

new InflateRaw(opts?: ZlibOptions) [#new-inflaterawopts-zliboptions]

Create an `InflateRaw` stream with the given `opts`.

**Parameters**

| Parameter | Type                          | Default | Description                                           |
| --------- | ----------------------------- | ------- | ----------------------------------------------------- |
| `opts?`   | [`ZlibOptions`](#zliboptions) | —       | Options for the stream and the underlying zlib state. |

Gzip [#gzip]

new Gzip(opts?: ZlibOptions) [#new-gzipopts-zliboptions]

Create a `Gzip` stream with the given `opts`.

**Parameters**

| Parameter | Type                          | Default | Description                                           |
| --------- | ----------------------------- | ------- | ----------------------------------------------------- |
| `opts?`   | [`ZlibOptions`](#zliboptions) | —       | Options for the stream and the underlying zlib state. |

Gunzip [#gunzip]

new Gunzip(opts?: ZlibOptions) [#new-gunzipopts-zliboptions]

Create a `Gunzip` stream with the given `opts`.

**Parameters**

| Parameter | Type                          | Default | Description                                           |
| --------- | ----------------------------- | ------- | ----------------------------------------------------- |
| `opts?`   | [`ZlibOptions`](#zliboptions) | —       | Options for the stream and the underlying zlib state. |

Types [#types]

ZlibOptions [#zliboptions]

```ts
interface ZlibOptions<S extends ZlibStream = ZlibStream> {
  flush?: number
  finishFlush?: number
  chunkSize?: number
  level?: number
  windowBits?: number
  memLevel?: number
  strategy?: number
  maxOutputLength?: number
  transform?(this: S, data: unknown, encoding: StreamEncoding, cb: StreamCallback): void
  encoding?: BufferEncoding
  highWaterMark?: number
  read?(this: S, size: number): void
  eagerOpen?: boolean
  signal?: AbortSignal
  open?(this: S, cb: StreamCallback): void
  predestroy?(this: S): void
  destroy?(this: S, err: Error | null, cb: StreamCallback): void
  write?(this: S, data: unknown, encoding: StreamEncoding, cb: StreamCallback): void
  writev?(this: S, batch: { chunk: unknown; encoding: StreamEncoding }[], cb: StreamCallback): void
  final?(this: S, cb: StreamCallback): void
}
```

ZlibCallback [#zlibcallback]

```ts
interface ZlibCallback {
}
```

Callback for the one-shot asynchronous functions, called with an error or the resulting `Buffer`.

ZlibFlushCallback [#zlibflushcallback]

```ts
interface ZlibFlushCallback {
}
```

Callback invoked once a `flush()` completes.

Classes [#classes]

ZlibError [#zliberror]

```ts
class ZlibError {
  code: ZlibErrorCode
  name: 'ZlibError'
}
```

An error thrown by a zlib operation, carrying a `code` identifying the underlying zlib failure (such as `DATA_ERROR` or `MEM_ERROR`).

bare-zlib/constants [#bare-zlibconstants]

Constants and variables [#constants-and-variables]

constants [#constants]

```ts
constants: {
  Z_NO_FLUSH: number
  Z_PARTIAL_FLUSH: number
  Z_SYNC_FLUSH: number
  Z_FULL_FLUSH: number
  Z_FINISH: number
  Z_BLOCK: number
  Z_TREES: number

  Z_FILTERED: number
  Z_HUFFMAN_ONLY: number
  Z_RLE: number
  Z_FIXED: number
  Z_DEFAULT_STRATEGY: number

  Z_NO_COMPRESSION: number
  Z_BEST_SPEED: number
  Z_BEST_COMPRESSION: number
  Z_DEFAULT_COMPRESSION: number

  Z_MIN_CHUNK: number
  Z_MAX_CHUNK: number
  Z_DEFAULT_CHUNK: number

  Z_MIN_MEMLEVEL: number
  Z_MAX_MEMLEVEL: number
  Z_DEFAULT_MEMLEVEL: number

  Z_MIN_LEVEL: number
  Z_MAX_LEVEL: number
  Z_DEFAULT_LEVEL: number

  Z_MIN_WINDOWBITS: number
  Z_MAX_WINDOWBITS: number
  Z_DEFAULT_WINDOWBITS: number

  Z_OK: number
  Z_STREAM_END: number
  Z_NEED_DICT: number
  Z_ERRNO: number
  Z_STREAM_ERROR: number
  Z_DATA_ERROR: number
  Z_MEM_ERROR: number
  Z_BUF_ERROR: number
  Z_VERSION_ERROR: number
}
```

Zlib-related constants such as flush modes, compression levels, strategies, and chunk/window/memory-level bounds.

bare-zlib/errors [#bare-zliberrors]

Classes [#classes-1]

errors.ZlibError [#errorszliberror]

An error thrown by a zlib operation, carrying a `code` identifying the underlying zlib failure (such as `DATA_ERROR` or `MEM_ERROR`).

See also [#see-also]

* Builds on `bare-stream`.
* [Bare modules](/reference/modules/bare-modules) — the full `bare-*` catalog.
* [Bare runtime API](/reference/bare/runtime) — the runtime these modules extend.