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

John Lindquist

*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

Comments below can no longer be edited.

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

  1. Stefan says:

    March 4, 2013

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

    • Fedor Korotkov says:

      March 4, 2013

      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:

        March 4, 2013

        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.

        • Fedor Korotkov says:

          March 4, 2013

          Did you enable “Upload external changes”?

          • Oskar Risberg says:

            March 13, 2013

            I can confirm this. Doesn’t work with “Upload external changes”.

            PhpStorm 6 on Mac OS X 10.8.2

          • Stanislav Gamayunov says:

            March 14, 2013

            I can confirm this. It work time-by-time.

            PhpStorm 6 on Windows 7 x64.

  2. Soren says:

    March 4, 2013

    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:

    March 4, 2013

    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?

    • Eugene Toporov says:

      March 5, 2013

      Eduard, next PyCharm update (2.7.2) will enable this plugin.

  4. Nazar says:

    March 4, 2013

    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:

      March 4, 2013

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

      • Nazar says:

        March 5, 2013

        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:

          March 9, 2013

          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!

          • Fedor Korotkov says:

            March 11, 2013

            You need to modify arguments too. Not only the output paths.

            If you want to generate css files to the parent folder please check this settings

          • Sergey S says:

            March 12, 2013

            Well, what about exclude from compiling _buttons.css etc. with prefix _ ?

            Option “root files only” doesn’t work at all ((

      • Frederik Peiniger says:

        March 13, 2013

        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)

        • Olivier says:

          March 21, 2013

          It works, thanks for the tip !

  5. Rarst says:

    March 4, 2013

    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:

      March 7, 2013

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

  6. Robert Isaev says:

    March 7, 2013

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

    • Fedor Korotkov says:

      March 11, 2013

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

      • Stuart Barker says:

        March 13, 2013

        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:

          March 13, 2013

          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:

          March 22, 2013

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

    • Paul Lomax says:

      March 19, 2013

      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:

    March 7, 2013

    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:

    March 9, 2013

    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:

      March 11, 2013

      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.

      • Martin says:

        March 12, 2013

        Tried that, did not help. Still lags one edit behind.

    • Andrey says:

      April 6, 2013

      С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:

    March 12, 2013

    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?

    • ragtek says:

      April 5, 2013

      i’m having the same problem

  10. Amparose says:

    March 12, 2013

    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:

    March 13, 2013

    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:

    March 14, 2013

    Would be great to see image compression/optimisation too!

  13. PyCharm 2.7.2 EAP | JetBrains PyCharm Blog says:

    March 14, 2013

    […] for Emmet (a new version of Zen Coding, a powerful abbreviation system for HTML/CSS developers) and File Watchers (a tool for automatic background compilation of CoffeeScript, SASS and other Web […]

  14. Samuele says:

    March 18, 2013

    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:

    March 23, 2013


    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:

    March 25, 2013

    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.

    • Dan Farrow says:

      March 26, 2013

      Kevin – just disable the file watcher in settings

    • Dan Farrow says:

      March 26, 2013

      Oh whoops that won’t work, sorry.

      I see there’s an area labelled Supressed watchers which suggests there’s a way to achieve what you’re after.

      I haven’t yet worked out how to supress a watcher…

  17. Grgur Grisogono says:

    April 2, 2013

    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:

    April 5, 2013

    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:

    April 25, 2013

    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. PhpStormでHandlebars.jsを使う | says:

    July 16, 2013

    […] 今回は、JetBrainsのフォーラムを参考にしました。2件のコメントがあったのですが、一方はワイルドカードを使ったプリコンパイル、もう一方は、1つ1つをプリコンパイルする方法を提示しています。 File Watchers in WebStorm/PhpStorm #comment-42174 […]