Skip to content
Lightweight RPC support for the ws WebSocket server
Find file
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.

ws-rpc: lightweight RPC support for the ws WebSocket server


Install dependencies:

npm install express
npm install ws
npm install ws-rpc
npm install ws-flash-client
npm install policyfile
Complete example with Express, ws, and the Flash client shim support:


  • args stands for multiple arguments, e.g. arg1, arg2, arg3
  • messages with callbacks can only be used when messaging a single client
var prod = process.env.NODE_ENV === 'production';
var app = require('express').createServer();
var wss = new (require('ws').Server)({ server: app });
var wsrpc = require('ws-rpc').extend(wss);
var wsflash = require('ws-flash-client');
require('policyfile').createServer().listen(prod ? 843 : 10843, app);

app.configure(function() {
    // configure other stuff like express globals, jade, stylus, etc.
    // ...

    // configure the ws-rpc middleware:

    // configure the ws-flash-client middleware:

    // static file handling must come afterwards:

    // bind node to a port
    app.listen(prod ? 80 : 1234);

// create/get a named room (channel)
var myRoom ='myRoom');

// handle a new client connection
wss.on('connect', function(client) {

    // add client to a room

    // message the client
    client.message('some message', args);

    // message the client with callback
    client.message('some message', args, function(err, args) {
            // ...

    //client.on(... <-- not here, see below

// handle message from a client without a callback
wss.on('some message', function(client, args) {

    // ...

// handle message from a client with a callback
wss.on('some message', function(client, args, cb) {

    // ...

    // call the callback (should use node convention but not mandatory)
    cb(null, 'ok');

// handle client disconnection
wss.on('disconnect', function(client) {

    //myRoom.remove(client); <- not necessary, this is done automatically

    // example: broadcast too all client's rooms
    for(id in client.rooms)
        client.rooms[id].message('some message', args);

// message all clients connected to the server
wss.message('some message', args);

// msg all clients in a room
myRoom.message('some message', args);

// and don't forget this if you don't want your Node to crash on an error:
// if the error comes from a client, the client is passed as second parameter
wss.on('error', function(e, client) {
    console.log(client ? 'client' : 'server', e);

Binary messages are not handled by the RPC extension, so you can handle them separately using the classic ws API.

Also, if you want to intercept the raw string messages and do your own handling in some cases, you can leave out the require('ws-rpc').extend(wss); line above, and do the following:

wss.on('connection', function(client) { // notice: "connection" vs "connect"
    client.on('message', function(data, flags) {
        if(is_my_message(data)) {
            // handle the raw message here
            // ...
            // notify the RPC extension that this message was already handled
            flags.handled = true;
        // otherwise the message will be handled as RPC

// only setup the RPC extension after the above


In your HTML page (JADE syntax shown):

!!! 5
        meta(http-equiv='X-UA-Compatible', content='IE=Edge,chrome=1')
        //if lt IE 8

Complete example with the Flash client shim support (for full usage and options please see ws-flash-client):

$(function() {

    $.wsFlashClientInit({}, function(err) {
            return log('no websocket support');

        // create the client (will use WebSocket object on the background)
        // param1: url
        // param2 (optional): protocols, see
        // param3 (optional): connection timeout in ms (default 4s), set to -1 to disable automatic reconnecting
        // param4 (optional): reconnection wait timeout (default 1s)
        var ws = new WebSocketRPC('ws://' + + '/');

        // handle a message from the server
        ws.on('some message', function(args) {

            // ...

        // handle a message from the server with a callback
        ws.on('some message', function(args, cb) {

            // ...

            cb(null, 'hello from client');

            // or, in the case of an error:

            cb(new Error('some problem'));

        // message the server
        ws.message('some message', args);

        // message the server with a callback
        ws.message('some message', args, function(err, args) {
                // ...

        // disconnect from the server
        // param1 (optional): disable automatic reconnection

        // connected event
        ws.on('open', function(world) {

            // access the WebSocket if needed:
            //ws.socket ... <- will be null when disconnected, and then a new one created

        // disconnected event
        ws.on('close', function(world) {

        // error event
        ws.on('error', function(e) {
            log(e.stack || e);

    // just an example
    function log(s) {
        var m = $('#msg');
        m.text(m.text()  + '\n' + s);

Usage without ws-flash-client:

var ws = new WebSocketRPC('ws://' + + '/');

// ..and the same operations as above..


New BSD License.

Something went wrong with that request. Please try again.