CoffeeScript

CoffeeScript is a little language that compiles into JavaScript. Underneath that awkward Java-esque patina, JavaScript has always had a gorgeous heart. CoffeeScript is an attempt to expose the good parts of JavaScript in a simple way.

The golden rule of CoffeeScript is: “It’s just JavaScript.” The code compiles one-to-one into the equivalent JS, and there is no interpretation at runtime. You can use any existing JavaScript library seamlessly from CoffeeScript (and vice-versa). The compiled output is readable, pretty-printed, and tends to run as fast or faster than the equivalent handwritten JavaScript.

Latest Version: 2.7.0

# Install locally for a project:
npm install --save-dev coffeescript

# Install globally to execute .coffee files anywhere:
npm install --global coffeescript

Overview

CoffeeScript on the topleft, compiled JavaScript output on the bottomright. The CoffeeScript is editable!

      # Assignment:
number   = 42
opposite = true

# Conditions:
number = -42 if opposite

# Functions:
square = (x) -> x * x

# Arrays:
list = [1, 2, 3, 4, 5]

# Objects:
math =
  root:   Math.sqrt
  square: square
  cube:   (x) -> x * square x

# Splats:
race = (winner, runners...) ->
  print winner, runners

# Existence:
alert "I knew it!" if elvis?

# Array comprehensions:
cubes = (math.cube num for num in list)

      # Assignment:
number   = 42
opposite = true

# Conditions:
number = -42 if opposite

# Functions:
square = (x) -> x * x

# Arrays:
list = [1, 2, 3, 4, 5]

# Objects:
math =
  root:   Math.sqrt
  square: square
  cube:   (x) -> x * square x

# Splats:
race = (winner, runners...) ->
  print winner, runners

# Existence:
alert "I knew it!" if elvis?

# Array comprehensions:
cubes = (math.cube num for num in list)

    

      // Assignment:
var cubes, list, math, num, number, opposite, race, square;

number = 42;

opposite = true;

if (opposite) {
  // Conditions:
  number = -42;
}

// Functions:
square = function(x) {
  return x * x;
};

// Arrays:
list = [1, 2, 3, 4, 5];

// Objects:
math = {
  root: Math.sqrt,
  square: square,
  cube: function(x) {
    return x * square(x);
  }
};

// Splats:
race = function(winner, ...runners) {
  return print(winner, runners);
};

if (typeof elvis !== "undefined" && elvis !== null) {
  // Existence:
  alert("I knew it!");
}

// Array comprehensions:
cubes = (function() {
  var i, len, results;
  results = [];
  for (i = 0, len = list.length; i < len; i++) {
    num = list[i];
    results.push(math.cube(num));
  }
  return results;
})();

      // Assignment:
var cubes, list, math, num, number, opposite, race, square;

number = 42;

opposite = true;

if (opposite) {
  // Conditions:
  number = -42;
}

// Functions:
square = function(x) {
  return x * x;
};

// Arrays:
list = [1, 2, 3, 4, 5];

// Objects:
math = {
  root: Math.sqrt,
  square: square,
  cube: function(x) {
    return x * square(x);
  }
};

// Splats:
race = function(winner, ...runners) {
  return print(winner, runners);
};

if (typeof elvis !== "undefined" && elvis !== null) {
  // Existence:
  alert("I knew it!");
}

// Array comprehensions:
cubes = (function() {
  var i, len, results;
  results = [];
  for (i = 0, len = list.length; i < len; i++) {
    num = list[i];
    results.push(math.cube(num));
  }
  return results;
})();

    

      
    

CoffeeScript 2

What’s New In CoffeeScript 2?

The biggest change in CoffeeScript 2 is that now the CoffeeScript compiler produces modern JavaScript syntax (ES6, or ES2015 and later). A CoffeeScript => becomes a JS =>, a CoffeeScript class becomes a JS class and so on. Major new features in CoffeeScript 2 include async functions and JSX. You can read more in the announcement.

There are very few breaking changes from CoffeeScript 1.x to 2; we hope the upgrade process is smooth for most projects.

Compatibility

Most modern JavaScript features that CoffeeScript supports can run natively in Node 7.6+, meaning that Node can run CoffeeScript’s output without any further processing required. Here are some notable exceptions:

JSX always requires transpilation.
Splats, a.k.a. object rest/spread syntax, for objects are supported by Node 8.6+.
The regular expression s (dotall) flag is supported by Node 9+.
Async generator functions are supported by Node 10+.
Modules are supported by Node 12+ with "type": "module" in your project’s package.json.

This list may be incomplete, and excludes versions of Node that support newer features behind flags; please refer to node.green for full details. You can run the tests in your browser to see what your browser supports. It is your responsibility to ensure that your runtime supports the modern features you use; or that you transpile your code. When in doubt, transpile.

For compatibility with other JavaScript frameworks and tools, see Integrations.

Installation

The command-line version of coffee is available as a Node.js utility, requiring Node 6 or later. The core compiler however, does not depend on Node, and can be run in any JavaScript environment, or in the browser (see Try CoffeeScript).

To install, first make sure you have a working copy of the latest stable version of Node.js. You can then install CoffeeScript globally with npm:

npm install --global coffeescript

This will make the coffee and cake commands available globally.

If you are using CoffeeScript in a project, you should install it locally for that project so that the version of CoffeeScript is tracked as one of your project’s dependencies. Within that project’s folder:

npm install --save-dev coffeescript

The coffee and cake commands will first look in the current folder to see if CoffeeScript is installed locally, and use that version if so. This allows different versions of CoffeeScript to be installed globally and locally.

If you plan to use the --transpile option (see Transpilation) you will need to also install @babel/core either globally or locally, depending on whether you are running a globally or locally installed version of CoffeeScript.

Usage

Command Line

Once installed, you should have access to the coffee command, which can execute scripts, compile .coffee files into .js, and provide an interactive REPL. The coffee command takes the following options:

Option	Description
`-c, --compile`	Compile a `.coffee` script into a `.js` JavaScript file of the same name.
`-t, --transpile`	Pipe the CoffeeScript compiler’s output through Babel before saving or running the generated JavaScript. Requires `@babel/core` to be installed, and options to pass to Babel in a `.babelrc` file or a `package.json` with a `babel` key in the path of the file or folder to be compiled. See Transpilation.
`-m, --map`	Generate source maps alongside the compiled JavaScript files. Adds `sourceMappingURL` directives to the JavaScript as well.
`-M, --inline-map`	Just like `--map`, but include the source map directly in the compiled JavaScript files, rather than in a separate file.
`-i, --interactive`	Launch an interactive CoffeeScript session to try short snippets. Identical to calling `coffee` with no arguments.
`-o, --output [DIR]`	Write out all compiled JavaScript files into the specified directory. Use in conjunction with `--compile` or `--watch`.
`-w, --watch`	Watch files for changes, rerunning the specified command when any file is updated.
`-p, --print`	Instead of writing out the JavaScript as a file, print it directly to stdout.
`-s, --stdio`	Pipe in CoffeeScript to STDIN and get back JavaScript over STDOUT. Good for use with processes written in other languages. An example: `cat src/cake.coffee \| coffee -sc`
`-l, --literate`	Parses the code as Literate CoffeeScript. You only need to specify this when passing in code directly over stdio, or using some sort of extension-less file name.
`-e, --eval`	Compile and print a little snippet of CoffeeScript directly from the command line. For example: `coffee -e "console.log num for num in [10..1]"`
`-r, --require [MODULE]`	`require()` the given module before starting the REPL or evaluating the code given with the `--eval` flag.
`-b, --bare`	Compile the JavaScript without the top-level function safety wrapper.
`--no-header`	Suppress the “Generated by CoffeeScript” header.
`--nodejs`	The `node` executable has some useful options you can set, such as `--debug`, `--debug-brk`, `--max-stack-size`, and `--expose-gc`. Use this flag to forward options directly to Node.js. To pass multiple flags, use `--nodejs` multiple times.
`--ast`	Generate an abstract syntax tree of nodes of the CoffeeScript. Used for integrating with JavaScript build tools.
`--tokens`	Instead of parsing the CoffeeScript, just lex it, and print out the token stream. Used for debugging the compiler.
`-n, --nodes`	Instead of compiling the CoffeeScript, just lex and parse it, and print out the parse tree. Used for debugging the compiler.

Examples:

Compile a directory tree of .coffee files in src into a parallel tree of .js files in lib:
coffee --compile --output lib/ src/
Watch a file for changes, and recompile it every time the file is saved:
coffee --watch --compile experimental.coffee
Concatenate a list of files into a single script:
coffee --join project.js --compile src/*.coffee
Print out the compiled JS from a one-liner:
coffee -bpe "alert i for i in [0..10]"
All together now, watch and recompile an entire project as you work on it:
coffee -o lib/ -cw src/
Start the CoffeeScript REPL (Ctrl-D to exit, Ctrl-Vfor multi-line):
coffee

To use --transpile, see Transpilation.

Node.js

If you’d like to use Node.js’ CommonJS to require CoffeeScript files, e.g. require './app.coffee', you must first “register” CoffeeScript as an extension:

require 'coffeescript/register'

App = require './app' # The .coffee extension is optional

If you want to use the compiler’s API, for example to make an app that compiles strings of CoffeeScript on the fly, you can require the full module:

CoffeeScript = require 'coffeescript'

eval CoffeeScript.compile 'console.log "Mmmmm, I could really go for some #{Math.pi}"'

The compile method has the signature compile(code, options) where code is a string of CoffeeScript code, and the optional options is an object with some or all of the following properties:

options.sourceMap, boolean: if true, a source map will be generated; and instead of returning a string, compile will return an object of the form {js, v3SourceMap, sourceMap}.
options.inlineMap, boolean: if true, output the source map as a base64-encoded string in a comment at the bottom.
options.filename, string: the filename to use for the source map. It can include a path (relative or absolute).
options.bare, boolean: if true, output without the top-level function safety wrapper.
options.header, boolean: if true, output the Generated by CoffeeScript header.
options.transpile, object: if set, this must be an object with the options to pass to Babel. See Transpilation.
options.ast, boolean: if true, return an abstract syntax tree of the input CoffeeScript source code.

Transpilation

CoffeeScript 2 generates JavaScript that uses the latest, modern syntax. The runtime or browsers where you want your code to run might not support all of that syntax. In that case, we want to convert modern JavaScript into older JavaScript that will run in older versions of Node or older browsers; for example, { a } = obj into a = obj.a. This is done via transpilers like Babel, Bublé or Traceur Compiler. See Build Tools.

Quickstart

From the root of your project:

npm install --save-dev @babel/core @babel/preset-env
echo '{ "presets": ["@babel/env"] }' > .babelrc
coffee --compile --transpile --inline-map some-file.coffee

Transpiling with the CoffeeScript compiler

To make things easy, CoffeeScript has built-in support for the popular Babel transpiler. You can use it via the --transpile command-line option or the transpile Node API option. To use either, @babel/core must be installed in your project:

npm install --save-dev @babel/core

Or if you’re running the coffee command outside of a project folder, using a globally-installed coffeescript module, @babel/core needs to be installed globally:

npm install --global @babel/core

By default, Babel doesn’t do anything—it doesn’t make assumptions about what you want to transpile to. You need to provide it with a configuration so that it knows what to do. One way to do this is by creating a .babelrc file in the folder containing the files you’re compiling, or in any parent folder up the path above those files. (Babel supports other ways, too.) A minimal .babelrc file would be just { "presets": ["@babel/env"] }. This implies that you have installed @babel/preset-env:

npm install --save-dev @babel/preset-env  # Or --global for non-project-based usage

See Babel’s website to learn about presets and plugins and the multitude of options you have. Another preset you might need is @babel/plugin-transform-react-jsx if you’re using JSX with React (JSX can also be used with other frameworks).

Once you have @babel/core and @babel/preset-env (or other presets or plugins) installed, and a .babelrc file (or other equivalent) in place, you can use coffee --transpile to pipe CoffeeScript’s output through Babel using the options you’ve saved.

If you’re using CoffeeScript via the Node API, where you call CoffeeScript.compile with a string to be compiled and an options object, the transpile key of the options object should be the Babel options:

CoffeeScript.compile(code, {transpile: {presets: ['@babel/env']}})

You can also transpile CoffeeScript’s output without using the transpile option, for example as part of a build chain. This lets you use transpilers other than Babel, and it gives you greater control over the process. There are many great task runners for setting up JavaScript build chains, such as Gulp, Webpack, Grunt and Broccoli.

Polyfills

Note that transpiling doesn’t automatically supply polyfills for your code. CoffeeScript itself will output Array.indexOf if you use the in operator, or destructuring or spread/rest syntax; and Function.bind if you use a bound (=>) method in a class. Both are supported in Internet Explorer 9+ and all more recent browsers, but you will need to supply polyfills if you need to support Internet Explorer 8 or below and are using features that would cause these methods to be output. You’ll also need to supply polyfills if your own code uses these methods or another method added in recent versions of JavaScript. One polyfill option is @babel/polyfill, though there are many other strategies.

Language Reference

This reference is structured so that it can be read from top to bottom, if you like. Later sections use ideas and syntax previously introduced. Familiarity with JavaScript is assumed. In all of the following examples, the source CoffeeScript is provided on the left, and the direct compilation into JavaScript is on the right.

Many of the examples can be run (where it makes sense) by pressing the ▶ button on the right. The CoffeeScript on the left is editable, and the JavaScript will update as you edit.

First, the basics: CoffeeScript uses significant whitespace to delimit blocks of code. You don’t need to use semicolons ; to terminate expressions, ending the line will do just as well (although semicolons can still be used to fit multiple expressions onto a single line). Instead of using curly braces { } to surround blocks of code in functions, if-statements, switch, and try/catch, use indentation.

You don’t need to use parentheses to invoke a function if you’re passing arguments. The implicit call wraps forward to the end of the line or block expression.
console.log sys.inspect object → console.log(sys.inspect(object));

Functions

Functions are defined by an optional list of parameters in parentheses, an arrow, and the function body. The empty function looks like this: ->

Functions may also have default values for arguments, which will be used if the incoming argument is missing (undefined).

Strings

Like JavaScript and many other languages, CoffeeScript supports strings as delimited by the " or ' characters. CoffeeScript also supports string interpolation within "-quoted strings, using #{ … }. Single-quoted strings are literal. You may even use interpolation in object keys.