coffee-react

Coffee-React

Coffee-React provides a JSX-like syntax for building React components with the full awesomeness of CoffeeScript.

Included is the cjsx executable, which is wrapper for coffee, using coffee-react-transform and coffee-script to transform CJSX to Javascript. You can also require() CJSX components under node for server-side rendering.

Example

neat-component.cjsx

# @cjsx React.DOM

NeatComponent = React.createClass
  render: ->
    <div className="neat-component">
      {<h1>A Component is I</h1> if @props.showTitle}
      <hr />
      {<p>This line has been printed {n} times</p> for n in [1..10]}
    </div>

compile it

$ cjsx -cb neat-component.cjsx

neat-component.js

// Generated by CoffeeScript 1.7.1
var NeatComponent;

NeatComponent = React.createClass({
  render: function() {
    var n;
    return React.createElement(React.DOM.div, {
      "className": "neat-component"
    }, (this.props.showTitle ? React.createElement(React.DOM.h1, null, "A Component is I") : void 0), React.createElement(React.DOM.hr, null), (function() {
      var _i, _results;
      _results = [];
      for (n = _i = 1; _i <= 10; n = ++_i) {
        _results.push(React.createElement(React.DOM.p, null, "This line has been printed ", n, " times"));
      }
      return _results;
    })());
  }
});

Installation

npm install -g coffee-react

Usage

$ cjsx -h

Usage: cjsx [options] path/to/script.cjsx -- [args]

If called without options, `cjsx` will run your script.

  -b, --bare         compile without a top-level function wrapper
  -c, --compile      compile to JavaScript and save as .js files
  -e, --eval         pass a string from the command line as input
  -h, --help         display this help message
  -j, --join         concatenate the source CoffeeScript before compiling
  -m, --map          generate source map and save as .map files
  -n, --nodes        print out the parse tree that the parser produces
      --nodejs       pass options directly to the "node" binary
      --no-header    suppress the "Generated by" header
  -o, --output       set the output directory for compiled JavaScript
  -p, --print        print out the compiled JavaScript
  -s, --stdio        listen for and compile scripts over stdio
  -l, --literate     treat stdio as literate style coffee-script
  -t, --tokens       print out the tokens that the lexer/rewriter produce
  -v, --version      display the version number
  -w, --watch        watch scripts for changes and rerun commands

Output compiled JS to a file of the same name:

$ cjsx -c my-component.cjsx

Require .cjsx files under node

As with the coffee-script module, you need to register .cjsx with the module loader:

require('coffee-react/register')

Component = require('./component.cjsx')

Spread attributes

A recent addition to JSX (and CJSX) is 'spread attributes' which allow merging an object of props into a component, eg:

extraProps = color: 'red', speed: 'fast'
<div color="blue" {... extraProps} />

which is transformed to:

extraProps = color: 'red', speed: 'fast'
React.createElement(React.DOM.div, Object.assign({"color": "blue"}, extraProps)

If you use this syntax in your code, be sure to include a shim for Object.assign for browsers/environments which don't yet support it (basically all of them). es6-shim and object.assign are two possible choices.

Breaking Changes in 1.0

React 0.12 will introduce changes to the way component descriptors are constructed, where the return value of React.createClass is not a descriptor factory but simply the component class itself, and descriptors must be created manually using React.createElement or by wrapping the component class with React.createDescriptor.

In preparation for this, coffee-react-transform (and as a result, coffee-react) now outputs calls to React.createElement to construct element descriptors from component classes for you, so you won't need to wrap your classes using React.createFactory. However, for this to work you will need to be using at least React 0.11.2, which adds React.createElement.

If you want the older style JSX output (which just desugars into function calls) then you need to use the 0.x branch, eg. 0.5.1.

Additionally, as of 1.0.0, all input files will be CJSX transformed, even if they don't have a .cjsx extension or # @cjsx pragma.

Related projects

• coffee-react-transform, the underlying parser/transformer package.
• node-cjsx: require CJSX files on the server (also possible with coffee-react/register).
• coffee-reactify: bundle CJSX files via browserify, see also cjsxify.
• react-coffee-quickstart: equivalent to react-quickstart.
• sprockets preprocessor: use CJSX with Rails/Sprockets
• ruby coffee-react gem: transform CJSX to Coffeescript under Ruby
• vim plugin for syntax highlighting
• sublime text package for syntax highlighting
• mimosa plugin for the mimosa build tool
• gulp plugin for the gulp build tool
• karma preprocessor for karma test runner