WebStorm 2016.2 Help

Using File Watchers

On this page:

Basics

WebStorm supports integration with various third-party transpilers that run in the background and perform the following:

  • Translate Less, Sass, and SCSS source code into CSS code.
  • Translate TypeScript and CoffeeScript source code into JavaScript code, possibly also creating source maps to enable debugging.
  • Compress JavaScript and CSS code.
Note that WebStorm does not contain built-in transpilers but only supports integration with the tools that you have to download and install outside WebStorm.

In WebStorm, these transpiler configurations are called File Watchers. For each supported transpiler, WebStorm provides a predefined File Watcher template. Predefined File Watcher templates are available at the WebStorm level. To run a transpiler against your project files you need to create a project-specific File Watcher based on the relevant template, at least, specify the path to the transpiler to use on your machine.

You can download a transpiler of your choice and set it up as a File Watcher. However, in this case no predefined template is available so you will have to specify all the settings manually.

To be applicable, a File Watcher must be enabled by selecting the check box next to it on the File Watchers page of the Settings dialog box, see Enabling and Disabling File Watchers. After that the File Watcher will be invoked automatically upon any changes made to the source code or upon save, depending on whether the Immediate File Synchronization check box is selected or cleared, see New Watcher Dialog.

The output of a File Watcher is stored in a separate file. The predefined templates suggest the type of the file depending on the transpiler type. By default the output file is created in the same folder as the input file when the File Watcher is invoked for the first time, whereupon this file is only updated. You can customize all these settings during File Watcher creation.

JavaScript files generated by File Watchers are excluded from code completion and refactoring.

In the Project tree view, the output file is shown under the original file which is shown as a node. This is done to improve visibility so you can easier locate necessary files.

File watchers have two dedicated code inspections:

  • The File watcher available inspection is invoked in every file that is recognized as subject for applying a predefined file watcher (Sass, Less, SCSS, TypeScript, or CoffeeScript). If none of the applicable predefined File Watchers is associated with the current project, WebStorm suggests to add one.
  • The File watcher problems inspection is invoked by a running File Watcher and highlights errors specific for it.

To create a project File Watcher based on a predefined template, perform these general steps:

  1. Make sure the transpiler to use is downloaded and installed on your machine.
  2. Make sure the File Watchers plugin is enabled. The plugin is bundled with WebStorm and activated by default. If the plugin is not activated, enable it on the Plugins page of the Settings / Preferences Dialog as described in Enabling and Disabling Plugins.
  3. Specify the File Watcher name, type, and description.
  4. In the Options area, configure the behaviour of the File Watcher: the events that will invoke it, from which files it can be invoked, when you want the console shown, etc.
  5. In the Watcher Settings area, configure interaction with the transpiler and its behaviour: the path to the executable file, the arguments to pass to it, the acceptable input and expected output file types, etc.

Specifying the File Watcher name, type, and description

  1. Open the Settings / Preferences Dialog by pressing Ctrl+Alt+S or by choosing File | Settings for Windows and Linux or WebStorm | Preferences for OS X, and click File Watchers under Tools.
  2. The File Watchers page that opens, shows the list of File Watchers that are already configured in the project. Click the Add button new.png or press Alt+Insert and do one of the following:
    • Choose the predefined template to create the File Watcher from. The choice depends on the transpiler you are going to use.
    • To set up a transpiler of your choice, choose Custom.
    After you choose the relevant template or the Custom option, the New Watcher dialog box opens.
  3. In the Name text box, type the name of the File Watcher. By default, WebStorm suggests the name of the selected predefined template.
  4. Provide a brief description of the File Watcher's functionality. Predefined templates already contain general information regarding the accepted input and produced output. Expand or update the description, if, for example, you have two File Watcher that apply to the same source code but differ from each other in some configuration settings. .

Configuring the behaviour of the File Watcher

In the Options area of the New Watcher dialog box, configure the behaviour of the File Watcher: the events that will invoke it, from which files it can be invoked, when you want the console shown, etc.

  1. Specify whether you want the File Watcher to interact with the WebStorm syntax parser:
    • To have the File Watcher ignore update, save, and change focus events in files that are syntactically invalid and start only in error-free files, select the Trigger watcher regardless of syntax errors check box.
    • To have the File Watcher start regardless of the syntactical correctness of a file, clear the Trigger watcher regardless of syntax errors check box. The File Watcher will start upon update, save, or frame deactivation, depending on the status of the Immediate file synchronization check box.
  2. Specify the events which will invoke the File Watcher:
    • To have the File Watcher invoked as soon as any changes are made to the source code, select the Immediate file synchronization check box.
    • Clear the check box to have the File Watcher started upon save (File | Save All)or when you move focus from WebStorm (upon frame deactivation).
  3. Specify how you want the File Watcher to deal with dependencies. When the File Watcher is invoked on a file, WebStorm detects all the files in which this file is included. For each of these files, in its turn, WebStorm again detects the files into which it is included. This operation is repeated recursively until WebStorm reaches the files that are not included anywhere within the specified scope. These files are referred to as root files (do not confuse with content roots).
    • To run the File Watcher only against the root files, select the Track only root files check box.

      Note that in the TypeScript file watcher, the check box has been renamed to Compile main files only.

    • Clear the check box to run the File Watcher against the file from which it is invoked and against all the files in which this file is recursively included within the specified scope.

    This option is available only for Babel, Closure Compiler, Compass, Jade, Less, Sass/SCSS, Stylus, Typescript, UglifyJS, and YUI Compressor JS.

  4. In the Show console drop-down list, specify when you want the console shown. The available options are:
    • Always: when this option is chosen, the File Watcher opens the console when it starts.
    • Error: when this option is chosen, the File Watcher opens the console only if any errors occur in transpilation.
    • Never: choose this option to suppress opening the console under any circumstances.
  5. Configure the output filters to distinguish the output of the File Watcher from other output. These filters make the basis for:
    1. Displaying paths to the File Watcher output files as links in error and other messages and logs. When you click such link, the corresponding file is opened in the editor.
    2. Error highlighting in the output files.
    Click the Output Filters button to open the Output Filters dialog and manage the list of filters.

Configuring interaction with the transpiler

In the Watcher Settings area, configure interaction with the transpiler: specify the path to the executable file, the arguments to pass to it, the acceptable input and expected output file types, etc.

  1. In the Program text box, specify the location of the transpiler's executable file (.exe, .cmd, .bat or other depending on the specific tool. .jar archives are also acceptable but defining PATH variables for them is not supported. Do one of the following:
    • Type the path explicitly.
    • Click the Browse button browseButton to open the Select Path dialog box and navigate to the desired location.
    • Click the Insert Macro button to open the Macros dialog box where you can select the relevant macro from the list.
  2. From the File type drop-down, choose the expected type of input files. The File Watcher will consider only files of this type as subject for analyzing and processing. File types are recognised based on associations between file types and file extensions.

    By default, the field shows the file type in accordance with the chosen predefined File Watcher template.

  3. In the Scope drop-down list, define the range of files the File Watcher can be applied to. Changes in these files will invoke the File Watcher either immediately or upon save or frame deactivation, depending on the status of the Immediate file synchronization check box.

    You can choose one of the predefined scopes from the drop-down list:

    • Project Files: all the files within the project content roots (see Content Root and Configuring Content Roots).
    • Project Production Files: all the files within the project content roots excluding test sources.
    • Project Test Files: all the files within the project test source roots.
    • Open Files: all the files that are currently opened in the editor.

    VCS Scopes: these scopes are only available if your project is under version control.

    • Changed Files: all changed files, that is, all files associated with all existing changelists.
    • Default: all the files associated with the changelist Default.
    Alternatively, click the Browse button and configure a custom scope in the Scopes dialog box that opens.

    For more details on scopes, see the pages Scopes and Scopes dialog.

    The Scope setting overrides the Track only root files check box setting: if a dependency is outside the specified scope, the File Watcher is not applied to it.

  4. In the Arguments text box, define the arguments to pass to the transpiler Among other cases, use this text box to change the default output location, that is, specify a custom location where you want the transpiler to store the files generated during transpilation. Do one of the following:
    • Type the list of arguments in the text box.
    • Click the Insert Macro button to open the Macros dialog box where you can select the desired macro from the list.

    When specifying the arguments, follow these rules:

    • Use spaces to separate individual arguments.
    • If an argument includes spaces, enclose the spaces or the argument that contains the spaces in double quotes, for example, some" "arg or "some arg".
    • If an argument includes double quotes (e.g. as part of the argument), escape the double quotes by means of the backslashes, for example, -Dmy.prop=\"quoted_value"\.
  5. In the Working Directory text box, specify the directory to which the transpiler will be applied. Because the tool is always invoked in the context of a file, the default working directory is the directory of the current file. This setting is specified in all predefined templates through a macros $FileDir$. To update this default settings, do one of the following:
    • Type the path explicitly in the text box.
    • Click the Browse button browseButton to open the Select Path dialog box and navigate to the desired location.
    • Click the Insert Macro button to open the Macros dialog box, where you can select the desired macro from the list.
  6. In the Output paths to refresh text box, specify the files where the transpiler stores its output: the resulting source code, source maps, and dependencies. Based on this settings, WebStorm detects files generated through transpilation.

    Please note, that changing the value in this text box does not make the transpiler store its output in another location. To do that, specify the desired output location in the Arguments text box.

    Do one of the following:

    • Type the output paths manually. Use colons as separators.
    • Click the Insert Macro button to open the Macros dialog box, where you can select the desired pattern from the list.
  7. Use the Create output file from stdout check box to specify how you want the output file generated.
    • To have WebStorm read the native transpiler's output (standard output stream (stdout)) and generate the resulting files from it, select the Create output file from stdout check box.
    • To have the transpiler write its output directly to the files specified in the Output paths to refresh field, clear the check box.
  8. Optionally, define environment variables. For example, specify the PATH variable for the tool that is required for starting the transpiler but is not referenced in the path to it. In most cases it is Node.js or ruby.exe. Such situation may happen if you installed the transpiler manually but not through the Node Package Manager or gem manager and its installation folder is not under Node.js or ruby.

Enabling and disabling File Watchers

To toggle the enable/disable status of a File Watcher, select/clear the check box next to it on the File Watchers page of the Settings dialog box. If an error occurs while a File Watcher is running, the File Watcher is automatically disabled. To restore the status, enable the File Watcher manually.

When a File Watcher is enabled, it starts automatically as soon as a file to which transpilation is applicable is changed or saved, see Configuring the behaviour of the File Watcher.

Examples of customizing the behaviour of a transpiler

Any transpiler is an external, third-party tool. Therefore the only way to influence a transpiler is pass arguments to it just as if you were working in the command line mode. These arguments are specific for each tool. Below are two examples of customizing the default output location for the CoffeeScript transpiler.

Suppose, you have a project with the following folder structure:

fileWatcherExampleImage1
By default, the generated files will be stored in the folder where the original file is. You can change this default location and have the generated files stored in the js folder. Moreover, you can have them stored in a flat list or arranged in the folder structure that repeats the original structure under the app node.

  • To have all the generated files stored in the output js folder without retaining the original folder structure under the app folder:
    1. In the Arguments text box, type:
      --output $ProjectFileDir$\js\ --compile --map $FileName$
    2. In the Output paths to refresh text box, type:
      $ProjectFileDir$\js\$FileNameWithoutExtension$.js:$ProjectFileDir$\js\$FileNameWithoutExtension$.map

    As a result, the project tree looks as follows:

    fileWatcherExampleImage2

  • To have the original folder structure under the app node retained in the output js folder:
    1. In the Arguments text box, type:
      --output $ProjectFileDir$\js\$FileDirRelativeToProjectRoot$\ --compile --map $FileName$
    2. In the Output paths to refresh text box, type:
      $ProjectFileDir$\js\$FileDirRelativeToProjectRoot$\$FileNameWithoutExtension$.js:$ProjectFileDir$\js\$FileDirRelativeToProjectRoot$\$FileNameWithoutExtension$.map

    As a result, the project tree looks as follows:

    fileWatcherExampleImage3

See Also

Last modified: 15 November 2016