react_on_rails 1.0.1 → 1.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3cafbd0b068b4be809103e6f043761aa5ca9dff1
-  data.tar.gz: 4466dd647b9846dc792d8e3926a6819caf40f989
+  metadata.gz: c4ccd3d1c479a04e020fc78586ee67d7a576f30c
+  data.tar.gz: b460a6963c951e32e0553968c1e2bc0240c3e34a
 SHA512:
-  metadata.gz: 827b09823116f3d03ddf43d2343f2cfa45aa18793011d4174ec3517c4777c49a331c35b4f4d6533e8b73040d9a18befa3f452a33e973925c08d3abf3e6c9b568
-  data.tar.gz: d529ec20ac5c921231b64b0fe06201a78ff7671c2c27197ee3b93f735b5cccf810262550027f760135d776d0c4d8ba04066ca6a382a949ea5b1eeb61fd447e9e
+  metadata.gz: 9cee01638202876298db6523b2f194ee8d51f7aa225a3962d5d33d198a751e873cc1fc6d80466276de6826f15c792d2ada4c88168a04b80c3b2dd13ec3d30807
+  data.tar.gz: e59ecec3df7a937202157385a848a0d4394e179a488f7defb1bd303a16adcc5a4bb35e1193c4e602b2a14a5991807f4557b5cf4a447c7b2736aa3779dd53745b

data/README.md

@@ -3,42 +3,91 @@
 # React on Rails
 React on Rails integrates Facebook's [React](https://github.com/facebook/react) front-end framework with Rails. Currently, both React v0.14 and v0.13 are supported. 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!
 
-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/rails/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/rackt/redux)
-+ [Webpack dev server](https://webpack.github.io/docs/webpack-dev-server.html) with [hot module replacement](https://webpack.github.io/docs/hot-module-replacement-with-webpack.html)
-+ [Webpack optimization functionality](https://github.com/webpack/docs/wiki/optimization)
-+ **(Coming Soon)** [React Router](https://github.com/rackt/react-router)
+Be sure to see the [React Webpack Rails Tutorial Code](https://github.com/shakacode/react-webpack-rails-tutorial) along with the live example at [www.reactrails.com](http://www.reactrails.com).
 
-See the [react-webpack-rails-tutorial](https://github.com/justin808/react-webpack-rails-tutorial/) for an example of a live implementation and code.
-
-### Including your React Component in your Rails Views
+## Including your React Component in your Rails Views
 Please see [Getting Started](#getting-started) for how to set up your Rails project for React on Rails if you have not already done so.
 
-+ *Normal Mode (JavaScript is rendered on client):*
++ *Normal Mode (React component will be rendered on client):*
 
   ```erb
   <%= react_component("HelloWorldApp", @some_props) %>
   ```
-+ *Server-Side Rendering:*
++ *Server-Side Rendering (React component is first rendered into HTML on the server):*
 
   ```erb
   <%= react_component("HelloWorldApp", @some_props, prerender: true) %>
   ```
 
-+ The `component_name` parameter here would be a string matching the name you used when globally exposing your React component.
-+ `@some_props` can be either a hash or JSON string or {} if you have no props. This will make the data available in your component:
++ The `component_name` parameter is a string matching the name you used to globally expose your React component. So, in the above examples, if you had a React component named "HelloWorldApp," you would set `window.HelloWorldApp = HelloWorldApp` in your JavaScript. 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("HelloWorldApp", { name: "Stranger" })
+  ```
   ```javascript
-    this.props.name
+    // inside your React component
+    this.props.name // "Stranger"
   ```
 
-### Client-Side Rendering vs. Server-Side Rendering
-In most cases, you should use the provided helper method to render the React component from your Rails views with `prerender: false` (default behavior). In some cases, such as when SEO is vital or many users will not have JavaScript enabled, you can pass the `--server-rendering` option to the generator to configure your application for server-side rendering. Your JavaScript can then be first rendered on the server and passed to the client as HTML.
+## Documentation
+
++ [Features](#features)
++ [Why Webpack?](#why-webpack)
++ [Getting Started](#getting-started)
++ [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)
+    - [Globally Exposing Your React Components](#globally-exposing-your-react-components)
+    - [Rails View Helpers In-Depth](#rails-view-helpers-in-depth)
++ [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)
+    - [Bootstrap Integration](#bootstrap-integration)
+        + [Bootstrap via Rails Server](#bootstrap-via-rails-server)
+        + [Bootstrap via Webpack HMR Dev Server](#bootstrap-via-webpack-hmr-dev-server)
+        + [Keeping Custom Bootstrap Configurations Synced](#keeping-custom-bootstrap-configurations-synced)
+    - [Linters](#linters)
+        + [JavaScript Linters](#javascript-linters)
+        + [Ruby Linters](#ruby-linters)
+        + [Running the Linters](#running-the-linters)
++ [Developing with the Webpack Dev Server](#developing-with-the-webpack-dev-server)
++ [Adding Additional Routes for the Dev Server](#adding-additional-routes-for-the-dev-server)
++ [Additional Reading](#additional-reading)
++ [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/rails/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:
 
-In the following screenshot you can see the actual HTML rendered for a side-by-side comparison of a React component left as JavaScript for the client to render followed by the same component rendered on the server to HTML along with any console error messages generated:
++ [Redux](https://github.com/rackt/redux)
++ [Webpack dev server](https://webpack.github.io/docs/webpack-dev-server.html) with [hot module replacement](https://webpack.github.io/docs/hot-module-replacement-with-webpack.html)
++ [Webpack optimization functionality](https://github.com/webpack/docs/wiki/optimization)
++ _*(Coming Soon)*_ [React Router](https://github.com/rackt/react-router)
+    + *([Gem *Pull Request*](https://github.com/shakacode/react_on_rails/pull/68))*
+    + *([Tutorial Pull Request](https://github.com/shakacode/react-webpack-rails-tutorial/pull/128))*
 
-![Comparison of a normal React Component with its server-rendered version](https://cloud.githubusercontent.com/assets/1118459/10157268/41435186-6624-11e5-9341-6fc4cf35ee90.png)
+See the [react-webpack-rails-tutorial](https://github.com/justin808/react-webpack-rails-tutorial/) for an example of a live implementation and code.
+
+## Why Webpack?
+
+Webpack is used for 2 purposes:
+
+1. Generate several JavaScript "bundles" for inclusion in `application.js`.
+2. Providing the Webpack Dev Server for quick prototyping of components without needing to refresh your browser to see updates.
+
+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.
 
 ## Getting Started
 1. Add the following to your Gemfile and bundle install:
@@ -73,25 +122,80 @@ The generator installs your webpack files in the `client` folder. Foreman uses w
 
 Inside your Rails views, you can now use the `react_component` helper method provided by React on Rails.
 
+### 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`. Your JavaScript can then be first rendered on the server and passed to the client as HTML.
+
+Note that **server-rendering requires globally exposing your components by setting them to `global`, not `window`** (as is the case with client-rendering). If using the generator, you can pass the `--server-rendering` option to configure your application for server-side rendering. 
+
+In the following screenshot you can see the 3 parts of react_on_rails rendering:
+
+1. Inline JavaScript to "client-side" render the React component.
+2. The wrapper div `<div id="HelloWorld-react-component-0">` enclosing the server-rendered HTML for the React component
+3. Additional JavaScript to console log any messages, such as server rendering errors.
+
+**Note**: If server rendering is not used (prerender: false), then the major difference is that the HTML rendered contains *only* the outer div: `<div id="HelloWorld-react-component-0"/>`
+
+![Comparison of a normal React Component with its server-rendered version](https://cloud.githubusercontent.com/assets/1118459/10157268/41435186-6624-11e5-9341-6fc4cf35ee90.png)
+
 ### Building the Bundles
-Each time you change your client code, you will need to re-generate the bundles. The included Foreman `Procfile.dev` will take care of this for you by watching your JavaScript code files for changes. Simply run `foreman start -f Procfile.dev`.
+Each time you change your client code, you will need to re-generate the bundles (the webpack-created JavaScript files included in application.js). The included Foreman `Procfile.dev` will take care of this for you by watching your JavaScript code files for changes. Simply run `foreman start -f Procfile.dev`.
+
+On Heroku deploys, the `lib/assets.rake` file takes care of running webpack during deployment. If you have used the provided generator, these bundles will automatically be added to your `.gitignore` in order to prevent extraneous noise from re-generated code in your pull requests. You will want to do this manually if you do not use the provided generator.
 
 ### Globally Exposing Your React Components
 Place your JavaScript code inside of the provided `client/app` folder. Use modules just as you would when using webpack alone. The difference here is that instead of mounting React components directly to an element using `React.render`, you **expose your components globally and then mount them with helpers inside of your Rails views**.
 
 + *Normal Mode (JavaScript is Rendered on client):*
-
+  
+  If you are not server rendering, `clientGlobals.jsx` will have
+ 
   ```javascript
-  window.HelloWorld = HelloWorldAppClient;
+  window.HelloWorldApp = HelloWorldApp;
   ```
 + *Server-Side Rendering:*
 
+  If you are server rendering, `globals.jsx` will have:
+  
+  ```javascript
+  window.HelloWorldApp = HelloWorldAppClient;
+  ```
+  
+  `serverGlobals.jsx` will have:
+  
   ```javascript
-  global.HelloWorld = HelloWorldAppServer;
+  global.HelloWorldApp = HelloWorldAppServer;
   ```
+  
+  In general, you want different initialization for your server rendered components.
    
+### Rails View Helpers In-Depth
+Once the bundled files have been generated in your `app/assets/javascripts/generated` folder and you have exposed your components globally, you will want to run your code in your Rails views using the included helper method.
+
+This is how you actually render the React components you exposed to `window` inside of `clientGlobals` (and `global` inside of `serverGlobals` if you are server rendering).
+
+#### react_component
+`react_component(component_name, props = {}, options = {})`
+
++ **react_component_name:** Can be a React component, created using a ES6 class, or `React.createClass`, or a generator function that returns a React component.
++ **props:** Ruby Hash which contains the properties to pass to the react object, or a JSON string. If you pass a string, we'll escape it for you.
++ **options:**
+  + **generator_function:** default is false, set to true if you want to use a generator function rather than a React Component. Why would you do this? For example, you may want the ability to use the passed-in props to initialize a redux store or setup react-router. Or you may want to return different components depending on what's in the props.
+  + **prerender:** enable server-side rendering of component. Set to false when debugging!
+  + **trace:** set to true to print additional debugging information in the browser. Defaults to true for development, off otherwise.
+  + **replay_console:** Default is true. False will disable echoing server-rendering logs to the browser. While this can make troubleshooting server rendering difficult, so long as you have the default configuration of logging_on_server set to true, you'll still see the errors on the server.
++ Any other options are passed to the content tag, including the id
+
+#### server_render_js
+`server_render_js(js_expression, options = {})`
+
++ js_expression, like 2 + 3, and not a block of js code. If you have more than one line that needs to be executed, wrap it in an [IIFE](https://en.wikipedia.org/wiki/Immediately-invoked_function_expression). JS exceptions will be caught and console messages handled properly
++ Currently the only option you may pass is `replay_console` (boolean)
+
+This is a helper method that takes any JavaScript expression and returns the output from evaluating it. If you have more than one line that needs to be executed, wrap it in an IIFE. JS exceptions will be caught and console messages handled properly.
+
+## Generator
+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.
 
-## Generator Options
 Run `rails generate react_on_rails:install --help` for descriptions of all available options:
 
 ```
@@ -99,9 +203,10 @@ Usage:
   rails generate react_on_rails:install [options]
 
 Options:
-  -R, [--redux], [--no-redux]                        # Setup Redux files
-  -S, [--server-rendering], [--no-server-rendering]  # Configure for server-side rendering of webpack JavaScript
-  -L, [--skip-linters], [--no-skip-linters]          # Don't install linter files
+  -R, [--redux], [--no-redux]                        # Install Redux gems and Redux version of Hello World Example
+  -S, [--server-rendering], [--no-server-rendering]  # Add necessary files and configurations for server-side rendering
+  -j, [--skip-js-linters], [--no-skip-js-linters]    # Skip installing JavaScript linting files
+  -L, [--ruby-linters], [--no-ruby-linters]          # Install ruby linting files, tasks, and configs
 
 Runtime options:
   -f, [--force]                    # Overwrite files that already exist
@@ -113,7 +218,7 @@ Description:
     Create react on rails files for install generator.
 ```
 
-We have a repo showing the results of running the generator with various combinations of options, each combination on its own branch: [Generator Results](https://github.com/shakacode/react_on_rails-generator-results-pre-0/pulls).
+For a clear example of what each generator option will do, see our generator results repo: [Generator Results](https://github.com/shakacode/react_on_rails-generator-results-1-0-0/pulls). Each pull request shows a git "diff" that highlights the changes that the generator has made.
 
 ### 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.
@@ -126,11 +231,13 @@ 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).
 
-#### Additional Redux Folders
-If you have used the `--redux` generator option, you will notice the familiar additional redux folders in addition to the aforementioned folders. In this organization paradigm, each bundle has its own store. We do not set a global store and then use partial stores based off of that. Again, this is for bundle code modularity and isolation. Note that if you want to reuse redux reducers across domains, then you will want to put the shared reducers under `/client/app/lib`.
+### 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`.
 
 ### Using Images and Fonts
-The generator has amended the folders created in `client/assets/` to Rails's asset path. We would that if you have any existing assets that you want to use with your client code that you should move them to these folders and use webpack as normal.
+The generator has amended the folders created in `client/assets/` to Rails's asset path. We recommend that if you have any existing assets that you want to use with your client code, you should move them to these folders and use webpack as normal. This allows webpack's development server to have access to your assets, as it will not be able to see any assets in the default Rails directories which are above the `/client` directory.
 
 Alternatively, if you have many existing assets and don't wish to move them, you could consider creating symlinks from client/assets that point to your Rails assets folders inside of `app/assets/`. The assets there will then be visible to both Rails and webpack.
 
@@ -144,32 +251,48 @@ In the former case, the Rails server loads `bootstrap-sprockets`, provided by th
 
 This allows for using Bootstrap in your regular Rails stylesheets. If you wish to customize any of the Bootstrap variables, you can do so via the `client/assets/stylesheets/_pre-bootstrap.scss` partial.
 
-#### Bootstrap via Webpack HMR Dev Server
+#### Bootstrap via Webpack Dev Server
 When using the webpack dev server, which does not go through Rails, bootstrap is loaded via the [bootstrap-sass-loader](https://github.com/shakacode/bootstrap-sass-loader) which uses the `client/bootstrap-sass-config.js` file.
 
 #### Keeping Custom Bootstrap Configurations Synced
-Because the HMR dev server and Rails each load Bootstrap via a different file (explained in the two sections immediately above), any changes to the way components are loaded in one file must also be made to the other file in order to keep styling consistent between the two. For example, if an import is excluded in `_bootstrap-custom.scss`, the same import should be excluded in `bootstrap-sass-config.js` so that styling in the Rails server and the webpack dev server will be the same.
+Because the webpack dev server and Rails each load Bootstrap via a different file (explained in the two sections immediately above), any changes to the way components are loaded in one file must also be made to the other file in order to keep styling consistent between the two. For example, if an import is excluded in `_bootstrap-custom.scss`, the same import should be excluded in `bootstrap-sass-config.js` so that styling in the Rails server and the webpack dev server will be the same.
 
-## Rails View Helpers In-Depth
-Once the bundled files have been generated in your `app/assets/javascripts/generated` folder and you have exposed your components globally, you will want to run your code in your Rails views using the included helper method.
+### Linters
+The React on Rails generator can add linters and their recommended accompanying configurations to your project. There are two classes of linters: ruby linters and JavaScript linters.
 
-This is how you actually render the React components you exposed to `window` inside of `clientGlobals` (and `global` inside of `serverGlobals` if you are server rendering).
+##### JavaScript Linters
+JavaScript linters are **enabled by default**, but can be disabled by passing the `--skip-js-linters` flag (alias `j`) , and those that run in Node have been add to `client/package.json` under `devDependencies`.
 
-`react_component(component_name, props = {}, options = {})`
-+ **react_component_name:** Can be a React component, created using a ES6 class, or `React.createClass`, or a generator function that returns a React component.
-+ **props:** Ruby Hash which contains the properties to pass to the react object
-+ **options:**
-  + **generator_function:** default is false, set to true if you want to use a generator function rather than a React Component.
-  + **prerender:** enable server-side rendering of component. Set to false when debugging!
-  + **trace:** set to true to print additional debugging information in the browser. Defaults to true for development, off otherwise.
-  + **replay_console:** Default is true. False will disable echoing server-rendering logs to the browser. While this can make troubleshooting server rendering difficult, so long as you have the default configuration of logging_on_server set to true, you'll still see the errors on the server.
-+ Any other options are passed to the content tag, including the id
+##### Ruby Linters
+Ruby linters are **disabled by default**, but can be enabled by passing the `--ruby-linters` flag when generating. These linters have been added to your Gemfile in addition to the the appropriate Rake tasks.
 
-`def server_render_js(js_expression, options = {})`
+We really love using all the linters! Give them a try.
 
-This is a helper method that takes any JavaScript expression and returns the output from evaluating it. If you have more than one line that needs to be executed, wrap it in an IIFE. JS exceptions will be caught and console messages handled properly.
+#### Running the Linters
+To run the linters (runs all linters you have installed, even if you installed both Ruby and Node):
+
+```bash
+rake lint
+```
 
-## Developing with Webpack Dev Server
+Run this command to see all the linters available
+
+```bash
+rake -T lint
+```
+
+**Here's the list:**
+```bash
+rake lint               # Runs all linters
+rake lint:eslint        # eslint
+rake lint:js            # JS Linting
+rake lint:jscs          # jscs
+rake lint:rubocop[fix]  # Run Rubocop lint in shell
+rake lint:ruby          # Run ruby-lint as shell
+rake lint:scss          # See docs for task 'scss_lint'
+```
+
+## Developing with the Webpack Dev Server
 One of the benefits of using webpack is access to [webpack's dev server](https://webpack.github.io/docs/webpack-dev-server.html) and its [hot module replacement](https://webpack.github.io/docs/hot-module-replacement-with-webpack.html) functionality.
 
 The webpack dev server with HMR will apply changes from the code (or styles!) to the browser as soon as you save whatever file you're working on. You won't need to reload the page, and your data will still be there. Start foreman as normal (it boots up the Rails server *and* the webpack HMR dev server at the same time).
@@ -185,19 +308,22 @@ Note that **React-related error messages are typically significantly more helpfu
 ### Adding Additional Routes for the Dev Server
 As you add more routes to your front-end application, you will need to make the corresponding API for the dev server in `client/server.js`. See our example `server.js` from our [tutorial](https://github.com/shakacode/react-webpack-rails-tutorial/blob/master/client/server.js).
 
-## Additional Documentation:
-
-+ [Linters](docs/linters.md)
-+ [Manual Configuration](docs/manual_configuration.md)
-+ [Node Dependencies and NPM](docs/node_dependencies_and_npm.md)
+## Additional Reading
++ [Generated Client Code](docs/additional_reading/generated_client_code.md)
++ [Heroku Deployment](docs/additional_reading/heroku_deployment.md)
++ [Manual Installation](docs/additional_reading/manual_installation.md)
++ [Node Dependencies and NPM](docs/additional_reading/node_dependencies_and_npm.md)
++ [Optional  Configuration](docs/additional_reading/optional_configuration.md)
++ [Server Rendering Tips](docs/additional_reading/server_rendering_tips.md)
++ [Tips](docs/additional_reading/tips.md)
 
 ## Contributing
-Bug reports and pull requests are welcome. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to our version of the [Contributor Covenant](contributor-covenant.org) code of conduct (see [CODE OF CONDUCT](CODE_OF_CONDUCT.md)).
+Bug reports and pull requests are welcome. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to our version of the [Contributor Covenant](contributor-covenant.org) code of conduct (see [CODE OF CONDUCT](docs/code_of_conduct.md)).
 
-See [Contributing](docs/Contributing.md) to get started.
+See [Contributing](docs/contributing.md) to get started.
 
 ## License
-The gem is available as open source under the terms of the [MIT License](LICENSE).
+The gem is available as open source under the terms of the [MIT License](docs/LICENSE).
 
 ## Authors
 [The Shaka Code team!](http://www.shakacode.com/about/)
@@ -214,7 +340,7 @@ And based on the work of the [react-rails gem](https://github.com/reactjs/react-
 
 ## About [ShakaCode](http://www.shakacode.com/)
 
-Visit [our forums!](http://forum.shakacode.com)
+Visit [our forums!](http://forum.shakacode.com). We've got a [category dedicated to react_on_rails](http://forum.shakacode.com/c/rails/reactonrails). 
 
 If you're looking for consulting on a project using React and Rails, email us ([contact@shakacode.com](mailto: contact@shakacode.com))! You can also join our slack room for some free advice.
 

data/docs/{gen-notes/reducers.md → additional_reading/generated_client_code.md}

@@ -1,4 +1,8 @@
-# Reducers
+# React Syntax
+## Communication Between Components
+See https://facebook.github.io/react/tips/communicate-between-components.html
+
+# Redux Reducers
 Documentation of generated Redux code for reducers.
 
 ## Example

data/docs/additional_reading/heroku_deployment.md

@@ -0,0 +1,21 @@
+# Heroku Deployment
+The generator has created the necessary files and gems for deployment to Heroku. If you have installed manually, you will need to provide these files yourself:
+
++ `Procfile`: used by Heroku and Foreman to start the server
++ `.buildpacks`: used to install Ruby and Node environments
++ `12factor` gem: required by Heroku
++ `lib/tasks/assets.rake`: rake task that generates your JavaScript bundles for production.
+
+## How to Deploy
+
+React on Rails requires both a ruby environment (for Rails) and a Node environment (for Webpack), so you will need to have Heroku use multiple buildpacks. Currently, we would suggest using [DDollar's Heroku Buildpack Multi](https://github.com/ddollar/heroku-buildpack-multi).
+
+Assuming you have downloaded and installed the Heroku command-line utility and have initialized the app, you will need to tell Heroku to use Heroku Buildpack Multi via the command-line:
+
+```
+heroku buildpacks:set https://github.com/heroku/heroku-buildpack-multi
+```
+
+Heroku will now be able to use the multiple buildpacks specified in `.buildpacks`. 
+
+Note, an alternative approach is to use the [Heroku Toolbelt to set buildpacks](https://devcenter.heroku.com/articles/using-multiple-buildpacks-for-an-app).

data/docs/{manual_configuration.md → additional_reading/manual_installation.md}

@@ -1,4 +1,4 @@
-## Manual Installation
+# Manual Installation
 Follow these steps if you choose to forgo the generator:
 
 1. Globally expose React in your webpack config like [this](https://github.com/shakacode/react-webpack-rails-tutorial/blob/537c985dc82faee333d80509343ca32a3965f9dd/client/webpack.client.base.config.js#L31):
@@ -55,7 +55,7 @@ See the next section for a sample webpack.server.rails.config.js.
 { test: require.resolve('react-dom/server'), loader: 'expose?ReactDOMServer' }, // not in client one, only server
 ```
 
-#### Sample webpack.server.rails.config.js (ONLY for server rendering)
+### Sample webpack.server.rails.config.js (ONLY for server rendering)
 Be sure to check out the latest example version of [client/webpack.server.rails.config.js](https://github.com/shakacode/react-webpack-rails-tutorial/blob/master/client/webpack.server.rails.config.js).
 
 ```javascript
@@ -91,7 +91,7 @@ module.exports = {
 };
 ```
 
-### What Happens?
+## What Happens?
 
 Here's what the browser will render with a call to the `react_component` helper.
 ![2015-09-28_20-24-35](https://cloud.githubusercontent.com/assets/1118459/10157268/41435186-6624-11e5-9341-6fc4cf35ee90.png)
@@ -112,7 +112,7 @@ Here's what the browser will render with a call to the `react_component` helper.
   * **replay_console**: <true/false> Default is true. False will disable echoing server rendering logs, which can make troubleshooting server rendering difficult.
   * Any other options are passed to the content tag, including the id.
 
-## JavaScript
+# JavaScript
 
 1. Configure your webpack configuration to create the file used for server rendering if you plan to do server rendering.
 2. Follow the examples in `spec/dummy/client/app/startup/clientGlobals.jsx` to expose your react components for client side rendering.
@@ -128,65 +128,6 @@ Here's what the browser will render with a call to the `react_component` helper.
   global.HelloWorld = HelloWorld;
   ```
 
-## Server Rendering 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.
-
-You might do something like this in some file for your top level component:
-```javascript
-global.App = () => <MyComponent serverSide={true} />;
-```
-
-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 sie.
-
-## Optional Configuration
-
-Create a file `config/react_on_rails.rb` to override any defaults. If you don't specify this file,
-the default options are below.
-
-The `server_bundle_js_file` must correspond to the bundle you want to use for server rendering.
-
-```ruby
-# Shown below are the defaults for configuration
-ReactOnRails.configure do |config|
-  # Client bundles are configured in application.js
-  # Server bundle is a single file for all server rendering of components.
-  # Set the server_bundle_js_file to "" if you know that you will not be server rendering.
-  config.server_bundle_js_file = "app/assets/javascripts/generated/server.js" # This is the default
-
-  # Below options can be overriden by passing to the helper method.
-  config.prerender = false # default is false
-  config.generator_function = false # default is false, meaning that you expose ReactComponents directly
-  config.trace = Rails.env.development? # default is true for development, off otherwise
-
-  # For server rendering. This can be set to false so that server side messages are discarded.
-  config.replay_console = true # Default is true. Be cautious about turning this off.
-  config.logging_on_server = true # Default is true. Logs server rendering messags to Rails.logger.info
-
-  # Settings for the pool of renderers:
-  config.server_renderer_pool_size  ||= 1  # ExecJS doesn't allow more than one on MRI
-  config.server_renderer_timeout    ||= 20 # seconds
-end
-```
-
-You can configure your pool of JS virtual machines and specify where it should load code:
-
-- On MRI, use `therubyracer` for the best performance (see [discussion](https://github.com/reactjs/react-rails/pull/290))
-- On MRI, you'll get a deadlock with `pool_size` > 1
-- If you're using JRuby, you can increase `pool_size` to have real multi-threaded rendering.
-
-## Tips
-+ **DO NOT RUN `rails s`** and instead run `foreman start -f Procfile.dev`
-+ The default for rendering right now is `prerender: false`. **NOTE:**  Server side rendering does not work for some components, namely react-router, that use an async setup for server rendering. You can configure the default for prerender in your config.
-+ You can expose either a React component or a function that returns a React component. If you wish to create a React component via a function, rather than simply props, then you need to set the property "generator" on that function to true. When that is done, the function is invoked with a single parameter of "props", and that function should return a React element.
-+ Be sure you can first render your react component client only before you try to debug server rendering!
-+ Open up the HTML source and take a look at the generated HTML and the JavaScript to see what's going on under the covers. Note that when server rendering is turned on, then you'll see the server rendered react components. When server rendering is turned off, then you'll only see the `div` element where the in-line JavaScript will render the component. You might also notice how the props you pass (a Ruby Hash) becomes in-line JavaScript on the HTML page.
-
 ## React 0.13 vs. React 0.14
 The main difference for using react_on_rails is that you need to add additional lines in the webpack config files: