Node.js & WebSocket — Simple chat tutorial

Node.js is a brilliant product. It gives you so much freedom and I think it’s ideal for single purpose web servers.

Another great thing is WebSocket. Nowadays it’s widely supported and its usage is mostly in very specific applications such as games or Google Docs. So I wanted to try to make some very simple real world application.

WebSocket requires it’s own backend application to communicate with (server side). Therefore you have to write single purpose server and, in my opinion, in this situation Node.js is much better than writing your server in Java, C++, PHP or whatever.

Btw, if you’re looking for some more in-depth information on how WebSockets work I recommend this article Websockets 101.

In this tutorial I’m going to write very simple chat application based on WebSocket and Node.js.

Chat features

At the beginning every user can select their name and the server will assign them some random color and will post some system message to the console that a new user just connected. Then the user can post messages. When a user closes the browser window, server will post another system massage to the console that a user has disconnected.

Also, every new user will receive entire message history.


Frontend is very simple HTML and CSS for now. We’ll add some JavaScripts later.

Communication client -> server, server -> client

Great advantage of WebSocket is two way communication. In this tutorial it means situation when some user sends a message (client -> server) and then server sends that message to all conected users (server -> client) — broadcast.

For client -> server communication I choosed simple text because it’s not necessary to wrap it in more complicated structure.

But for server -> client it’s a bit more complex. We have to distinguish between 3 different types of message:

  • server assigns a color to user
  • server sends entire message history
  • server broadcasts a message to all users

Therefore every message is a simple JavaScript object encoded into JSON.

Node.js server

Node.js itself doesn’t have support for WebSocket but there are already some plugins that implement WebSocket protocols. I’ve tried two of them:

  • node-websocket-server — (now deprecated) very easy to use, but it doesn’t support draft-10. That’s a big problem because Chrome 14+ supports only draft-10 which is not compatible with older drafts. According to issues on GitHub the author is working on version 2.0 that should support also draft-10.
  • WebSocket-Node — very easy to and well documented. Supports draft-10 and also older drafts.

In this tutorial I’m going to use the second one, so let’s install it with npm (Node Package Manager) which comes together with node.js. There might be a little tricky if you're using Windows because it needs to compile some small part of the module from C++ (read more on

WebSocket server template

WebSocket server code template looks like this:

So, this is just the most basic skeleton that we’ll extend now with more logic.

WebSocket server full source code

That’s all for the server part. I added comments where it was appropriate but I think it’s very simple to understand.

Frontend application

Frontend app template is basically just three callback methods:

Frontend full source code

Frontend is quite simple as well, I just added some logging and some enabling/disabling of the input field so it’s more user friendly.

Again I tried to put comments where it’s appropriate, but I think it’s still very simple.

Running the server

I wrote and tested the server on node.js v0.4.10 and v0.5.9 but I think I’m not using any special functions so it should run on older and newer version without any problem. If you’re using Windows node.js > 0.5.x comes with Windows executable. I tested it on Windows as well.

So under Unix, Windows or whatever:

and you should see something like this

Now you can open chat.html and if everything's fine it should ask you for your name and the server should write to the console:

So what’s next?

That’s actually all. I’m adding a few notes at the end just to make some things a little bit more obvious.

Pros and cons of node.js

For this purpose is node.js ideal tool because:

  • It’s event driven. Together with closures it’s very simple to imagine the client lifecycle.
  • You don’t have to care about threads, locks and all the parallel stuff.
  • It’s very fast (built on V8 JavaScript Engine)
  • For games you can write the game logic just once and then use it for both server and frontend.
  • It’s just like any other JavaScript.

On the other hand there are some gotchas:

  • It’s all relatively new. I haven’t seen many real applications in Node.js. Just a bunch of games and some nice demos.
  • Node.js unlike Apache doesn’t use processes for each connection.

The last point has some important consequences. Look at the server source code where I’m declaring colors variable. I hard coded 7 colors but what if there were 7 active connections and 8th client tried to connect? Well, this would probably threw an exception and the server would broke down immediately because the exception is uncaught.

The problem is that Apache runs separate process for each request and if you have a bug in your code it brakes just one process and doesn’t influence the rest. Of course, creating new processes for each client is much better in terms of stability but it generates some overhead.

I like talk HTML5 Games with Rob Hawkes of Mozilla where Rob Hawkes mentions that he used monit to observe if the server is running and eventually start it again in the case it broke.

What about is an interesting project (it’s a module for node.js) implementing WebSocket backend and frontend with many fallbacks for probably every possible browser you can imagine. So I should probably explain why I’m not using it.

The first reason is that I think it’s always better to try to write it by yourself first because then you have much better insight what’s going on and when it doesn’t work you can easily figure out why.

The second reason is that I want to try to write some simple games using WebSocket. Therefore all the fallbacks provided by are useless because I need as low latency as it’s possible. Also, there is some magic / which is probably generated according to your browser's capabilities but I'm rather trying to avoid debuging javascripts for IE6 :).

I thing is great, but it would be very unpleasant if I spent month of writing a game and then realised that generates so much overhead so it’s useless and I had to rewrite it.

Anyway, for other applications (like this chat for instance) would be ideal, because ±100ms is absolutely irrelevant and this chat would work on all browser and not just Chrome 14+ and Firefox 7+.

What if I want some usage statistics?

I think good questions is how can I dig some information from the WebSocket server like number of active connections or number sent messages?

As I mentioned at the beginning is tied to HTTP server. At this moment it comes handy because we can run on the same port WebSocket server and also HTTP server.

So let’s say, we want to be able to ask the server for number of current connections and number of all sent messages. For this purpose we have to create simple HTTP server that knows just one URL (/status) and sends JSON with these two numbers as a response.

Now when you access http://localhost:1337/status you should see something similar to:

Clients and history are two global variables (I know, bad practise) that I'm using for different purpose but in this situation I can reuse them easily without modifying rest of the server.


I put all source codes on GitHub, so feel free to modify whatever you want.


That’s all for this tutorial. I would be really glad if you could post to comment some examples of WebSocket usage that you liked (it doesn’t have to be built on Node.js).

Additional resources