IntelliJ IDEA 2017.3 Help

Using File Watchers

This feature is only supported in the Ultimate edition.

IntelliJ IDEA integrates with various third-party compilers that run in the background and translate Less, Sass, SCSS, and Stylus into CSS, or CoffeeScript into JavaScript, as well as compress JavaScript and CSS.

To use a compiler in IntelliJ IDEA, you need to configure it as a File Watcher. For each supported compiler, IntelliJ IDEA provides a predefined File Watcher template.

The output of a File Watcher is stored in a separate file. Each predefined template suggests the type of the output file depending on the compiler 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, after that this file is only updated. However, 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 runs in every file where a predefined File Watcher is applicable. If the project has no relevant File Watcher configured, IntelliJ IDEA suggests to add one.
  • The File watcher problems inspection is invoked by a running File Watcher and highlights errors specific for it.

Creating a File Watcher

  1. In the Settings/Preferences dialog (Ctrl+Alt+S), choose File Watchers under Tools. The File Watchers page opens showing a list of File Watchers that are already configured in the project.
  2. Click new.png and choose the predefined template from which you want to create a File Watcher. The choice depends on the compiler you are going to use. To use a compiler that is not on the list, choose Custom. The New Watcher dialog box opens.
  3. In the Name text box, type the name of the File Watcher. By default, IntelliJ IDEA suggests the name of the selected predefined template.

Configuring the expected type and location of input files

Use the controls in the Files to watch area to define the range of files where you want to apply the File Watcher.

  1. From the File type drop-down list, 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.
  2. Choose the Scope in which the File Watcher is applicable. Changes in these files will invoke the File Watcher either immediately or upon save or frame deactivation, depending on the status of the Auto-save edited files to trigger the watcher checkbox.

    Choose one of the predefined scopes from the drop-down list or click browseButton and configure a custom scope in the Scopes dialog that opens.

Optionally
Specify how you want the File Watcher to deal with dependencies. When the File Watcher is invoked in a file, IntelliJ IDEA detects all the files where it is included. For each of the detected files, in its turn, IntelliJ IDEA again detects the containing files. This operation is repeated recursively until IntelliJ IDEA 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 root files, select the Track only root files checkbox.
  • Clear the checkbox 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.
Note that the Scope setting overrides the Track only root files checkbox setting: if a dependency is outside the specified scope, the File Watcher is not applied to it.

Configuring interaction with the compiler

In the Tool to run on changes area, specify the compiler to use, the arguments to pass to it, the expected output file types, etc.

  1. In the Program text box, specify the path to the executable file of the compiler (.exe, .cmd, .bat, or other depending on the specific tool).
  2. In the Arguments text box, define the arguments to pass to the compiler.
    • To change the default output location, specify a custom location for the compiler to store the generated files. Note that if you re-define the default output location here you need to clear the Create output file from stdout checkbox in the Advanced Options area because otherwise the content of your generated file will be overwritten by the compiler's output stream.
    • Suppose, an action affects several files watched by the same File Watcher. As a result, the File Watcher wakes up on each changed file. However, running several tasks is redundant because the File Watcher processes all the watched files during the first run. To tell IntelliJ IDEA that running File Watcher just once in enough, even if several files have been changed, make sure there is no file-specific macro, such as $FileNameWithoutExtension$, in the Arguments field.
  3. In the Output paths to refresh text box, specify the files where the compiler stores its output: the resulting source code, source maps, and dependencies. Based on these settings, IntelliJ IDEA recognizes the files generated through compilation.
    Please note, that changing the value in this text box does not make the compiler store its output in another location. To do that, specify the desired output location in the Arguments text box: type the output paths using colons as separators or click the Insert Macro button to open the Macros dialog box and select the desired pattern from the list.

Optionally

  1. Expand the Working Directory and Environment Variables hidden area.
  2. Define the environment variables. For example, specify the PATH variable for the tool that is required for starting the compiler 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 compiler in a custom installation folder manually but not through the Node Package Manager (npm) or gem manager.
  3. In the Working Directory text box, specify the directory to which the compiler 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. The default working directory is specified in all predefined templates through a $FileDir$ macros. To specify a custom working directory, type the path to it in the text box, or click browseButton and choose the directory in the Select Path dialog box, or click Insert Macro and select the desired macro from the list in the Macros dialog box.

Configuring advanced options

In the Advanced Options area, customize the default behaviour of the File Watcher.

  1. Specify the events that will invoke the File Watcher:
    • To invoke the File Watcher as soon as any changes are made to the source code, select the Auto-save edited files to trigger the watcher checkbox.
      When the checkbox is cleared, the File Watcher starts upon save (File | Save All) or when you move the focus from IntelliJ IDEA (on frame deactivation).
    • By default, the File Watcher wakes up on any saved change, including the updates received from you version control system when you, for example, check out a branch. To ignore such changes and invoke the File Watcher only you update your code in IntelliJ IDEA, clear the Trigger the watcher on external changes checkbox.
  2. Specify whether you want the File Watcher to interact with the IntelliJ IDEA syntax parser:
    • When the Trigger watcher regardless of syntax errors checkbox is selected, the File Watcher start regardless of the syntactical correctness of a file. The File Watcher will start upon update, save, or frame deactivation, depending on the status of the Auto-save edited files to trigger the watcher checkbox.
    • When the Trigger watcher regardless of syntax errors checkbox is cleared, the File Watcher ignores all triggers in files that are syntactically invalid and starts only in error-free files.
  3. Use the Create output file from stdout checkbox to specify how you want to generate the output file.
    • When the checkbox is selected, IntelliJ IDEA reads the native compiler output (standard output stream (stdout)) and generates the resulting files from it.
    • When the checkbox is cleared, the compiler writes its output directly to the files specified in the Output paths to refresh field.
  4. In the Show console drop-down list, choose when you want the File Watcher to open the console.
    • Always: with this option, the console opens when the File Watcher starts.
    • Error: with this option, the File Watcher opens the console only if any errors occur during compilation.
    • Never: choose this option to suppress opening the console at all.

Optionally
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. For example, to get useful error messages displayed, specify the following expression in the Regular expression to match output field of the Add/Edit Filter Dialog:
    $FILE_PATH$:$LINE$ $MESSAGE$
  2. Error highlighting in the output files.

Enabling and disabling File Watchers

To toggle the enable/disable status of a File Watcher, select/clear the checkbox 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 compilation is applicable is changed or saved, see Configuring advanced options.

Examples of customizing the behaviour of a compiler

Any compiler is an external, third-party tool. Therefore the only way to influence a compiler 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 compiler.

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

Last modified: 16 December 2017

See Also