[![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) *If this projects helps you, please give us a star!* [The ShakaCode team has availability to help your project](http://www.shakacode.com/work). If your team might need my help, please [email me](mailto:justin@shakacode.com) for a free half-hour project consultation, on anything from React on Rails to any aspect of web or mobile application development for both consumer and enterprise products. # React on Rails v10 is based on Webpacker 3.0! * See the article [Introducing React on Rails v9 with Webpacker Support](https://blog.shakacode.com/introducing-react-on-rails-v9-with-webpacker-support-f2584c6c8fa4) for an overview of the integration of React on Rails with Webpacker. * [Video of running the v9 installer with Webpacker v3](https://youtu.be/M0WUM_XPaII). * See the updated [Tutorial](https://github.com/shakacode/react_on_rails/blob/master/docs/tutorial.md). * See the [CHANGELOG.md](https://github.com/shakacode/react_on_rails/blob/master/CHANGELOG.md) for migration instructions. ---- Given that Webpacker already provides React integration, why would you add React on Rails? Additional features of React on Rails include: 1. Server rendering, often for SEO optimization. 2. Easy passing of props directly from your Rails view to your React components rather than having your Rails view load and then make a separate request to your API. 3. Redux and React-Router integration 4. Localization support 5. Rspec test helpers to ensure your Webpack bundles are ready for tests ---- ## Steps to a New App with rails/webpacker v3 plus latest React on Rails: First be sure to run `rails -v` and check that you are using Rails 5.1.3 or above. If you are using an older version of Rails, you'll need to install webpacker with React per the instructions [here](https://github.com/rails/webpacker). ### Basic installation for a new Rails App *See below for steps on an existing Rails app* 1. New Rails app: `rails new my-app --webpack=react`. `cd` into the directory. 2. Add gem version: `gem 'react_on_rails', '10.0.2' # prefer exact gem version to match npm version` 3. Run the generator: `rails generate react_on_rails:install` 4. Start the app: `rails s` 5. Visit http://localhost:3000/hello_world ### Turn on server rendering *The rails/wepbacker default setup does not work with hot or live reloading, yet, per [Webpacker issue #842](https://github.com/rails/webpacker/issues/842). If you want the combination of both server rendering and hot reloading during development, you will need to a custom webpack setup as shown [here](https://github.com/shakacode/react-webpack-rails-tutorial/blob/master/client/webpack.client.rails.hot.config.js)* 1. Edit `app/views/hello_world/index.html.erb` and set `prerender` to `true`. 2. Refresh the page. This is the line where you turn server rendering on by setting prerender to true: ``` <%= react_component("HelloWorld", props: @hello_world_props, prerender: false) %> ``` --------------- ## Thank you from Justin Gordon and [ShakaCode](http://www.shakacode.com) Thank you for considering using [React on Rails](https://github.com/shakacode/react_on_rails). * **Video:** [Front-End Sadness to Happiness: The React on Rails Story](https://www.youtube.com/watch?v=SGkTvKRPYrk): History, motivations, philosophy, and overview. * [Front-End Sadness to Happiness: The React on Rails Story at GORUCO 2017](https://blog.shakacode.com/front-end-sadness-to-happiness-the-react-on-rails-story-at-goruco-2017-d63b8fd26ca4) We at [ShakaCode](http://www.shakacode.com) are a small, boutique, remote-first application development company. We fund this project by: * Providing priority support and training for anything related to React + Webpack + Rails in our [Pro Support program](http://www.shakacode.com/work/shakacode-pro-support.pdf). * Building custom web and mobile (React Native) applications. We typically work with a technical founder or CTO and instantly provide a full development team including designers. * Migrating **Angular** + Rails to React + Rails. You can see an example of React on Rails and our work converting Angular to React on Rails at [egghead.io](https://egghead.io/browse/frameworks). * Augmenting your team to get your product completed more efficiently and quickly. My article "[Why Hire ShakaCode?](https://blog.shakacode.com/can-shakacode-help-you-4a5b1e5a8a63#.jex6tg9w9)" provides additional details about our projects. If any of this resonates with you, please email me, [justin@shakacode.com](mailto:justin@shakacode.com). I offer a free half-hour project consultation, on anything from React on Rails to any aspect of web or mobile application development for both consumer and enterprise products. We are **[currently looking to hire](http://www.shakacode.com/about/#work-with-us)** like-minded developers that wish to work on our projects, including [Hawaii Chee](https://www.hawaiichee.com). I appreciate your attention and sharing of these offerings with anybody that we can help. Your support allows me to bring you and your team [front-end happiness in the Rails world](https://www.youtube.com/watch?v=SGkTvKRPYrk). Aloha and best wishes from the ShakaCode team! ------ # Community Please [**click to 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 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! Let us know if you want to contribute. * **[forum.shakacode.com](https://forum.shakacode.com)**: Post your questions * **[@ShakaCode on Twitter](https://twitter.com/shakacode)** * For a live, [open source](https://github.com/shakacode/react-webpack-rails-tutorial), example of this gem, see [www.reactrails.com](http://www.reactrails.com). ------ # 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 * [Front-End Sadness to Happiness: The React on Rails Story at GORUCO 2017](https://blog.shakacode.com/front-end-sadness-to-happiness-the-react-on-rails-story-at-goruco-2017-d63b8fd26ca4) * [Webpacker Lite: Why Fork Webpacker?](https://blog.shakacode.com/webpacker-lite-why-fork-webpacker-f0a7707fac92) * [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. [GORUCO 2017: Front-End Sadness to Happiness: The React on Rails Story by Justin Gordon](https://www.youtube.com/watch?v=SGkTvKRPYrk) 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 * 2018-02-27: **Version 10.1.2** Supports the React API for ReactDOM.hydrate. * 2017-09-06: **VERSION 9.0.0 shipped!** This version depends on Webpacker directly. See the [CHANGELOG.md](https://github.com/shakacode/react_on_rails/blob/master/CHANGELOG.md) for migration instructions. * The Docs here on `master` refer to 9.x including support for [rails/webpacker](https://github.com/rails/webpacker). *Use the [7.0.4 docs](https://github.com/shakacode/react_on_rails/tree/7.0.4) to refer to the older asset pipeline way.* * *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 React via the [**Webpacker**](https://github.com/rails/webpacker) gem. 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 **execJS**. ## Table of Contents + [Features](#features) + [Why Webpack?](#why-webpack) + [rails/webpacker or custom setup for Webpack?](#webpack-configuration-custom-setup-for-webpack-or-railswebpacker) + [Getting Started with an existing Rails app](#getting-started-with-an-existing-rails-app) - [Installation Overview](#installation-overview) - [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) - [Convert rails-5 API only app to rails app](#convert-rails-5-api-only-app-to-rails-app) - [NPM](#npm) - [Webpacker Configuration](#webpacker-configuration) + [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 and Generator Functions](#rails-context-and-generator-functions) - [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.js for Server Rendering](#integration-with-nodejs-for-server-rendering) + [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). 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 JavaScript and CSS "bundles" directly to your `/public` directory. [webpacker](https://github.com/rails/webpacker) provides view helpers to access the Webpack generated (and fingerprinted) JS and CSS. These files totally skip the Rails asset pipeline. You are responsible for properly processing your Webpack output via the Webpack config files. This usage of webpack fits neatly and simply into existing Rails apps. 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). ## Webpack Configuration: custom setup for Webpack or rails/webpacker? Version 9 of React on Rails added support for the rails/webpacker view helpers so that Webpack produced assets would no longer pass through the Rails asset pipeline. As part of this change, React on Rails added a configuration option to support customization of the node_modules directory. This allowed React on Rails to support the rails/webpacker configuration of the Webpack configuration. A key decision in your use React on Rails is whether you go with the rails/webpacker default setup or the traditional React on Rails setup of putting all your client side files under the `/client` directory. While there are technically 2 independent choices involved, the directory structure and the mechanism of Webpack configuration, for simplicity sake we'll assume that these choices go together. ### Traditional React on Rails using the /client directory Until version 9, all React on Rails apps used the `/client` directory for configuring React on Rails in terms of the configuration of Webpack and location of your JavaScript and Webpack files, including the node_modules directory. Version 9 changed the default to `/` for the `node_modules` location using this value in `config/initializers/react_on_rails.rb`: `config.node_modules_location`. The [ShakaCode Team](http://www.shakacode.com) _recommends_ this approach for projects beyond the simplest cases as it provides the greatest transparency in your webpack and overall client-side setup. The *big advantage* to this is that almost everything within the `/client` directory will apply if you wish to convert your client-side code to a pure Single Page Application that runs without Rails. This allows you to google for how to do something with Webpack configuration and what applies to a non-Rails app will apply just as well to a React on Rails app. The two best examples of this patten are the [react-webpack-rails-tutorial](https://github.com/shakacode/react-webpack-rails-tutorial) and the integration test example in [spec/dummy](https://github.com/shakacode/react_on_rails/tree/master/spec/dummy). In this case, you don't need to understand the nuances of customization of your Wepback config via the [Webpacker mechanism](https://github.com/rails/webpacker/blob/master/docs/webpack.md). ### rails/webpacker Setup Typical rails/webpacker apps have a standard directory structure as documented [here](https://github.com/rails/webpacker/blob/master/docs/folder-structure.md). If you follow the steps in the the [basic tutorial](https://github.com/shakacode/react_on_rails/blob/master/docs/tutorial.md), you will see this pattern in action. In order to customize the Webpack configuration, you need to consult with the [rails/webpacker Webpack configuration](https://github.com/rails/webpacker/blob/master/docs/webpack.md). Version 9 made this the default for generated apps for 2 reasons: 1. It's less code to generate and thus less to explain. 2. `rails/webpacker` might be viewed as a convention in the Rails community. The *advantage* of this is that there is very little code needed to get started and you don't need to understand really anything about Webpack customization. The *big disadvantage* to this is that you will need to learn the ins and outs of the [rails/webpacker way to customize Webpack]([Webpacker mechanism](https://github.com/rails/webpacker/blob/master/docs/webpack.md)) (not the plain [Webpack way](https://webpack.js.org/)) if you wish to beyond the basic setup, and this sort of knowledge is not going to be particularly applicable if you eventually want to convert your client-side app to a pure Single Page Application that runs without rails. Overall, consider carefully if you prefer the `rails/webpacker` directory structure and Webpack configuration, over the placement of all client side files within the `/client` directory along with conventional Webpack configuration. See [Issue 982: Tutorial Generating Correct Project Structure?](https://github.com/shakacode/react_on_rails/issues/982) to discuss this issue. ## Upgrade To upgrade existing apps to React on Rails 8 see the [Installation Overview](docs/basics/installation-overview.md) ## Getting Started with an existing Rails app **For more detailed instructions on a fresh Rails app**, see the [React on Rails Basic Tutorial](docs/tutorial.md). **If you have rails-5 API only project**, Then [convert rails-5 API only app to rails app](#convert-rails-5-api-only-app-to-rails-app) before [getting started](#getting-started-with-an-existing-rails-app). 1. Add the following to your Gemfile and `bundle install`. We recommend fixing the version of React on Rails, as you will need to keep the exact version in sync with the version in your `client/package.json` file. ```ruby gem "react_on_rails", "10.0.0" gem "webpacker", "~> 3.0" ``` 2. Run the following 2 commands to install Webpacker with React: ``` bundle exec rails webpacker:install bundle exec rails webpacker:install:react ``` 2. Commit this to git (or else you cannot run the generator unless you 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. 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. ### Convert rails-5 API only app to rails app 1. Go to the directory where you created your app ``` rails new your-current-app-name ``` Rails will start creating the app and will skip the files you have already created. If there is some conflict then it will stop and you need to resolve it manually. be careful at this step as it might replace you current code in conflicted files. 2. Resolve conflicts ``` 1. Press "d" to see the difference 2. If it is only adding lines then press "y" to continue 3. If it is removeing some of your code then press "n" and add all additions manually ``` 3. Run `bundle install` and follow [Getting started](#getting-started-with-an-existing-rails-app) ### 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 (assuming you are in the directory where you have your `node_modules`): ```bash yarn add react-on-rails ``` That will install the latest version and update your package.json. ### Webpacker Configuration React on Rails users should set configuration value `compile` to false, as React on Rails handles compilation for test and production environments. ## 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 contains the properties of the React component, such as the registered name and any props. A JavaScript function runs after the page loads to 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 only to 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 `