File Watchers in WebStorm/PhpStorm 6 (a.k.a. “Background Tasks”)

*Note – users of other JetBrains IDEs (RubyMine, PyCharm, IntelliJ IDEA, …) will need to download and install the File Watchers plugin to use this functionality (available for free). The plugin is already bundled with WebStorm and PhpStorm.

Many users have requested variations of “Automatic JS/CSS minification,” “Automatic TypeScript compilation,” “Automatic Less compilation,” and many others.

Supporting all of these features requires leveraging myriad tools. Let’s just list a few with the most votes (in no particular order):

That list is a very small sample of the tools available in the wide world of Web development (and the list is going to just keep getting bigger every day).

Our solution to support this large set of tools is simple: File Watchers.

When WebStorm detects that you’re using a type of File which it can “watch” for you, it will prompt you to set up a File Watcher (or you can customize your own).

Below is an example of the TypeScript File Watcher:

From this panel, you can see this File Watcher will do the following:

  1. Watch for changes on all TypeScript files (within the defined scope)
  2. Compile them using ‘tsc’ (the TypeScript compiler) when they change
  3. Uses arguments for any additional flags required by the tool (like –sourcemap for tsc)

By default, the File Watchers will trigger while you type. If you’d rather wait until you manually save your files with File->Save All (or when the IDE triggers a save when you switch to a new file), then uncheck the “Immediate File Synchronization” checkbox. This is especially helpful if you’ve set up the IDE to automatically upload files.

The generated files (in the case of TypeScript, a JavaScript file and a Sourcemap) will appear grouped under the TypeScript file. This allows you to keep project view neat and organized so you can focus on your TypeScript:


WebStorm 6 will include templates for the following compilers:

  • YUI Compressor CSS
  • TypeScript
  • YUI Compressor JS
  • Closure Compiler
  • CoffeeScript
  • CoffeeScriptReduxSourceMap
  • LESS
  • SASS
  • SCSS
  • UglifyJS

If you get lost or want to get more info on the options, just check out the help:

Or click here for an explanation of each of the settings:

Even though we include the template, you will still need to install the external compilers/tools that the templates will use. For example, TypeScript requires the NodeJS to be installed. Then, to install TypeScript, you need to execute “npm install -g typescript” from the terminal.

We encourage you to experiment with the settings with each of the templates. Also, feel free to integrate your own custom tools using the File Watcher panel to see what you can achieve.

Please download the latest build, provide feedback for bugs and feature requests here, and leave questions in the comments below or in our forums!

Develop with pleasure!
-JetBrains WebStorm Team

This blog is permanently closed.

For up-to-date information please follow to corresponding WebStorm blog or PhpStorm blog.

This entry was posted in Cool Feature, PhpStorm, WebStorm. Bookmark the permalink.

50 Responses to File Watchers in WebStorm/PhpStorm 6 (a.k.a. “Background Tasks”)

  1. Stefan says:

    Hi, is it possible to use “automatic upload” for compiled files?

    • Fedor Korotkov says:

      A compiled file is a regular file. Automatic upload should work for them as expected.

      FYI you may want to reduce an amount of uploads. To do so, just disable “Immediate file synchronization” option.

      • Sebastian Michaelsen says:

        This seems not be the case. Automatic upload for generated Files (SCSS => CSS) doesn’t work for me. Neither with “always” nor with “on explizit save” option.

  2. Soren says:

    A problem I’m having with this plugin is that every time a create a new watch I have to go to my terminal, copy the echo $PATH then go into the environment variables field create a new one called PATH, pasting into it. I feel like I’m doing repetitive work that the IDE should be doing.

    So the question is: is it possible to fix this workflow using the tools the platform already offers, or is this an area in it that needs improvement?

  3. Eduard says:

    Sadly, the File Watchers plugin is not supported in PyCharm (it doesn’t show in the plugin list, and is not active when it is installed from disk). Is it intended this way?

  4. Nazar says:

    I have several scss files like _config.scss, _mixins.scss, how to exclude them from compiling, compiling only style.scss, that includes files mentioned before?

    At the same time I want to recompile style.scss when configuration file was changed.

    Previously I’ve used language preprocessor for this, but file wacher looks better.

    • Fedor Korotkov says:

      You can enable “Track only root files” option. The plugin will compile only style.scss on every change of included files.

      • Nazar says:

        This doesn’t works for me. Option is selected, but anyway _layout.scss file compiles to _layout.css, and style.css doesn’t changes.

        Even in latest build 127.67

        • Matt MacLaurin says:

          not working for me either. 127.68: _items.scss gets compiled into _items.css even though it’s included in main.scss and “root files only” is selected.

          the output directory isn’t being respected either. I have it as “../$FileNameWithoutExtension$.css”, yet the output file is dumped in the same directory as the input file.

          Finally, it looks like the output path should automatically be placed into the “arguments” field, but it isn’t; with the output path shown above, the arguments still reads as “$FileName$:$FileNameWithoutExtension$.css”

          Looks a bit half-baked, guys!

      • Just found out that the “track only root files” option in case of SCSS (that’s the only one I tested) only works as expected if you use the @import syntax with full filenames.

        e.g. you have to use
        @import “foo.scss”; (or @import “_foo.scss” if it’s a partial)
        instead of
        @import “foo”;
        to get this feature to work correctly. Once changed it works correctly.

        Would be great if you could add support for the other syntax aswell (@import “foo” could mean to import “foo.scss” or “_foo.scss”, depends whether it’s a partial or not)

  5. Rarst says:

    Weird that it’s not getting bundled with PhpStorm…

    So it is going to need external compiler for LESS? Node? There is already the LESS compiler plugin that has no external dependencies.

    • Mikhail Vink says:

      It is bundled with PhpStorm from the Public Preview version.
      Yes, you need an external compiler.

  6. Robert Isaev says:

    Drops me an error while trying to include compass built-in files. Does compass support coming ? Anyway, great feature, thank you!

    • Fedor Korotkov says:

      Please vote up and check this comment Also there is a useful forum thread

      • Stuart Barker says:

        I am also getting

        error screen.scss (Line 6: File to import not found or unreadable: compass/reset.
        Load path: /Users/stu/Projects/Hearst/commercial/company/nokia/c1/sass)

        So is the filewatcher something extra I have to install or is it already working with phpStorm v6?

        • Stuart Barker says:

          I’ve just tried to trick it by putting a symbolic link in my sass folder to the compass library, it nearly works I now get /usr/bin/scss –no-cache –update screen.scss:screen.css
          error compass/reset/_utilities.scss (Line 116: Invalid CSS after “elements-of-type”: expected selector, was “(html5-block)”)

          Anyone got any ideas? what I like about this vs a filewatch is it seems to be compiling on every single change not just a save.

        • Stuart Barker says:

          I’ve worked out how to get compass compiling on the mac

    • Paul Lomax says:

      Okay, took me a while to figure this out. I used to use Compass App on Windows, but figured this would be cleaner.

      Install Ruby (, make sure to add the paths when installing.

      Install Compass (type ‘gem install compass’)

      Shut down and restart storm so it picks up the paths. If you just want to use SASS at this stage, Storm will automatically add the path to sass.bat for you, so just add the watcher and it just works.

      To use compass, add an SCSS watcher then use these options:

      Program: C:\Program Files\Ruby\bin\compass.bat (or wherever Ruby is installed)
      Arguments: compile –trace –sass-dir css –css-dir css -s expanded –no-line-comments
      Working Directory: $FileParentDir$

      You will need to change the folders to how you like your CSS folders set up, but thats it. You wont need a config.rb file.

      If you type ‘compass help compile’ on the command line it will give you all the compile options so you can tweak the arguments how you like them.

  7. Jason says:

    Just tried this out with typescript, had a little trouble getting it working the tsc.cmd wasn’t finding my node executable but once I got that working…wow! very nice work! If you are a windows user make sure to set the program in Edit Watcher to \tsc.cmd not just \tsc as it shows in the example.

  8. Martin says:

    I am having slight issues with a custom Jade watcher. I’ve just added it, and it generates the html just fine. But when I have a Live edit session running from the html, it always lags one edit behind – when I make a change in the .jade file, the browser gets updated to the previous state, always lagging a save behind. Is there anything to do about it?

    • Fedor Korotkov says:

      You can try to disable “Immediate file sync” option for your custom file watcher. After that just press Ctrl/Cmd + S to manually notify the watcher about changes.

    • Andrey says:

      Сould you send a sample of your custom Jade watcher at the my address and please write me how exactly you are processing Jade files.
      I am struggling with this problem for several days and can not find a solution.
      ‘ll be very grateful.

  9. servage says:

    How to use SCSS for windows. How to setup New Watcher? When i try to setup it i got Please set program to run!, but what program?

  10. Amparose says:

    Why does this not work (Windows env):


    For the Program field?

    Also I get an error saying that the less.min.js is not a valid Win32 application… Is there a chunk of the manual missing on how to actually get any of these watchers working?

  11. Yop says:

    I’ve tried so hard to set a file watcher to my .coffee file and the result is so
    error messages displaying like :

    image link

  12. Matt says:

    Would be great to see image compression/optimisation too!

  13. Pingback: PyCharm 2.7.2 EAP | JetBrains PyCharm Blog

  14. Samuele says:

    To automatically upload external changed files go to:
    and check
    Upload External changes.
    For file watcher set the path to monitor under “Scope”
    Program: “C:\Program Files (x86)\lessc\lessc.cmd” (path to lessc compiler.. to download see here
    Arguments: “main.less main.css”
    Working directory: “$ProjectFileDir$\media\styles\”
    Environment variables :”” (void)
    Output paths :”” (void)
    Create output file from stdout: unckecked

  15. Shoaib says:


    I don’t see an option for installing it in Idea. The plugin is neither bundled with idea 12 nor it shows up in plugin repository.


  16. Kevin Parkerson says:

    This functionality is cool, but I already have my own solution for this that works just as well. How do I get Webstorm to stop prompting me every time it detects a file it can watch? It’s annoying to have to click dismiss each time I open a LESS file.

  17. Grgur Grisogono says:

    Thanks for a cool feature. I like the idea of having multiple watchers without having to launch respective processes through console (e.g. compass + grunt).

    One thing I’d point out is the delay before a watcher kicks in. I don’t like seeing errors just because I still haven’t finished the line of code (-> Exception). Then if I finish the line while the watcher was running, it doesn’t get respawned and the change is not applied.

    It’d be great to configure watchers to react on blur.

    Other than that, good work, team!

  18. Toon says:

    I’m using this plugin for compiling my handlebars template files into one js file.

    Program: /usr/local/bin/handlebars
    Arguments: $FileDir$/*.handlebars -f $FileDir$/templates.js

    Because I want all the handlebars files in this folder to be compiled into one, I use *.handlebars. This is how I do it in terminal console.

    But I get this response from handlebars:
    Unable to open template file ” ……/*.handlebars”

    If I use $FilePath$ it works but I only process this file and I’ll need all the files to compile into one. Not just the one I worked on.
    Are there some macros I can use to add all files with extension “handlebars”?

  19. Marc Stock says:

    I also set this up for handlebars. My config is a little different than Toon’s because I’m on Windows and I’m just generating compiled templates one at a time into independent js files. So, my program dir is:


    My arguments are: $FileDir$/$FileName$ -f $FileDir$/$FileNameWithoutExtension$.js

    Set the file type and you’re all set!

    This assumes you’ve done an npm install global for handlebars.

  20. Pingback: PhpStormでHandlebars.jsを使う |

Comments are closed.