Exciting news!Announcing our $4.6M Series Seed. Learn more
Log in


Package Overview
File Explorer

Advanced tools


WebSocket messages to Redux action bridge


Version published
Yearly downloads
increased by682.26%

Weekly downloads



[0.3.0-0] - 2018-02-01


  • options.fold, to fold an action to string or ArrayBuffer
    • return falsy to not folding the action to Web Socket
    • by default, fold will JSON.stringify the action if meta.send set to true or the Web Socket
  • options.unfold, to unfold a message to action
    • return falsy to not unfolding the message
    • the unfolded action must be FSA-compliant
    • by default, unfold will add meta.webSocket
  • send meta will only match against true or the Web Socket, but not options.namespace
    • this behavior can be changed by overriding options.fold



Bridge WebSocket messages and Redux actions

npm version Build Status

Inspired by redux-websocket.

This bridge middleware will:

  • Dispatch WebSocket messages into Redux store
  • Lift Redux actions to WebSocket


WebSocket provides a full duplex connection. On top of request-response model, the server can watch-and-push to the browser continuously. But comparing coding effort between REST and WebSocket, fetching data using REST is much simpler.

We want to reduce the effort to consume APIs exposed thru WebSocket.

By combining WebSocket and Flux architecture (Redux), we found that the coding effort can be dramatically lowered to a level comparable to traditional REST APIs.

Thus, we made Redux WebSocket bridge. It promotes WebSocket messages to a first-class citizen in Flux architecture, enabling front end developers with less knowledge on WebSocket to work with new collaborative and reactive services.

How to use

Store: adding middleware

import { applyMiddleware, createStore } from 'redux'; import ReduxWebSocketBridge from 'redux-websocket-bridge'; const createStoreWithMiddleware = applyMiddleware( ReduxWebSocketBridge('ws://localhost:4000/') )(createStore); export default createStoreWithMiddleware(...);

Tips: you can use namespace to add multiple ReduxWebSocketBridge

Reducer: handling incoming messages

When you receive any WebSocket messages that resembles a Flux Standard Action (FSA) in JSON, it will automatically parsed and dispatched to the store. We call this "unfold".

Server code

When the server send a JSON message that looks like a FSA, it will be automatically unfolded and dispatch to the store.

app.on('connection', socket => { socket.write(JSON.stringify({ type: 'SERVER/GREETING', payload: { version: '1.0.0' } })); });

Client code

function reducer(state = {}, action) { switch (action.type) { case 'SERVER/GREETING': // action.meta.webSocket reference to the WebSocket object return { ...state, ...action.payload, connected: true }; default: break; } }

Handling WebSocket events

For WebSocket events, they will be dispatched thru @@websocket/*.

import { OPEN, CLOSE, MESSAGE } from 'redux-websocket-bridge'; function serverConnectivity(state = {}, action) { switch (action.type) { case `@@websocket/${ OPEN }`: state = { ...state, connected: true }; break; case `@@websocket/${ CLOSE }`: state = { ...state, connected: false }; break; case `@@websocket/${ MESSAGE }`: // Process the raw message here, either string, ArrayBuffer, or Blob break; default: break; } return state; }

Action: sending WebSocket messages

There are two ways to send WebSocket messages:

Sending raw WebSocket message

Payload will be send as-is without modifications. Depends on your WebSocket implementation, you may also send ArrayBuffer or Blob.

For example, to send a message thru Slack RTM API.

import { SEND } from 'redux-websocket-bridge'; function sendHelloWorld() { return { type: `@@websocket/${ SEND }`, payload: JSON.stringify({ id: 1, type: 'message', channel: 'C024BE91L', text: 'Hello world' }) }; }

Sending action as JSON

You can also opt-in to send any action dispatched to your store thru WebSocket. On the action object, set meta.send to true (or your namespace). When you dispatch the action, the bridge will also JSON.stringify and send a copy of the action to WebSocket.

this.props.dispatch({ type: 'CLIENT/SIGN_IN', meta: { send: true } // or '@@websocket', or a WebSocket object, payload: { token: 'my very secret token' } });

The action dispatched will be sent thru WebSocket similar to the following code. Note the meta.send property is stripped from the message and is not send across the wire.

ws.send(JSON.stringify({ type: 'CLIENT/SIGN_IN', payload: { token: 'my very secret token' } }));

Tips: you can also use the bridge on server-side to unfold messages back into a Redux store

What-if: if your action is not a FSA-compliant, we will still send it thru. This behavior may change in the future.

Advanced topics

Use SockJS or other implementations

The bridge supports any libraries that adheres to WebSocket standard, for example, SockJS, which provides fallback for browser/proxy that does not support WebSocket.

const createStoreWithMiddleware = applyMiddleware( WebSocketBridge( () => new SockJS('http://localhost:3000/ws/') ) )(createStore);

WebSocket APIs used by the bridge

Your WebSocket implementation will work on the bridge if they implemented the interface below:

interface WebSocket { onopen(); onclose(); onmessage(event: { data: string }); send(data: string); }

We currently do not process onerror, we might add it in near future.

Prefer ArrayBuffer

This feature is for browser only, it requires FileReader API

WebSocket support binary message. But receiving binary data means you might be receiving either ArrayBuffer or Blob, depends on your WebSocket implementation.

For your convenience, if you set binaryType to arraybuffer in options, we will convert all Blob to ArrayBuffer before dispatching it to Redux store. Because the conversion is an asynchronous operation (using FileReader), it is easier for the bridge to convert it for you.

Vice versa, if you set binaryType to blob, we will convert all ArrayBuffer into Blob.

Reconnection logic

For simplicity, the bridge does not have any reconnection mechanism. But it is easy to implement one, thanks to simple WebSocket API.

To implement your own reconnection logic, you can create a new WebSocket-alike. When disconnected, your implementation will recreate a new WebSocket object, which reconnect to your server. You will be managing the lifetime of WebSocket objects, event subscriptions, and resend backlog.

Although you are recommended to fully implement the WebSocket API, you can check out the subset required by the bridge.

Unfolding actions from multiple bridges

We support multiple bridges. In rare cases, you may want to tag unfolded actions from multiple bridges. You can write a middleware between bridges to tag actions.

const createStoreWithMiddleware = applyMiddleware( ReduxWebSocketBridge('ws://localhost:4000/'), store => next => action => { if (action === 'SERVER/GREETING') { action = { ...action, meta: { from: 'server1', ...action.meta } }; } next(action); }, ReduxWebSocketBridge('ws://localhost:4001/'), store => next => action => { if (action === 'SERVER/GREETING') { action = { ...action, meta: { from: 'server2', ...action.meta } }; } next(action); }, )(createStore);

For clarity, we did not refactor the sample code.

In this example, we added two middleware to tag all SERVER/GREETING action, adding a meta.from property indicate where the action was from. Note the order of spread/rest property matters, we will not overriding meta.from if it was already defined.

You can refactor the code out and use RegExp for pattern-matching action types.

If this sample does not works for you, please do let us know.

Delayed connection setup

Some services requires calling their REST API before setting up a WebSocket connection, for example, Slack requires a handshake call rtm.connect to get the endpoint for their WebSocket RTM API.

You can create a WebSocket-alike to do the REST API handshake. Once your handshake is done, you can then establish the WebSocket connection. You will need to proxy events before the connection is made. But since the bridge prefer onopen than addEventListener, the effort is minimal.


binaryTypeConvert binary to "arraybuffer" or "blob"null
namespaceAction prefix for all system messages"@@websocket/"
unfoldUnfold messages as actions if they are JSON and look like a Flux Standard Actiontrue


Like us? Star us.

Something not right? File us an issue.



What is redux-websocket-bridge?

WebSocket messages to Redux action bridge

Is redux-websocket-bridge popular?

The npm package redux-websocket-bridge receives a total of 232 weekly downloads. As such, redux-websocket-bridge popularity was classified as not popular.

Is redux-websocket-bridge well maintained?

We found that redux-websocket-bridge demonstrated a not healthy version release cadence and project activity. It has 1 open source maintainer collaborating on the project.

Last updated on 01 Feb 2018


Subscribe to our newsletter

Get open source security insights delivered straight into your inbox. Be the first to learn about new features and product updates.

  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc