Damir's Corner.

Using WebStorm to Debug CoffeeScript Grunt Scripts in Windows

Creating a Debug Configuration

As soon as I started developing my first Grunt multi task, it became obvious that being able to debug it, will shorten my development time a lot. Since I've been recently using WebStorm as my JavaScript IDE of choice, I also wanted to be able to debug my task directly inside it. To no surprise, WebStorm has built-in support for debugging all kinds of Node.js scripts, including Gruntfiles. It's only a matter of getting used to WebStorm's debugging workflow.

Although there's support for temporary debug configurations which can be created ad hoc, this approach can't be used for debugging Grunt scripts. A proper debug configuration needs to be created for that, using Run/Debug Configurations dialog (accessible via Run > Edit Configurations... menu). The little "plus" icon in its top left corner opens a menu with a selection of preconfigured templates for debugging different types of Node.js scripts. Among them is also Grunt.js - the one that we need to use.

If you have your Node.js environment correctly setup and grunt-cli package installed globally, two important fields should already be prefilled for you:

• Node interpreter should point to your Node executable (C:\Program Files\nodejs\node.exe in my case)
• Grunt-cli package should point to where you have the package globally installed (C:\Users\damir\AppData\Roaming\npm\node_modules\grunt-cli in my case)

The only things left for you to fill in are the configuration Name (up to you) and the path to the Gruntfile you want to the debug. Optionally you can also set the Tasks to run if you want to debug anything else than default.

Debugging a CoffeeScript Gruntfile

If you have written your Grunt script in JavaScript, then that's all you need to do. You can now set a couple of breakpoints and start debugging using the Run menu or the Debug tool window (the latter will open automatically once you start debugging, if you have it closed). If your Gruntfile is written in CoffeeScript, you're not done yet. Even though Grunt can run CoffeeScript scripts directly, WebStorm will report errors if you set a CoffeeScript Gruntfile in your debug configuration.

My next attempt was starting the Node interpreter directly and attaching to it from WebStorm. Not only was that much less convenient (having to manually start Node from command line every time), the mapping to CoffeeScript source was also mismatched, which made the approach almost useless.

It turned out that WebStorm's file watchers were the right way to go. You will first need to configure a CoffeeScript file watcher in the Settings dialog. Select Tools > File Watchers node in the tree view on the left (you can search for file watchers, to find it quicker) and click on the "plus" icon in the top right corner to add a new file watcher, based on CoffeeScript template. Again, almost everything is preconfigured for you; only the Program must be chosen manually. I suggest you install the coffee-script NPM package globally and point to coffee.cmd file it installs in the root of your global package installation directory (C:\Users\damir\AppData\Roaming\npm in my case).

Now your CoffeeScript Gruntfile will automatically be converted to a JavaScript one, whenever WebStorm detects changes. A JavaScript source map will be generated alongside it, allowing you to debug the original CoffeeScript file instead of the converted JavaScript one. You will still need to point to the JavaScript Gruntfile in the WebStorm debug configuration, though. Also, to make sure the converted file is always up-to-date, you should require the debug configuration to Run File Watchers before launching the script.

Now, you will be able to debug your CoffeeScript Gruntfile just as if it was written in JavaScript.