node package manager
Stop wasting time. Easily manage code sharing in your team. Create a free org »


simple-websocket travis npm downloads javascript style guide

Simple, EventEmitter API for WebSockets

Sauce Test Status


  • super simple API for working with WebSockets in the browser
  • supports text and binary data
  • node.js duplex stream interface
  • client & server implementations

This module works in the browser with browserify, and it's used by WebTorrent!


npm install simple-websocket

real-world applications that use simple-websocket

  • StudyNotes - Helping students learn faster and better
  • WebTorrent - The streaming torrent app
  • bittorrent-tracker - Simple, robust, BitTorrent tracker (client & server) implementation
  • - Secure, anonymous, streaming file transfer
  • lxjs-chat - Omegle chat clone
  • [ your application here - send a PR ]


var Socket = require('simple-websocket')
var socket = new Socket('ws://')
socket.on('connect', function () {
  // socket is connected!
socket.on('data', function (data) {
  console.log('got message: ' + data)

Note: If you're NOT using browserify, then use the standalone simplewebsocket.min.js file included in this repo. This exports a SimpleWebsocket function on the window.


socket = new Socket(url)

Create a new WebSocket connection to the server at url. This usage is a shorthand for `socket = new Socket({ url: url })

socket = new Socket(opts)

If opts.url is specified as a string, then a WebSocket connection will be created to the server at opts.url.

If opts.socket is specified as an instance of a raw WebSocket object, then the given WebSocket object will be used and one will not be automatically be created internally. (This is for advanced users.)

Other properties on opts will be passed through to the underlying superclass, stream.Duplex.


Send text/binary data to the WebSocket server. data can be any of several types: String, Buffer (see buffer), TypedArrayView (Uint8Array, etc.), ArrayBuffer, or Blob (in browsers that support it).

Note: If this method is called before the socket.on('connect') event has fired, then data will be buffered.


Destroy and cleanup this websocket connection.

If the optional onclose paramter is passed, then it will be registered as a listener on the 'close' event.


Detect WebSocket support in the javascript environment.

var Socket = require('simple-websocket')
  // websocket support!
} else {
  // fallback


socket.on('connect', function () {})

Fired when the websocket connection is ready to use.

socket.on('data', function (data) {})

Received a message from the websocket server.

data will be either a String or a Buffer/Uint8Array (see buffer). JSON strings will be parsed and the resulting Object emitted.

socket.on('close', function () {})

Called when the websocket connection has closed.

socket.on('error', function (err) {})

err is an Error object.

Fired when a fatal error occurs.


The server implementation is basically ws but the 'connection' event provides sockets that are instances of simple-websocket, i.e. they are duplex streams.

var Server = require('simple-websocket/server')
var server = new Server({ port: port }) // see `ws` docs for other options
server.on('connection', function (socket) {
  socket.on('data', function (data) {})
  socket.on('close', function () {})
  socket.on('error', function (err) {})


MIT. Copyright (c) Feross Aboukhadijeh.