# @zerva/websocket

> 🌱 Zerva websocket module

Latest version **0.90.0** (published 2026-03-30) · MIT license · 0 weekly downloads

## Install

```sh
npm install @zerva/websocket
pnpm add @zerva/websocket
yarn add @zerva/websocket
bun add @zerva/websocket
```

## Health

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

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.90.0 |
| Published | 2026-03-30 |
| First published | 2022-03-23 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=22.0.0 |
| Dependencies | 5 |
| Unpacked size | 26.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Dirk Holtwick |
| Maintainers | zerva |
| Keywords | server, typescript, event, websocket, socket, zerva, zeed |

## Links

- npm: https://www.npmjs.com/package/@zerva/websocket
- Funding: https://github.com/sponsors/holtwick
- npm.io page: https://npm.io/package/@zerva/websocket

## Dependencies (5)

- [ws](https://npm.io/package/ws.md) ^8.20.0
- [zeed](https://npm.io/package/zeed.md) ^1.3.1
- [@types/ws](https://npm.io/package/@types/ws.md) ^8.18.1
- [@zerva/core](https://npm.io/package/@zerva/core.md) 0.90.0
- [@zerva/http](https://npm.io/package/@zerva/http.md) 0.90.0

## Alternatives

- [@opentelemetry/exporter-zipkin](https://npm.io/package/@opentelemetry/exporter-zipkin.md) — 14.8M weekly downloads
- [pusher-js](https://npm.io/package/pusher-js.md) — 2.0M weekly downloads
- [browserify](https://npm.io/package/browserify.md) — 1.7M weekly downloads
- [sqs-consumer](https://npm.io/package/sqs-consumer.md) — 1.7M weekly downloads
- [@sanity/eventsource](https://npm.io/package/@sanity/eventsource.md) — 930.8K weekly downloads

## Recent versions

- 0.90.0 (latest) — 2026-03-30
- 0.88.0 — 2026-03-30
- 0.86.1 — 2026-03-13
- 0.81.1 — 2025-10-22
- 0.80.1 — 2025-10-13
- 0.79.0 — 2025-10-10
- 0.78.1 — 2025-10-09
- 0.77.1 — 2025-10-08
- 0.74.4 — 2025-09-19
- 0.74.2 — 2025-09-10
- 0.74.1 — 2025-09-04
- 0.73.1 — 2025-08-31
- 0.73.0 — 2025-08-31
- 0.72.0 — 2025-08-24
- 0.71.0 — 2025-06-14
- … 123 more at https://npm.io/package/@zerva/websocket/versions

## README

# 🌱 Zerva useWebSocket

**This is a side project of [Zerva](https://github.com/holtwick/zerva)**

> Plain resilient WebSocket connections with Zerva.

## Get started

```ts
import { useWebSocket } from '@zerva/websocket'

useHttp({ port: 8080 })
useWebSocket()
```

## Communication

### Variant A: Channel

By establishing a connection you get a [Zeed Channel](https://github.com/holtwick/zeed/tree/master/src/common/msg#channel) to send raw string or binary data between server and client. The interfaces are the same for client and server side. On server side minimal code looks like this:

```ts
on('webSocketConnect', ({ channel }) => {
  channel.postMessage('Hello World')
  channel.on('message', (msg) => {
    console.log(msg.data)
  })
})
```

Client side like this:

```ts
const channel = new WebSocketConnection()
channel.on('connect', () => {
  channel.postMessage('Hello World')
})
channel.on('message', (msg) => {
  console.log(msg.data)
})
```

### Variant B: Message Interface

You can also use the [Zeed Message](https://github.com/holtwick/zeed/tree/master/src/common/msg#messages) overlay to have a convenient messaging infrastructure. First define the methods the server should listen to:

```ts
interface Messages {
  echo: (msg: string) => string
}
```

Then implement them in on the server side:

```ts
on('webSocketConnect', ({ channel }) => {
  useMessageHub({ channel }).listen<Messages>({
    echo(message) {
      return message
    },
  })
})
```

On the client side you may connect easily and call the messages:

```ts
const channel = new WebSocketConnection()
const send = useMessageHub({ channel }).send<Messages>()

const response = await send.echo('Hello World')
expect(response).toBe('Hello World')
```

### Variant C: PubSub Interface

Similar to Messages is the [PubSub](https://github.com/holtwick/zeed/tree/master/src/common/msg#pubsub) interface.

## Features

### Reconnection / Resilience

For a connection you always receive one Channel. This channel might be disconnected due to network issues, but once it reconnects you can continue to use the same Channel. You can check the state via `channel.isConnected`.

Both the client and the server try to stay connected and send ping/pong (heart beat) messages. On failure the client tries to reconnect. The Channel events `connect` and `disconnect` help to manage states in your app in case the connection is lost. You don't need to reconnect yourself.

### Encoding

Communication uses binary data. Encoding is usually provided by Message, PubSub and others using JSON. You can plug in any other encoding, e.g. crypto or compression.

## Alternatives

Similar projects:

- [Socket.io](https://socket.io/)
- [SocketCluster](https://socketcluster.io/)
- [SockJS](https://github.com/sockjs/sockjs-client)

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