Merge pull request #24 from johnthethird/server-rendering

Implement server-side rendering

Author: jtmalinowski

README.md

@@ -7,11 +7,10 @@
 
 react-rails is a ruby gem which makes it easier to use [React](http://facebook.github.io/react/) and [JSX](http://facebook.github.io/react/docs/jsx-in-depth.html) in your Ruby on Rails application.
 
-This is done in 2 ways:
-
-1. making it easy to include `react.js` as part of your dependencies in `application.js`.
-2. transforming JSX into regular JS on request, or as part of asset precompilation.
 
+1. Making it easy to include `react.js` as part of your dependencies in `application.js`.
+2. Transforming JSX into regular JS on request, or as part of asset precompilation.
+3. View helpers to render React components in an unobtrusive style and/or on the server.
 
 ## Installation
 
@@ -53,7 +52,18 @@ Alternatively, you can include it directly as a separate script tag:
 
 To transform your JSX into JS, simply create `.js.jsx` files, and ensure that the file has the `/** @jsx React.DOM */` docblock. These files will be transformed on request, or precompiled as part of the `assets:precompile` task.
 
-### Unobtrusive javascript
+CoffeeScript files can also be used, by creating `.js.jsx.coffee` files. You must use this form of the docblock at the top of each file: `###* @jsx React.DOM ###`. We also need to embed JSX inside backticks so CoffeeScript ignores the syntax it doesn't understand. Here's an example:
+
+```coffee
+###* @jsx React.DOM ###
+
+Component = React.createClass
+  render: ->
+    `<ExampleComponent videos={this.props.videos} />`
+```
+
+
+### Unobtrusive JavaScript
 
 `react_ujs` will call `React.renderComponent` for every element with `data-react-class` attribute. React properties can be specified by `data-react-props` attribute in JSON format. For example:
 
@@ -76,7 +86,7 @@ To use `react_ujs`, simply `require` it after `react` (and after `turbolinks` if
 
 ### Viewer helper
 
-There is a viewer helper method `react_component`. It is designed to work with `react_ujs` and takes React class name, properties, HTML options as arguments:
+There is a viewer helper method `react_component`. It is designed to work with `react_ujs` and takes a React class name, properties, and HTML options as arguments:
 
 ```ruby
 react_component('HelloMessage', :name => 'John')
@@ -93,19 +103,48 @@ react_component('HelloMessage', {:name => 'John'}, {:id => 'hello', :class => 'f
 # <span class="foo" id="hello" data-...></span>
 ```
 
+### Server Rendering
 
-## CoffeeScript
+React components can also use the same ExecJS mechanisims in Sprockets to execute JavaScript code on the server, and render React components to HTML to be delivered to the browser, and then the `react_ujs` script will cause the component to be mounted. In this way, users get fast initial page loads and search-engine-friendly pages.
 
-It is possible to use JSX with CoffeeScript. The caveat is that you will still need to include the docblock. Since CoffeeScript doesn't allow `/* */` style comments, we need to do something a little different. We also need to embed JSX inside backticks so CoffeeScript ignores the syntax it doesn't understand. Here's an example:
+#### ExecJS
+
+By default, ExecJS will use node.js in an external process to run JS code. Because we will be executing JS on the server in production, an in-process, high-performance JS VM should be used. Simply add the proper one for your platform to your Gemfile:
+
+```ruby
+gem "therubyracer", :platforms => :ruby
+gem "therubyrhino", :platforms => :jruby
+```
+
+#### components.js
+
+In order for us to render your React components, we need to be able to find them and load them into the JS VM. By convention, we look for a `assets/components.js` file through the asset pipeline, and load that. For example:
+
+```sass
+// app/assets/javascripts/components.js
+//= require_tree ./components
+```
+
+This will bring in all files located in the `app/assets/components` directory.  You can organize your code however you like, as long as a request for `/assets/components.js` brings in a concatenated file containing all of your React components, and each one has to be available in the global scope (either `window` or `global` can be used). For `.js.jsx` files this is not a problem, but if you are using `.js.jsx.coffee` files then the wrapper function needs to be taken into account:
 
 ```coffee
 ###* @jsx React.DOM ###
 
 Component = React.createClass
   render: ->
     `<ExampleComponent videos={this.props.videos} />`
+
+window.Component = Component
 ```
 
+#### View Helper
+
+To take advantage of server rendering, use the same view helper `react_component`, and pass in `:prerender => true` in the `options` hash.
+
+```erb
+react_component('HelloMessage', {:name => 'John'}, {:prerender => true})
+```
+This will return the fully rendered component markup, and as long as you have included the `react_ujs` script in your page, then the component will also be instantiated and mounted on the client.
 
 ## Configuring
 
@@ -126,6 +165,7 @@ end
 ```
 
 ### Add-ons
+
 Beginning with React v0.5, there is another type of build. This build ships with some "add-ons" that might be useful - [take a look at the React documentation for details](http://facebook.github.io/react/docs/addons.html). In order to make these available, we've added another configuration (which defaults to `false`).
 
 ```ruby
@@ -134,13 +174,37 @@ MyApp::Application.configure do
 end
 ```
 
-### Changing react.js and JSXTransformer.js versions
+### Server Rendering
 
-In some cases you may want to have your `react.js` and `JSXTransformer.js` files come from a different release than the one, that is specified in the `react-rails.gemspec`. To achieve that, you have to manually replace them in your app.
+For performance and thread-safety reasons, a pool of JS VMs are spun up on application start, and the size of the pool and the timeout on requesting a VM from the pool are configurable. You can also say where you want to grab the `react.js` code from, and if you want to change the filenames for the components (this should be an array of filenames that will be requested from the asset pipeline and concatenated together.)
 
-react-rails at `0.x` requires React at `0.4+`, or `0.5+` or even higher if you need certain add-ons.
+```ruby
+# config/environments/application.rb
+# These are the defaults if you dont specify any yourself
+MyApp::Application.configure do
+  config.react.max_renderers = 10
+  config.react.timeout = 20 #seconds
+  config.react.react_js = lambda {File.read(::Rails.application.assets.resolve('react.js'))}
+  config.react.component_filenames = ['components.js']
+end
+
+```
 
-react-rails at `1.x` requires React at `0.9+`.
+## CoffeeScript
+
+It is possible to use JSX with CoffeeScript. The caveat is that you will still need to include the docblock. Since CoffeeScript doesn't allow `/* */` style comments, we need to do something a little different. We also need to embed JSX inside backticks so CoffeeScript ignores the syntax it doesn't understand. Here's an example:
+
+```coffee
+###* @jsx React.DOM ###
+
+Component = React.createClass
+  render: ->
+    `<ExampleComponent videos={this.props.videos} />`
+```
+
+### Changing react.js and JSXTransformer.js versions
+
+In some cases you may want to have your `react.js` and `JSXTransformer.js` files come from a different release than the one, that is specified in the `react-rails.gemspec`. To achieve that, you have to manually replace them in your app.
 
 #### Instructions
 
@@ -154,4 +218,4 @@ after `config.react.variant`, e.g. you set `config.react.variant = :development`
 If you replace `JSXTransformer.js` in production environment, you have to restart your rails instance,
 because the jsx compiler context is cached.
 
-Name of the `JSXTransformer.js` file *is case-sensitive*.
+Name of the `JSXTransformer.js` file *is case-sensitive*.

lib/react-rails.rb

@@ -1,3 +1,4 @@
 require 'react/jsx'
+require 'react/renderer'
 require 'react/rails'
 

lib/react/rails/railtie.rb

@@ -8,6 +8,16 @@ class Railtie < ::Rails::Railtie
       # Sensible defaults. Can be overridden in application.rb
       config.react.variant = (::Rails.env.production? ? :production : :development)
       config.react.addons = false
+      # Server-side rendering
+      config.react.max_renderers = 10
+      config.react.timeout = 20 #seconds
+      config.react.react_js = lambda {File.read(::Rails.application.assets.resolve('react.js'))}
+      config.react.component_filenames = ['components.js']
+
+      # Watch .jsx files for changes in dev, so we can reload the JS VMs with the new JS code.
+      initializer "react_rails.add_watchable_files" do |app|
+        app.config.watchable_files.concat Dir["#{app.root}/app/assets/javascripts/**/*.jsx*"]
+      end
 
       # run after all initializers to allow sprockets to pick up react.js and
       # jsxtransformer.js from end-user to override ours if needed
@@ -37,11 +47,32 @@ class Railtie < ::Rails::Railtie
         app.assets.prepend_path dropin_path if dropin_path.exist?
 
         # Allow overriding react files that are based on environment
-        # e.g. /vendor/assets/react/react.js
+        # e.g. /vendor/assets/react/development/react.js
         dropin_path_env = app.root.join("vendor/assets/react/#{app.config.react.variant}")
         app.assets.prepend_path dropin_path_env if dropin_path_env.exist?
+      end
+
+
+      config.after_initialize do |app|
+        # Server Rendering
+        # Concat component_filenames together for server rendering
+        app.config.react.components_js = app.config.react.component_filenames.map do |filename|
+          app.assets[filename].to_s
+        end.join(";")
 
+        do_setup = lambda do
+          cfg = app.config.react
+          React::Renderer.setup!( cfg.react_js.call, cfg.components_js,
+                                {:size => cfg.size, :timeout => cfg.timeout})
+        end
+
+        do_setup.call
+
+        # Reload the JS VMs in dev when files change
+        ActionDispatch::Reloader.to_prepare(&do_setup)
       end
+
+
     end
   end
 end

lib/react/rails/view_helper.rb

@@ -1,39 +1,14 @@
 module React
   module Rails
     module ViewHelper
-      # Render a react component named +name+. Returns a HTML tag and some
-      # javascript to render the component.
-      #
-      # HTML attributes can be specified by +options+. The HTML tag is +div+
-      # by default and can be changed by +options[:tag]+. If +options+ is a
-      # symbol, use it as +options[:tag]+.
-      #
-      # Static child elements can be rendered by using a block. Be aware that
-      # they will be replaced once javascript gets executed.
-      #
-      # ==== Examples
-      #
-      #   # // <HelloMessage> defined in a .jsx file:
-      #   # var HelloMessage = React.createClass({
-      #   #   render: function() {
-      #   #     return <div>{'Hello ' + this.props.name}</div>;
-      #   #   }
-      #   # });
-      #   react_component(:HelloMessage, :name => 'John')
-      #
-      #   # Use <span> instead of <div>:
-      #   react_component(:HelloMessage, {:name => 'John'}, :span)
-      #   react_component(:HelloMessage, {:name => 'John'}, :tag => :span)
-      #
-      #   # Add HTML attributes:
-      #   react_component(:HelloMessage, {}, {:class => 'c', :id => 'i'})
+
+      # Render a UJS-type HTML tag annotated with data attributes, which
+      # are used by react_ujs to actually instantiate the React component
+      # on the client.
       #
-      #   # (ERB) Customize child elements:
-      #   <%= react_component :HelloMessage do -%>
-      #     Loading...
-      #   <% end -%>
       def react_component(name, args = {}, options = {}, &block)
         options = {:tag => options} if options.is_a?(Symbol)
+        block = Proc.new{React::Renderer.render(name, args)} if options[:prerender] == true
 
         html_options = options.reverse_merge(:data => {})
         html_options[:data].tap do |data|
@@ -44,6 +19,7 @@ def react_component(name, args = {}, options = {}, &block)
 
         content_tag(html_tag, '', html_options, &block)
       end
+
     end
   end
 end

lib/react/renderer.rb

@@ -0,0 +1,51 @@
+require 'connection_pool'
+
+module React
+  class Renderer
+
+    cattr_accessor :pool
+
+    def self.setup!(react_js, components_js, args={})
+      args.assert_valid_keys(:size, :timeout)
+      @@react_js = react_js
+      @@components_js = components_js
+      @@pool.shutdown{} if @@pool
+      @@pool = ConnectionPool.new(:size => args[:size]||10, :timeout => args[:timeout]||20) { self.new }
+    end
+
+    def self.render(component, args={})
+      @@pool.with do |renderer|
+        renderer.render(component, args)
+      end
+    end
+
+    def self.combined_js
+      @@combined_js ||= <<-CODE
+        var global = global || this;
+        #{@@react_js};
+        React = global.React;
+        #{@@components_js};
+      CODE
+    end
+
+    def context
+      @context ||= ExecJS.compile(self.class.combined_js)
+    end
+
+    def render(component, args={})
+      jscode = <<-JS
+        function() {
+          return React.renderComponentToString(#{component}(#{args.to_json}));
+        }()
+      JS
+      context.eval(jscode).html_safe
+    # What should be done here? If we are server rendering, and encounter an error in the JS code,
+    # then log it and continue, which will just render the react ujs tag, and when the browser tries
+    # to render the component it will most likely encounter the same error and throw to the browser
+    # console for a better debugging experience.
+    rescue ExecJS::ProgramError => e
+      ::Rails.logger.error "[React::Renderer] #{e.message}"
+    end
+
+  end
+end

react-rails.gemspec

@@ -24,6 +24,7 @@ Gem::Specification.new do |s|
   s.add_dependency 'execjs'
   s.add_dependency 'rails', '>= 3.1'
   s.add_dependency 'react-source', '0.9.0'
+  s.add_dependency 'connection_pool'
 
   s.files = Dir[
     'lib/**/*',

test/dummy/app/assets/javascripts/components.js

@@ -0,0 +1,8 @@
+//= require_self
+//= require_tree ./components
+
+// This is because we compile this file into a JS VM
+// for server rendering, and some components may be
+// .coffee and wrapped in a func, so they need a
+// global to glom on to.
+var self, window, global = global || window || self;

test/dummy/app/assets/javascripts/components/Todo.js.jsx.coffee

@@ -0,0 +1,9 @@
+###* @jsx React.DOM ###
+
+Todo = React.createClass
+  render: ->
+    `<li>{this.props.todo}</li>`
+
+# Because Coffee files are in an anonymous function,
+# expose it for server rendering tests
+global.Todo = Todo

test/dummy/app/assets/javascripts/components/TodoList.js.jsx

@@ -0,0 +1,21 @@
+/** @jsx React.DOM */
+
+TodoList = React.createClass({
+  getInitialState: function() {
+    return({mounted: "nope"});
+  },
+  componentWillMount: function() {
+    this.setState({mounted: 'yep'});
+  },
+  render: function() {
+    return (
+      <ul>
+        <li id='status'>{this.state.mounted}</li>
+        {this.props.todos.map(function(todo, i) {
+          return (<Todo key={i} todo={todo} />)
+        })}
+      </ul>
+    )
+  }
+})
+

test/dummy/app/controllers/server_controller.rb

@@ -0,0 +1,5 @@
+class ServerController < ApplicationController
+  def show
+    @todos = %w{todo1 todo2 todo3}
+  end
+end

test/dummy/app/views/server/show.html.erb

@@ -0,0 +1 @@
+<%= react_component "TodoList", {:todos => @todos}, :prerender => true %>

test/dummy/config/routes.rb

@@ -1,3 +1,4 @@
 Dummy::Application.routes.draw do
   resources :pages, :only => [:show]
+  resources :server, :only => [:show]
 end

test/react_renderer_test.rb

@@ -0,0 +1,11 @@
+require 'test_helper'
+
+class ReactRendererTest < ActiveSupport::TestCase
+
+  test 'Server rendering class directly' do
+    result = React::Renderer.render "TodoList", :todos => %w{todo1 todo2 todo3}
+    assert_match /todo1.*todo2.*todo3/, result
+    assert_match /data-react-checksum/, result
+  end
+
+end