React-Rails

React-Rails is a flexible tool to use React with Rails. The benefits: * Automatically renders React server-side and client-side * Supports Webpacker 4.x, 3.x, 2.x, 1.1+ * Supports Sprockets 4.x, 3.x, 2.x * Lets you use JSX, ES6, TypeScript, CoffeeScript

A source code example utilizing React-Rails: https://github.com/BookOfGreg/react-rails-example-app

Contents

• Get started with Webpacker
  • File naming
• Use with Asset Pipeline
  • Custom JSX Transformer
  • React.js versions
• View Helper
  • Custom View Helper
• UJS
  • Mounting & Unmounting
  • Event Handling

  • getConstructor

• Server-Side Rendering
  • Configuration
  • JavaScript State
  • Custom Server Renderer
• Controller Actions
• Component Generator
  • Use with JBuilder
  • Camelize Props
• Upgrading
  • 2.3 to 2.4
• Common Errors
  • During installation
  • Undefined Set
  • Using TheRubyRacer
  • HMR
• Related Projects
• Contributing

After reading this README file, additional information about React-Rails can be found in the Wiki page: https://github.com/reactjs/React-Rails/wiki The Wiki page features a significant amount of additional information about React-Rails which includes instructional articles and answers to the most frequently asked questions.

Get started with Webpacker

Alternatively, get started with Sprockets

Webpacker provides modern JS tooling for Rails. Here are the listed steps for integrating Webpacker and Rails-React with Rails:

1) Create a new Rails app:

$ rails new my-app
$ cd my-app

2) Add

react-rails

to your Gemfile:

gem 'react-rails'

Note: On rails versions < 6.0, You need to add

gem 'webpacker'

3) Now run the installers:

Rails 6.x and 5.x:

$ bundle install
$ rails webpacker:install         # OR (on rails version < 5.0) rake webpacker:install
$ rails webpacker:install:react   # OR (on rails version < 5.0) rake webpacker:install:react
$ rails generate react:install

This gives you:

• app/javascript/components/

  directory for your React components

• ReactRailsUJS

  setup in

  app/javascript/packs/application.js

• app/javascript/packs/server_rendering.js

  for server-side rendering

Note: On rails versions < 6.0, link the JavaScript pack in Rails view using

javascript_pack_tag

erb

4) Generate your first component:

$ rails g react:component HelloWorld greeting:string

5) You can also generate your component in a subdirectory:

$ rails g react:component my_subdirectory/HelloWorld greeting:string

Note: Your component is added to

app/javascript/components/

Note: If your component is in a subdirectory you will append the directory path to your erb component call.

Example:

6) Render it in a Rails view:

7) Lets Start the app:

$ rails s

output: greeting: Hello from react-rails", inspect webpage in your browser too see change in tag props.

Component name

The component name tells

react-rails

react_component

require

react_component("Item")

require("Item")

react_component("items/index")

require("items/index")

react_component("items.Index")

require("items").Index

react_component("items.Index.Header")

require("items").Index.Header

This way, you can access top-level, default, or named exports.

The

require.context

packs/application.js

ReactRailsUJS.useContext

var myCustomContext = require.context("custom_components", true)
var ReactRailsUJS = require("react_ujs")
// use `custom_components/` for  calls
ReactRailsUJS.useContext(myCustomContext)

If

require

ReactRailsUJS

File naming

React-Rails supports plenty of file extensions such as: .js, .jsx.js, .js.jsx, .es6.js, .coffee, etcetera! Sometimes this will cause a stumble when searching for filenames.

react_component

app/javascript/components/samplecomponent.js

react_component("samplecomponent")

app/javascript/components/sample_component.js

react_component("sample_component")

app/javascript/components/SampleComponent.js

react_component("SampleComponent")

app/javascript/components/SampleComponent.js.jsx

react_component("SampleComponent")

Typescript support

If you want to use React-Rails with Typescript, simply run the installer and add @types:

$ bundle exec rails webpacker:install:typescript
$ yarn add @types/react @types/react-dom

Doing this will allow React-Rails to support the .tsx extension. Additionally, it is recommended to add

ts

tsx

server_renderer_extensions

config.react.server_renderer_extensions = ["jsx", "js", "tsx", "ts"]

Test component

You can use

assert_react_component

app/views/welcome/index.html.erb

class WelcomeControllerTest < ActionDispatch::IntegrationTest
  test 'assert_react_component' do
    get "/welcome"
    assert_equal 200, response.status

# assert rendered react component and check the props
assert_react_component "HelloWorld" do |props|
  assert_equal "Hello from react-rails.", props[:greeting]
  assert_equal "react-rails", props[:info][:name]
  assert_select "[class=?]", "hello-world"
end

# or just assert component rendered
assert_react_component "HelloWorld"
  end
end

Use with Asset Pipeline

react-rails

react-rails

gem 'react-rails'

And then install the react generator:

$ rails g react:install

Then restart your development server.

This will:

• add some

  //= require

  s to

  application.js

• add a

  components/

  directory for React components
• add

  server_rendering.js

  for server-side rendering

Now, you can create React components in

.jsx

// app/assets/javascripts/components/post.jsx

window.Post = createReactClass({
  render: function() {
    return 
{this.props.title}
  }
})

// or, equivalent:
class Post extends React.Component {
  render() {
    return 
{this.props.title}
  }
}

Then, you can render those components in views:

Components must be accessible from the top level, but they may be namespaced, for example:

Custom JSX Transformer

react-rails

config.react.jsx_transformer_class

• #initialize(options)

  , where options is the value passed to

  config.react.jsx_transform_options

• #transform(code_string)

  to return a string of transformed code

react-rails

React::JSX::BabelTransformer

React::JSX::JSXTransformer

JSXTransformer.js

Transform Plugin Options

To supply additional transform plugins to your JSX Transformer, assign them to

config.react.jsx_transform_options

react-rails

babel-source

For example, to use

babel-plugin-transform-class-properties

config.react.jsx_transform_options = {
  optional: ['es7.classProperties']
}

React.js versions

//= require react

React

By default, React's [development version] is provided to

Rails.env.development

# Here are the defaults:
# config/environments/development.rb
MyApp::Application.configure do
  config.react.variant = :development
end

config/environments/production.rb
MyApp::Application.configure do
  config.react.variant = :production
end

Be sure to restart your Rails server after changing these files. See VERSIONS.md to learn which version of React.js is included with your

react-rails

rake tmp:clear

View Helper

react-rails

The view helper (

react_component

div

On page load, the

react_ujs

data-react-class

data-react-props

The view helper's signature is:

react_component(component_class_name, props={}, html_options={})

• component_class_name

  is a string which identifies a component. See getConstructor for details.

• props

  is either:
  • an object that responds to

    #to_json

    ; or
  • an already-stringified JSON object (see JBuilder note below).

• html_options

  may include:

  • tag:

    to use an element other than a

    div

    to embed

    data-react-class

    and

    data-react-props

    .

  • prerender: true

    to render the component on the server.

  • camelize_props

    to transform a props hash

  • **other

    Any other arguments (eg

    class:

    ,

    id:

    ) are passed through to

    content_tag

    .

Custom View Helper

react-rails

react_component

react_component

config.react.view_helper_implementation

• #react_component(name, props = {}, options = {}, &block)

  to return a string to inject into the Rails view

• #setup(controller_instance)

  , called when the helper is initialized at the start of the request

• #teardown(controller_instance)

  , called at the end of the request

react-rails

React::Rails::ComponentMount

UJS

react-rails

"react_ujs"

ReactRailsUJS

Mounting & Unmounting

Usually,

react-rails

You can also mount & unmount components from

// Mount all components on the page:
ReactRailsUJS.mountComponents()
// Mount components within a selector:
ReactRailsUJS.mountComponents(".my-class")
// Mount components within a specific node:
ReactRailsUJS.mountComponents(specificDOMnode)

// Unmounting works the same way:
ReactRailsUJS.unmountComponents()
ReactRailsUJS.unmountComponents(".my-class")
ReactRailsUJS.unmountComponents(specificDOMnode)

You can use this when the DOM is modified by AJAX calls or modal windows.

Event Handling

ReactRailsUJS

• Turbolinks

• pjax

• jQuery

• Native DOM events

ReactRailsUJS

If you need to re-detect events, you can call

detectEvents

// Remove previous event handlers and add new ones:
ReactRailsUJS.detectEvents()

For example, if

Turbolinks

ReactRailsUJS

If

Turbolinks

import

ReactRailsUJS

// Order is particular. First start Turbolinks:
Turbolinks.start();
// Add Turbolinks to the global namespace:
window.Turbolinks = Turbolinks;
// Remove previous event handlers and add new ones:
ReactRailsUJS.detectEvents();
// (Optional) Clean up global namespace:
delete window.Turbolinks;

getConstructor

Components are loaded with

ReactRailsUJS.getConstructor(className)

• On the asset pipeline, it looks up

  className

  in the global namespace.
• On Webpacker, it

  require

  s files and accesses named exports, as described in Get started with Webpacker.

You can override this function to customize the mapping of name-to-constructor. Server-side rendering also uses this function.

Server-Side Rendering

You can render React components inside your Rails server with

prerender: true

  
Hello, John!

(It will also be mounted by the UJS on page load.)

Server rendering is powered by

ExecJS

• react-rails

  must load your code. By convention, it uses

  server_rendering.js

  , which was created by the install task. This file must include your components and their dependencies (eg, Underscore.js).
• Your code can't reference

  document

  or

  window

  . Prerender processes don't have access to

  document

  or

  window

  , so jQuery and some other libs won't work in this environment :(

ExecJS

mini_racer

Configuration

Server renderers are stored in a pool and reused between requests. Threaded Rubies (eg jRuby) may see a benefit to increasing the pool size beyond the default

0

These are the default configurations:

# config/application.rb
# These are the defaults if you don't specify any yourself
module MyApp
  class Application < Rails::Application
    # Settings for the pool of renderers:
    config.react.server_renderer_pool_size  ||= 1  # ExecJS doesn't allow more than one on MRI
    config.react.server_renderer_timeout    ||= 20 # seconds
    config.react.server_renderer = React::ServerRendering::BundleRenderer
    config.react.server_renderer_options = {
      files: ["server_rendering.js"],       # files to load for prerendering
      replay_console: true,                 # if true, console.* will be replayed client-side
    }
    # Changing files matching these dirs/exts will cause the server renderer to reload:
    config.react.server_renderer_extensions = ["jsx", "js"]
    config.react.server_renderer_directories = ["/app/assets/javascripts", "/app/javascript/"]
  end
end

JavaScript State

Some of ExecJS's backends are stateful (eg, mini_racer, therubyracer). This means that any side-effects of a prerender will affect later renders with that renderer.

To manage state, you have a couple options:

• Make a custom renderer with

  #before_render

  /

  #after_render

  hooks as described below
• Use

  per_request_react_rails_prerenderer

  to manage state for a whole controller action.

To check out a renderer for the duration of a controller action, call the

per_request_react_rails_prerenderer

class PagesController < ApplicationController
  # Use the same React server renderer for the entire request:
  per_request_react_rails_prerenderer
end

Then, you can access the ExecJS context directly with

react_rails_prerenderer.context

def show
  react_rails_prerenderer           # => #<:serverrendering::bundlerenderer>
  react_rails_prerenderer.context   # => #<:context>

Execute arbitrary JavaScript code
self is the global context
  react_rails_prerenderer.context.exec("self.Store.setup()")
  render :show
  react_rails_prerenderer.context.exec("self.Store.teardown()")
end
</:context></:serverrendering::bundlerenderer>

react_rails_prerenderer

Custom Server Renderer

react-rails

config.react.server_renderer

• #initialize(options={})

  , which accepts the hash from

  config.react.server_renderer_options

• #render(component_name, props, prerender_options)

  to return a string of HTML

react-rails

React::ServerRendering::ExecJSRenderer

React::ServerRendering::BundleRenderer

ExecJSRenderer

• #before_render(component_name, props, prerender_options)

  to return a string of JavaScript to execute before calling

  React.render

• #after_render(component_name, props, prerender_options)

  to return a string of JavaScript to execute after calling

  React.render

Any subclass of

ExecJSRenderer

BundleRenderer

console.*

Controller Actions

Components can also be server-rendered directly from a controller action with the custom

component

class TodoController < ApplicationController
  def index
    @todos = Todo.all
    render component: 'TodoList', props: { todos: @todos }, tag: 'span', class: 'todo'
  end
end

You can also provide the "usual"

render

content_type

layout

location

status

yield

data: {remote: true}

Prerendering is set to

true

prerender: false

Component Generator

You can generate a new component file with:

rails g react:component ComponentName prop1:type prop2:type ...

For example,

rails g react:component Post title:string published:bool published_by:instanceOf{Person}

would generate:

var Post = createReactClass({
  propTypes: {
    title: PropTypes.string,
    published: PropTypes.bool,
    publishedBy: PropTypes.instanceOf(Person)
  },

  render: function() {
    return (
      <react.fragment>
        Title: {this.props.title}
        Published: {this.props.published}
        Published By: {this.props.publishedBy}
      </react.fragment>
    );
  }
});

The generator also accepts options:

• --es6

  : use

  class ComponentName extends React.Component

• --coffee

  : use CoffeeScript

Accepted PropTypes are:

• Plain types:

  any

  ,

  array

  ,

  bool

  ,

  element

  ,

  func

  ,

  number

  ,

  object

  ,

  node

  ,

  shape

  ,

  string

• instanceOf

  takes an optional class name in the form of

  instanceOf{className}

  .

• oneOf

  behaves like an enum, and takes an optional list of strings in the form of

  'name:oneOf{one,two,three}'

  .

• oneOfType

  takes an optional list of react and custom types in the form of

  'model:oneOfType{string,number,OtherType}'

  .

Note that the arguments for

oneOf

oneOfType

Use with JBuilder

If you use Jbuilder to pass a JSON string to

react_component

# BAD: returns a stringified array
json.array!(@messages) do |message|
  json.extract! message, :id, :name
  json.url message_url(message, format: :json)
end

GOOD: returns a stringified hash
json.messages(@messages) do |message|
  json.extract! message, :id, :name
  json.url message_url(message, format: :json)
end

Camelize Props

You can configure

camelize_props

MyApp::Application.configure do
  config.react.camelize_props = true # default false
end

Now, Ruby hashes given to

react_component(...)

{ all_todos: @todos, current_status: @status }
# becomes:
{ "allTodos" => @todos, "currentStatus" => @status }

You can also specify this option in

react_component

Upgrading

2.3 to 2.4

Keep your

react_ujs

yarn upgrade

React-Rails 2.4.x uses React 16+ which no longer has React Addons. Therefore the pre-bundled version of react no longer has an addons version, if you need addons still, there is the 2.3.1+ version of the gem that still has addons.

If you need to make changes in your components for the prebundled react, see the migration docs here:

• https://reactjs.org/blog/2016/11/16/react-v15.4.0.html
• https://reactjs.org/blog/2017/04/07/react-v15.5.0.html
• https://reactjs.org/blog/2017/06/13/react-v15.6.0.html

For the vast majority of cases this will get you most of the migration: - global find+replace

React.Prop

Prop

import PropTypes from 'prop-types'

bundle exec rails webpacker:install:react

Common Errors

During installation

1) While using installers.(rails webpacker:install:react && rails webpacker:install) Error:

public/packs/manifest.json. Possible causes:
1. You want to set webpacker.yml value of compile to true for your environment
   unless you are using the `webpack -w` or the webpack-dev-server.
2. webpack has not yet re-run to reflect updates.
3. You have misconfigured Webpacker's config/webpacker.yml file.
4. Your webpack configuration is not creating a manifest.
or
yarn: error: no such option: --dev
ERROR: [Errno 2] No such file or directory: 'add'

yarn install ```

Undefined Set

ExecJS::ProgramError (identifier 'Set' undefined):

(execjs):1

If you see any variation of this issue, see Using TheRubyRacer

Using TheRubyRacer

TheRubyRacer hasn't updated LibV8 (The library that powers Node.js) from v3 in 2 years, any new features are unlikely to work.

LibV8 itself is already beyond version 7 therefore many serverside issues are caused by old JS engines and fixed by using an up to date one such as MiniRacer or TheRubyRhino on JRuby.

HMR

Hot Module Replacement is possible with this gem as it does just pass through to Webpacker. Please open an issue to let us know tips and tricks for it to add to the wiki.

Sample repo that shows HMR working with

react-rails

One caveat is that currently you cannot Server-Side Render along with HMR.

Related Projects

• webpacker-react: Integration of React with Rails utilizing Webpack with Hot Module Replacement (HMR).
• The React on Rails Course A video course which teaches the basics of React and how to get started using it in Rails with

  react-rails

  .
• react_on_rails: Integration of React with Rails utilizing Webpack, Redux, React-Router.
• react-rails-hot-loader Simple live-reloader for

  react-rails

  .
• react-rails-benchmark_renderer adds performance instrumentation to server rendering.
• Ruby Hyperstack: Use Ruby to build reactive user interfaces with React.

Contributing

🎉 Thanks for taking the time to contribute! 🎉

With 5 Million+ downloads of the react-rails Gem and another 2 Million+ downloads of react_ujs on NPM, you're helping the biggest React + Rails community!

By contributing to React-Rails, you agree to abide by the code of conduct.

You can always help by submitting patches or triaging issues, even offering reproduction steps to issues is incredibly helpful!

Please see our Contribution guide for more info.