react_on_rails 11.0.5 → 13.4.0

data/Rakefile

@@ -3,9 +3,7 @@
 # Rake will automatically load any *.rake files inside of the "rakelib" folder
 # See rakelib/
 
-require_relative "./spec/react_on_rails/support/rails32_helper"
-
-tasks = %w[run_rspec lint]
+tasks = %w[lint run_rspec]
 prepare_for_ci = %w[node_package dummy_apps]
 
 if ENV["USE_COVERALLS"] == "TRUE"
@@ -14,11 +12,6 @@ if ENV["USE_COVERALLS"] == "TRUE"
   tasks << "coveralls:push"
 end
 
-if using_rails32?
-  tasks = %w[run_rspec:gem_rails32 run_rspec:dummy_no_webpacker]
-  prepare_for_ci = %w[node_package dummy_apps:dummy_no_webpacker]
-end
-
 desc "Run all tests and linting"
 task default: tasks
 

data/SUMMARY.md

@@ -1,50 +1,72 @@
-# Table of Content
+# Table of Contents
 
-### **Rails**
-  + [Rails Assets](./docs/additional-reading/rails-assets.md)
+Doccumentation for React on Rails has moved!
+
+Here is the new link:
+
+**[React on Rails Documentation Link](https://www.shakacode.com/react-on-rails/docs/)**
+
+-----
+
+## **OLD DOCS BELOW**
++ [Home](./README.md)
+
+## **Basics**
+  + [React on Rails Basic Installation Tutorial](./docs/tutorial.md)
+  + [Webpack Configuration](./docs/guides/webpack-configuration.md)
+  + [How React on Rails Works](docs/outdated/how-react-on-rails-works.md)
+  + [Client vs. Server Rendering](./docs/guides/client-vs-server-rendering.md)
+  + [React Server Rendering](./docs/guides/react-server-rendering.md)
+  + [Render-Functions and the RailsContext](docs/guides/render-functions-and-railscontext.md)
+  + [Caching and Performance: React on Rails Pro](https://github.com/shakacode/react_on_rails/wiki).
+  + [Deployment](docs/guides/deployment.md).
+  + [React on Rails Internationalization (I18n, localization)](docs/guides/i18n.md)
+  + [RSpec Test Helpers Configuration](docs/guides/rspec-configuration.md)
+  + [Minitest Configuration](docs/guides/minitest-configuration.md)
+  + [Upgrading React on Rails](docs/guides/upgrading-react-on-rails.md)
+  
+## **API**
+  - [View Helpers API](./docs/api/view-helpers-api.md)
+  - [JavaScript API](./docs/api/javascript-api.md)
+  - [Redux Store API](./docs/api/redux-store-api.md)
+
+## **Additional Details**
+  + [Migration from react-rails](./docs/guides/migrating-from-react-rails.md)
+  + [Generator Details](docs/guides/generator-details.md)
+  + [Updating Dependencies](./docs/additional-reading/updating-dependencies.md)
+  + [Manual Installation Overview](docs/outdated/manual-installation-overview.md)
+  + [Upgrading from rails/webpacker v3 to v4](docs/additional-reading/upgrade-webpacker-v3-to-v4.md)
+  + [Recommended Project Structure](docs/additional-reading/recommended-project-structure.md)
+  
+## **Rails**
   + [Rails Engine Integration](./docs/additional-reading/rails-engine-integration.md)
   + [Rails View Rendering from Inline JavaScript](./docs/additional-reading/rails_view_rendering_from_inline_javascript.md)
-  + [RSpec Configuration](./docs/additional-reading/rspec-configuration.md)
   + [Turbolinks](./docs/additional-reading/turbolinks.md)
-  + [React on Rails Internationalization (I18n)](https://github.com/shakacode/react_on_rails/blob/master/docs/basics/i18n.md)
+  + [Converting a Rails 5 API only app to a Rails app](./docs/additional-reading/convert-rails-5-api-only-app.md)
 
-### **Javascript**
+## **Javascript**
   + [Node Dependencies, NPM, and Yarn](./docs/additional-reading/node-dependencies-and-npm.md)
-  + [Babel](./docs/additional-reading/babel.md)
   + [React Router](./docs/additional-reading/react-router.md)
   + [React & Redux](./docs/additional-reading/react-and-redux.md)
-  + [Webpack](./docs/additional-reading/webpack.md)
-  + [Webpack Configuration](./docs/additional-reading/webpack.md)
-  + [Webpack Cookbook](https://christianalfoni.github.io/react-webpack-cookbook/index.html)
-  + [Developing with the Webpack Dev Server](docs/additional-reading/webpack-dev-server.md)
-  + [Node Server Rendering](./docs/additional-reading/node-server-rendering.md)
+  + [Webpack Tips](./docs/additional-reading/webpack.md)
   + [Server Rendering Tips](./docs/additional-reading/server-rendering-tips.md)
-  + [Code Splitting](./docs/additional-reading/code-splitting.md)
+  + [Code Splitting](docs/outdated/code-splitting.md)
   + [AngularJS Integration and Migration to React on Rails](./docs/additional-reading/angular-js-integration-migration.md)
-  + [Webpack, the Asset Pipeline, and Using Assets w/ React](./docs/additional-reading/rails-assets-relative-paths.md)
 
-### **Development**
-  + [React on Rails Basic Installation Tutorial](./docs/tutorial.md)
-  + [Installation Overview](./docs/basics/installation-overview.md)
-  + [Migration from react-rails](./docs/basics/migrating-from-react-rails.md)
-  + [Recommended Project Structure](./docs/additional-reading/recommended-project-structure.md)
-  + [Generator Tips](./docs/basics/generator.md)
-  + [Hot Reloading of Assets For Rails Development](./docs/additional-reading/hot-reloading-rails-development.md)
-  + [Heroku Deployment](./docs/additional-reading/heroku-deployment.md)
+## **Deployment**
+  + [Heroku Deployment](docs/guides/heroku-deployment.md)
   + [Elastic Beanstalk Deployment](./docs/additional-reading/elastic-beanstalk.md)
-  + [Updating Dependencies](./docs/additional-reading/updating-dependencies.md)
 
-### **API**
-  + [JavaScript API](./docs/api/javascript-api.md)
-  + [Ruby API](./docs/api/ruby-api.md)
-  + [Setting up Hot Reloading during Rails Development, API docs](./docs/api/ruby-api-hot-reload-view-helpers.md)
+## Outdated Non-Webpack Docs
+  + [Developing with the Webpack Dev Server](./docs/additional-reading/webpack-dev-server.md)
+  + [Webpack, the Asset Pipeline, and Using Assets w/ React](./docs/outdated/rails-assets-relative-paths.md)
 
-### **[CONTRIBUTING](CONTRIBUTING.md)**
+## **[CONTRIBUTING](CONTRIBUTING.md)**
   + [Generator Testing](./docs/contributor-info/generator-testing.md)
   + [Linting](./docs/contributor-info/linters.md)
   + [Releasing](./docs/contributor-info/releasing.md)
 
-### **Misc**
+## **Misc**
   + [Tips](./docs/additional-reading/tips.md)
   + [Changelog](./CHANGELOG.md)
   + [Projects](./PROJECTS.md)

data/book.json

@@ -7,12 +7,12 @@
       "url": "https://github.com/shakacode/react_on_rails/"
     },
     "sharing": {
-      "facebook":   true,
-      "twitter":    true,
-      "google":     true,
-      "weibo":      true,
+      "facebook": true,
+      "twitter": true,
+      "google": true,
+      "weibo": true,
       "instapaper": true,
-      "vk":         true
+      "vk": true
     }
   }
 }

data/docs/{basics/generator.md → additional-details/generator-details.md}

@@ -1,7 +1,4 @@
-- [Generator](#generator)
-  - [Understanding the Organization of the Generated Client Code](#understanding-the-organization-of-the-generated-client-code)
-  - [Redux](#redux)
-  - [Using Images and Fonts](#using-images-and-fonts)
+# Generator Details
 
 The `react_on_rails:install` generator combined with the example pull requests of generator runs will get you up and running efficiently. There's a fair bit of setup with integrating Webpack with Rails. Defaults for options are such that the default is for the flag to be off. For example, the default for `-R` is that `redux` is off, and the default of `-b` is that `skip-bootstrap` is off.
 
@@ -38,16 +35,12 @@ can pass the redux option if you'd like to have redux setup for you automaticall
 Then you may run
 
     `rails s`
-
-More Details:
-
-    `https://github.com/shakacode/react_on_rails/blob/master/docs/basics/generator.md`
 ```
 
-Another good option is to create a simple test app per the [Tutorial](../tutorial.md).
+Another good option is to create a simple test app per the [Tutorial](https://www.shakacode.com/react-on-rails/docs/guides/tutorial/).
 
-### Understanding the Organization of the Generated Client Code
-The generated client code follows our organization scheme. Each unique set of functionality, is given its own folder inside of `client/app/bundles`. This encourages for modularity of *domains*.
+# Understanding the Organization of the Generated Client Code
+The generated client code follows our organization scheme. Each unique set of functionality, is given its own folder inside of `app/javascript/app/bundles`. Note, the recommended for bigger projects is `client/app/bundles`. This encourages for modularity of *domains*.
 
 Inside of the generated "HelloWorld" domain you will find the following folders:
 
@@ -57,8 +50,7 @@ Inside of the generated "HelloWorld" domain you will find the following folders:
 
 You may also notice the `app/lib` folder. This is for any code that is common between bundles and therefore needs to be shared (for example, middleware).
 
-### Redux
+## Redux
 If you have used the `--redux` generator option, you will notice the familiar additional redux folders in addition to the aforementioned folders. The Hello World example has also been modified to use Redux.
 
 Note the organizational paradigm of "bundles". These are like application domains and are used for grouping your code into webpack bundles, in case you decide to create different bundles for deployment. This is also useful for separating out logical parts of your application. The concept is that each bundle will have it's own Redux store. If you have code that you want to reuse across bundles, including components and reducers, place them under `/client/app/lib`.
-

data/docs/{basics/installation-overview.md → additional-details/manual-installation-overview.md}

@@ -1,17 +1,12 @@
-# Installation Overview
+# Manual Installation Overview
 
-Here's an overview of installation if you're not using the generator.
+TODO: Review this file
 
-Note, the best way to understand how to use ReactOnRails is to study the examples:
 
-1. Run the generator per the [Tutorial](../tutorial.md).
-2. [spec/dummy](../../spec/dummy): Simple, no DB example.
-3. [github.com/shakacode/react-webpack-rails-tutorial](https://github.com/shakacode/react-webpack-rails-tutorial): Full featured example.
+This file summarizes what the React on Rails generator does.
 
 ## Configure the `/client` Directory
 
-Note, version 9.0 of React on Rails removed the requirement to place all client side files in the `/client` directory.
-
 This directory has no references to Rails outside of the destination directory for the files created by the various Webpack config files.
 
 The only requirements within this directory for basic React on Rails integration are:
@@ -19,17 +14,17 @@ The only requirements within this directory for basic React on Rails integration
 1. Your webpack configuration files:
    1. Create outputs in a directory like `/public/webpack`, which is customizable in your `config/initializers/react_on_rails.rb`.
    1. Provide server rendering if you wish to use that feature.
-1. Your JavaScript code "registers" any components and stores per the ReactOnRails APIs of ReactOnRails.register(components) and ReactOnRails.registerStore(stores). See API docs in [README.md](../../README.md) and the [ReactOnRails.js source](../../node_package/src/ReactOnRails.js).
+1. Your JavaScript code "registers" any components and stores per the ReactOnRails APIs of ReactOnRails.register(components) and ReactOnRails.registerStore(stores). See [our javascript API docs](https://www.shakacode.com/react-on-rails/docs/api/javascript-api/) and the [ReactOnRails.js source](https://github.com/shakacode/react_on_rails/tree/master/node_package/src/ReactOnRails.js).
 1. Set your registration file as an "entry" point in your Webpack configs.
-1. Add the [Manifest plugin](https://github.com/danethurber/webpack-manifest-plugin) to your config. For examples see [dummy config](../../spec/dummy/client/webpack.client.base.config.js).
+1. Add the [Manifest plugin](https://github.com/danethurber/webpack-manifest-plugin) to your config.
 The default path: `public/webpack` can be loaded with webpackConfigLoader as shown in the dummy example.
 1. You create scripts in `client/package.json` per the example apps. These are used for building your Webpack assets. Also do this for your top level `package.json`.
 
 ## Rails Steps (outside of /client)
-1. Add  `gem "webpacker"` to the Gemfile, run bundle. The gem provides the `stylesheet_pack_tag` and `javascript_pack_tag` helpers which is used to load the bundled assets to your layouts.[Dummy Example](../../spec/dummy/app/views/layouts/application.html.erb)
-1. 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](../../spec/dummy/config/initializers/react_on_rails.rb) for a detailed example of configuration, including comments on the different values to configure.
+1. Add  `gem "webpacker"` to the Gemfile, run bundle. The gem provides the `stylesheet_pack_tag` and `javascript_pack_tag` helpers which is used to load the bundled assets to your layouts.[Dummy Example](https://github.com/shakacode/react_on_rails/tree/master/spec/dummy/app/views/layouts/application.html.erb)
+1. Configure the `config/initializers/react_on_rails.rb`. You can adjust some necessary settings and defaults. See file [https://github.com/shakacode/react_on_rails/tree/master/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.
 1. Configure your Procfiles per the example apps. These are at the root of your Rails installation.
-1. Configure your top level JavaScript files for inclusion in your layout. You'll want a version that you use for static assets, and you want a file for any files in your setup that are not part of your webpack build. The reason for this is for use with hot-reloading. If you are not using hot reloading, then you only need to configure your `application.js` file to include your Webpack generated files. For more information on hot reloading, see [Hot Reloading of Assets For Rails Development](../additional-reading/hot-reloading-rails-development.md)
-1. If you are deploying to Heroku, see [heroku-deployment.md](/docs/additional-reading/heroku-deployment.md)
+1. Configure your top level JavaScript files for inclusion in your layout. You'll want a version that you use for static assets, and you want a file for any files in your setup that are not part of your webpack build. The reason for this is for use with hot-reloading. If you are not using hot reloading, then you only need to configure your `application.js` file to include your Webpack generated files.
+1. If you are deploying to Heroku, see [our heroku deployment documentation](https://www.shakacode.com/react-on-rails/docs/deployment/heroku-deployment/)
 
 If I missed anything, please submit a PR or file an issue.

data/docs/{basics → additional-details}/migrating-from-react-rails.md

@@ -11,7 +11,7 @@ If you are using [react-rails](https://github.com/reactjs/react-rails) in your p
 //= require components
 ```
 
-- Follow our getting started guide: https://github.com/shakacode/react_on_rails#getting-started.
+- Follow our [getting started guide](https://www.shakacode.com/react-on-rails/docs/getting-started/).
 
 Note: If you have components from react-rails you want to use, then you will need to port them into react_on_rails which uses webpack instead of the asset pipeline.
 

data/docs/additional-details/recommended-project-structure.md

@@ -0,0 +1,69 @@
+# Recommended Project structure
+
+The React on Rails generator uses the standard Shakapacker convention of this structure:
+
+```yml
+app/javascript:
+  ├── bundles:
+  │   # Logical groups of files that can be used for code splitting
+  │   └── hello-world-bundle.js
+  ├── packs:
+  │   # only webpack entry files here
+  │   └── hello-world-bundle.js
+```
+
+Per the example repo [shakacode/react_on_rails_demo_ssr_hmr](https://github.com/shakacode/react_on_rails_demo_ssr_hmr),
+you should consider keeping your codebase mostly consistent with the defaults for [Shakapacker](https://github.com/shakacode/shakapacker).
+
+## Steps to convert from the generator defaults to use a `/client` directory for source code 
+
+1. Move the directory:
+
+```
+mv app/javascript client
+```
+
+2. Edit your `/config/shakapacker.yml` file. Change the `default/source_path`:
+
+```yml
+  source_path: client
+```
+
+## Moving node_modules from `/` to `/client` with a custom webpack setup.
+
+Shakapacker probably doesn't support having your main node_modules directory under `/client`, so only follow these steps if you want to use your own webpack configuration.
+
+1. Move the `/package.json` to `/client/package.json`
+2. Create a `/package.json` that delegates to `/client/package.json`. 
+   ```
+     "scripts": {
+       "heroku-postbuild": "cd ./client && yarn"
+     },
+   ```
+3. If your `node_modules` directory is not at the top level of the Rails project, then you will need to set the
+ENV value of `SHAKAPACKER_CONFIG` to the location of the `config/shakapacker.yml` file per [rails/webpacker PR 2561](https://github.com/rails/webpacker/pull/2561). (Notice the change of spelling from Webpacker to Shakapacker)
+
+## CSS, Sass, Fonts, and Images
+Should you move your styling assets to Webpack? Or stick with the plain Rails asset pipeline. It depends!
+
+Here's a good discussion of this option: [Why does Rails 6 include both Webpacker and Sprockets?](https://rossta.net/blog/why-does-rails-install-both-webpacker-and-sprockets.html). 
+
+You have 2 basic choices:
+
+### Simple Rails Way
+This isn't really any technique, as you keep handling all your styling assets using Rails standard tools, such as using the [sass-rails gem](https://rubygems.org/gems/sass-rails/versions/5.0.4). Basically, Webpack doesn't get involved with styling. Your Rails layouts just doing the styling the standard Rails way.
+
+#### Advantages to the Simple Rails Way
+1. Much simpler! There's no changes really from your current processes.
+
+### Using Webpack to Manage Styling Assets
+This technique involves customization of the webpack config files to generate CSS, image, and font assets. 
+
+#### Directory structure
+1. `/client/app/assets`: Assets for CSS for client app.
+1. `/client/app/assets/fonts` and `/client/app/assets/styles`: Globally shared assets for styling. Note, most Sass and image assets will be stored next to the JavaScript files.
+
+#### Advantages to having Webpack Manage Styles
+1. You can use [CSS modules](https://github.com/css-modules/css-modules), which is super compelling once you seen the benefits.
+1. You can use CSS in JS.
+1. You can do hot reloading of your assets. Thus, you do not have to refresh your web page to see asset change, including changing styles.

data/docs/additional-details/tips-for-usage-with-sp6.md

@@ -0,0 +1,15 @@
+# Tips for usage with Shakapacker 6
+
+As mentioned earlier in the documentation, we assume you install ReactOnRails in a project with Shakapacker 7+ installed and configured. If you still use Shakapacker 6, we encourage you to check the upgrade to the version 7 guide. Otherwise, you need to consider the following:
+
+1. The install generator tries to take the necessary steps to adapt the installed files to match the file structure and configurations for Shakapacker 6. So you don't need to be worried about the ReactOnRails installation process.
+
+2. Check the following table to map the references in the documentation to the relevant ones in Shakapacker 6:
+
+  |Usage in Shakapacker 7      |Equivalant in Shakapacker 6|
+  |----------------------------|---------------------------|
+  |`config/shakapacker.yml`    |`config/webpacker.yml`     |
+  |`bin/shakapacker`           |`bin/webpacker`            |
+  |`bin/shakapacker-dev-server`|`bin/webpacker-dev-server` |
+
+3. Any environment variables starting with `SHAKAPACKER_*` should be changed to `WEBPACKER_*`.

data/docs/additional-details/upgrade-webpacker-v3-to-v4.md

@@ -0,0 +1,10 @@
+# Upgrading rails/webpacker v3.5 to v4
+
+The following steps can be followed to update a Webpacker v3.5 app to v4.
+
+1. Update the gem `webpacker` and the package `@rails/webpacker`
+1. Merge changes from the new default [.babelrc](https://github.com/shakacode/react_on_rails/tree/master/lib/install/config/.babelrc) to your `/.babelrc`. If you are using React, you need to add `"@babel/preset-react"`, to the list of `presets`.
+1. Copy the file [.browserslistrc](https://github.com/shakacode/react_on_rails/tree/master/lib/install/config/.browserslistrc) to `/`.
+1. Merge any differences between [config/webpacker.yml](https://github.com/shakacode/react_on_rails/tree/master/lib/install/config/webpacker.yml) and your `/config/webpacker.yml`.
+
+Here is an [example commit of these changes](https://github.com/shakacode/react_on_rails-tutorial-v11/pull/1/files).

data/docs/api/javascript-api.md

@@ -1,20 +1,40 @@
 # ReactOnRails JavaScript API
-The best source of docs is the main [ReactOnRails.js](../../node_package/src/ReactOnRails.js) file. Here's a quick summary. No guarantees that this won't be outdated!
+## CSRF protection
+
+Rails has built-in protection for Cross-Site Request Forgery (CSRF), see [Rails Documentation](http://guides.rubyonrails.org/security.html#cross-site-request-forgery-csrf). To nicely utilize this feature in JavaScript requests, React on Rails provides two helpers that can be used as following for POST, PUT or DELETE requests:
+
+```js
+import ReactOnRails from 'react-on-rails';
+
+// reads from DOM csrf token generated by Rails in <%= csrf_meta_tags %>
+csrfToken = ReactOnRails.authenticityToken();
+
+// compose Rails specific request header as following { X-CSRF-Token: csrfToken, X-Requested-With: XMLHttpRequest }
+header = ReactOnRails.authenticityHeaders(otherHeader);
+```
+
+If you are using [jquery-ujs](https://github.com/rails/jquery-ujs) for AJAX calls, then these helpers are not needed because the [jquery-ujs](https://github.com/rails/jquery-ujs) library updates header automatically, see [jquery-ujs documentation](https://robots.thoughtbot.com/a-tour-of-rails-jquery-ujs#cross-site-request-forgery-protection).
+
+
+
+## API
+
+The best source of docs is the main [ReactOnRails.js](https://github.com/shakacode/react_on_rails/node_package/src/ReactOnRails.js) file. Here's a quick summary. No guarantees that this won't be outdated!
 
 ```js
   /**
    * Main entry point to using the react-on-rails npm package. This is how Rails will be able to
    * find you components for rendering. Components get called with props, or you may use a
-   * "generator function" to return a React component or an object with the following shape:
+   * "Render-Function" to return a React component or an object with the following shape:
    * { renderedHtml, redirectLocation, error }.
-   * For server rendering, if you wish to return multiple HTML strings from a generator function,
-   * you may return an Object from your generator function with a single top level property of
+   * For server rendering, if you wish to return multiple HTML strings from a Render-Function,
+   * you may return an Object from your Render-Function with a single top level property of
    * renderedHtml. Inside this Object, place a key called componentHtml, along with any other
    * needed keys. This is useful when you using side effects libraries like react helmet.
    * Your Ruby code with get this Object as a Hash containing keys componentHtml and any other
    * custom keys that you added:
    * { renderedHtml: { componentHtml, customKey1, customKey2 } }
-   * See the example in /docs/additional-reading/react-helmet.md
+   * See the example in https://www.shakacode.com/react-on-rails/docs/javascript/react-helmet
    * @param components (key is component name, value is component)
    */
   register(components)
@@ -38,6 +58,15 @@ The best source of docs is the main [ReactOnRails.js](../../node_package/src/Rea
    */
   getStore(name, throwIfMissing = true )
 
+  /**
+   * Renders or hydrates the react element passed. In case react version is >=18 will use the new api.
+   * @param domNode
+   * @param reactElement
+   * @param hydrate if true will perform hydration, if false will render
+   * @returns {Root|ReactComponent|ReactElement|null}
+   */
+  reactHydrateOrRender(domNode, reactElement, hydrate)
+
   /**
    * Set options for ReactOnRails, typically before you call ReactOnRails.register
    * Available Options:
@@ -49,7 +78,7 @@ The best source of docs is the main [ReactOnRails.js](../../node_package/src/Rea
    * Allow directly calling the page loaded script in case the default events that trigger react
    * rendering are not sufficient, such as when loading JavaScript asynchronously with TurboLinks:
    * More details can be found here:
-   * https://github.com/shakacode/react_on_rails/blob/master/docs/additional-reading/turbolinks.md
+   * https://www.shakacode.com/react-on-rails/docs/rails/turbolinks
    */
   reactOnRailsPageLoaded()
 

data/docs/api/redux-store-api.md

@@ -0,0 +1,102 @@
+# Redux Store
+
+_This redux API is no longer recommended as it prevents dynamic code splitting for performance. Instead, you should use the standard react_component view helper passing in a "Render-Function."_
+
+You don't need to use the `redux_store` api to use redux. This api was setup to support multiple calls to `react_component` on one page that all talk to the same redux store.
+
+If you are only rendering one react component on a page, as is typical to do a "Single Page App" in React, then you should _probably_ pass the props to your React component in a "Render-Function."
+
+Consider using the `redux_store` helper for the two following use cases:
+
+1. You want to have multiple React components accessing the same store at once.
+2. You want to place the props to hydrate the client side stores at the very end of your HTML, probably server rendered, so that the browser can render all earlier HTML first. This is particularly useful if your props will be large. However, you're probably better off using [React on Rails Pro](https://github.com/shakacode/react_on_rails/wiki) if you're at all concerned about performance.
+
+## Multiple React Components on a Page with One Store
+
+You may wish to have 2 React components share the same the Redux store. For example, if your navbar is a React component, you may want it to use the same store as your component in the main area of the page. You may even want multiple React components in the main area, which allows for greater modularity. Also, you may want this to work with Turbolinks to minimize reloading the JavaScript.
+
+A good example of this would be something like a notifications counter in a header. As each notification is read in the body of the page, you would like to update the header. If both the header and body share the same Redux store, then this is trivial. Otherwise, we have to rely on other solutions, such as the header polling the server to see how many unread notifications exist.
+
+Suppose the Redux store is called `appStore`, and you have 3 React components that each needs to connect to a store: `NavbarApp`, `CommentsApp`, and `BlogsApp`. I named them with `App` to indicate that they are the registered components.
+
+You will need to make a function that can create the store you will be using for all components and register it via the `registerStore` method. Note: this is a **storeCreator**, meaning that it is a function that takes (props, location) and returns a store:
+
+```js
+function appStore(props, railsContext) {
+  // Create a hydrated redux store, using props and the railsContext (object with
+  // Rails contextual information).
+  return myAppStore;
+}
+
+ReactOnRails.registerStore({
+  appStore
+});
+```
+
+When registering your component with React on Rails, you can get the store via `ReactOnRails.getStore`:
+
+```js
+// getStore will initialize the store if not already initialized, so creates or retrieves store
+const appStore = ReactOnRails.getStore("appStore");
+return (
+  <Provider store={appStore}>
+    <CommentsApp />
+  </Provider>
+);
+```
+
+From your Rails view, you can use the provided helper `redux_store(store_name, props)` to create a fresh version of the store (because it may already exist if you came from visiting a previous page). Note: for this example, since we're initializing this from the main layout, we're using a generic name of `@react_props`. In other words, the Rails controller would set `@react_props` to the properties to hydrate the Redux store.
+
+**app/views/layouts/application.html.erb**
+
+```erb
+...
+<%= redux_store("appStore", props: @react_props) %>;
+<%= react_component("NavbarApp") %>
+yield
+...
+```
+
+Components should be created as [stateless function(al) components](https://facebook.github.io/react/docs/reusable-components.html#stateless-functions). Since you can pass in initial props via the helper `redux_store`, you do not need to pass any props directly to the component. Instead, the component hydrates by connecting to the store.
+
+**_comments.html.erb**
+
+```erb
+<%= react_component("CommentsApp") %>
+```
+
+**_blogs.html.erb**
+
+```erb
+<%= react_component("BlogsApp") %>
+```
+
+*Note:* You will not be doing any partial updates to the Redux store when loading a new page. When the page content loads, React on Rails will rehydrate a new version of the store with whatever props are placed on the page.
+
+## Controller Extension
+
+Include the module `ReactOnRails::Controller` in your controller, probably in ApplicationController. This will provide the following controller method, which you can call in your controller actions:
+
+`redux_store(store_name, props: {})`
+
+- **store_name:** A name for the store. You'll refer to this name in 2 places in your JavaScript:
+  1. You'll call `ReactOnRails.registerStore({storeName})` in the same place that you register your components.
+  2. In your component definition, you'll call `ReactOnRails.getStore('storeName')` to get the hydrated Redux store to attach to your components.
+- **props:**  Named parameter `props`. ReactOnRails takes care of setting up the hydration of your store with props from the view.
+
+For an example, see [spec/dummy/app/controllers/pages_controller.rb](https://github.com/shakacode/react_on_rails/tree/master/spec/dummy/app/controllers/pages_controller.rb). Note: this is preferable to using the equivalent view_helper `redux_store` in that you can be assured that the store is initialized before your components.
+
+## View Helper
+
+`redux_store(store_name, props: {})`
+
+This method has the same API as the controller extension. **HOWEVER**, we recommend the controller extension instead because the Rails executes the template code in the controller action's view file (`erb`, `haml`, `slim`, etc.) before the layout. So long as you call `redux_store` at the beginning of your action's view file, this will work. However, it's an easy mistake to put this call in the wrong place. Calling `redux_store` in the controller action ensures proper load order, regardless of where you call this in the controller action. Note: you won't know of this subtle ordering issue until you server render and you find that your store is not hydrated properly.
+
+`redux_store_hydration_data`
+
+Place this view helper (no parameters) at the end of your shared layout so ReactOnRails will render the redux store hydration data. Since we're going to be setting up the stores in the controllers, we need to know where on the view to put the client-side rendering of this hydration data, which is a hidden div with a matching class that contains a data props. For an example, see [spec/dummy/app/views/layouts/application.html.erb](https://github.com/shakacode/react_on_rails/tree/master/spec/dummy/app/views/layouts/application.html.erb).
+
+# More Details
+
+* [lib/react_on_rails/controller.rb](https://github.com/shakacode/react_on_rails/tree/master/lib/react_on_rails/controller.rb) source
+* [lib/react_on_rails/helper.rb](https://github.com/shakacode/react_on_rails/tree/master/lib/react_on_rails/helper.rb) source