Watch Mode

The CoffeeScript plugin has a feature called watch mode that mimics coffee --watch (see the CoffeeScript documentation). Tired of switching to a terminal to start/stop compilation or to check if your scripts compiled successfully? Watch mode to the rescue.

Important Notes

This feature works with Sublime Text 2's project feature, if you are not using it then you can't use watch mode.

Also, it is assumed that the 1st (well, 0th) directory in the sidebar is your project's base directory (for the sake of simplicity). If you have added multiple directories to your project via Project > Add Folder(s) to Project, only the first will be regarded as your project.

Hopefully this won't be a problem as it is presumed that most people keep all of their project files in one directory. If people are against this decision however then this will likely be changed.

---

Configuration

The following configuration options are available:

<tr>
    <td><strong>mode</strong> <code>(string)</code></td>
    <td>Where output from watch mode will be sent to. One of: panel; status or console.</td>
</tr>

<tr>
    <td><strong>wrap</strong> <code>(boolean)</code></td>
    <td>Enable top-level function wrappers (<code>coffee --bare</code>).</td>
</tr>

<tr>
    <td><strong>on_success</strong> <code>(boolean)</code></td>
    <td>Output a message when a script is compiled successfully.</td>
</tr>

<tr>
    <td><strong>on_failure</strong> <code>(boolean)</code></td>
    <td>Output a message when a script fails to compile.</td>
</tr>

<tr>
    <td><strong>directories</strong> <code>(object)<code></td>
    <td>A mapping of input directories (containing <code>.coffee</code> files) to output directories (<code>.js</code>).</td>
</tr>

Key	Use

The directory setting warrants further explanation, see the directory mapping section below.

Global Settings

Assuming you have ran the Coffee: Setup command then no further configuration is necessary.

You may however wish to edit the default settings (which are used when no project-specific settings are present). See the default settings section below.

Project-specific Settings

If you require project-specific settings then you can add them to your .sublime-project file e.g.:

{
    "folders": [
        // ...
    ],
    "settings": {
        "coffeescript": {
            "watch_mode": {
                "wrap": true
            }
        }
    }
}

See the Sublime Text 2 documentation for more information.

Default Settings

By default, compiled .js files will be placed alongside their un-compiled counterparts which means that $project_path/foo/bar.coffee will compile to $project_path/foo/bar.js. If this is not the behaviour you desire then you can change it - see the directory mapping section below.

To view the default settings - Preferences > Package Settings > CoffeeScript > Settings - Default.

Be sure to only edit Settings - User and NOT Settings - Default, or your changes will be lost when upgrading.

---

Usage

Usage is fairly simple, there are two new commands that can be accessed via either the Command Palette (ctrl+shift+P or cmd+shift+P) or their respective shortcuts.

1. alt+shift+w Toggle Watch Mode
2. alt+shift+z Toggle Output Panel

---

Directory Mapping

Here are some examples which demonstrate how to use the directories setting:

Example 1

Compile anything in the project to the same directory (the default behaviour):

"directories": {
    ".": "." // You can also use "", "/" and "./"
}

Example 2

Compile anything in and under the cs directory to the js directory:

"directories": {
    "cs": "js"
}

• cs/foobar.coffee » js/foobar.js
• cs/fub/ar.coffee » js/fub/ar.js

Example 3

Similar to example 2 but with multiple directories:

"directories": {
    "code/src": "code/lib",
    "spec/src": "spec/lib"
}

• code/src/foo.coffee » code/lib/foo.js
• spec/src/bar.coffee » spec/lib/bar.js

Example 4

Compile multiple directories into one (beware of conflicts, of course):

"directories": {
    "one": "three",
    "two": "three"
}

• one/foo.coffee » three/foo.js
• two/bar.coffee » three/bar.js

Example 5

Similar to example 4 except maintains directory structure:

"directories": {
    "one": "three/$source",
    "two": "three/$source"
}

• one/foo.coffee » three/one/foo.js
• two/bar.coffee » three/two/bar.js

---