Upon popular demand for YAML configuration (or rather lack of demand for angle brackets of web.config), iisnode v0.1.20 adds support for specifying configuration options in a YAML file. This allows you to use an established, user-friendly format to control most aspects of hosting node.js applications in IIS on Windows using iisnode.


You can use iisnode.yml file to control several configuration options for iisnode. For a full and current list with a description see here.

 1 # The optional iisnode.yml file provides overrides of   
 2 # the iisnode configuration settings specified in web.config.  
 4 node_env: production  
 5 nodeProcessCommandLine: "c:\program files\nodejs\node.exe"  
 6 interceptor: "c:\program files\iisnode\interceptor.js"  
 7 nodeProcessCountPerApplication: 1  
 8 maxConcurrentRequestsPerProcess: 1024  
 9 maxNamedPipeConnectionRetry: 24  
10 namedPipeConnectionRetryDelay: 250  
11 maxNamedPipeConnectionPoolSize: 512  
12 maxNamedPipePooledConnectionAge: 30000  
13 asyncCompletionThreadCount: 0  
14 initialRequestBufferSize: 4096  
15 maxRequestBufferSize: 65536  
16 watchedFiles: *.js;iisnode.yml  
17 uncFileChangesPollingInterval: 5000  
18 gracefulShutdownTimeout: 60000  
19 loggingEnabled: true  
20 logDirectory: iisnode  
21 debuggingEnabled: true  
22 debuggerPortRange: 5058-6058  
23 debuggerPathSegment: debug  
24 maxLogFileSizeInKB: 128  
25 maxTotalLogFileSizeInKB: 1024  
26 maxLogFiles: 20  
27 devErrorsEnabled: true  
28 flushResponse: false  
29 enableXFF: false  
30 promoteServerVars:

The iisnode.yml configuration file is not a replacement of web.config: both can exist at the same time. However, if iisnode.yml is present, its settings override the values specified in the system.webServer\iisnode section of web.config.


By default, when the iisnode.yml configuration file changes, iisnode will gracefully recycle the node.js application. Active requests will be allowed to finish, but all new requests will be handled by a newly created node.js process that uses new configuration values.

So why do I still need web.config?

Even if you use iisnode.yml file to configure your node.js application running in iisnode, you still need to include a web.config file. Since IIS is a hosting environment that supports a vast (and extensible) variety of content types running side by side (static files, ASP.NET apps, PHP, node.js , …), web.config is a mechanism to tell IIS that your node.js entry point (e.g. server.js) should be handled by iisnode. In addition, web.config provides the full control over how IIS behaves and can add unique value to your node.js application as explained below.

The good news is that in majority of situations you can use a boilerplate web.config below and never come back to it, relying solely on iisnode.yml for configuration of node.js applications running in IIS.

 1 <?xml version="1.0" encoding="utf-8"?>  
 2 <configuration>  
 3     <system.webServer>           
 4       <handlers>  
 5            <add name="iisnode" path="server.js" verb="*" modules="iisnode"/>  
 6      </handlers>  
 7       <rewrite>  
 8            <rules>  
 9                 <rule name="LogFile" patternSyntax="ECMAScript" stopProcessing="true">  
10                      <match url="iisnode"/>  
11                 </rule>  
12                 <rule name="NodeInspector" patternSyntax="ECMAScript" stopProcessing="true">                      
13                     <match url="^server.js\/debug[\/]?" />  
14                 </rule>  
15                 <rule name="StaticContent">  
16                      <action type="Rewrite" url="public{{REQUEST_URI}}"/>  
17                 </rule>  
18                 <rule name="DynamicContent">  
19                      <conditions>  
20                           <add input="{{REQUEST_FILENAME}}" matchType="IsFile" negate="True"/>  
21                      </conditions>  
22                      <action type="Rewrite" url="server.js"/>  
23                 </rule>  
24            </rules>  
25       </rewrite>  
26    </system.webServer>  
27  </configuration>

The web.config above has the following effect:

  1. It specifies server.js as the entry point to your node.js application.
  2. It redirects all requests for URLs that map to physical files in the “public” subdirectory to an IIS static file handler. Using IIS static file handler has a large performance benefit compared to serving static content from within a node.js application. The handler leverages IIS and OS low level caching mechanisms which offer superb performance.
  3. It allows IIS to serve the log files that capture output of a node.js application as static files such that you can access them over HTTP. By default, if your server.js entry point is reached at, the log files would be accessible at
  4. It exposes the built-in node-inspector debugger at Learn more about debugging with iisnode.
  5. It sends all other HTTP requests to be processed by your node.js application in server.js.

Try it out

Get your copy if iisnode at and give YAML config a try!

Blog Logo

Tomasz Janczuk



Tomek on Software

Software - shaken, not stirred

Back to Overview