express-ws

What is express-ws?

The express-ws package is an extension for the Express.js framework that adds WebSocket support. It allows you to easily set up WebSocket endpoints alongside your existing HTTP routes, enabling real-time communication between the server and clients.

What are express-ws's main functionalities?

Setting up a WebSocket endpoint

This code sets up a basic WebSocket endpoint at '/echo' that echoes back any message it receives. The express-ws package is initialized with the Express app, and a WebSocket route is defined using app.ws().

const express = require('express');
const expressWs = require('express-ws');
const app = express();
expressWs(app);

app.ws('/echo', (ws, req) => {
  ws.on('message', (msg) => {
    ws.send(msg);
  });
});

app.listen(3000, () => {
  console.log('Server is running on port 3000');
});

Broadcasting messages to all connected clients

This code sets up a WebSocket endpoint at '/broadcast' that broadcasts any received message to all connected clients except the sender. It maintains a list of connected clients and iterates through them to send the message.

const express = require('express');
const expressWs = require('express-ws');
const app = express();
expressWs(app);

let clients = [];

app.ws('/broadcast', (ws, req) => {
  clients.push(ws);
  ws.on('message', (msg) => {
    clients.forEach(client => {
      if (client !== ws && client.readyState === 1) {
        client.send(msg);
      }
    });
  });
  ws.on('close', () => {
    clients = clients.filter(client => client !== ws);
  });
});

app.listen(3000, () => {
  console.log('Server is running on port 3000');
});

Integrating WebSocket with existing HTTP routes

This code demonstrates how to integrate WebSocket endpoints with existing HTTP routes. It sets up a simple HTTP GET route at '/' and a WebSocket route at '/ws'.

const express = require('express');
const expressWs = require('express-ws');
const app = express();
expressWs(app);

app.get('/', (req, res) => {
  res.send('Hello, HTTP!');
});

app.ws('/ws', (ws, req) => {
  ws.on('message', (msg) => {
    ws.send('Hello, WebSocket!');
  });
});

app.listen(3000, () => {
  console.log('Server is running on port 3000');
});

Other packages similar to express-ws

ws

The ws package is a simple to use, blazing fast, and thoroughly tested WebSocket client and server for Node.js. Unlike express-ws, ws does not integrate directly with Express.js, but it provides a more low-level API for WebSocket communication, which can be more flexible for certain use cases.

socket.io

Socket.IO is a library that enables real-time, bidirectional, and event-based communication between web clients and servers. It is built on top of the WebSocket protocol and provides additional features like fallback to HTTP long-polling, automatic reconnection, and rooms/namespaces. Compared to express-ws, Socket.IO offers more advanced features and a higher-level API.

README

express-ws

WebSocket endpoints for Express 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 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:

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.

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:

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

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:

• You have enabled options.leaveRouterUntouched, or
• 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.