V3.0.0 is released with Shakapacker v6 support, including SSR. Please try it out and report any issues. We'll try to address any critical issues ASAP.
For version 2.7 documentation checkout 2.7-stable branch.
React-Rails is a flexible tool to use React with Rails. The benefits:
- Automatically renders React server-side and client-side
- Supports Shakapacker v7
- Supports Sprockets 4.x, 3.x
- Lets you use JSX, ES6, TypeScript, CoffeeScript
ShakaCode offers support for upgrading this gem, and related gems such as Webpacker and using Shakapacker. If interested, contact Justin Gordon, [email protected]. We're also hiring!
Here's a testimonial of how ShakaCode can help, from Florian GΓΆΓler of Blinkist, January 2, 2023:
Hey Justin π
I just wanted to let you know that we today shipped the webpacker to shakapacker upgrades and it all seems to be running smoothly! Thanks again for all your support and your teams work! π
On top of your work, it was now also very easy for me to upgrade Tailwind and include our external node_module based web component library which we were using for our other (more modern) apps already. That work is going to be shipped later this week though as we are polishing the last bits of it. π
Have a great 2023 and maybe we get to work together again later in the year! π
Read the full review here. Here's another review of a Shakapacker migration that led to more work.
- Click to join React + Rails Slack. Then join the channel
#react-rails. - If you are upgrading, you might consider migrating to the react_on_rails gem.
- Source code example utilizing React-Rails: https://github.com/BookOfGreg/react-rails-example-app
- Get started with Shakapacker
- Use with Asset Pipeline
- View Helper
- UJS
- Server-Side Rendering
- Controller Actions
- Component Generator
- Upgrading
- Common Errors
- 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.
Alternatively, get started with Sprockets
- Create a new Rails app:
Prevent installing default javascript dependencies by using
--skip-javascriptoption:
rails new my-app --skip-javascript
cd my-app- Install
shakapacker:
bundle add shakapacker --strict
rails shakapacker:install- Install
reactand some other required npm packages:
yarn add react react-dom @babel/preset-react prop-types \
css-loader style-loader mini-css-extract-plugin css-minimizer-webpack-pluginAlso update the Babel configuration in the package.json file:
"babel": {
"presets": [
- "./node_modules/shakapacker/package/babel/preset.js"
+ "./node_modules/shakapacker/package/babel/preset.js",
+ "@babel/preset-react"
]
},- Install
react-rails:
$ bundle add 'react-rails' --strict
$ rails generate react:installThis gives you:
app/javascript/components/directory for your React componentsReactRailsUJSsetup inapp/javascript/packs/application.jsapp/javascript/packs/server_rendering.jsfor server-side rendering
- Generate your first component:
$ rails g react:component HelloWorld greeting:stringYou can also generate your component in a subdirectory:
$ rails g react:component my_subdirectory/HelloWorld greeting:stringNote: Your component is added to app/javascript/components/ by default.
Note: If your component is in a subdirectory you will append the directory path to your erb component call.
Example:
<%= react_component("my_subdirectory/HelloWorld", { greeting: "Hello from react-rails." }) %><!-- erb: paste this in view -->
<%= react_component("HelloWorld", { greeting: "Hello from react-rails." }) %>- Lets Start the app:
$ rails sOutput: greeting: Hello from react-rails", inspect webpage in your browser to see the change in tag props.
- Run dev server (optional) In order to run dev server with HMR feature you need to parallely run:
$ ./bin/shakapacker-dev-serverNote: On Rails 6 you need to specify webpack-dev-server host. To this end, update config/initializers/content_security_policy.rb and uncomment relevant lines.
The component name tells react-rails where to load the component. For example:
react_component call |
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 inserted into packs/application.js is used to load components. If you want to load components from a different directory, override it by calling ReactRailsUJS.useContext:
var myCustomContext = require.context("custom_components", true)
var ReactRailsUJS = require("react_ujs")
// use `custom_components/` for <%= react_component(...) %> calls
ReactRailsUJS.useContext(myCustomContext)If require fails to find your component, ReactRailsUJS falls back to the global namespace, described in Use with Asset Pipeline.
In some cases, having multiple require.context entries may be desired. Examples of this include:
- Refactoring a typical Rails application into a Rails API with an (eventually) separate Single Page Application (SPA). For this use case, one can add a separate pack in addition to the typical
applicationone. React components can be shared between the packs but the new pack can use a minimal Rails view layout, different default styling, etc. - In a larger application, you might find it helpful to split your JavaScript by routes/controllers to avoid serving unused components and improve your site performance by keeping bundles smaller. For example, you might have separate bundles for homepage, search, and checkout routes. In that scenario, you can add an array of
require.contextcomponent directory paths viauseContextstoserver_rendering.js, to allow for Server-Side Rendering across your application:
// server_rendering.js
var homepageRequireContext = require.context('homepage', true);
var searchRequireContext = require.context('search', true);
var checkoutRequireContext = require.context('checkout', true);
var ReactRailsUJS = require('react_ujs');
ReactRailsUJS.useContexts([
homepageRequireContext,
searchRequireContext,
checkoutRequireContext
]);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.
| Component File Name | react_component call |
|---|---|
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 |
Has to be renamed to SampleComponent.jsx, then use react_component("SampleComponent") |
yarn add typescript @babel/preset-typescriptBabel wonβt perform any type-checking on TypeScript code. To optionally use type-checking run:
yarn add fork-ts-checker-webpack-pluginAdd tsconfig.json with the following content:
{
"compilerOptions": {
"declaration": false,
"emitDecoratorMetadata": true,
"experimentalDecorators": true,
"lib": ["es6", "dom"],
"module": "es6",
"moduleResolution": "node",
"sourceMap": true,
"target": "es5",
"jsx": "react",
"noEmit": true
},
"exclude": ["**/*.spec.ts", "node_modules", "vendor", "public"],
"compileOnSave": false
}Then modify the webpack config to use it as a plugin:
// config/webpack/webpack.config.js
const { webpackConfig, merge } = require("shakapacker");
const ForkTSCheckerWebpackPlugin = require("fork-ts-checker-webpack-plugin");
module.exports = merge(webpackConfig, {
plugins: [new ForkTSCheckerWebpackPlugin()],
});Doing this will allow React-Rails to support the .tsx extension. Additionally, it is recommended to add ts and tsx to the server_renderer_extensions in your application configuration:
config.react.server_renderer_extensions = ["jsx", "js", "tsx", "ts"]You can use assert_react_component to test component render:
<!-- app/views/welcome/index.html.erb -->
<%= react_component("HelloWorld", { greeting: "Hello from react-rails.", info: { name: "react-rails" } }, { class: "hello-world" }) %>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
endreact-rails provides a pre-bundled React.js & a UJS driver to the Rails asset pipeline. Get started by adding the react-rails gem:
gem 'react-rails'And then install the react generator:
$ rails g react:install
Then restart your development server.
This will:
- add some
//= requires toapplication.js - add a
components/directory for React components - add
server_rendering.jsfor server-side rendering
Now, you can create React components in .jsx files:
// app/assets/javascripts/components/post.jsx
window.Post = createReactClass({
render: function() {
return <h1>{this.props.title}</h1>
}
})
// or, equivalent:
class Post extends React.Component {
render() {
return <h1>{this.props.title}</h1>
}
}Then, you can render those components in views:
<%= react_component("Post", {title: "Hello World"}) %>Components must be accessible from the top level, but they may be namespaced, for example:
<%= react_component("Comments.NewForm", {post_id: @post.id}) %>
<!-- looks for `window.Comments.NewForm` -->react-rails uses a transformer class to transform JSX in the asset pipeline. The transformer is initialized once, at boot. You can provide a custom transformer to config.react.jsx_transformer_class. The transformer must implement:
#initialize(options), where options is the value passed toconfig.react.jsx_transform_options#transform(code_string)to return a string of transformed code
react-rails provides two transformers, React::JSX::BabelTransformer (which uses ruby-babel-transpiler) and React::JSX::JSXTransformer (which uses the deprecated JSXTransformer.js).
To supply additional transform plugins to your JSX Transformer, assign them to config.react.jsx_transform_options
react-rails uses the Babel version of the babel-source gem.
For example, to use babel-plugin-transform-class-properties :
config.react.jsx_transform_options = {
optional: ['es7.classProperties']
}
//= require react brings React into your project.
By default, React's [development version] is provided to Rails.env.development. You can override the React build with a config:
# 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
endBe 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 version. In some edge cases you may need to bust the sprockets cache with rake tmp:clear
react-rails includes a view helper and an unobtrusive JavaScript driver which work together to put React components on the page.
The view helper (react_component) puts a div on the page with the requested component class & props. For example:
<%= react_component('HelloMessage', name: 'John') %>
<!-- becomes: -->
<div data-react-class="HelloMessage" data-react-props="{"name":"John"}"></div>On page load, the react_ujs driver will scan the page and mount components using data-react-class
and data-react-props.
The view helper's signature is:
react_component(component_class_name, props={}, html_options={})component_class_nameis a string which identifies a component. See getConstructor for details.propsis either:- an object that responds to
#to_json; or - an already-stringified JSON object (see JBuilder note below).
- an object that responds to
html_optionsmay include:tag:to use an element other than adivto embeddata-react-classanddata-react-props.prerender: trueto render the component on the server.camelize_propsto transform a props hash**otherAny other arguments (egclass:,id:) are passed through tocontent_tag.
react-rails uses a "helper implementation" class to generate the output of the react_component helper. The helper is initialized once per request and used for each react_component call during that request. You can provide a custom helper class to config.react.view_helper_implementation. The class must implement:
#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 provides one implementation, React::Rails::ComponentMount.
react-rails's JavaScript is available as "react_ujs" in the asset pipeline or from NPM. It attaches itself to the window as ReactRailsUJS.
Usually, react-rails mounts & unmounts components automatically as described in Event Handling below.
You can also mount & unmount components from <%= react_component(...) %> tags using UJS:
// 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.
ReactRailsUJS checks for various libraries to support their page change events:
TurbolinkspjaxjQuery- Native DOM events
ReactRailsUJS will automatically mount components on <%= react_component(...) %> tags and unmount them when appropriate.
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 is loaded after ReactRailsUJS, you'll need to call this again. This function removes previous handlers before adding new ones, so it's safe to call as often as needed.
If Turbolinks is imported via Shakapacker (and thus not available globally), ReactRailsUJS will be unable to locate it. To fix this, you can temporarily add it to the global namespace:
// 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;Components are loaded with ReactRailsUJS.getConstructor(className). This function has two default implementations, depending on if you're using the asset pipeline or Shakapacker:
- On the asset pipeline, it looks up
classNamein the global namespace (ReactUJS.constructorFromGlobal). - On Shakapacker, it
requires files and accesses named exports, as described in Get started with Shakapacker, falling back to the global namespace (ReactUJS.constructorFromRequireContextWithGlobalFallback).
You can override this function to customize the mapping of name-to-constructor. Server-side rendering also uses this function.
For example, the fallback behavior of
ReactUJS.constructorFromRequireContextWithGlobalFallback can sometimes make
server-side rendering errors hard to debug as it will swallow the original error
(more info
here).
ReactUJS.constructorFromRequireContext is provided for this reason. You can
use it like so:
// Replaces calls to `ReactUJS.useContext`
ReactUJS.getConstructor = ReactUJS.constructorFromRequireContext(require.context('components', true));You can render React components inside your Rails server with prerender: true:
<%= react_component('HelloMessage', {name: 'John'}, {prerender: true}) %>
<!-- becomes: -->
<div data-react-class="HelloMessage" data-react-props="{"name":"John"}">
<h1>Hello, John!</h1>
</div>(It will also be mounted by the UJS on page load.)
Server rendering is powered by ExecJS and subject to some requirements:
react-railsmust load your code. By convention, it usesserver_rendering.js, which was created by the install task. This file must include your components and their dependencies (eg, Underscore.js).- Requires separate compilations for server & client bundles (see Webpack config)
- Your code can't reference
documentorwindow. Prerender processes don't have access todocumentorwindow, so jQuery and some other libs won't work in this environment :(
ExecJS supports many backends. CRuby users will get the best performance from mini_racer.
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
endSome 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_renderhooks as described below - Use
per_request_react_rails_prerendererto 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 helper in the controller class:
class PagesController < ApplicationController
# Use the same React server renderer for the entire request:
per_request_react_rails_prerenderer
endThen, you can access the ExecJS context directly with react_rails_prerenderer.context:
def show
react_rails_prerenderer # => #<React::ServerRendering::BundleRenderer>
react_rails_prerenderer.context # => #<ExecJS::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()")
endreact_rails_prerenderer may also be accessed in before- or after-actions.
react-rails depends on a renderer class for rendering components on the server. You can provide a custom renderer class to config.react.server_renderer. The class must implement:
#initialize(options={}), which accepts the hash fromconfig.react.server_renderer_options#render(component_name, props, prerender_options)to return a string of HTML
react-rails provides two renderer classes: React::ServerRendering::ExecJSRenderer and React::ServerRendering::BundleRenderer.
ExecJSRenderer offers two other points for extension:
#before_render(component_name, props, prerender_options)to return a string of JavaScript to execute before callingReact.render#after_render(component_name, props, prerender_options)to return a string of JavaScript to execute after callingReact.render
Any subclass of ExecJSRenderer may use those hooks (for example, BundleRenderer uses them to handle console.* on the server).
Components can also be server-rendered directly from a controller action with the custom component renderer. For example:
class TodoController < ApplicationController
def index
@todos = Todo.all
render component: 'TodoList', props: { todos: @todos }, tag: 'span', class: 'todo'
end
endYou can also provide the "usual" render arguments: content_type, layout, location and status. By default, your current layout will be used and the component, rather than a view, will be rendered in place of yield. Custom data-* attributes can be passed like data: {remote: true}.
Prerendering is set to true by default, but can be turned off with prerender: false.
You can generate a new component file with:
rails g react:component ComponentName prop1:type prop2:type ... [options]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: generates a function component--coffee: use CoffeeScript
For example,
rails g react:component ButtonComponent title:string --es6would generate:
import React from "react"
import PropTypes from "prop-types"
function ButtonComponent(props) {
return (
<React.Fragment>
Title: {this.props.title}
</React.Fragment>
);
}
ButtonComponent.propTypes = {
title: PropTypes.string
};
export default ButtonComponentNote: In a Shakapacker project, es6 template is the default template in the generator.
Accepted PropTypes are:
- Plain types:
any,array,bool,element,func,number,object,node,shape,string instanceOftakes an optional class name in the form ofinstanceOf{className}.oneOfbehaves like an enum, and takes an optional list of strings in the form of'name:oneOf{one,two,three}'.oneOfTypetakes an optional list of react and custom types in the form of'model:oneOfType{string,number,OtherType}'.
Note that the arguments for oneOf and oneOfType must be enclosed in single quotes
to prevent your terminal from expanding them into an argument list.
If you use Jbuilder to pass a JSON string to react_component, make sure your JSON is a stringified hash,
not an array. This is not the Rails default -- you should add the root node yourself. For example:
# 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)
endYou can configure camelize_props option:
MyApp::Application.configure do
config.react.camelize_props = true # default false
endNow, Ruby hashes given to react_component(...) as props will have their keys transformed from underscore- to camel-case, for example:
{ all_todos: @todos, current_status: @status }
# becomes:
{ "allTodos" => @todos, "currentStatus" => @status }You can also specify this option in react_component:
<%= react_component('HelloMessage', {name: 'John'}, {camelize_props: true}) %>To make simple changes to Component templates, copy the respective template file to your Rails project at lib/templates/react/component/template_filename.
For example, to change the ES6 Component template, copy it to lib/templates/react/component/component.es6.jsx and modify it.
- Keep your
react_ujsup to date:yarn upgrade - Drop support for Webpacker: Before any ReactRails upgrade, make sure upgrading from Webpacker to Shakapacker 7. For more information check out Shakapacker
- SSR: ReactRails 3.x requires separate compilations for server & client bundles. See Webpack config directory in the dummy app to addapt the new implementation.
Keep your react_ujs up to date, 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 - add
import PropTypes from 'prop-types'(Webpacker only) - re-run
bundle exec rails webpacker:install:reactto update npm packages (Webpacker only)
You may see a warning like this when building a Webpack bundle using any version of React below 18. This warning can be safely suppressed in your Webpack configuration. The following is an example of this suppression in config/webpack/webpack.config.js:
- const { webpackConfig } = require('shakapacker')
+ const { webpackConfig, merge } = require('shakapacker')
+const ignoreWarningsConfig = {
+ ignoreWarnings: [/Module not found: Error: Can't resolve 'react-dom\/client'/],
+};
- module.exports = webpackConfig
+ module.exports = merge({}, webpackConfig, ignoreWarningsConfig)ExecJS::ProgramError (identifier 'Set' undefined):
(execjs):1
If you see any variation of this issue, see 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.
Check out Enabling Hot Module Replacement (HMR) in Shakapacker documentation.
One caveat is that currently you cannot Server-Side Render along with HMR.
- 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.
π 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!
The following companies support the development of this and other open-source projects maintained by ShakaCode by providing licenses to the ShakaCode team. ShakaCode stands by the usefulness of these products!
Please see our Contribution guide for more info.