# koa-websocket

> Light wrapper around Koa providing a websocket middleware handler that is koa-route compatible.

Latest version **7.0.0** (published 2022-04-18) · MIT license · 0 weekly downloads

## Install

```sh
npm install koa-websocket
pnpm add koa-websocket
yarn add koa-websocket
bun add koa-websocket
```

## Health

**Score 23/100 (F)** — status: abandoned.

Positive: has types package; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 7.0.0 |
| Published | 2022-04-18 |
| First published | 2015-03-08 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | separate (@types/koa-websocket) |
| Module format | CommonJS |
| Dependencies | 4 |
| Unpacked size | 18.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 257 |
| Author | Jonathan Cremin |
| Maintainers | kudos |
| Keywords | koa, websockets, ws, sockets, routes |

## Links

- npm: https://www.npmjs.com/package/koa-websocket
- Repository: https://github.com/kudos/koa-websocket
- Issues: https://github.com/kudos/koa-websocket/issues
- npm.io page: https://npm.io/package/koa-websocket

## Dependencies (4)

- [co](https://npm.io/package/co.md) ^4.6.0
- [ws](https://npm.io/package/ws.md) ^8.5.0
- [debug](https://npm.io/package/debug.md) ^4.3.4
- [koa-compose](https://npm.io/package/koa-compose.md) ^4.1.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

- 7.0.0 (latest) — 2022-04-18
- 3.0.1 (next) — 2016-10-01
- 6.0.0 — 2019-07-08
- 5.0.1 — 2018-05-23
- 5.0.0 — 2018-05-21
- 4.1.0 — 2017-11-05
- 4.0.0 — 2017-05-06
- 2.1.0 — 2016-10-01
- 2.0.0 — 2016-06-01
- 1.1.0 — 2015-08-29
- 1.0.0 — 2015-07-05
- 0.1.2 — 2015-05-14
- 0.1.1 — 2015-05-06
- 0.1.0 — 2015-03-08

## README

# koa-websocket

[![CI Status](https://github.com/kudos/koa-websocket/actions/workflows/node.js.yml/badge.svg)](https://github.com/kudos/koa-websocket/actions)

> Koa v2 is now the default. For Koa v1 support install with koa-websocket@2 and see the `legacy` branch.

Supports `ws://` and `wss://`

## Installation

`npm install koa-websocket`

## Usage

```js
const Koa = require('koa'),
  route = require('koa-route'),
  websockify = require('koa-websocket');

const app = websockify(new Koa());

// Regular middleware
// Note it's app.ws.use and not app.use
app.ws.use(function(ctx, next) {
  // return `next` to pass the context (ctx) on to the next ws middleware
  return next(ctx);
});

// Using routes
app.ws.use(route.all('/test/:id', function (ctx) {
  // `ctx` is the regular koa context created from the `ws` onConnection `socket.upgradeReq` object.
  // the websocket is added to the context on `ctx.websocket`.
  ctx.websocket.send('Hello World');
  ctx.websocket.on('message', function(message) {
    // do something with the message from client
        console.log(message);
  });
}));

app.listen(3000);
```

Example with Let's Encrypt ([the Greenlock package](https://git.daplie.com/Daplie/greenlock-koa)):

```js
const Koa = require('koa');
const greenlock = require('greenlock-express');
const websockify = require('koa-websocket');
 
const le = greenlock.create({
  // all your sweet Let's Encrypt options here
});
 
// the magic happens right here
const app = websockify(new Koa(), wsOptions, le.httpsOptions);
 
app.ws.use((ctx) => {
   // the websocket is added to the context as `ctx.websocket`.
  ctx.websocket.on('message', function(message) {
    // do something
  });
});
 
app.listen(3000);
```

With custom websocket options.

```js
const Koa = require('koa'),
  route = require('koa-route'),
  websockify = require('koa-websocket');

const wsOptions = {};
const app = websockify(new Koa(), wsOptions);

app.ws.use(route.all('/', (ctx) => {
   // the websocket is added to the context as `ctx.websocket`.
  ctx.websocket.on('message', function(message) {
    // print message from the client
    console.log(message);
  });
}));

app.listen(3000);
```

## API
#### websockify(KoaApp, [WebSocketOptions], [httpsOptions])
The WebSocket options object just get passed right through to the `new WebSocketServer(options)` call.

The optional HTTPS options object gets passed right into `https.createServer(options)`. If the HTTPS options are 
passed in, koa-websocket will use the built-in Node HTTPS server to provide support for the `wss://` protocol.

## License
MIT

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