thomasfrank.se

CoffeeMaker

June 4, 2011

I've been playing around with Jeremy Ashkenas' excellent little language CoffeeScript a bit lately. And I like it a lot!
For those of you that haven't tried it -- check it out: It's warm and friendly and feels like JavaScript deuglified. (And it compiles to ordinary, quite readable JavaScript.)
I wanted to set up a CoffeeScript compiler environment that was between just playing with <text/coffeescript> script tags ("not for serious use" according to the documentation) and having to install and configure (the otherwise awesome js-server) node.js.
Thus CoffeeMaker was born. It runs on most modern LAMP servers (I use it on my localhost development server, XAMPP) and compiles CoffeeScript on the client but caches and stores it on the server. CoffeeMaker lives on GitHub, so go there and have a look or downlad a zip file directly.

A small note: If you use XAMPP on a Mac like I do and have problems with setting write permissions, then read this.

How to install

  1. Make sure you have a LAMP server with Apache > 2.0, PHP > 5.2 and that Apache mod-rewrite is not disabled.
  2. Copy the coffeemaker folder to your public document root folder.
  3. If you do NOT have an .htaccess file in your public document root folder already then copy the .htaccess file here. ELSE add the following 4 lines to the provided .htaccess file in your public document root folder:
       RewriteEngine On
   RewriteRule (.*\.cof)/?$ /coffeemaker/coffeemaker.php?file=/$1
   RewriteRule coffeemaker/?$ /_-_-_-_-_-_-_-_
   RewriteRule coffeemaker/.*/.* /_-_-_-_-_-_-

  4. Set write permissions for the coffeemaker/cache folder so that PHP can write to it - do a chmod 777 if you must (but preferably don't do this for the whole coffeemaker-folder).

Basic Usage

Write your CoffeeScript and include it on your web page with the following code

Important: The script must have the extension ".cof".

Includes

Naturally you can include several CoffeeScripts on your web page using multiple script tags. But you can also perform includes from your Coffeescript files. You do this through a comment:
# include filename.cof

The file will be included on the same 'indentation level' as your comment. If you include a file with the extension '.js' CoffeeMaker assumes this is JavaScript and includes it without compilation. Relative paths are resolves from the script that performs the include.

How does it work?

The rewrite rules in the .htaccess will rewrite the request for the .cof-script to coffeemaker.php. CoffeMaker then checks if a compiled verison of the script has been cached since it last changed - if so it returns a cached version. Otherwise CoffeeMaker will compile the script and cache it.
CoffeeMaker uses the client (your browser) for compilation but caches the result on the server, in its cache folder. (See notes on security in the configuration section below.)

Configuration

Configuration can be made in the coffeemaker/config.php file. Here you will find a number of flags that can be set to true or false:

$allowCacheCreation

Default: true
If you turn this off CoffeeMaker can not compile anymore -- it can only serve up files already compiled.
For maximum security please configure this flag so that it is set to false on your production server -- since CoffeeMaker compiles on the client side there could otherwise be a danger of code injection.Then copy the coffeemaker/cache folder (or the subfolder in it related to your project) to the production server when you want to go live.
(However CoffeeMaker also counters this with a ticket system - thus trying to block unlegit write attempts to its cache.)

$allowIncludes

Default: true
Can be turned off if you do not want to enable includes (see above).

$splitVarDeclarations

Default: true
Splits long lines of var declarations in the compiled JavaScript code, for enhanced readability.

$splitConcatenations

Default: true
Splits long lines of string concatenations in the compiled JavaScript code, for enhanced readability.

$keepCoffeeComments

Default: true
Keeps one-line comments from CoffeeSCript in the compiled JavaScript code, for debugging and readability purposes.

$keepBlankLines

Default: true
Keeps blank lines from CoffeeSCript in the compiled JavaScript code, for debugging and readability purposes.

$uglifyJS

Default: false
Minifies the compiled JavaScript code using UglifyJS.
[comments]