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!


Related Content

2 February 2022
fetch() In Node.js Core: Why You Should Care

Node 17.5 introduces support for the fetch() HTTP client, a new way to send requests to HTTP APIs.

23 February 2022
Node.js Adds Support for Direct Registry-less HTTPS Imports

Node is planning to introduce support for HTTPS imports in Node 18 - a feature that enables you to use urls to directly import modules over HTTPS into your project.

15 February 2022
Run Every Node.js Version in AWS Lambda

Run any version of Node.js in AWS Lambda within hours after release using custom AWS Lambda runtimes from Fusebit