Running NodeJS in Harmony Mode on Azure Web Apps

One of my big things is taking advantage of newer language features – right now, that’s ASP.NET5 and ECMAScript 2015. NodeJS already has a lot of the ECMAScript 2015 features. You may have to run node --es_staging or node --harmony for some features, which is a problem when you upload your service to a cloud provider like Azure. Thankfully, more and more features are in the standard set of features supplied in NodeJS. How do you get your scripts to run with the correct environment attached?

The main component of Microsoft Azure App Service is the Web App, and I’ve blogged about creating a web app before. One file I failed to mention is iisnode.yml. This is a YAML file that Azure creates for you if you don’t supply one. It contains, by default, the path to the NodeJS runtime executable. Unfortunately, you don’t know where that is and it can change over time, which makes it a pain to handle.

Getting the iisnode.yml

To download the iisnode.yml file, you need to get the publish settings, open them up, then use the ftp publish settings to download the file. First off, log into and select your web app. You want to download the Publish Settings file for your site. It’s available on the main page of your web app within the portal:


This will download an XML file. The best place to open this is in a web browser. Add a .xml extension to the file before you do this though. When you do, it looks like this:


Don’t bother checking out these publication settings – the test site I used has already been removed. Create your own web site and download your own publish settings. You will note that there are two publication settings – one for MSDeploy and the other for FTP. You will want the FTP one. You need the publishUrl, the userName and the userPWD for the FTP deployment method. Open up a new web browser page and cut and paste the publishUrl into the address bar. It will prompt you for the username and password – use cut and paste to enter those too.

Note: Don’t use Internet Explorer as your web browser for this – it doesn’t allow cut and paste from an XML document. I used Opera instead.

Assuming you’ve already got a deployed application in there and the package.json has an engines section, here is what you will see in the wwwroot directory:


There is the mysterious iisnode.yml file. So, what’s in that file? Here are my contents:

nodeProcessCommandLine: "D:\Program Files (x86)\nodejs\4.1.2\node.exe"

Right now, Azure Web Apps is running v4.1.2 (also known as the very latest node version). You can easily add the –harmony flag to this file and then check it into the root of your project. Note that the file MUST be called iisnode.yml and it MUST appear in the top-level directory of your project once deployed, which generally means the top-level directory of your project.

A Warning

And this is a big one. You are specifying a specific path here. Microsoft may change this path. It will definitely change as the version of NodeJS changes. If you specify, for example, “node >= 4.1.0”, then when NodeJS 5.0 comes out (probably next month), this path will also change. You are hard-coding something here.

So don’t do this unless you absolutely need a feature that hides behind a flag.

Since ES6 features are moving within V8 from harmony to staging to production, you will find that your application is less and less likely to need the harmony flag. You can check compliance by utilizing the Kangax Compat Table, although it isn’t showing v4.1.x compatibility as of right now. Another good page is the NodeJS ES6 page, which lists the features that it supports.