[![Build Status](https://travis-ci.org/shakacode/react_on_rails.svg?branch=master)](https://travis-ci.org/shakacode/react_on_rails) [![Codeship Status for shakacode/react_on_rails](https://app.codeship.com/projects/cec6c040-971f-0134-488f-0a5146246bd8/status?branch=master)](https://app.codeship.com/projects/187011) [![Dependency Status](https://gemnasium.com/shakacode/react_on_rails.svg)](https://gemnasium.com/shakacode/react_on_rails) [![Gem Version](https://badge.fury.io/rb/react_on_rails.svg)](https://badge.fury.io/rb/react_on_rails) [![npm version](https://badge.fury.io/js/react-on-rails.svg)](https://badge.fury.io/js/react-on-rails) [![Code Climate](https://codeclimate.com/github/shakacode/react_on_rails/badges/gpa.svg)](https://codeclimate.com/github/shakacode/react_on_rails) [![Coverage Status](https://coveralls.io/repos/shakacode/react_on_rails/badge.svg?branch=master&service=github)](https://coveralls.io/github/shakacode/react_on_rails?branch=master) #### The Docs here on `master` refer to 8.0.0-beta.1 including support for Webpacker! 7.0.4 docs are [here](https://github.com/shakacode/react_on_rails/tree/7.0.4). **[VERSION 8.0.0-beta.1](https://rubygems.org/gems/react_on_rails/versions/8.0.0.beta.1)** has shipped with [webpacker_lite](https://github.com/shakacode/webpacker_lite) support! Please try [the 8.0.0-beta.1 beta](https://rubygems.org/gems/react_on_rails/versions/8.0.0.beta.1) and please report issues! **For a complete example of this gem, see our live demo at [www.reactrails.com](http://www.reactrails.com). ([Source Code](https://github.com/shakacode/react-webpack-rails-tutorial))** **Speaking!**: Justin is speaking [GORUCO](http://goruco.com/#speakers) on Saturday, June 24, 2017 in NYC: "Front-End Sadness to Happiness: The React on Rails Story". [Email Justin](mailto:justin@shakacode.com) to give this talk at your local meetup or company. [Subscribe](https://app.mailerlite.com/webforms/landing/l1d9x5) to be notified of local and *online* presentations of this talk. **Aloha from Justin Gordon** ([bio](http://www.railsonmaui.com/about)) and the [ShakaCode](http://www.shakacode.com) Team! We're actively looking for new projects involving React, React-Native, and Rails, including conversion of AngularJs to React. Please [contact me](mailto:justin@shakacode.com) if we could potentially help you in any way. Besides consulting on bigger projects, [ShakaCode](http://www.shakacode.com) is doing ScreenHero plus Slack/Github based [coaching](http://www.shakacode.com/work/shakacode-coaching-plan.pdf) for React on Rails. See our blog post [Can ShakaCode Help You?](https://blog.shakacode.com/can-shakacode-help-you-4a5b1e5a8a63#.jex6tg9w9) for more information. I'm offering a free half-hour project consultation, on anything from React on Rails to any aspect of web application development for both consumer and enterprise products. In addition to React.js and Rails, we're doing React-Native iOS and Android apps! Whether you have a new project or need help on an existing project, feel free to contact me directly at [justin@shakacode.com](mailto:justin@shakacode.com) and thanks in advance for any referrals! Your support keeps this project going! (Want to become a contributor? [Contact us](mailto:contact@shakacode.com) for a Slack room invite and let us know that you want to contribute.) # Community Please [Subscribe](https://app.mailerlite.com/webforms/landing/l1d9x5) to keep in touch with Justin Gordon and [ShakaCode](http://www.shakacode.com/). I intend to send a monthly summary including announcements of new releases of React on Rails and of our latest [blog articles](https://blog.shakacode.com) and tutorials. Subscribers will also have access to **exclusive content**, including tips and examples. [![2017-01-31_14-16-56](https://cloud.githubusercontent.com/assets/1118459/22490211/f7a70418-e7bf-11e6-9bef-b3ccd715dbf8.png)](https://app.mailerlite.com/webforms/landing/l1d9x5) * **Slack Room**: [Contact us](mailto:contact@shakacode.com) for an invite to the ShakaCode Slack room! * **[forum.shakacode.com](https://forum.shakacode.com)**: Post your questions * **[@ShakaCode on Twitter](https://twitter.com/shakacode)** # Testimonials From Joel Hooks, Co-Founder, Chief Nerd at [egghead.io](https://egghead.io/), January 30, 2017: ![2017-01-30_11-33-59](https://cloud.githubusercontent.com/assets/1118459/22443635/b3549fb4-e6e3-11e6-8ea2-6f589dc93ed3.png) For more testimonials, see [Live Projects](PROJECTS.md) and [Kudos](./KUDOS.md). # Articles, Videos, and Podcasts ### Articles * [React on Rails, 2000+ 🌟 Stars](https://medium.com/shakacode/react-on-rails-2000-stars-32ff5cfacfbf#.6gmfb2gpy) * [The React on Rails Doctrine](https://medium.com/@railsonmaui/the-react-on-rails-doctrine-3c59a778c724) ### Videos 1. [egghead.io: Creating a component with React on Rails](https://egghead.io/lessons/react-creating-a-component-with-react-on-rails) 1. [egghead.io: Creating a redux component with React on Rails](https://egghead.io/lessons/react-add-redux-state-management-to-a-react-on-rails-project) 1. [React On Rails Tutorial Series](https://www.youtube.com/playlist?list=PL5VAKH-U1M6dj84BApfUtvBjvF-0-JfEU) 1. [History and Motivation](https://youtu.be/F4oymbUHvoY) 1. [Basic Tutorial Walkthrough](https://youtu.be/_bjScw60FBk) 1. [Code Walkthrough](https://youtu.be/McQ9UM-_ocQ) ### Podcasts * [284 Ruby Rogues: React on Rails with Justin Gordon and Rob Wise](https://devchat.tv/ruby-rogues/284-rr-react-on-rails-with-justin-gordon-and-rob-wise) # NEWS * 2017-04-25: 7.0.0 Shipped! Performance improvements! Please upgrade! Only "breaking" change is that you have to update both the node module and the Ruby gem. * 2017-04-09: 8.0.0 beta work to include webpacker_lite gem has begun. See [#786](https://github.com/shakacode/react_on_rails/issues/786). * *See [NEWS.md](NEWS.md) for more notes over time.* # React on Rails **Project Objective**: To provide an opinionated and optimal framework for integrating Ruby on Rails with modern JavaScript tooling and libraries, including [**Webpack**](http://webpack.github.io/), [**Babel**](https://babeljs.io/), [**React**](https://facebook.github.io/react/), [**Redux**](https://github.com/reactjs/redux), [**React-Router**](https://github.com/reactjs/react-router). This differs significantly from typical Rails architecture. When considering what goes into **react_on_rails**, we ask ourselves, is the functionality related to the intersection of using Rails and modern JavaScript? If so, then the functionality belongs right here. In other cases, we're releasing separate npm packages or Ruby gems. If you are interested in implementing React using traditional Rails architecture, see [react-rails](https://github.com/reactjs/react-rails). React on Rails integrates Facebook's [React](https://github.com/facebook/react) front-end framework with Rails. React v0.14.x and greater is supported, with server rendering. [Redux](https://github.com/reactjs/redux) and [React-Router](https://github.com/reactjs/react-redux) are supported as well, also with server rendering, using either **execJS** or a [Node.js server](https://github.com/shakacode/react_on_rails/blob/master/docs%2Fadditional-reading%2Fnode-server-rendering.md). See the Rails on Maui [blog post](http://www.railsonmaui.com/blog/2014/10/03/integrating-webpack-and-the-es6-transpiler-into-an-existing-rails-project/) that started it all! ## Table of Contents + [Features](#features) + [Why Webpack?](#why-webpack) + [Getting Started](#getting-started) - [Installation Summary](#installation-summary) - [Initializer Configuration: config/initializers/react_on_rails.rb](#initializer-configuration) - [Including your React Component in your Rails Views](#including-your-react-component-in-your-rails-views) - [I18n](#i18n) + [How it Works](#how-it-works) - [Client-Side Rendering vs. Server-Side Rendering](#client-side-rendering-vs-server-side-rendering) - [Building the Bundles](#building-the-bundles) - [Rails Context](#rails-context) - [Globally Exposing Your React Components](#globally-exposing-your-react-components) - [ReactOnRails View Helpers API](#reactonrails-view-helpers-api) - [ReactOnRails JavaScript API](#reactonrails-javascript-api) - [React-Router](#react-router) - [Deployment](#deployment) + [Integration with Node](#integration-with-node) + [Additional Documentation](#additional-documentation) + [Contributing](#contributing) + [License](#license) + [Authors](#authors) + [About ShakaCode](#about-shakacode) --- ## Features Like the [react-rails](https://github.com/reactjs/react-rails) gem, React on Rails is capable of server-side rendering with fragment caching and is compatible with [turbolinks](https://github.com/turbolinks/turbolinks). Unlike react-rails, which depends heavily on sprockets and jquery-ujs, React on Rails uses [webpack](http://webpack.github.io/) and does not depend on jQuery. While the initial setup is slightly more involved, it allows for advanced functionality such as: + [Redux](https://github.com/reactjs/redux) + [Webpack optimization functionality](https://github.com/webpack/docs/wiki/optimization) + [React Router](https://github.com/reactjs/react-router) See the [react-webpack-rails-tutorial](https://github.com/shakacode/react-webpack-rails-tutorial) for an example of a live implementation and code. ## Why Webpack? Webpack is used to generate several JavaScript "bundles" for inclusion in `application.js` or directly in your layout. This usage of webpack fits neatly and simply into the existing Rails sprockets system and you can include React components on a Rails view with a simple helper. Compare this to some alternative approaches for SPAs (Single Page Apps) that utilize Webpack and Rails. They will use a separate node server to distribute web pages, JavaScript assets, CSS, etc., and will still use Rails as an API server. A good example of this is our ShakaCode team member Alex's article [ Universal React with Rails: Part I](https://medium.com/@alexfedoseev/isomorphic-react-with-rails-part-i-440754e82a59). We're definitely not doing that. With react_on_rails, webpack is mainly generating a nice JavaScript file for inclusion into `application.js`. We're going to KISS. And that's all relative given how much there is to get right in an enterprise class web application. ## Upgrade To upgrade existing apps to react on rails 7 see the [Installation Overview](docs/basics/installation-overview.md) ## Getting Started **For more detailed instructions**, see the [React on Rails Basic Tutorial](docs/tutorial.md). 1. Add the following to your Gemfile and `bundle install`. ```ruby gem "react_on_rails", "~> 7" ``` 2. Commit this to git (you cannot run the generator unless you do this or pass the option `--ignore-warnings`). 3. See help for the generator: ```bash rails generate react_on_rails:install --help ``` 4. Run the generator with a simple "Hello World" example (more options below): ```bash rails generate react_on_rails:install ``` 5. Bundle and NPM install. Make sure you are on a recent version of node. Please use at least Node v5. Bundle is for adding execJs. You can remove that if you are sure you will not server render. ```bash bundle && yarn ``` 6. Ensure that you have `foreman` installed: `gem install foreman`. 7. Start your Rails server: ```bash foreman start -f Procfile.dev ``` 8. Visit [localhost:3000/hello_world](http://localhost:3000/hello_world). Note, `foreman` defaults to PORT 5000 unless you set the value of PORT in your environment. For example, you can `export PORT=3000` to use the Rails default port of 3000. For the hello_world example this is already set. ### Installation Overview See the [Installation Overview](docs/basics/installation-overview.md) for a concise set summary of what's in a React on Rails installation. ### Initializer Configuration Configure the `config/initializers/react_on_rails.rb`. You can adjust some necessary settings and defaults. See file [spec/dummy/config/initializers/react_on_rails.rb](https://github.com/shakacode/react_on_rails/tree/master/spec/dummy/config/initializers/react_on_rails.rb) for a detailed example of configuration, including comments on the different values to configure. ### Including your React Component in your Rails Views + *Normal Mode (React component will be rendered on client):* ```erb <%= react_component("HelloWorld", props: @some_props) %> ``` + *Server-Side Rendering (React component is first rendered into HTML on the server):* ```erb <%= react_component("HelloWorld", props: @some_props, prerender: true) %> ``` + The `component_name` parameter is a string matching the name you used to expose your React component globally. So, in the above examples, if you had a React component named "HelloWorld," you would register it with the following lines: ```js import ReactOnRails from 'react-on-rails'; import HelloWorld from './HelloWorld'; ReactOnRails.register({ HelloWorld }); ``` Exposing your component in this way is how React on Rails is able to reference your component from a Rails view. You can expose as many components as you like, as long as their names do not collide. See below for the details of how you expose your components via the react_on_rails webpack configuration. + `@some_props` can be either a hash or JSON string. This is an optional argument assuming you do not need to pass any options (if you want to pass options, such as `prerender: true`, but you do not want to pass any properties, simply pass an empty hash `{}`). This will make the data available in your component: ```ruby # Rails View <%= react_component("HelloWorld", props: { name: "Stranger" }) %> ``` ```javascript // inside your React component this.props.name // "Stranger" ``` ### I18n You can enable the i18n functionality with [react-intl](https://github.com/yahoo/react-intl). React on Rails provides an option for automatic conversions of Rails `*.yml` locale files into `*.js` files for `react-intl`. See the [How to add I18n](docs/basics/i18n.md) for a summary of adding I18n. ## NPM All JavaScript in React On Rails is loaded from npm: [react-on-rails](https://www.npmjs.com/package/react-on-rails). To manually install this (you did not use the generator), assuming you have a standard configuration, run this command: ``` cd client && yarn add react-on-rails ``` That will install the latest version and update your package.json. ## How it Works The generator installs your webpack files in the `client` folder. Foreman uses webpack to compile your code and output the bundled results to `app/assets/webpack`, which are then loaded by sprockets. These generated bundle files have been added to your `.gitignore` for your convenience. Inside your Rails views, you can now use the `react_component` helper method provided by React on Rails. You can pass props directly to the react component helper. You can also initialize a Redux store with view or controller helper `redux_store` so that the store can be shared amongst multiple React components. See the docs for `redux_store` below and scan the code inside of the [/spec/dummy](https://github.com/shakacode/react_on_rails/tree/master/spec/dummy) sample app. ### Client-Side Rendering vs. Server-Side Rendering In most cases, you should use the `prerender: false` (default behavior) with the provided helper method to render the React component from your Rails views. In some cases, such as when SEO is vital, or many users will not have JavaScript enabled, you can enable server-rendering by passing `prerender: true` to your helper, or you can simply change the default in `config/initializers/react_on_rails`. Now the server will interpret your JavaScript using [ExecJS](https://github.com/rails/execjs) and pass the resulting HTML to the client. We recommend using [mini_racer](https://github.com/discourse/mini_racer) as ExecJS's runtime. The generator will automatically add it to your Gemfile for you (once we complete [#501](https://github.com/shakacode/react_on_rails/issues/501)). In the following screenshot you can see the 3 parts of React on Rails rendering: 1. A hidden HTML div that contains the properties of the React component, such as the registered name and any props. A JavaScript function runs after the page loads to convert take this data and build initialize React components. 2. The wrapper div `
` specifies the div where to place the React rendering. It encloses the server-rendered HTML for the React component 3. Additional JavaScript is placed to console log any messages, such as server rendering errors. Note, these server side logs can be configured to only be sent to the server logs. **Note**: * If server rendering is not used (prerender: false), then the major difference is that the HTML rendered for the React component only contains the outer div: `
`. The first specification of the React component is just the same. * The below image is not yet updated for version 7.0.0 which uses a `