React On Rails

Gem Published: https://rubygems.org/gems/react_on_rails

Live example, including server rendering + redux: http://www.reactrails.com/

See Action Plan for v1.0. We're probably feature complete and ready for v1.0.

Feedback and pull-requests encouraged! Thanks in advance! We've got a private slack channel to discuss react + webpack + rails. [Email us for an invite contact@shakacode.com](mailto: contact@shakacode.com).

Supports:

Rails
Webpack
React
Redux
Turbolinks
Server side rendering with fragment caching
react-router for client side rendering (and server side very soon)

OPEN ISSUES

Almost all the open issues are nice to haves like more tests.
If you want to work on any of the open issues, please comment on the issue. My team is mentoring anybody that's trying to help with the issues.
Longer term, we hope to put in many conveniences into this gem, in terms of Webpack + Rails integration. We're open to suggestions.

How is different than the react-rails gem?

react_on_rails depends on webpack. react-rails integrates closely with sprockets and helps you integrate JSX and the react code into a Rails project.
Likewise, using Webpack as shown in the react-webpack-rails-tutorial does involve some extra setup. However, we feel that tight and simple integration with the node ecosystem is more than worth any minor setup costs.
react-rails depends on jquery-ujs for client side rendering. react_on_rails has it's own JS code that does not depend on jquery.

Installation Checklist

Include the gems react_on_rails and therubyracer like this and run bundle. Note, you can sustitute your preferable JavaScript engine.

gem "react_on_rails"
gem "therubyracer"

Globally expose React in your webpack config like this:

  module: {
    loaders: [
      // React is necessary for the client rendering:
      {test: require.resolve('react'), loader: 'expose?React'},
  ```
1. Require `react_on_rails` in your `application.js` like  [this](https://github.com/shakacode/react-webpack-rails-tutorial/blob/361f4338ebb39a5d3934b00cb6d6fcf494773000/app/assets/javascripts/application.js#L15). It possibly should come after you require `turbolinks`:

//= require react_on_rails

1. Expose your client globals like [this](https://github.com/shakacode/react-webpack-rails-tutorial/blob/537c985dc82faee333d80509343ca32a3965f9dd/client/app/startup/clientGlobals.jsx#L3):

 ```javascript
 import App from './ClientApp';
 window.App = App;

Put your client globals file as webpack entry points like this. Similar pattern for server rendering.

config.entry.app.push('./app/startup/clientGlobals');

See customization of configuration options below.

Additional Steps For Server Rendering (option `prerender` shown below)

See the next section for a aample webpack.server.rails.config.js.

Expose your server globals like this

import App from './ServerApp';
global.App = App;

Make the server globals file an entry point in your webpack config, like this
```
entry: ['./app/startup/serverGlobals'],
```
Ensure the name of your ouput file (shown here) 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.
Expose React in your webpack config, like this

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.

  // Common webpack configuration for server bundle

module.exports = {

  // the project dir
  context: __dirname,
  entry: ['./app/startup/serverGlobals'],
  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/serverGlobals.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'},
    ],
  },
};

What Happens?

Here's what the browser will render with a call to the react_component helper.

Usage

See section below titled "Try it out"

Helper Method

The main API is a helper:

  <%= react_component(component_name, props = {}, options = {}) %>

Params are:

react_component_name: [string] 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: For client rendering, expose the react_component_name on window:
```
window.MyReactComponentApp = MyReactComponentApp;
```
For server rendering, export the react_component_name on global:
```
global.MyReactComponentApp = MyReactComponentApp;
```
If you're curious as to what the gem generates for the server and client rendering, see spec/dummy/client/app/startup/serverGlobals.jsx and spec/dummy/client/app/startup/ClientReduxApp.jsx 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

<%= react_component('App', render(template: "/comments/index.json.jbuilder"),
    generator_function: true, prerender: true) %>

options: [hash]
- generator_function: <true/false> default is false, set to true if you want to use a generator function rather than a React Component.
- 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

Configure your webpack configuration to create the file used for server rendering if you plan to do server rendering.
Follow the examples in spec/dummy/client/app/startup/clientGlobals.jsx to expose your react components for client side rendering.
```
import HelloWorld from '../components/HelloWorld';
window.HelloWorld = HelloWorld;
```
Follow the examples in spec/dummy/client/app/startup/serverGlobals.jsx to expose your react components for server side rendering.
```
import HelloWorld from '../components/HelloWorld';
global.HelloWorld = HelloWorld;
```

Server Rendering Tips

Your code can't reference document. Server side JS execution does not have access to document, so jQuery and some other libs won't work in this environment. You can debug this by putting in console.log statements in your code.
You can conditionally avoid running code that references document by passing in a boolean prop to your top level react component. Since the passed in props Hash from the view helper applies to client and server side code, the best way to do this is to use a generator function.

You might do something like this in some file for your top level component:

global.App = () => <MyComponent serverSide={true} />;

The point is that you have separate files for top level client or server side, and you pass some extra option indicating that rendering is happening server sie.

Optional Configuration

Create a file config/react_on_rails.rb to override any defaults. 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.

# 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.
  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.generator_function = false # default is false, meaning that you expose ReactComponents directly
  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)
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.

Try it out in the simple sample app

Contributions and pull requests welcome!

Setup and run the test app in spec/dummy. Note, there's no database.

cd spec/dummy
bundle
npm i
foreman start

Visit http://localhost:3000
Notice that the first time you hit the page, you'll see a message that server is rendering. See spec/dummy/app/views/pages/index.html.erb:17 for the generation of that message.
Look at the layouts in spec/dummy/app/views/pages for samples of usage.
Open up the browser console and see some tracing.
Open up the source for the page and see the server rendered code.
If you want to turn on server caching for development, run the server like: export RAILS_USE_CACHE=YES && foreman start
If you're testing with caching, you'll need to open the console and run Rails.cache.clear to clear the cache. Note, even if you stop the server, you'll still have the cache entries around.
If you click back and forth between the react page links, you can see the rails console log as well as the browser console to see what's going on with regards to server rendering and caching.

Key Tips

See sample app in spec/dummy for how to set this up. See note below on ensuring you **DO NOT RUN rails s and instead run foreman start.
Test out the different options and study the JSX samples in spec/dummy/client/app/startup.
Experiment with changing the settings on the render_component helper calls in the ERB files.
The file used for server rendering is hard coded as generated/server.js (assets/javascripts/generated/server.js).
The default for rendering right now is prerender: false. NOTE: Server side rendering does not work for some components, namely react-router, that use an async setup for server rendering. You can configure the default for prerender in your config.
You can expose either a React component or a function that returns a React component. If you wish to create a React component via a function, rather than simply props, then you need to set the property "generator" on that function to true. When that is done, the function is invoked with a single parameter of "props", and that function should return a React element.
Be sure you can first render your react component client only before you try to debug server rendering!
Open up the HTML source and take a look at the generated HTML and the JavaScript to see what's going on under the covers. Not that when server rendering is turned on, then you'll see the server rendered react components. When server rendering is turned off, then you'll only see the div element where the inline JavaScript will render the component. You might also notice how the props you pass (a Ruby Hash) becomes inline JavaScript on the HTML page.

JavaScript Runtime Configuration

See this discussion on JavaScript performance. The net result is that you want to add this line to your Gemfile to get therubyracer as your default JavaScript engine.

gem "therubyracer"

References

[Making the helper for server side rendering work with JS created by Webpack] (reactjs/react-rails#301 (comment))
Add Demonstration of Server Side Rendering
Charlie Marsh's article "Rendering React Components on the Server"
Node globals

Development Setup for Gem Contributors

Initial Setup

After checking out the repo, making sure you have rvm and nvm setup (setup ruby and node), cd to spec/dummy and run bin/setup to install dependencies.
You can also run bin/console for an interactive prompt that will allow you to experiment.

Starting the Dummy App

To run the test app, it's CRITICAL to not just run rails s. You have to run foreman start. If you don't do this, then webpack will not generate a new bundle, and you will be seriously confused when you change JavaScript and the app does not change.

Install and Release

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

RSpec Testing

Run rake for testing the gem and spec/dummy. Otherwise, the rspec command only works for testing within spec/dummy.

If you run rspec at the top level, you'll see this message: require': cannot load such file -- rails_helper (LoadError)

Debugging

Start the sample app like this for some debug printing:

TRACE_REACT_ON_RAILS=true && foreman start

Generated JavaScript

See spec/dummy/spec/sample_generated_js/server-generated.js to see the JavaScript for typical server rendering.
See spec/dummy/spec/sample_generated_js/client-generated.js to see the JavaScript for typical client rendering.

Linting

All linting is performed from the docker container. You will need docker and docker-compose installed locally to lint code changes via the lint container.

Once you have docker and docker-compose running locally, run docker-compose build lint. This will build the reactonrails_lint docker image and docker-compose lint container. The inital build is slow, but after the install, startup is very quick.

Linting Commands

Run rake -D docker to see all docker linting commands for rake. rake docker will run all linters. For individual rake linting commands please refer to rake -D docker for the list. You can run specfic linting for directories or files by using docker-compose run lint rubocop (file path or directory), etc. docker-compose run lint /bin/bash sets you up to run from the container command line.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/shakacode/react_on_rails. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

License

The gem is available as open source under the terms of the MIT License.

Updating New Versions of the Gem

See https://github.com/svenfuchs/gem-release

gem bump
cd spec/dummy
bundle
git commit -am "Updated Gemfile.lock"
cd ../..
gem tag
gem release

Authors

The Shaka Code team!

And based on the work of the react-rails gem

ericbrooke/react_on_rails

React On Rails

OPEN ISSUES

Links

How is different than the react-rails gem?

Installation Checklist

Additional Steps For Server Rendering (option `prerender` shown below)

Sample webpack.server.rails.config.js (ONLY for server rendering)

What Happens?

Usage

Helper Method

JavaScript

Server Rendering Tips

Optional Configuration

Try it out in the simple sample app

Key Tips

JavaScript Runtime Configuration

References

Development Setup for Gem Contributors

Initial Setup

Starting the Dummy App

Install and Release

RSpec Testing

Debugging

Generated JavaScript

Linting

Linting Commands

Contributing

License

Updating New Versions of the Gem

Authors

ericbrooke/react_on_rails

React On Rails

OPEN ISSUES

Links

How is different than the react-rails gem?

Installation Checklist

Additional Steps For Server Rendering (option prerender shown below)

Sample webpack.server.rails.config.js (ONLY for server rendering)

What Happens?

Usage

Helper Method

JavaScript

Server Rendering Tips

Optional Configuration

Try it out in the simple sample app

Key Tips

JavaScript Runtime Configuration

References

Development Setup for Gem Contributors

Initial Setup

Starting the Dummy App

Install and Release

RSpec Testing

Debugging

Generated JavaScript

Linting

Linting Commands

Contributing

License

Updating New Versions of the Gem

Authors

Additional Steps For Server Rendering (option `prerender` shown below)