Monthly Archives: April 2014

Debugging Sails Applications with WebStorm

Lately I’ve been experimenting with a Rails-like web framework based on node and express called Sails. While it’s still missing a few convenient features from Rails like view scaffolding, manual migrations, and model associations, it’s been fun to work with. I’ve been using the fantastic WebStorm editor from JetBrains, which has some great features for node development, including an interactive debugger.

What’s not straightforward, though, is how to enable debugging for a Sails app. Normally, you start a Sails application by running the sails lift command at the command line. This presents a problem when debugging with WebStorm, as the IDE assumes that you’ll be running the node executable, passing in the name of the startup file of your app. This is easy to fix, though.

First, create a new Run/Debug configuration in WebStorm, based on the default “Node.js” configuration. The “Node interpreter” and “Working directory” fields should already be filled in for you. Check to be sure the working directory is set to the root of your Sails app. In the “JavaScript file” field type “app.js” or choose it from the file explorer dialog by clicking the “…” button to the right of the “JavaScript file” field. Sails generates this file when you create a new project, but you probably wouldn’t notice it unless you were looking for it.

sails debug 1

Next, you’ll need to install the Sails npm module directly into your application, rather than relying on the module you likely installed globally if you were following the instructions on the website when getting started. To do this, type “npm install sails --save” at the command line while in the root directory of your app. Note the lack of the “-g” option; this stands for “global”, and it’s not what we want. The “--save” option just adds a dependency to your package.json file, so that if you clone the project from source control later, “npm install” will automatically download the Sails package.

You should now be able to use this configuration to run and debug your Sails app from WebStorm.

That’s great, but what if you want to use CoffeeScript in your Sails project? Both Sails and WebStorm support CoffeeScript, but the above setup will result in a CoffeeScript parsing error when you try to start up your app with any *.coffee files present. If you run “sails lift” at the command line, everything works just fine, but you’re losing the ability to debug your application. Frankly, I’m not sure what the difference is between the state of the environment created by “sails lift” and the one created by running the node executable against app.js. Fortunately, I found a workaround.

By installing the Sails module locally, you actually ended up with a copy of the code that runs when you invoke “sails lift“. All we need to do is tell WebStorm to use that instead of app.js. To do this, open up your run configuration in WebStorm and change the “JavaScript file” field to “node_modules/sails/bin/sails.js“. In the “Application parameters” field, type “lift“.

sails debug 2

This will allow your app to run via the WebStorm runner. To enable automatic generation of JavaScript files from your CoffeeScript files and the mapping files that will enable CoffeeScript debugging, we need to create a CoffeeScript file watcher. To do this, go into your Project Settings -> File Watchers, click the plus sign, and choose “CoffeeScript”. The default settings should work.

sails debug 3

Now, when you debug with WebStorm by clicking on the little green beetle, you should be able to set breakpoints in your CoffeeScript code and debug it line-by-line.