A recursive CoffeeScript watcher also aware of newly added files.


A recursive CoffeeScript watcher also aware of newly added files. The built-in CoffeeScript watcher doesn't work this way. Now you can start CoffeeStand at your root directory once and for all and forget about restarting the watch process every time you add a new file.

The simplest way to recursively watch your entire project from the command-line is run coffeestand in the project root directory.

  • Recursively watch directories and auto-recompile when coffee files are changed.
  • Write compiled code to destination js files.
  • Aware of newly created files and directories too! So you don't have to rewatch every time you add a file.
  • Also Aware of newly created directories and files inside.
  • Auto-Coffeelint (not JSLint) the source code after every compilation.
  • Ignore Files through glob matching option and .csingore file
  • Outupt JS dir & file mapping through .csmapper file

Use npm, -g option is recommended so you can globally use coffeestand CLI.

sudo npm install -g coffeestand
coffeestand <dir> [options]

dir : the root directory to watch, CoffeeStand walks down its sub directories and watches the entire project tree. If omitted, dir will be set ./ which is the current working directory.

--nolog : supress the stdout log messages, useful when using the coffeestand module in your node scripts
--nojs : don't write compiled code to JS files, useful if you just want to see how compilation goes
--nolint : don't coffeelint after compilation
-l --lintconfig : path to the coffeelint configuration file, default to .coffeelint
-m --mapper : path to the CS to JS mapping file, default to .csmapper
-i --ignore : path to the ignore setting file, default to .csignore
-p --ipatterns : comma separeted glob patterns to ignore files, you can also use .csignore file to do the same

CoffeeStand does auto-CooffeeLint your coffeescript files after every compilation to keep you code beautiful. You can suppess this feature by passing --nolint option.

To change the default configurations, put .coffeelint file in your project root directory. You can also put config file at a defferent location, just pass -l or --lintconfig option followed by your arbitrary location to the config file.

See CoffeeLint website for the lint options and an example configuration file.

You can make CoffeeStand to ignore some files and directories eather by

  1. passing --ipatterns (-p for short) option followed by comma separated glob patterns
  2. putting .csignore file in your project root directory

If you use a location other than /path/to/project/root/.csignore, just pass -i (--ignore for short) option with your arbitrary location.

CoffeeStand uses glob patterns to match file paths using minimatch module.


The above patterns ignore node_modules directory and dot files, convenient for git users and node module developers.

If the parent directory is ignored CoffeeStand doesn't go into its sub directories so it can efficiently reduce the number of watch processes.

These 2 patterns are indeed set as default values to ease node module development.

Add your patterns by setting a .csignore (can be a different name) file and write one glob pattern per line. Ignore Patterns can be also specified as an inline command line option. Separate the patterns with a comma and give it to coffeestand command with -p or --ipatterns option.

coffeestand -p **/node_modules,**/.*

By default, CoffeeStand saves compiled JS code to a JS file in the same directory the original coffeescript file is in, that is, /path/to/project/foo.coffe will be compiled to /path/to/project/foo.js. To change this behavior, you can put .csmapper JSON file into the project root directory.

An example .csmapper file would look something like this

{"**/src/*" : [/\/src\//, "/lib/"]}

This is what I use to auto-compile the coffee files in the src directories into the lib directory. I use CoffeeStand to watch files while developing CoffeeStand. So this applies to the source tree of this node module repo and it works.

  1. The content of .csmapper must be JSON formatted that can be parsed by JSON.parse()
  2. Each mapping pattern is a key-value pair
  3. The key is a glob and put in a pattern matching test against file paths
  4. If the glob key matches a file path, the path is replaced using the Javascript replace() method with the value array as arguments to replace()

So in the above example, **/src/* matches /project/root/src/, and [/\/src\//, "/lib/"] turns to replace(/\/src\//, "/lib/") and replaces the path to /project/root/lib/foo.js.

The .coffee extension will be auto-replaced to .js.

You can put as many key-value pairs as you want in a .csmapper file

Putting multiple patterns in .csmapper

  "**/src/*" : [/\/src\//, "/lib/"],
  "**/cofffe/*" : ["before", "after"],    

.csmapper can be named differently and put at a different location, in such cases, pass -m or --mapper followed by the file location as a command line option.

coffeestand -m /path/to/your/mapping/file.json

Run tests with mocha


CoffeeStand is released under the MIT License. - see LICENSE file