Please browse through the issues if you have trouble, because the docs and examples below may not be up to date. Contributions are more than welcome.

Install

The simplest way to install Guard is to use Bundler.
Please make sure to have Guard installed.

Add Guard::Coffeescript to your Gemfile:

group :developmentdo
gem 'guard-coffeescript'end

Add the default Guard::Coffeescript template to your Guardfile by running:

$ guard init coffeescript

JSON

The JSON library is also required but is not explicitly stated as a gem dependency. If you're on Ruby 1.8 you'll need
to install the json or json_pure gem. On Ruby 1.9, JSON is included in the standard library.

CoffeeScript

Guard::CoffeeScript uses Ruby CoffeeScript to compile the CoffeeScripts,
that in turn uses ExecJS to pick the best runtime to evaluate the JavaScript.

With CRuby you want to use a V8 JavaScript Engine or Mozilla SpiderMonkey.

With JRuby you want to use the Mozilla Rhino.

On Mac OS X you want to use Apple JavaScriptCore.

On Linux or as a node.js developer you want to use Node.js (V8).

On Windows you want to use Microsoft Windows Script Host.

JavaScript runtimes

The following sections gives you a short overview of the available JavaScript runtimes and how to install it.

Node.js (V8)

You can install node.js and use its V8 engine. On OS X you may want to install it with
Homebrew, on Linux with your package manager and on Windows you have to download and
install the executable.

V8 JavaScript Engine

To use the V8 JavaScript Engine, simple add therubyracer to your Gemfile.
The Ruby Racer acts as a bridge between Ruby and the V8 engine, that will be automatically installed by the Ruby Racer.

group :developmentdo
gem 'therubyracer'end

Another alternative is Mustang, a Ruby proxy library for the awesome Google V8
JavaScript engine. Just add mustang to your Gemfile:

Ruby project

If your output directory is the same as the input directory, you can simply skip it:

guard 'coffeescript', :input => 'javascripts'

Rails app with the asset pipeline

With the introduction of the asset pipeline in Rails 3.1 there is
no need to compile your CoffeeScripts with this Guard.

However, if you would still like to have feedback on the validation of your CoffeeScripts
(preferably with a Growl notification) directly after you save a change, then you can still
use this Guard and simply skip generation of the output file:

This give you a faster compilation feedback compared to making a subsequent request to your Rails application. If you
just want to be notified when an error occurs you can hide the success compilation message:

Output short notation

In addition to the standard configuration, this Guard has a short notation for configure projects with a single input
and output directory. This notation creates a watcher from the :input parameter that matches all CoffeeScript files
under the given directory and you don't have to specify a watch regular expression.

guard 'coffeescript', :input => 'javascripts'

Selective bare option

The :bare option can take a boolean value that indicates if all scripts should be compiled without the top-level
function wrapper.

:bare => true

But you can also pass an Array of filenames that should be compiled without the top-level function wrapper. The path of
the file to compile is ignored, so the list of filenames should not contain any path information:

:bare => %w{ a.coffee b.coffee }

In the above example, all a.coffee and b.coffee files will be compiled with option :bare => true and all other
files with option :bare => false.

Nested directories

The Guard detects by default nested directories and creates these within the output directory. The detection is based on
the match of the watch regular expression:

A file

/app/coffeescripts/ui/buttons/toggle_button.coffee

that has been detected by the watch

watch(%r{^app/coffeescripts/(.+\.coffee)$})

with an output directory of

:output => 'public/javascripts/compiled'

will be compiled to

public/javascripts/compiled/ui/buttons/toggle_button.js

Note the parenthesis around the .+\.coffee. This enables Guard::CoffeeScript to place the full path that was matched
inside the parenthesis into the proper output directory.

This behavior can be switched off by passing the option :shallow => true to the Guard, so that all JavaScripts will be
compiled directly to the output directory.

Issues

You can report issues and feature requests to GitHub Issues. Try to figure out
where the issue belongs to: Is it an issue with Guard itself or with a Guard::Cucumber? Please don't
ask question in the issue tracker, instead join us in our Google group or on
#guard (irc.freenode.net).

When you file an issue, please try to follow to these simple rules if applicable:

Make sure you run Guard with bundle exec first.

Add debug information to the issue by running Guard with the --debug option.

Contributors

Acknowledgment

The Guard Team for giving us such a nice piece of software
that is so easy to extend, one has to make a plugin for it!

All the authors of the numerous Guards available for making the Guard ecosystem
so much growing and comprehensive.

License

(The MIT License)

Copyright (c) 2010-2013 Michael Kessler

Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
'Software'), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.