How to use WebSockets with node.js apps hosted in iisnode

Hero Image

Note: if you are interested in hosting WebSocket applications in IIS using iisnode, check out the more recent post at

The recent release of iisnode v0.2.0 enables using WebSockets in node.js applications hosted in IIS 8.  This functionality requires Windows Server 2012 or Windows 8. To read more about iisnode in general check out my previous post.

Getting started

After installing iisnode v0.2.0, get a sample WebSocket application from (if you are not a Git person, you can also download a ZIP):

   git clone

Next, download the node.js dependencies and set up an IIS application in IIS 8 that points to the downloaded code:

npm install  

Lastly, navigate to http://localhost/dante/server-faye.js and enjoy Dante’s Dive Comedy, Canto 1, streamed to you over WebSockets though IIS and iisnode, once stanza every 2 seconds:


Under the hood

If you have a closer look at server.js, you will notice the application uses the faye-websocket module to establish a WebSocket server, just like a self-hosted node.js WebSocket application would:

var WebSocket = require('faye-websocket')  
    , http = require('http');  
var server = http.createServer(handler);  
server.addListener('upgrade', function(request, socket, head) {  
    var ws = new WebSocket(request, socket, head);  
    // ...  
function handler (req, res) {  
    // ...  
server.listen(process.env.PORT || 8888);  


In fact, you could take this application and run it self-hosted using node.exe without any changes at all.

The iisnode module uses the functionality enabled in IIS 8 on Windows Server 2012 and Windows 8 to expose the HTTP Upgrade mechanism to the node.js application. Modules like faye-websocket, ws, or implement the WebSocket protocol on top of the HTTP Upgrade mechanism and expose WebSocket functionality to the application.

Using WebSockets in a node.js applications running in iisnode requires that – contrary to what one would expect – websockets are disabled in web.config:

    <webSocket enabled="false" />  
      <add name="iisnode" path="server-faye.js" verb="*" modules="iisnode" />  

This is required because IIS 8 provides its own implementation of the WebSocket protocol that builds on top of the HTTP Upgrade mechanism. If the IIS 8 WebSocket module remained enabled, it would conflict with the WebSocket implementation provided by the node.js application itself in the form of one of the node.js modules, e.g. faye-websocket, ws, or The IIS 8 WebSocket module is used to enable WebSocket functionality in ASP.NET applications.

So where does it leave you?

The release of iisnode 0.2.0 closes the last major functional gap between self-hosting and IIS hosting node.js applications on Windows: the availability of WebSockets. You can now host your application in IIS 8 using WebSockets as opposed to falling back to HTTP long polling. Note that WebSocket functionality is only supported on IIS 8 running on Windows Server 2012 or Windows 8. WebSocket on!


Most Recent

24 January 2022
Run Node.js from Google Sheets

Import data from any API or data source to Google Sheets using Node.js, NPM, and Fusebit Connectors.

21 January 2022
Linear and Discord Slash Commands

Learn how to build an interactive Slash Command for a Discord bot that lets users create a new issue in Linear.

19 January 2022
Add Slash Commands to Your Discord Bot!

Slash Commands are an extremely powerful way to provide rich interactivity for members of your Discord server, all you have to do is type “/” and you're ready to use your favorite bot.