Important
This is a fork of the existing express-ws
npm package - which is what you probably want to use.
Original: https://github.com/henningm/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.
npm install --save @mintplex-labs/express-ws
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('@mintplex-labs/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);
var express = require('express');
var app = express();
var expressWs = require('@mintplex-labs/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);
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 thatexpress-ws
can use it to set up the WebSocket upgrade handlers. If you don't specify aserver
, you will only be able to use it with the server that is created automatically when you callapp.listen
. - options: Optional. An object containing further options.
- leaveRouterUntouched: Set this to
true
to keepexpress-ws
from modifying the Router prototype. You will have to manuallyapplyTo
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.
- leaveRouterUntouched: Set this to
This function will return a new express-ws
API object, which will be referred to as wsInstance
in the rest of the documentation.
This property contains the app
that express-ws
was set up on.
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.
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.
This module is written in ES6 and uses ESM.