Alex MacCaw - The Little Book on CoffeeScript

Copyright 2012 Alex MacCaw

OReilly books may be purchased for educational, business, or sales promotional use. Online editions are also available for most titles (.

Nutshell Handbook, the Nutshell Handbook logo, and the OReilly logo are registered trademarks of OReilly Media, Inc. The Little Book on CoffeeScript and related trade dress are trademarks of OReilly Media, Inc.

Many of the designations used by manufacturers and sellers to distinguish their products are claimed as trademarks. Where those designations appear in this book, and OReilly Media, Inc. was aware of a trademark claim, the designations have been printed in caps or initial caps.

While every precaution has been taken in the preparation of this book, the publisher and author assume no responsibility for errors or omissions, or for damages resulting from the use of the information contained herein.

CoffeeScript is a little language that compiles down to JavaScript. The syntax is inspired by Ruby and Python, and implements many features from those two languages. This book is designed to help you learn CoffeeScript, understand best practices, and start building awesome client-side applications. The book is little, only six chapters, but thats rather apt as CoffeeScript is a little language too.

This book is completely open source, and was written by Alex MacCaw (@maccman) with great contributions from David Griffiths, Satoshi Murakami, Chris Smith, Katsuya Noguchi, and Jeremy Ashkenas.

If you have any errata or suggestions, please dont hesitate to open a ticket on the books GitHub page. Readers may also be interested in JavaScript Web Applications (OReilly), a book I authored that explores rich JavaScript applications and moving state to the client side.

So lets dive right into it: why is CoffeeScript better than writing pure JavaScript? Well, for a start, theres less code to write; CoffeeScript is very succinct, and takes white space into account. In my experience, this reduces code by a third to a half of the original pure JavaScript. In addition, CoffeeScript has some neat features, such as array comprehensions, prototype aliases, and classes that further reduce the amount of typing you need to do.

More importantly though, JavaScript has a lot of skeletons in its closet which can often trip up inexperienced developers. CoffeeScript neatly sidesteps these by only exposing a curated selection of JavaScript features, fixing many of the languages oddities.

CoffeeScript is not a superset of JavaScript, so although you can use external JavaScript libraries from inside CoffeeScript, youll get syntax errors if you compile JavaScript as is, without converting it. The compiler converts CoffeeScript code into its counterpart JavaScript, theres no interpretation at runtime.

So lets get some common fallacies out of the way. You will need to know JavaScript in order to write CoffeeScript, as runtime errors require JavaScript knowledge. However, having said that, runtime errors are usually pretty obvious, and so far I havent found mapping JavaScript back to CoffeeScript to be an issue. The second problem Ive often heard associated with CoffeeScript is speed (i.e., the code produced by the CoffeeScript compiler would run slower than its equivalent written in pure JavaScript). In practice though, it turns out this isnt a problem either. CoffeeScript tends to run as fast or faster than handwritten JavaScript.

What are the disadvantages of using CoffeeScript? Well, it introduces another compile step between you and your JavaScript. CoffeeScript tries to mitigate the issue as best it can by producing clean and readable JavaScript, and with its server integrations which automate compilation. The other disadvantage, as with any new language, is the fact that the community is still small at this point, and youll have a hard time finding fellow collaborators who already know the language. CoffeeScript is quickly gaining momentum though, and its IRC list is well staffed; any questions you have are usually answered promptly.

CoffeeScript is not limited to the browser, and can be used to great effect in server-side JavaScript implementations, such as Node.js. Additionally, CoffeeScript is getting much wider use and integration, such as being a default in Rails 3.1. Now is definitely the time to jump on the CoffeeScript train. The time you invest in learning about the language now will be repaid by major time savings later.

One of the easiest ways to initially play around with the library is to use it right inside the browser. Navigate to http://coffeescript.org and click on the Try CoffeeScript tab. The site uses a browser version of the CoffeeScript compiler, converting any CoffeeScript typed inside the left panel to JavaScript in the right panel.

You can also convert JavaScript back to CoffeeScript using the js2coffee project, especially useful when migrating JavaScript projects to CoffeeScript.

In fact, you can use the browser-based CoffeeScript compiler yourself, by including this script in a page, marking up any CoffeeScript script tags with the correct type:

Obviously, in production, you dont want to be interpreting CoffeeScript at runtime, as itll slow things up for your clients. Instead, CoffeeScript offers a Node.js compiler to pre-process CoffeeScript files.

To install it, first make sure you have a working copy of the latest stable version of Node.js and npm (the Node Package Manager). You can then install CoffeeScript with npm:

The -g flag is important, as it tells npm to install the coffee-script package globally, rather than locally. Without it, you wont get the coffee executable.

If you execute the coffee executable without any command line options, itll give you the CoffeeScript console, which you can use to quickly execute CoffeeScript statements. To pre-process files, pass the --compile option:

If --output is not specified, CoffeeScript will write to a JavaScript file with the same name, in this case my-script.js. This will overwrite any existing files, so be careful youre not overwriting any JavaScript files unintentionally. For a full list of the command line options available, pass --help.

You can also pass the --compile option a directory, and CoffeeScript will recursively compile every file with a .coffee extension:

If all this compilation seems like a bit of an inconvenience and bother, thats because it is. Well be getting onto ways to solve this by automatically compiling CoffeeScript files, but first lets take a look at the languages syntax.