react_on_rails 11.0.3 → 12.0.0

data/Rakefile

@@ -2,6 +2,7 @@
 
 # Rake will automatically load any *.rake files inside of the "rakelib" folder
 # See rakelib/
+
 tasks = %w[run_rspec lint]
 prepare_for_ci = %w[node_package dummy_apps]
 
@@ -11,11 +12,6 @@ if ENV["USE_COVERALLS"] == "TRUE"
   tasks << "coveralls:push"
 end
 
-if File.basename(ENV["BUNDLE_GEMFILE"] || "") == "Gemfile.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,63 @@
-# Table of Content
+# Table of Contents
 
-### **Rails**
-  + [Rails Assets](./docs/additional-reading/rails-assets.md)
++ [Home](./README.md)
+
+## **Basics**
+  + [React on Rails Basic Installation Tutorial](./docs/tutorial.md)
+  + [Webpack Configuration](./docs/basics/webpack-configuration.md)
+  + [How React on Rails Works](docs/outdated/how-react-on-rails-works.md)
+  + [Client vs. Server Rendering](./docs/basics/client-vs-server-rendering.md)
+  + [React Server Rendering](./docs/basics/react-server-rendering.md)
+  + [Recommended Project Structure](./docs/basics/recommended-project-structure.md)
+  + [Render-Functions and the RailsContext](docs/basics/render-functions-and-railscontext.md)
+  + [Caching and Performance: React on Rails Pro](https://github.com/shakacode/react_on_rails/wiki).
+  + [Deployment](docs/basics/deployment.md).
+  + [React on Rails Internationalization (I18n, localization)](docs/basics/i18n.md)
+  + [RSpec Test Helpers Configuration](docs/basics/rspec-configuration.md)
+  + [Minitest Configuration](docs/basics/minitest-configuration.md)
+  + [Upgrading React on Rails](docs/basics/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/basics/migrating-from-react-rails.md)
+  + [Generator Details](docs/basics/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)
+  
+## **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/basics/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/additional-reading/asset-pipeline.md

@@ -1,20 +1,12 @@
-# Asset Pipeline
+# Asset Pipeline with React on Rails
 
-The plumbing of webpack produced assets through the asset pipeline is deprecated as of v9.0.
+In general, you should not be mixing the asset pipeline with rails/webpacker and React on Rails.
 
-The information in this document is here for those that have not yet upgraded.
+If you're using React, then all of your CSS and images should be under either `/client` or
+`/app/javascript` or wherever you want your client side application.
 
+If you are incrementally migrating a large application, your main concern will be how to minimize
+duplication of styles and images between your old application and the new one.
 
-
-
-This option still works for your `/config/initializers/react_on_rails.rb` if you are still using the
-asset pipeline.
-```
-  ################################################################################
-  # MISCELLANEOUS OPTIONS
-  ################################################################################
-  # If you want to use webpack for CSS and images, and still use the asset pipeline,
-  # see https://github.com/shakacode/react_on_rails/blob/master/docs/additional-reading/rails-assets.md
-  # And you will use a setting like this.
-  config.symlink_non_digested_assets_regex = /\.(png|jpg|jpeg|gif|tiff|woff|ttf|eot|svg|map)/
-```
+Please email [justin@shakacode.com](mailto:justin@shakacode.com) if you would be interested in help
+to migrate a larger application.

data/docs/additional-reading/convert-rails-5-api-only-app.md

@@ -0,0 +1,19 @@
+# Convert Rails 5 API only app to a Rails app
+
+1. Go to the directory where you created your app
+
+```bash
+$ 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 [the instructions for installing into an existing Rails app](../basics/installation-into-an-existing-rails-app.md).*

data/docs/additional-reading/credits.md

@@ -0,0 +1,10 @@
+## Authors
+
+[The Shaka Code team!](http://www.shakacode.com/about/)
+
+The origins of the project began with the need to do a rich JavaScript interface for a ShakaCode's client. The choice to use Webpack and Rails is described in [Fast Rich Client Rails Development With Webpack and the ES6 Transpiler](http://www.railsonmaui.com/blog/2014/10/03/integrating-webpack-and-the-es6-transpiler-into-an-existing-rails-project/).
+
+The gem project started with [Justin Gordon](https://github.com/justin808/) pairing with [Samnang Chhun](https://github.com/samnang) to figure out how to do server rendering with Webpack plus Rails. [Alex Fedoseev](https://github.com/alexfedoseev) then joined in. [Rob Wise](https://github.com/robwise), [Aaron Van Bokhoven](https://github.com/aaronvb), and [Andy Wang](https://github.com/yorzi) did the bulk of the generators. Many others have [contributed](https://github.com/shakacode/react_on_rails/graphs/contributors).
+
+The gem was initially inspired by the [react-rails gem](https://github.com/reactjs/react-rails).
+

data/docs/additional-reading/images.md

@@ -39,7 +39,7 @@ const assetLoaderRules = [
 
 
 
-A full example can be found at [spec/dummy/client/app/components/ImageExample/ImageExample.js](../../spec/dummy/client/app/components/ImageExample/ImageExample.js)
+A full example can be found at [spec/dummy/client/app/components/ImageExample/ImageExample.jsx](../../spec/dummy/client/app/components/ImageExample/ImageExample.jsx)
 
 You are free to use images either in image tags or as background images in SCSS files. You can 
 use a "global" location of /client/app/assets/images or a relative path to your JS or SCSS file, as

data/docs/additional-reading/rails-engine-integration.md

@@ -32,3 +32,10 @@ This is necessary because React on Rails attaches itself to the rake assets:prec
 Requiring `react_on_rails` and including the helper will get rid of any issues where react on rails or react_component is undefined.
 
 As far as solving the assets issue, `lib/tasks/assets.rake` in `react_on_rails` would somehow have to know that `react_on_rails` was included in an engine, and decide the path accordingly. This might be impossible, especially in the case of multiple engines using `react_on_rails` in a single application. Another solution would be to detach this rake task from the rails assets:precompile task, and let people use it separately.
+
+# Github Issues
+
+* [Integration with an engine #342](https://github.com/shakacode/react_on_rails/issues/342)
+* [Feature: target destination option for the install generator #459](https://github.com/shakacode/react_on_rails/issues/459)
+* [Integration with Rails 5 Engines #562](https://github.com/shakacode/react_on_rails/issues/562)
+* [Run inside a Rails engine? #257](https://github.com/shakacode/react_on_rails/issues/257)

data/docs/additional-reading/rails_view_rendering_from_inline_javascript.md

@@ -12,9 +12,10 @@ You can easily render React components in your JavaScript with `render` method t
  * @param name Name of your registered component
  * @param props Props to pass to your component
  * @param domNodeId
+ * @param hydrate [optional] Pass truthy to update server rendered html. Default is falsy
  * @returns {virtualDomElement} Reference to your component's backing instance
  */
-ReactOnRails.render(componentName, props, elementId)
+ReactOnRails.render(componentName, props, domNodeId)
 ```
 
 ## Why do we need this?

data/docs/additional-reading/react-helmet.md

@@ -1,12 +1,13 @@
 # Using React Helmet to build `<head>` content
 
 ## Installation and general usage
-See https://github.com/nfl/react-helmet for details. Run `yarn add react-helmet` in your `client` directory to add this package to your application.
+See [nfl/react-helmet](https://github.com/nfl/react-helmet) for details on how to use this package.
+Run `yarn add react-helmet` to add this package to your application.
 
 ## Example
 Here is what you need to do in order to configure your Rails application to work with **ReactHelmet**.
 
- Create generator function for server rendering like this:
+ Create a render-function for server rendering like this:
 
 ```javascript
 export default (props, _railsContext) => {
@@ -20,17 +21,35 @@ export default (props, _railsContext) => {
   return { renderedHtml };
 };
 ```
-You can add more **helmet** properties to result, e.g. **meta**, **base** and so on. See https://github.com/nfl/react-helmet#server-usage.
+You can add more **helmet** properties to the result, e.g. **meta**, **base** and so on. See https://github.com/nfl/react-helmet#server-usage.
 
-Use regular component or generator function for client-side:
+Use a regular React functional or class component or a render-function for your client-side bundle:
 
 ```javascript
-export default (props, _railsContext) => (
+// React functional component
+export default (props) => (
   <App {...props} />
 );
 ```
 
-Put **ReactHelmet** component somewhere in your `<App>`:
+Or a render-function. Note you can't return just the JSX (React element), but you need to return
+either a React functional or class component.
+```javascript
+// React functional component
+export default (props, railsContext) => (
+  () => <App {{railsContext, ...props}} />
+);
+```
+
+Note, this doesn't work, because this function just returns a React element rather than a React component
+```javascript
+// React functional component
+export default (props, railsContext) => (
+  <App {{railsContext, ...props}} />
+);
+```
+
+Put the **ReactHelmet** component somewhere in your `<App>`:
 ```javascript
 import { Helmet } from 'react-helmet';
 
@@ -55,15 +74,18 @@ ReactOnRails.register({
 });
 ```
 ```javascript
+// Note the import from the server file.
 import ReactHelmetApp from '../ReactHelmetServerApp';
 
 ReactOnRails.register({
   ReactHelmetApp
 });
 ```
-Now when the `react_component_hash` helper is called with **"ReactHelmetApp"** as a first argument it will return a hash instead of HTML string:
+Now when the `react_component_hash` helper is called with **"ReactHelmetApp"** as a first argument it
+will return a hash instead of HTML string. Note, there is no need to specify "prerender" as it would not
+make sense to use react_component_hash without server rendering:
 ```ruby
-<% react_helmet_app = react_component_hash("ReactHelmetApp", prerender: true, props: { hello: "world" }, trace: true) %>
+<% react_helmet_app = react_component_hash("ReactHelmetApp", props: { hello: "world" }, trace: true) %>
 
 <% content_for :title do %>
   <%= react_helmet_app['title'] %>
@@ -76,5 +98,3 @@ So now we're able to insert received title tag to our application layout:
 ```ruby
  <%= yield(:title) if content_for?(:title) %>
 ```
-
-Note: Use of `react_component` for this functionality is deprecated. Please use `react_component_hash` instead.

data/docs/additional-reading/react-router.md

@@ -1,39 +1,28 @@
+_This article needs updating for the latest version of React Router_
+
 # Using React Router
 
-React on Rails supports the use of React Router. Client-side code doesn't need any special configuration for the React on Rails gem. Implement React Router how you normally would. Note, you might want to avoid using Turbolinks as both Turbolinks and React-Router will be trying to handle the back and forward buttons. If you get this figured out, please do share with the community! Otherwise, you might have to tweak the basic settings for Turbolinks, and this may or may not be worth the effort.
 
-When attempting to use server-rendering, it is necessary to take steps that prevent rendering when there is a router error or redirect. In these cases, the client code should return an object containing the `error` and a `redirectLocation` instead of the React component. The `react_component` helper method in your Rails view will automatically detect that there was an error/redirect and handle it accordingly.
+React on Rails supports the use of React Router. Client-side code doesn't need any special configuration for the React on Rails gem. Implement React Router how you normally would. Note, you might want to avoid using Turbolinks as both Turbolinks and React-Router will be trying to handle the back and forward buttons. If you get this figured out, please do share with the community! Otherwise, you might have to tweak the basic settings for Turbolinks, and this may or may not be worth the effort.
 
 If you are working with the HelloWorldApp created by the react_on_rails generator, then the code below corresponds to the module in `client/app/bundles/HelloWorld/startup/HelloWorldApp.jsx`.
 
 ```js
+
+import { BrowserRouter, Switch } from 'react-router-dom'
+import routes from './routes.jsx'
+
 const RouterApp = (props, railsContext) => {
-  let error;
-  let redirectLocation;
-  let routeProps;
-  const { location } = railsContext;
-  
   // create your hydrated store
   const store = createStore(props);
-
-  // See https://github.com/reactjs/react-router/blob/master/docs/guides/ServerRendering.md
-  match({ routes, location }, (_error, _redirectLocation, _routeProps) => {
-    error = _error;
-    redirectLocation = _redirectLocation;
-    routeProps = _routeProps;
-  });
-
-  // This tell react_on_rails to skip server rendering any HTML. Note, client rendering
-  // will handle the redirect. What's key is that we don't try to render.
-  // Critical to return the Object properties to match this { error, redirectLocation }
-  if (error || redirectLocation) {
-    return { error, redirectLocation };
-  }
-
-  // Important that you don't do this if you are redirecting or have an error.
+  
   return (
     <Provider store={store}>
-      <RouterContext {...routeProps} />
+      <BrowserRouter>
+        <Switch>
+          {routes}
+        </Switch>
+      </BrowserRouter>
     </Provider>
   );
 };
@@ -50,64 +39,52 @@ For a fleshed out integration of react_on_rails with react-router, check out [Re
 
 # Server Rendering Using React Router V4
 
-Your generator function may not return an object with the property `renderedHtml`. Thus, you call 
+Your render function may not return an object with the property `renderedHtml`. Thus, you call 
 renderToString() and return an object with this property.
 
 This example **only applies to server rendering** and should be only used in the server side bundle.
 
-From the [original example in the ReactRouter docs](https://react-router.now.sh/ServerRouter)
+From the [original example in the ReactRouter docs](https://github.com/ReactTraining/react-router/blob/v4.3.1/packages/react-router-dom/docs/guides/server-rendering.md)
  
 ```javascript
    import React from 'react'
    import { renderToString } from 'react-dom/server'
-   import { ServerRouter, createServerRenderContext } from 'react-router'
-   
-   const ReactRouterComponent = (props, railsContext) => {
-   
-     // first create a context for <ServerRouter>, it's where we keep the
-     // results of rendering for the second pass if necessary
-     const context = createServerRenderContext()
-     const { location } = railsContext;
-
-     // render the first time
-     let markup = renderToString(
-       <ServerRouter
-         location={location}
-         context={context}
-       >
-         <App/>
-       </ServerRouter>
-     )
-   
-     // get the result
-     const result = context.getResult()
-   
-     // the result will tell you if it redirected, if so, we ignore
-     // the markup and send a proper redirect.
-     if (result.redirect) {
-       return { 
-         redirectLocation: result.redirect.pathname 
-       };
-     } else {
-   
-       // the result will tell you if there were any misses, if so
-       // we can send a 404 and then do a second render pass with
-       // the context to clue the <Miss> components into rendering
-       // this time (on the client they know from componentDidMount)
-       if (result.missed) {
-         // React on Rails does not support the 404 status code for the browser.  
-         // res.writeHead(404)
-         
-         markup = renderToString(
-           <ServerRouter
-             location={location}
-             context={context}
-           >
-             <App/>
-           </ServerRouter>
-         )
-       }
-       return { renderedHtml: markup };
-     }
+   import { StaticRouter } from 'react-router'
+   import { Provider } from 'react-redux'
+   import ReactOnRails from 'react-on-rails'
+
+   // App.jsx from src/client/App.jsx
+   import App from '../App'
+
+   const ReactServerRenderer = (props, railsContext) => {
+      const context = {}
+
+      // commentStore from src/server/store/commentStore
+      const store = ReactOnRails.getStore('../store/commentStore')
+
+      // Route Store generated from react-on-rails
+      
+      const { location } = railsContext
+
+      const html = ReactDOMServer.renderToString(
+        <Provider store={store}>
+          <StaticRouter
+            location={location}
+            context={context}
+            props={props}
+          >
+            <App />
+          </StaticRouter>
+        </ Provider>
+        )
+
+        if (context.url) {
+          // Somewhere a `<Redirect>` was rendered
+          redirect(301, context.url)
+        } else {
+          // we're good, send the response
+          return { renderedHtml: html };
+        }
+    }
   }
 ```

data/docs/additional-reading/server-rendering-tips.md

@@ -1,18 +1,21 @@
 # Server Rendering Tips
 
-Be sure to use mini_racer. See [issues/428](https://github.com/shakacode/react_on_rails/issues/428)
+For the best performance with Server Rendering, consider using [React on Rails Pro]
+
+Be sure to use mini_racer. See [issues/428](https://github.com/shakacode/react_on_rails/issues/428).
+
+
 
 ## General Tips
-- Your code can't reference `document`. Server side JS execution does not have access to `document`, so jQuery and some
-  other libs won't work in this environment. You can debug this by putting in `console.log`
-  statements in your code.
-- You can conditionally avoid running code that references document by passing in a boolean prop to your top level react
-  component. Since the passed in props Hash from the view helper applies to client and server side code, the best way to
-  do this is to use a generator function.
-- If you're serious about server rendering, it's worth the effort to have different entry points for client and server rendering. It's worth the extra complexity.
-- You can enable node server rendering if you want. See more information here: https://github.com/shakacode/react_on_rails/blob/master/docs/additional-reading/node-server-rendering.md
-
-The point is that you have separate files for top level client or server side, and you pass some extra option indicating that rendering is happening server side.
+- Your code can't reference `document`. Server side JS execution does not have access to `document`,
+  so jQuery and some other libs won't work in this environment. You can debug this by putting in
+  `console.log` statements in your code.
+- You can conditionally avoid running code that references document by either checking if `window`
+  is defined or using the "railsContext" 
+  your top level react component. Since the passed in props Hash from the view helper applies to
+  client and server side code, the best way to do this is to use a render function.
+- If you're serious about server rendering, it's worth the effort to have different entry points for client and server rendering. It's worth the extra complexity. The point is that you have separate files for top level client or server side, and you pass some extra option indicating that rendering is happening server side.
+- You can enable Node.js server rendering via [React on Rails Pro](https://github.com/shakacode/react_on_rails/wiki).
 
 ## Troubleshooting Server Rendering
 

data/docs/additional-reading/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](../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](../lib/install/config/.browserslistrc) to `/`.
+1. Merge any differences between [config/webpacker.yml](../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/additional-reading/webpack.md

@@ -18,5 +18,5 @@ Webpack v2 makes this very convenient! See:
 * [Implicit Common Vendor Chunk](https://webpack.js.org/guides/code-splitting-libraries/#implicit-common-vendor-chunk)
 * [Manifest File](https://webpack.js.org/guides/code-splitting-libraries/#manifest-file)
 
-
-
+## Webpack v4
+Webpack v4 is heartily recommended. If you need help with migrating your project to Webpack v4, please contact me, [justin@shakacode.com](mailto:justin@shakacode.com).

data/docs/api/javascript-api.md

@@ -1,14 +1,34 @@
 # 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