Reaxt

Use your React components into your elixir application, using webpack 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 :

# 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 :

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 :

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, and a nice UI.

  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

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).

// 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

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

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').

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.

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 :

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 :

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.

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

← Previous Page Changelog