npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@hoobs/express-ws

v6.0.1

Published

WebSocket endpoints for Express applications (require version)

Downloads

8

Readme

express-ws Dependency Status

This fork uses require() instead of ES6 imports.

You should probably use the upstream (it’s awesome; thank you, Henning).


Still here? OK, so here’s why I hacked together this fork:

  • I needed to include it from my fork (for reasons)
  • The build process wasn’t documented.
  • I don’t want to use Babel and add a build process for a simple library.
  • Without Babel it was causing errors in Nexe due to the additional complexity in module loading.
  • ES6 imports in Node.js… Y, tho? :)

If these are not concerns for you, please head on over to the upstream. If you npm install it instead of including it from source, the issues I outlined above should not affect you.

If you do want to include this fork in your project instead of the upstream, in your package.json:

"dependencies": {
  "express-ws": "github:aral/express-ws"
}

In addition to using require() instead of ES6 imports, this fork also enables you to access the WebSocket Server instance and the Express app instance from within routes via this:

app.ws('/chat', function(ws, req) {

  ws.on('message', message => {
    this.getWss('/chat').clients.forEach(client => {
      client.send(message)
    })
  })

});

See the Chat example for a demonstration.

We now return to the regular upstream documentation…


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(/* optional */ route)

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.

To get just the clients for a given route, please specify the route using the optional route parameter.

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.

A note on route scope

Routes are bound to the wsInstance so you can access .getWss() and .app via this in your routes even if the original wsInstance is not in scope (e.g., if you have your routes defined in external files).

Development

This module is written in ES6 and uses ESM.