# hyperswarm

> A distributed networking stack for connecting peers

Latest version **4.17.1** (published 2026-09-08) · MIT license · 0 weekly downloads

## Install

```sh
npm install hyperswarm
pnpm add hyperswarm
yarn add hyperswarm
bun add hyperswarm
```

## Health

**Score 60/100 (C)** — status: active.

Positive: no vulnerabilities; has provenance; recently updated; high maintenance score.

Warnings: low downloads; no types; no esm support.

## Facts

| | |
|---|---|
| Version | 4.17.1 |
| Published | 2026-09-08 |
| First published | 2015-05-10 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 7 |
| Unpacked size | 43.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 1337 |
| Author | Mathias Buus |
| Maintainers | mafintosh |

## Links

- npm: https://www.npmjs.com/package/hyperswarm
- Repository: https://github.com/holepunchto/hyperswarm
- Issues: https://github.com/holepunchto/hyperswarm/issues
- npm.io page: https://npm.io/package/hyperswarm

## Dependencies (7)

- [b4a](https://npm.io/package/b4a.md) ^1.3.1
- [unslab](https://npm.io/package/unslab.md) ^1.3.0
- [streamx](https://npm.io/package/streamx.md) ^2.22.1
- [hyperdht](https://npm.io/package/hyperdht.md) ^6.21.0
- [bare-events](https://npm.io/package/bare-events.md) ^2.2.0
- [safety-catch](https://npm.io/package/safety-catch.md) ^1.0.2
- [shuffled-priority-queue](https://npm.io/package/shuffled-priority-queue.md) ^2.1.0

## Recent versions

- 4.17.1 (latest) — 2026-09-08
- 4.13.0 (tmp) — 2025-08-07
- 4.17.0 — 2026-02-20
- 4.16.0 — 2025-11-28
- 4.15.4 — 2025-11-28
- 4.15.3 — 2025-11-27
- 4.15.2 — 2025-11-27
- 4.15.1 — 2025-11-19
- 4.15.0 — 2025-11-19
- 4.14.2 — 2025-10-09
- 4.14.1 — 2025-10-07
- 4.14.0 — 2025-09-01
- 4.13.1 — 2025-08-16
- 4.12.1 — 2025-07-11
- 4.12.0 — 2025-07-11
- … 100 more at https://npm.io/package/hyperswarm/versions

## README

# hyperswarm

### [See the full API docs at docs.pears.com](https://docs.pears.com/building-blocks/hyperswarm)

A high-level API for finding and connecting to peers who are interested in a "topic."

## Installation

```
npm install hyperswarm
```

## Usage

```js
const Hyperswarm = require('hyperswarm')

const swarm = new Hyperswarm()

swarm1.on('connection', (conn) => {
  // swarm1 will receive server connections
  conn.write('this is a server connection')
  conn.end()
})

const discoveryKey = Buffer.alloc(32).fill('hello world') // must be 32 bytes

// join the swarm, others will find you
swarm2.join(discoveryKey, { server: true, client: true })
```

## Hyperswarm API

#### `const swarm = new Hyperswarm(opts = {})`

Construct a new Hyperswarm instance.

`opts` can include:

- `keyPair`: A Noise keypair that will be used to listen/connect on the DHT. Defaults to a new key pair.
- `seed`: A unique, 32-byte, random seed that can be used to deterministically generate the key pair.
- `maxPeers`: The maximum number of peer connections to allow.
- `firewall`: A sync function of the form `remotePublicKey => (true|false)`. If true, the connection will be rejected. Defaults to allowing all connections.
- `dht`: A DHT instance. Defaults to a new instance.

#### `swarm.connecting`

Number that indicates connections in progress.

#### `swarm.connections`

A set of all active client/server connections.

#### `swarm.peers`

A Map containing all connected peers, of the form: `(Noise public key hex string) -> PeerInfo object`

See the [`PeerInfo`](#peerinfo-api) API for more details.

#### `swarm.dht`

A [`hyperdht`](https://github.com/holepunchto/hyperdht) instance. Useful if you want lower-level control over Hyperswarm's networking.

#### `swarm.on('connection', (socket, peerInfo) => {})`

Emitted whenever the swarm connects to a new peer.

`socket` is an end-to-end (Noise) encrypted Duplex stream

`peerInfo` is a [`PeerInfo`](#peerinfo-api) instance

#### `swarm.on('update', () => {})`

Emitted when internal values are changed, useful for user interfaces.

For example: emitted when `swarm.connecting` or `swarm.connections` changes.

#### `const discovery = swarm.join(topic, opts = {})`

Start discovering and connecting to peers sharing a common topic. As new peers are connected to, they will be emitted from the swarm as `connection` events.

`topic` must be a 32-byte Buffer
`opts` can include:

- `server`: Accept server connections for this topic by announcing yourself to the DHT. Defaults to `true`.
- `client`: Actively search for and connect to discovered servers. Defaults to `true`.
- `limit`: Set the max number of peers to connect to when joining the topic. Defaults to `Infinity`.

Returns a [`PeerDiscovery`](#peerdiscovery-api) object.

#### Clients and Servers

In Hyperswarm, there are two ways for peers to join the swarm: client mode and server mode. If you've previously used Hyperswarm v2, these were called "lookup" and "announce", but we now think "client" and "server" are more descriptive.

When you join a topic as a server, the swarm will start accepting incoming connections from clients (peers that have joined the same topic in client mode). Server mode will announce your keypair to the DHT, so that other peers can discover your server. When server connections are emitted, they are not associated with a specific topic -- the server only knows it received an incoming connection.

When you join a topic as a client, the swarm will do a query to discover available servers, and will eagerly connect to them. As with server mode, these connections will be emitted as `connection` events, but in client mode they **will** be associated with the topic (`info.topics` will be set in the `connection` event).

#### `await swarm.leave(topic)`

Stop discovering peers for the given topic.

`topic` must be a 32-byte Buffer

If a topic was previously joined in server mode, `leave` will stop announcing the topic on the DHT. If a topic was previously joined in client mode, `leave` will stop searching for servers announcing the topic.

`leave` will **not** close any existing connections.

#### `swarm.joinPeer(noisePublicKey)`

Establish a direct connection to a known peer.

`noisePublicKey` must be a 32-byte Buffer

As with the standard `join` method, `joinPeer` will ensure that peer connections are reestablished in the event of failures.

#### `swarm.leavePeer(noisePublicKey)`

Stop attempting direct connections to a known peer.

`noisePublicKey` must be a 32-byte Buffer

If a direct connection is already established, that connection will **not** be destroyed by `leavePeer`.

#### `const discovery = swarm.status(topic)`

Get the [`PeerDiscovery`](#peerdiscovery-api) object associated with the topic, if it exists.

#### `await swarm.listen()`

Explicitly start listening for incoming connections. This will be called internally after the first `join`, so it rarely needs to be called manually.

#### `await swarm.flush()`

Wait for any pending DHT announces, and for the swarm to connect to any pending peers (peers that have been discovered, but are still in the queue awaiting processing).

Once a `flush()` has completed, the swarm will have connected to every peer it can discover from the current set of topics it's managing.

`flush()` is not topic-specific, so it will wait for every pending DHT operation and connection to be processed -- it's quite heavyweight, so it could take a while. In most cases, it's not necessary, as connections are emitted by `swarm.on('connection')` immediately after they're opened.

#### `await swarm.suspend({ log: () => {} })`

Suspend the swarm disconnecting all peers, suspends server listening and stops discovery of new peers. Useful for suspending when the runtime suspends to pause networking.

`log` is a logging function, which defaults to a noop function.

#### `await swarm.resume({ log: () => {} })`

Resume a suspended swarm refreshing discovery of new peers and servers. Useful for reannouncing to the DHT and reconnecting to peers when the runtime resumes.

`log` is a logging function, which defaults to a noop function.

#### `swarm.on('ban', peerInfo, err)`

Emitted when a peer gets banned. `err` is an error object describing the reason for the ban (e.g. firewalled).

## PeerDiscovery API

`swarm.join` returns a `PeerDiscovery` instance which allows you to both control discovery behavior, and respond to lifecycle changes during discovery.

#### `await discovery.flushed()`

Wait until the topic has been fully announced to the DHT. This method is only relevant in server mode. When `flushed()` has completed, the server will be available to the network.

#### `await discovery.refresh({ client, server })`

Update the `PeerDiscovery` configuration, optionally toggling client and server modes. This will also trigger an immediate re-announce of the topic, when the `PeerDiscovery` is in server mode.

#### `await discovery.destroy()`

Stop discovering peers for the given topic.

If a topic was previously joined in server mode, `leave` will stop announcing the topic on the DHT. If a topic was previously joined in client mode, `leave` will stop searching for servers announcing the topic.

## PeerInfo API

`swarm.on('connection', ...)` emits a `PeerInfo` instance whenever a new connection is established.

There is a one-to-one relationship between connections and `PeerInfo` objects -- if a single peer announces multiple topics, those topics will be multiplexed over a single connection.

#### `peerInfo.publicKey`

The peer's Noise public key.

#### `peerInfo.topics`

An Array of topics that this Peer is associated with -- `topics` will only be updated when the Peer is in client mode.

#### `peerInfo.prioritized`

If true, the swarm will rapidly attempt to reconnect to this peer.

#### `peerInfo.ban(banStatus = false)`

Ban or unban the peer. Banning will prevent any future reconnection attempts, but it will **not** close any existing connections.

## License

MIT

---
_Source: https://npm.io/package/hyperswarm · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._