README.md

Reaxt
=====

Use your [React](http://facebook.github.io/react/) components into your elixir application, using [webpack](http://webpack.github.io/) compilation, so :

- An isomorphic ready library (SEO/JS are now nice together), but with Elixir on the server side
- Just a Library, with a minimum constraint about your application organization and layout :
  - use any javascript compiled language
  - use any javascript routing logic or library
  - you can use JS React rendered component only for parts of your webpage
- Nice fluent dev workflow, with :
  - combined stacktrace : elixir | javascript
  - hot loading on both server and browser
  - NPM/Webpack as the only config for respectively dependencies/compilation
  - A cool UI to have an overview of your compiled javascript application
  - You do not have to think about the server side Javascript configuration, 
    just write a webpack conf for the browser, and it is ready to use.

TODO List :

- [ ] Handle Source map in server side for combined stacktrace generation
- [ ] Add Source map in client side 
- [ ] Currently the compiler compile in parallel server entry and client
      entries, but server side compilation does not handle *cacheable* and slow
      down very much the compilation
- [ ] handle css loader for `reaxt/style` loader, currently it is ignored in
      server side, which is a problem for URL remapping in CSS.

## Usage ##

See https://github.com/awetzel/reaxt-example for a ready to use example
application, but lets look into details and requirements.

In your mix.exs, add the dependency and the custom compiler for webpack: 
- Add the `:reaxt` dependency to your project.deps and application.applications
- Add `compilers: [:reaxt_webpack] ++ Mix.compilers` to your project, (`:reaxtWebpack` for elixir < v1.0.3)

In your config/config.exs, link the reaxt application to the
application containing the JS web app
- `config :reaxt,:otp_app,:yourapp`

Create the good directory and file layout:
- `MIXROOT/web`
- `MIXROOT/web/package.json` containing your app NPM dependencies
- `MIXROOT/web/webpack.config.js` containing only the client side
  logic, use "reaxt/style" instead of "style" loader to load your css.
  A typical output path is `../priv/static`.
- `MIXROOT/web/components` containing modules exporting React components

In your elixir code generating HTML :
- add `WebPack.header` in the `<head>`
- add a script with src `/your/public/path/<%= WebPack.file_of(:entry_name) %>` 

Then render your server side HTML :

```elixir
# if web/components/thefile exports the react component
Reaxt.render!(:thefile,%{it: "is", the: "props"})

# if web/components/thefile exports an object containing a react component
# at the key "component_key"

Reaxt.render!({:thefile,:component_key},%{it: "is", the: "props"})
```

The function return a `%{html: html,css: css,js_render: js_render}`, you have to add in the html :
- the css `<style><%= render.css %></style>`
- the html in an identified block (`<div id="myblockid"><%= render.html %></div>`)
- the client side rendering call with `<script><%= render.js_render %>("myblockid")</script>`

For example, if you want a page entirely generated by the react
component exported at `web/components/app.js`, then in your elixir web server, send :

```elixir
EEx.eval_string("""
  <html>
  <head> <%= WebPack.header %>
    <style><%= render.css %></style>
  </head>
  <body>
    <div id="content"><%= render.html %></div>
    <script src="/public/<%= WebPack.file_of(:main) %>"></script>
    <script><%= render.js_render %>("content")</script>
  </body>
  </html>
""",render: Reaxt.render!(:app,%{my: "props"}))
```

Finally, you have to serve files generated by webpack :
```elixir
plug Plug.Static, at: "/public", from: :yourapp
```

Then `iex -S mix` and enjoy, but the best is to come.

## Custom Plug : Live reloading and WebPack web UI

When you serve files generated by webpack, use the plug
`WebPack.Plug.Static` instead of `Plug.Static`, it contains 
 an elixir implementation of
 [webpack-dev-server](https://www.npmjs.com/package/webpack-dev-server),
 and a [nice UI](http://webpack.github.io/analyse/).

```elixir
  if Mix.env == :dev do 
    use Plug.Debugger
    plug WebPack.Plug.Static, at: "/public", from: :myweb
  else
    plug Plug.Static, at: "/public", from: :myweb
  end
```

Then go to http://yourhost/webpack to see a beautiful summary of
your compiled js application.

Then configure in your application configuration :
- `config :reaxt,:hot,true` to enable that:
  - server and client side JS will be compiled each time you change files
  - server side renderers will be restarted at each compilation 
  - client browser page will be reloaded, a desktop notification will be triggered
  - The `/webpack` UI will be automatically reloaded if it is on your browser
- `config :reaxt,:hot,:client` to enable the same hot loading, but
  with webpack module hot loading on browser to avoid full page reload
  - use the webpack loader `react-hot-loader` to load your
    component to enable automatic browser hot reloading of your components
  - the `reaxt/style` loader for your css enable hot reloading of your css

## Dynamic Handler and customize rendering (useful with react-router)

See a full example in [reaxt-example](https://github.com/awetzel/reaxt-example/blob/master/web/components/my_router.js)

Reaxt provides facilities to easily customize the rendering process at the
server and the client side : this is done by attaching `reaxt_server_render`
and/or `reaxt_client_render` to the module or object referenced by the first
argument of `Reaxt.render!(`.

- `reaxt_server_render(arg,render)` will 
  - take `arg` from the second argument of `Reaxt.render`, 
  - have to execute `render(component,param)` when the wanting handler and props
    are determined. `param` is any stringifyable object passed to client rendering
- `reaxt_client_render(props,render,param)` have to render the
  good selected component on the client side. 
  - `props` is the initial props used in server rendering,
  - `render` is function you have to call to make the client react rendering
  - `param` is the deserialized version of the third parameter of the callback in `reaxt_server_render`

To understand how they work, let's look at the default implementation
of these functions (what happened when they are not implemented).

```javascript
// default server rendering only take the exported module as the
// handler to render and the argument as the props
default_reaxt_server_render = function(arg,render){
  render(<this {...arg}/>,null)
}
// default client rendering only take the exported module as the
// handler to render, the param is ignored
default_reaxt_client_render = function(props,render,param){
  render(<this {...props}/>)
}
```

Now let's see an example usage of these functions : react-router
integration (`Reaxt.render` second argument is the Path):
See a full example in [reaxt-example](https://github.com/awetzel/reaxt-example/blob/master/web/components/my_router.js)

```elixir
Reaxt.render!(:router_handler,full_path(conn))
```

```javascript
var App = require("./app")
var Router = require("react-router")
var Routes = require("./routes")
module.exports = {
  reaxt_server_render: function(path,render){
    Router.run(Routes, path,function (Handler, state) {
      render(<Handler/>)
    })
  },
  reaxt_client_render: function(props,render){
    Router.run(Routes,Router.HistoryLocation,function(Handler,state){
      render(<Handler {...props}/>)
    })
  }
}
```

## Error management

JS exceptions and stacktraces during rendering are converted into
Elixir one with a fake stacktrace pointing to the generated javascript file.

This is really nice because you can see javascript stacktrace in the `Plug.Debugger` UI on exception.

## Global Configuration

You can define a term in Elixir using Application `env`
`global_config` which will be available globally in the server and
the client side with `require('reaxt/config')`.

```elixir
config :reaxt,:global_config, %{
  some_config1: "value1",
  some_config2: "value2"
}
```

This configuration is static once the `:reaxt` application has started. So if
you want to change this configuration at runtime, you need to reload all
`:reaxt` renderer with `Reaxt.reload`. Remember : this is a costly reload, do
not use it to maintain a state at real time but only for configuration purpose.

```elixir
Application.put_env :reaxt, :global_config, %{
  some_config1: "value3",
  some_config2: "value4"
}
Reaxt.reload
```

Then in your javascript component, you can use this config using : 

```javascript
require('reaxt/config').some_config1
```

## Perfs and pool management

The NodeJS renderers are managed in a pool (to obtain "multicore" JS rendering), so :

- `config :reaxt,:pool_size` configure the number of worker running permanently
- `config :reaxt,:pool_max_overflow` configure the maximum extension of the
  pool when query happens an it is full

A clever configuration could be : 

```elixir
config :reaxt,:pool_size, if(Mix.env == :dev, do: 1, else: 10)
```

For minification, remember that webpack compilation is launched by Mix, so you
can use `process.env.MIX_ENV` in your webpack config.

```elixir
{
  externals: { react: "React" },
  plugins: (function(){
    if(process.env.MIX_ENV == "prod") 
      return [new webpack.optimize.UglifyJsPlugin({minimize: true})]
    else
      return []
  })()
}
```