Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/bigpipe/react-jsx

Compile transform your JSX templates into a template engine that works client AND server side
https://github.com/bigpipe/react-jsx

Last synced: 1 day ago
JSON representation

Compile transform your JSX templates into a template engine that works client AND server side

Awesome Lists containing this project

README 

        
# react-jsx



[![Version npm][version]](http://browsenpm.org/package/react-jsx)[![Build Status][build]](https://travis-ci.org/bigpipe/react-jsx)[![Dependencies][david]](https://david-dm.org/bigpipe/react-jsx)[![Coverage Status][cover]](https://coveralls.io/r/bigpipe/react-jsx?branch=master)



[from]: https://img.shields.io/badge/from-bigpipe.io-9d8dff.svg?style=flat-square

[version]: http://img.shields.io/npm/v/react-jsx.svg?style=flat-square

[build]: http://img.shields.io/travis/bigpipe/react-jsx/master.svg?style=flat-square

[david]: https://img.shields.io/david/bigpipe/react-jsx.svg?style=flat-square

[cover]: http://img.shields.io/coveralls/bigpipe/react-jsx/master.svg?style=flat-square



The `react-jsx` module allows you to compile your JSX (`.jsx`) templates to:



- React's `React.createElement` DOM syntax (default for server and client).

- React's HTML output.

- Pure HTML output.



These templates can be used on the server **and** client. This way you can move

your `JSX` templates out of your `React.createClass`'s `render` method and to

it's own template files which leads to a more manageable code base.



In addition to the features mentioned above we also eliminated the requirement

of "global" and "locally" scoped variables in your template. You can now pass in

the data using a `data` argument.



By using the same templates on the front and back-end you can create

progressively enhanced and SEO friendly web pages.



## Table of Contents



- [Installation](#installation)

- [Versioning](#versioning)

- [Usage](#usage)

- [Passing data around](#passing-data-around)

- [Templates](#templates)

- [Client-side](#client-side)

- [Output](#output)

- [Warnings](#warnings)

- [License](#license)



## Installation



The module is published in the public npm registry and can be installed using:



```

npm install --save react-jsx

```



And that's it! To learn more about how the API works, continue to the [usage]

section.



## Versioning



The minor version of this module is in sync with the version of `react` and

`react-tools` that we depend upon. Bug fixes to this library will be done as

patch releases so you should read our versioning as:



```

..

```



The earliest version of react that we support is **0.12**. So please note that

our 0.0.x releases CAN include a breaking change so when you're adding this

module to your package.json make sure you put down the full semver version.



## Usage



In all of the examples we assume that you've already required the `jsx` compiler

as following:



```js

'use strict';



var jsx = require('react-jsx');

```



This `jsx` variable now contains 3 methods:



- **server** Use this method if you want transform your `jsx` templates for

  server-side usage. We will automatically inject `React` as global in the

  templates so it all works as intended. We will return a function which you can

  call to render your template.

- **client** Use this method if you want to transform your `jsx` templates for

  client-side usage. It assumes that React is already available as global on the

  page. We will return a function which you can call to render you template.

- **transform** Our internal compiler which transforms the JSX templates to a

  template API.



Both the **server** and **client** method share the same API for compiling and

rendering:



```js

var template = fs.readFileSync('template.jsx', 'utf-8');



var server = jsx.server(template, { /* options */});

var client = jsx.client(template, {});



console.log(server({ data: 'for template' }));

```



And they also share the same options:



- **filename**: File name of the template file we're about to process. This will

  be used for debugging purposes in the inlined source map when you've set

  `debug` to true.

- **debug**: When set to `true`, we will automatically inline source map.

- **ecma**: Which ECMA version should the template be compiled towards. It

  defaults to `es3` for the client and `es5` on the server.

- **types** Don't use strict types.

- **raw** This allows you to control how the generated HTML is outputted. By

  default we output the React generated HTML which is full of `data-react-xxx`

  attributes. Setting this option to `true` will return a clean HTML instead.



When rendering the templates both the server and client method will return the

expected `React.createElement` nodes just like you would normally do in your

templates so you can easily share templates with child/parent relations. If you

want the template methods. But your might want to output the raw/pure HTML

instead. This can be done by supplying `{ html: true }` as option to the

template function:



```js

var template = fs.readFileSync('/path/to/template.jsx', 'utf-8')

  , render = jsx.server(template, { filename: 'template.jsx' });



console.log(render({ foo: 'bar' }, { html: true }));

```



### Passing data around



The generated client and server functions accept data or "scope" for the

templates as first argument:



```js

render({ foo: 'bar' });

```



If you want to set a custom `this` context for the template you could call the

returned template function as followed:



```js

render.call({ custom: 'this', value: 'is possible' });

```



But the template function we've generated is smart enough to figure out if

you're passing around React instances and will automatically set the supplied

`data` argument as context:



```js

var HelloWorld = React.createClass({

  render: function render() {

    return render(this);

  }

});

```



So in the example above the data argument is set to `this` so it will

automatically be introduced as `this` in the template AND all properties and

methods will also be introduced as local variables. So if where to mixins the

`React.Intl` module in the class above your template would have access to

`` components:



```js

var HelloWorld = React.createClass({

  mixins: [require('react-intl').IntlMixin]

  render: function render() {

    return render(this);

  }

});

```



And the template that you would render could then contain:



```jsx

}

/>

```



### Templates



The `.jsx` templates that you're creating should only contain the parts that are

transformed in to `React.createElement`'s. In addition to that there is no need

to `return` or `module.exports` the template. This is all taken care of under

the hood. The following example would a valid example of this:



```jsx



  

;

```



Working with components isn't a problem either, you can still pass them around

using the `data` argument of the template function as illustrated in this HTTP

server example: 



```js

var http = require('http')

  , path = require('path')

  , React = require('react')

  , jsx = require('react-jsx')

  , read = require('fs').readFileSync;



var templates = {

  hello: jsx.server(read(path.join(__dirname, 'hello.jsx'), 'utf-8')),

  index: jsx.server(read(path.join(__dirname, 'index.jsx'), 'utf-8'))

};



var HelloWorld = React.createClass({

  render: function render() {

    return templates.hello(this);

  }

});



http.createServer(function (req, res) {

  res.statusCode = 200;

  res.setHeader('Content-Type', 'text/html');



  res.end(templates.index({

    HelloWorld: HelloWorld,

    title: 'Hello world',

    another: 'variable'

  }, { html: true }));

}).listen(8080);

```



```jsx

/* index.jsx */



  

    {title}

  

  

    

  



```



```jsx

/* hello.jsx */



  Hello world, you're just another {this.props.name}



```



### Client-side



The client that we generate is a function but is optimized for ES3 so it works

in older browser versions without any addition hassle. As the `jsx.client()`

method returns a function you might need to transform this to a string if you

want to use it for client side templates. The string transformation is quite

easy to do:



```js

var build = 'var mytemplate = '+ jsx.client(template).toString();

```



The `.toString()` method automatically transforms the function in to an

anonymous function. In the example above we saved the template as `mytemplate`

variable. So when we store this a JavaScript file to disk using a

`fs.writeFileSync('/mytemplate.js', build);` we can easily access the

template on the client side by referencing the `mytemplate` global.



So with this knowledge, an illustration of this:



```js

var Component = React.createClass({

  render: function render() {

    return mytemplate({ foo: 'bar' });

  }

});

```



### Output



To give you an idea about what we're actually generating here, lets take the

following JSX template and convert it a client and server template:



```jsx



  

  Click Me!

  
    

        {['un', 'deux', 'trois'].map(function(number) {

          return 
  • {number}
    • ;

        })}

      


;

```



When we compile this template for server-side usage with the **raw** and

**html** options enabled:



```js

var server = jsx.server(template, { raw: true });

console.log(server({ defaultValue: 10 }, { html: true }));

```



It will generate the following output:



```html

Click Me!
    

  • un
    • 

  • deux
    • 

  • trois
    • 





```



And with the **raw** option set to **false** it will generate:



```html

Click Me!
    

  • un
    • 

  • deux
    • 

  • trois
    • 





```



But by default we will just return React.createElement structures:



```js

var client = jsx.client(template);

console.log(client({ defaultValue: 10 }));

```



Returns the expected `React.createElement` structure:



```js

React.createElement("div", null,

  React.createElement("input", {type: "text", value: defaultValue}),

  React.createElement("button", {onclick: "alert('clicked!');"}, "Click Me!"),

  React.createElement("ul", null,

    ['un', 'deux', 'trois'].map(function(number) {

      return React.createElement("li", null, number);

    })

  )

);

```



## Warnings



As we are using the `react-tools` to compile the templates to all the nice

things it can happen that it output's "useful" information about your templates

in the terminal. For example for the template used above you would see the

following warning in your terminal:



```

Warning: You provided a `value` prop to a form field without an `onChange`

handler. This will render a read-only field. If the field should be mutable use

`defaultValue`. Otherwise, set either `onChange` or `readOnly`.

```



There's not really a way to prevent this from happening except for running your

code with `NODE_ENV=production` as this will silence the warnings.



## License



MIT