# simple-websockets

> ![CI](https://img.shields.io/github/actions/workflow/status/osztenkurden/simple-websockets/.github/workflows/main.yaml?branch=master) ![Dependencies](https://img.shields.io/librariesio/github/osztenkurden/simple-websockets) ![Downloads](https://img.shie

Latest version **3.0.1** (published 2026-07-14) · MIT license · 0 weekly downloads

## Install

```sh
npm install simple-websockets
pnpm add simple-websockets
yarn add simple-websockets
bun add simple-websockets
```

## Health

**Score 70/100 (B)** — status: active.

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

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 3.0.1 |
| Published | 2026-07-14 |
| First published | 2021-02-27 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM |
| Node | >=22.18 |
| Dependencies | 5 |
| Unpacked size | 15.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 1 |
| Maintainers | osztenkurden |

## Links

- npm: https://www.npmjs.com/package/simple-websockets
- Repository: https://github.com/osztenkurden/simple-websockets
- Homepage: https://github.com/osztenkurden/simple-websockets#readme
- Issues: https://github.com/osztenkurden/simple-websockets/issues
- npm.io page: https://npm.io/package/simple-websockets

## Dependencies (5)

- [ws](https://npm.io/package/ws.md) ^8.20.0
- [events](https://npm.io/package/events.md) ^3.3.0
- [@types/ws](https://npm.io/package/@types/ws.md) ^8.18.1
- [browser-or-node](https://npm.io/package/browser-or-node.md) ^1.3.0
- [reconnecting-websocket](https://npm.io/package/reconnecting-websocket.md) ^4.4.0

## Recent versions

- 3.0.1 (latest) — 2026-07-14
- 3.0.0 — 2026-04-14
- 2.2.2 — 2026-04-14
- 2.2.0 — 2026-04-13
- 2.1.0 — 2025-10-03
- 2.0.3 — 2025-06-02
- 2.0.2 — 2025-05-21
- 2.0.1 — 2025-05-21
- 2.0.0 — 2025-05-21
- 1.3.1 — 2023-10-12
- 1.3.0 — 2023-09-21
- 1.2.0 — 2022-08-11
- 1.1.0 — 2021-06-15
- 1.0.4 — 2021-02-28
- 1.0.3 — 2021-02-28
- … 3 more at https://npm.io/package/simple-websockets/versions

## README

![CI](https://img.shields.io/github/actions/workflow/status/osztenkurden/simple-websockets/.github/workflows/main.yaml?branch=master)
![Dependencies](https://img.shields.io/librariesio/github/osztenkurden/simple-websockets)
![Downloads](https://img.shields.io/npm/dm/simple-websockets)
![Version](https://img.shields.io/npm/v/simple-websockets)

# Simple Websockets

> Requires **Node.js >= 22**

Super easy, super thin event-based WebSocket wrapper to work with `simple-websockets/server` (inspired by socket.io but with no bloat).

As of v3, the client uses the native global `WebSocket` available in both browsers and Node.js 22+, removing the need for the `ws` library on the client side.

# Client

## Basic usage

```typescript
import { SimpleWebSocket } from 'simple-websockets';

const socket = new SimpleWebSocket('ws://localhost:123');

socket._socket; // Instance of native WebSocket

socket.on('event name', (arg1, arg2, arg3) => {
	// Listen for custom event from server
});

socket.send('event name to send to server', 1, 2, 3, 'fourth argument');
```

## Wrapping an existing WebSocket

```typescript
import { SimpleWebSocket } from 'simple-websockets';

const webSocket = new WebSocket('ws://localhost:123');

const socket = new SimpleWebSocket(webSocket);
```

## Wrapping a `ws` socket

If you have a `ws` library socket (e.g. from a server connection callback), you can wrap it too:

```typescript
import { SimpleWebSocket } from 'simple-websockets';
import WebSocket from 'ws';

const wsSocket = new WebSocket('ws://localhost:123');

const socket = new SimpleWebSocket(wsSocket);
```

## Auto-reconnect

Pass `{ autoReconnect: true }` to automatically reconnect on disconnection (uses `reconnecting-websocket` under the hood):

```typescript
const socket = new SimpleWebSocket('ws://localhost:123', { autoReconnect: true });
```

## Static factory methods

For precise type inference on `_socket`, use the static factory methods:

```typescript
// From a URL string or URL object
const socket = SimpleWebSocket.fromAddress('ws://localhost:123');
const reconnecting = SimpleWebSocket.fromAddress('ws://localhost:123', { autoReconnect: true });

// From an existing native WebSocket
const socket = SimpleWebSocket.fromWebSocket(existingWebSocket);

// From a ws library socket
const socket = SimpleWebSocket.fromWsSocket(wsSocket);

// From a ReconnectingWebSocket
const socket = SimpleWebSocket.fromReconnecting(existingReconnectingSocket);
```

## Type-safe events

```typescript
type MyEvents = {
	'chat message': [message: string, sender: string];
	'user joined': [username: string];
};

const socket = new SimpleWebSocket<MyEvents>('ws://localhost:123');

socket.on('chat message', (message, sender) => {
	// message: string, sender: string
});

socket.send('chat message', 'hello', 'alice');
```

## Documentation

`socket.send` sends to server a stringified JSON object:

```javascript
{
    eventName: "event name is the first argument",
    values: []
}
```

where `values` is the array of arguments after the first argument of the `send` method.

`socket.on` listens for incoming data that fits the scheme and calls the listener.

You can send events without values.

Event name must be a non-empty string.

By default, the socket emits `connection` and `disconnect` events on its own.

This package is considered feature-complete - probably will not add any features, only bugfixes.

# Server

## Example

```typescript
import { SimpleWebSocketServer } from 'simple-websockets/server';

const server = new SimpleWebSocketServer({ port: 1234 });

server.onConnection((socket, request) => {
	socket.on('some event from socket', (someData) => {
		socket.send('some response', someResponseData);
	});
});

server.send('event name to send to all clients', 1, 2, 3, 'fourth argument');
```

## Documentation

`SimpleWebSocketServer` extends `ws.WebSocketServer`, so the constructor accepts the same options. It has 2 additional methods:

-   `onConnection(callback)` - connection listener. The callback receives a `SimpleWebSocket` instance and the `http.IncomingMessage` request
-   `send(eventName, ...values)` - sends an event with data to all connected sockets

`server.send` sends to all clients a stringified JSON object:

```javascript
{
    eventName: "event name is the first argument",
    values: []
}
```

where `values` is the array of arguments after the first argument of the `send` method.

`socket.on` listens for incoming data that fits the scheme and calls the listener.

You can send events without values.

Event name must be a non-empty string.

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