react_on_rails 2.0.0.beta.1 → 2.0.0.beta.2

data/Rakefile

@@ -0,0 +1,5 @@
+# Rake will automatically load any *.rake files inside of the "rakelib" folder
+# See rakelib/
+
+desc "Run all tests and linting"
+task default: ["run_rspec", "docker:lint"]

data/app/helpers/react_on_rails_helper.rb

@@ -0,0 +1,215 @@
+# NOTE:
+# For any heredoc JS:
+# 1. The white spacing in this file matters!
+# 2. Keep all #{some_var} fully to the left so that all indentation is done evenly in that var
+require "react_on_rails/prerender_error"
+
+module ReactOnRailsHelper
+  # react_component_name: can be a React component, created using a ES6 class, or
+  #   React.createClass, or a
+  #     `generator function` that returns a React component
+  #       using ES6
+  #          let MyReactComponentApp = (props) => <MyReactComponent {...props}/>;
+  #       or using ES5
+  #          var MyReactComponentApp = function(props) { return <YourReactComponent {...props}/>; }
+  #    Exposing the react_component_name is necessary to both a plain ReactComponent as well as
+  #      a generator:
+  #    See README.md for how to "register" your react components.
+  #    See spec/dummy/client/app/startup/serverRegistration.jsx and
+  #      spec/dummy/client/app/startup/ClientRegistration.jsx for examples of this
+  # props: Ruby Hash or JSON string which contains the properties to pass to the react object
+  #
+  #  options:
+  #    prerender: <true/false> set to false when debugging!
+  #    trace: <true/false> set to true to print additional debugging information in the browser
+  #           default is true for development, off otherwise
+  #    replay_console: <true/false> Default is true. False will disable echoing server rendering
+  #                    logs to browser. While this can make troubleshooting server rendering difficult,
+  #                    so long as you have the default configuration of logging_on_server set to
+  #                    true, you'll still see the errors on the server.
+  #    raise_on_prerender_error: <true/false> Default to false. True will raise exception on server
+  #       if the JS code throws
+  #  Any other options are passed to the content tag, including the id.
+  def react_component(component_name, props = {}, options = {})
+    # Create the JavaScript and HTML to allow either client or server rendering of the
+    # react_component.
+    #
+    # Create the JavaScript setup of the global to initialize the client rendering
+    # (re-hydrate the data). This enables react rendered on the client to see that the
+    # server has already rendered the HTML.
+    # We use this react_component_index in case we have the same component multiple times on the page.
+    react_component_index = next_react_component_index
+    react_component_name = component_name.camelize # Not sure if we should be doing this (JG)
+    if options[:id].nil?
+      dom_id = "#{component_name}-react-component-#{react_component_index}"
+    else
+      dom_id = options[:id]
+    end
+
+    # Setup the page_loaded_js, which is the same regardless of prerendering or not!
+    # The reason is that React is smart about not doing extra work if the server rendering did its job.
+    turbolinks_loaded = Object.const_defined?(:Turbolinks)
+
+    data = { component_name: react_component_name,
+             props: props,
+             trace: trace(options),
+             expect_turbolinks: turbolinks_loaded,
+             dom_id: dom_id
+    }
+
+    component_specification_tag =
+      content_tag(:div,
+                  "",
+                  class: "js-react-on-rails-component",
+                  style: "display:none",
+                  data: data)
+
+    # Create the HTML rendering part
+    result = server_rendered_react_component_html(options, props, react_component_name, dom_id)
+
+    server_rendered_html = result["html"]
+    console_script = result["consoleReplayScript"]
+
+    content_tag_options = options.except(:generator_function, :prerender, :trace,
+                                         :replay_console, :id, :react_component_name,
+                                         :server_side, :raise_on_prerender_error)
+    content_tag_options[:id] = dom_id
+
+    rendered_output = content_tag(:div,
+                                  server_rendered_html.html_safe,
+                                  content_tag_options)
+
+    # IMPORTANT: Ensure that we mark string as html_safe to avoid escaping.
+    <<-HTML.html_safe
+#{component_specification_tag}
+#{rendered_output}
+#{replay_console(options) ? console_script : ''}
+    HTML
+  end
+
+  def sanitized_props_string(props)
+    props.is_a?(String) ? json_escape(props) : props.to_json
+  end
+
+  # Helper method to take javascript expression and returns the output from evaluating it.
+  # If you have more than one line that needs to be executed, wrap it in an IIFE.
+  # JS exceptions are caught and console messages are handled properly.
+  def server_render_js(js_expression, options = {})
+    wrapper_js = <<-JS
+(function() {
+  var htmlResult = '';
+  var consoleReplayScript = '';
+  var hasErrors = false;
+
+  try {
+    htmlResult =
+      (function() {
+        return #{js_expression};
+      })();
+  } catch(e) {
+    htmlResult = ReactOnRails.handleError({e: e, name: null,
+      jsCode: '#{escape_javascript(js_expression)}', serverSide: true});
+    hasErrors = true;
+  }
+
+  consoleReplayScript = ReactOnRails.buildConsoleReplay();
+
+  return JSON.stringify({
+      html: htmlResult,
+      consoleReplayScript: consoleReplayScript,
+      hasErrors: hasErrors
+  });
+
+})()
+    JS
+
+    result = ReactOnRails::ServerRenderingPool.server_render_js_with_console_logging(wrapper_js)
+
+    # IMPORTANT: To ensure that Rails doesn't auto-escape HTML tags, use the 'raw' method.
+    html = result["html"]
+    console_log_script = result["consoleLogScript"]
+    raw("#{html}#{replay_console(options) ? console_log_script : ''}")
+  rescue ExecJS::ProgramError => err
+    # rubocop:disable Style/RaiseArgs
+    raise ReactOnRails::PrerenderError.new(component_name: "N/A (server_render_js called)",
+                                           err: err,
+                                           js_code: wrapper_js)
+    # rubocop:enable Style/RaiseArgs
+  end
+
+  private
+
+  def next_react_component_index
+    @react_component_index ||= -1
+    @react_component_index += 1
+  end
+
+  # Returns Array [0]: html, [1]: script to console log
+  # NOTE, these are NOT html_safe!
+  # rubocop:disable Metrics/CyclomaticComplexity
+  def server_rendered_react_component_html(options, props, react_component_name, dom_id)
+    return { "html" => "", "consoleReplayScript" => "" } unless prerender(options)
+
+    # On server `location` option is added (`location = request.fullpath`)
+    # React Router needs this to match the current route
+
+    # Make sure that we use up-to-date server-bundle
+    ReactOnRails::ServerRenderingPool.reset_pool_if_server_bundle_was_modified
+
+    # Since this code is not inserted on a web page, we don't need to escape.
+    props_string = props.is_a?(String) ? props : props.to_json
+
+    wrapper_js = <<-JS
+(function() {
+  var props = #{props_string};
+  return ReactOnRails.serverRenderReactComponent({
+    name: '#{react_component_name}',
+    domNodeId: '#{dom_id}',
+    props: props,
+    trace: #{trace(options)},
+    location: '#{request.fullpath}'
+  });
+})()
+    JS
+
+    result = ReactOnRails::ServerRenderingPool.server_render_js_with_console_logging(wrapper_js)
+
+    if result["hasErrors"] && raise_on_prerender_error(options)
+      # We caught this exception on our backtrace handler
+      # rubocop:disable Style/RaiseArgs
+      fail ReactOnRails::PrerenderError.new(component_name: react_component_name,
+                                            # Sanitize as this might be browser logged
+                                            props: sanitized_props_string(props),
+                                            err: nil,
+                                            js_code: wrapper_js,
+                                            console_messages: result["consoleReplayScript"])
+      # rubocop:enable Style/RaiseArgs
+    end
+    result
+  rescue ExecJS::ProgramError => err
+    # This error came from execJs
+    # rubocop:disable Style/RaiseArgs
+    raise ReactOnRails::PrerenderError.new(component_name: react_component_name,
+                                           # Sanitize as this might be browser logged
+                                           props: sanitized_props_string(props),
+                                           err: err,
+                                           js_code: wrapper_js)
+    # rubocop:enable Style/RaiseArgs
+  end
+
+  def raise_on_prerender_error(options)
+    options.fetch(:raise_on_prerender_error) { ReactOnRails.configuration.raise_on_prerender_error }
+  end
+
+  def trace(options)
+    options.fetch(:trace) { ReactOnRails.configuration.trace }
+  end
+
+  def prerender(options)
+    options.fetch(:prerender) { ReactOnRails.configuration.prerender }
+  end
+
+  def replay_console(options)
+    options.fetch(:replay_console) { ReactOnRails.configuration.replay_console }
+  end
+end

data/docker-compose.yml

@@ -0,0 +1,11 @@
+lint:
+  image: dylangrafmyre/docker-lint
+  working_dir: /app/
+  volumes:
+    - '.:/app/'
+tests:
+  build: .
+  dockerfile: Dockerfile_tests
+  working_dir: /app/
+  volumes:
+    - '.:/app/'

data/docs/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Justin Gordon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/docs/additional_reading/heroku_deployment.md

@@ -0,0 +1,23 @@
+# Heroku Deployment
+The generator has created the necessary files and gems for deployment to Heroku. If you have installed manually, you will need to provide these files yourself:
+
++ `Procfile`: used by Heroku and Foreman to start the Puma server
++ `.buildpacks`: used to install Ruby and Node environments
++ `12factor` gem: required by Heroku
++ `'puma'` gem: recommended Heroku webserver
++ `config/puma.rb`: Puma webserver config file
++ `lib/tasks/assets.rake`: This rake task file is provided by the generator regardless of whether the user chose Heroku Deployment as an option. It is highlighted here because it is helpful to understand that this task is what generates your JavaScript bundles in production.
+
+## How to Deploy
+
+React on Rails requires both a ruby environment (for Rails) and a Node environment (for Webpack), so you will need to have Heroku use multiple buildpacks. Currently, we would suggest using [DDollar's Heroku Buildpack Multi](https://github.com/ddollar/heroku-buildpack-multi).
+
+Assuming you have downloaded and installed the Heroku command-line utility and have initialized the app, you will need to tell Heroku to use Heroku Buildpack Multi via the command-line:
+
+```
+heroku buildpacks:set https://github.com/heroku/heroku-buildpack-multi
+```
+
+Heroku will now be able to use the multiple buildpacks specified in `.buildpacks`. 
+
+Note, an alternative approach is to use the [Heroku Toolbelt to set buildpacks](https://devcenter.heroku.com/articles/using-multiple-buildpacks-for-an-app).

data/docs/additional_reading/manual_installation.md

@@ -0,0 +1,118 @@
+# TODO FIX THIS FILE AFTER this is updated: https://github.com/shakacode/react-webpack-rails-tutorial
+
+# Manual Installation
+Follow these steps if you choose to forgo the generator:
+
+1. Globally expose React in your webpack config like [this](https://github.com/shakacode/react-webpack-rails-tutorial/blob/537c985dc82faee333d80509343ca32a3965f9dd/client/webpack.client.base.config.js#L31):
+
+  ```javascript
+  module: {
+    loaders: [
+      // React is necessary for the client rendering:
+      { test: require.resolve('react'), loader: 'expose?React' },
+
+      // For React 0.14
+      { test: require.resolve('react-dom'), loader: 'expose?ReactDOM' }, // not in the server one
+  ```
+
+
+3. Expose your client globals like [this](https://github.com/shakacode/react-webpack-rails-tutorial/blob/537c985dc82faee333d80509343ca32a3965f9dd/client/app/startup/clientRegistration.jsx#L3):
+
+  ```javascript
+  import App from './ClientApp';
+  import ReactOnRails from 'react-on-rails';
+  ReactOnRails.register({ App });
+  ```
+4. Put your client globals file as webpack entry points like [this](https://github.com/shakacode/react-webpack-rails-tutorial/blob/537c985dc82faee333d80509343ca32a3965f9dd/client/webpack.client.rails.config.js#L22). Similar pattern for server rendering.
+
+  ```javascript
+  config.entry.app.push('./app/startup/clientRegistration');
+  ```
+
+## Additional Steps For Server Rendering (option `prerender` shown below)
+See the next section for a sample webpack.server.rails.config.js.
+
+1. Expose your server globals like [this](https://github.com/shakacode/react-webpack-rails-tutorial/blob/537c985dc82faee333d80509343ca32a3965f9dd/client/app/startup/serverRegistration.jsx#L7)
+
+  ```javascript
+  import App from './ServerApp';
+  global.App = App;
+  ```
+2. Make the server globals file an entry point in your webpack config, like [this](https://github.com/shakacode/react-webpack-rails-tutorial/blob/537c985dc82faee333d80509343ca32a3965f9dd/client/webpack.server.rails.config.js#L7)
+
+  ```javascript
+  entry: ['./app/startup/serverRegistration'],
+  ```
+3. Ensure the name of your ouput file (shown [here](https://github.com/shakacode/react-webpack-rails-tutorial/blob/537c985dc82faee333d80509343ca32a3965f9dd/client/webpack.server.rails.config.js#L9)) of your server bundle corresponds to the configuration of the gem. The default path is `app/assets/javascripts/generated`. See below for customization of configuration variables.
+4. Expose `React` in your webpack config, like [this](https://github.com/shakacode/react-webpack-rails-tutorial/blob/master/client/webpack.server.rails.config.js#L23)
+
+```javascript
+{ test: require.resolve('react'), loader: 'expose?React' },
+
+// For React 0.14
+{ test: require.resolve('react-dom/server'), loader: 'expose?ReactDOMServer' }, // not in client one, only server
+```
+
+### Sample webpack.server.rails.config.js (ONLY for server rendering)
+Be sure to check out the latest example version of [client/webpack.server.rails.config.js](https://github.com/shakacode/react-webpack-rails-tutorial/blob/master/client/webpack.server.rails.config.js).
+
+```javascript
+// Common webpack configuration for server bundle
+
+module.exports = {
+
+  // the project dir
+  context: __dirname,
+  entry: ['./app/startup/serverRegistration'],
+  output: {
+    filename: 'server-bundle.js',
+    path: '../app/assets/javascripts/generated',
+
+    // CRITICAL to set libraryTarget: 'this' for enabling Rails to find the exposed modules IF you
+    //   use the "expose" webpackfunctionality. See startup/serverRegistration.jsx.
+    // NOTE: This is NOT necessary if you use the syntax of global.MyComponent = MyComponent syntax.
+    // See http://webpack.github.io/docs/configuration.html#externals for documentation of this option
+    //libraryTarget: 'this',
+  },
+  resolve: {
+    extensions: ['', '.webpack.js', '.web.js', '.js', '.jsx', 'config.js'],
+  },
+  module: {
+    loaders: [
+      {test: /\.jsx?$/, loader: 'babel-loader', exclude: /node_modules/},
+
+      // React is necessary for the client rendering:
+      { test: require.resolve('react'), loader: 'expose?React' },
+      { test: require.resolve('react-dom/server'), loader: 'expose?ReactDOMServer' },
+    ],
+  },
+};
+```
+
+## What Happens?
+
+Here's what the browser will render with a call to the `react_component` helper.
+![2015-09-28_20-24-35](https://cloud.githubusercontent.com/assets/1118459/10157268/41435186-6624-11e5-9341-6fc4cf35ee90.png)
+
+  If you're curious as to what the gem generates for the server and client rendering, see [`spec/dummy/client/app/startup/serverRegistration.jsx`](https://github.com/shakacode/react_on_rails/blob/master/spec/dummy/spec/sample_generated_js/server-generated.js)
+  and [`spec/dummy/client/app/startup/ClientReduxApp.jsx`](https://github.com/shakacode/react_on_rails/blob/master/spec/dummy/spec/sample_generated_js/client-generated.js) for examples of this. Note, this is not the code that you are providing. You can see the client code by viewing the page source.
+
+* **props**: [hash | string of json] Properties to pass to the react object. See this example if you're using Jbuilder: [react-webpack-rails-tutorial view rendering props using jBuilder](https://github.com/shakacode/react-webpack-rails-tutorial/blob/master/app/views/pages/index.html.erb#L20)
+
+```erb
+<%= react_component('App', render(template: "/comments/index.json.jbuilder"), prerender: true) %>
+```
+* **options:** [hash]
+  * **prerender**: <true/false> set to false when debugging!
+  * **trace**: <true/false> set to true to print additional debugging information in the browser default is true for development, off otherwise
+  * **replay_console**: <true/false> Default is true. False will disable echoing server rendering logs, which can make troubleshooting server rendering difficult.
+  * Any other options are passed to the content tag, including the id.
+
+# JavaScript
+
+1. Configure your webpack configuration to create the file used for server rendering if you plan to do server rendering.
+2. Follow the examples in `spec/dummy/client/app/startup/clientRegistration.jsx` to expose your react components for client side rendering.
+3. Follow the examples in `spec/dummy/client/app/startup/serverRegistration.jsx` to expose your react components for server side rendering. The code is the same, but you might be importing from a file specialized for server rendering.
+
+## React 0.13 vs. React 0.14
+We no longer support React 0.13.

data/docs/additional_reading/node_dependencies_and_npm.md

@@ -0,0 +1,29 @@
+# Node Dependencies and NPM
+## Updating
+After installing the files, you may want to update the node dependencies. This is analogous to updating gem versions:
+
+```bash
+cd client
+npm install -g npm-check-updates
+rm npm-shrinkwrap.json
+npm-check-updates -u
+npm install
+npm prune
+npm shrinkwrap
+```
+
+Confirm that the hot replacement dev server and the Rails server both work. You may have to delete `node_modules` and `npm-shrinkwrap.json` and then run `npm shrinkwrap`.
+
+*Note: `npm prune` is required before running `npm shrinkwrap` to remove dependencies that are no longer needed after doing updates.*
+
+## Adding New Dependencies
+Typically, you can add your Node dependencies as you normally would. Occasionally, adding a new dependency may require removing and re-running `npm shrinkwrap`:
+
+```bash
+cd client
+npm install --save module_name@version
+# or
+# npm install --save_dev module_name@version
+rm npm-shrinkwrap.json
+npm shrinkwrap
+```

data/docs/additional_reading/optional_configuration.md

@@ -0,0 +1,33 @@
+# Optional Configuration
+
+Create a file `config/react_on_rails.rb` to override any defaults (this file is automatically created for you when using the generator). If you don't specify this file, the default options are below.
+
+The `server_bundle_js_file` must correspond to the bundle you want to use for server rendering.
+
+```ruby
+# Shown below are the defaults for configuration
+ReactOnRails.configure do |config|
+  # Client bundles are configured in application.js
+  # Server bundle is a single file for all server rendering of components.
+  # Set the server_bundle_js_file to "" if you know that you will not be server rendering.
+  config.server_bundle_js_file = "app/assets/javascripts/generated/server.js" # This is the default
+
+  # Below options can be overriden by passing to the helper method.
+  config.prerender = false # default is false
+  config.trace = Rails.env.development? # default is true for development, off otherwise
+
+  # For server rendering. This can be set to false so that server side messages are discarded.
+  config.replay_console = true # Default is true. Be cautious about turning this off.
+  config.logging_on_server = true # Default is true. Logs server rendering messags to Rails.logger.info
+
+  # Settings for the pool of renderers:
+  config.server_renderer_pool_size  ||= 1  # ExecJS doesn't allow more than one on MRI
+  config.server_renderer_timeout    ||= 20 # seconds
+end
+```
+
+You can configure your pool of JS virtual machines and specify where it should load code:
+
+- On MRI, use `therubyracer` for the best performance (see [discussion](https://github.com/reactjs/react-rails/pull/290))
+- On MRI, you'll get a deadlock with `pool_size` > 1
+- If you're using JRuby, you can increase `pool_size` to have real multi-threaded rendering.