# express-ws

> WebSocket endpoints for Express applications

Latest version **5.0.2** (published 2021-06-07) · BSD-2-Clause license · 0 weekly downloads

## Install

```sh
npm install express-ws
pnpm add express-ws
yarn add express-ws
bun add express-ws
```

## Health

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

Positive: has types package; no vulnerabilities.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 5.0.2 |
| Published | 2021-06-07 |
| First published | 2014-03-14 |
| Weekly downloads | 0 |
| License | BSD-2-Clause |
| TypeScript types | separate (@types/express-ws) |
| Module format | CommonJS |
| Node | >=4.5.0 |
| Dependencies | 1 |
| Unpacked size | 17 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 881 |
| Author | Henning Morud |
| Maintainers | henningm |
| Keywords | express, ws, websocket |

## Links

- npm: https://www.npmjs.com/package/express-ws
- Repository: https://github.com/HenningM/express-ws
- Issues: https://github.com/HenningM/express-ws/issues
- npm.io page: https://npm.io/package/express-ws

## Dependencies (1)

- [ws](https://npm.io/package/ws.md) ^7.4.6

## 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

- 5.0.2 (latest) — 2021-06-07
- 5.0.1 — 2021-06-07
- 4.0.0 — 2018-06-06
- 3.0.0 — 2017-02-16
- 2.0.0 — 2016-08-15
- 2.0.0-rc.1 — 2016-04-18
- 2.0.0-beta — 2016-04-02
- 1.0.0 — 2016-02-14
- 1.0.0-rc.2 — 2015-10-03
- 1.0.0-rc.1 — 2015-08-21
- 0.2.6 — 2015-03-31
- 0.2.5 — 2015-02-27
- 0.2.4 — 2015-01-21
- 0.2.3 — 2014-12-30
- 0.2.2 — 2014-12-17
- … 4 more at https://npm.io/package/express-ws/versions

## README

# express-ws [![Dependency Status](https://snyk.io/test/github/henningm/express-ws/badge.svg)](https://snyk.io/test/github/henningm/express-ws)

[WebSocket](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API) endpoints for [Express](http://expressjs.com/) applications. Lets you define WebSocket endpoints like any other type of route, and applies regular Express middleware. The WebSocket support is implemented with the help of the [ws](https://github.com/websockets/ws) library.

## Installation

`npm install --save express-ws`

## Usage

__Full documentation can be found in the API section below. This section only shows a brief example.__

Add this line to your Express application:

```javascript
var expressWs = require('express-ws')(app);
```

__Important: Make sure to set up the `express-ws` module like above *before* loading or defining your routers!__ Otherwise, `express-ws` won't get a chance to set up support for Express routers, and you might run into an error along the lines of `router.ws is not a function`.

After setting up `express-ws`, you will be able to add WebSocket routes (almost) the same way you add other routes. The following snippet sets up a simple echo server at `/echo`.  The `ws` parameter is an instance of the WebSocket class described [here](https://github.com/websockets/ws/blob/master/doc/ws.md#class-websocket).

```javascript
app.ws('/echo', function(ws, req) {
  ws.on('message', function(msg) {
    ws.send(msg);
  });
});
```

It works with routers, too, this time at `/ws-stuff/echo`:

```javascript
var router = express.Router();

router.ws('/echo', function(ws, req) {
  ws.on('message', function(msg) {
    ws.send(msg);
  });
});

app.use("/ws-stuff", router);
```

## Full example

```javascript
var express = require('express');
var app = express();
var expressWs = require('express-ws')(app);

app.use(function (req, res, next) {
  console.log('middleware');
  req.testing = 'testing';
  return next();
});

app.get('/', function(req, res, next){
  console.log('get route', req.testing);
  res.end();
});

app.ws('/', function(ws, req) {
  ws.on('message', function(msg) {
    console.log(msg);
  });
  console.log('socket', req.testing);
});

app.listen(3000);
```

## API

### expressWs(app, *server*, *options*)

Sets up `express-ws` on the specified `app`. This will modify the global Router prototype for Express as well - see the `leaveRouterUntouched` option for more information on disabling this.

* __app__: The Express application to set up `express-ws` on.
* __server__: *Optional.* When using a custom `http.Server`, you should pass it in here, so that `express-ws` can use it to set up the WebSocket upgrade handlers. If you don't specify a `server`, you will only be able to use it with the server that is created automatically when you call `app.listen`.
* __options__: *Optional.* An object containing further options.
  * __leaveRouterUntouched:__ Set this to `true` to keep `express-ws` from modifying the Router prototype. You will have to manually `applyTo` every Router that you wish to make `.ws` available on, when this is enabled.
  * __wsOptions:__ Options object passed to WebSocketServer constructor. Necessary for any ws specific features.

This function will return a new `express-ws` API object, which will be referred to as `wsInstance` in the rest of the documentation.

### wsInstance.app

This property contains the `app` that `express-ws` was set up on.

### wsInstance.getWss()

Returns the underlying WebSocket server/handler. You can use `wsInstance.getWss().clients` to obtain a list of all the connected WebSocket clients for this server.

Note that this list will include *all* clients, not just those for a specific route - this means that it's often *not* a good idea to use this for broadcasts, for example.

### wsInstance.applyTo(router)

Sets up `express-ws` on the given `router` (or other Router-like object). You will only need this in two scenarios:

1. You have enabled `options.leaveRouterUntouched`, or
2. You are using a custom router that is not based on the express.Router prototype.

In most cases, you won't need this at all.

## Development

This module is written in ES6, and uses Babel for compilation. What this means in practice:

* The source code lives in the `src/` directory.
* After changing this code, make sure to run `npm run build` to compile it.

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