react_on_rails 11.0.3 → 12.0.0

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](../../lib/react_on_rails/controller.rb) source
+* [lib/react_on_rails/helper.rb](../../lib/react_on_rails/helper.rb) source

data/docs/api/view-helpers-api.md

@@ -0,0 +1,133 @@
+# View and Controller Helpers
+##  View Helpers API
+
+Once the bundled files have been generated in your `app/assets/webpack` folder and you have registered your components, you will want to render these components on your Rails views using the included helper method, `react_component`.
+
+------------
+
+### react_component
+
+```ruby
+react_component(component_name,
+                props: {},
+                prerender: nil)
+                html_options: {})
+```
+
+Uncommonly used options:
+```
+  trace: nil,
+  replay_console: nil,
+  raise_on_prerender_error: nil,
+  id: nil,
+```
+
+- **component_name:** Can be a React component, created using an ES6 class or a render function that returns a React component (or, only on the server side, an object with shape { redirectLocation, error, renderedHtml }), or a "renderer function" that manually renders a React component to the dom (client side only).
+  All options except `props, id, html_options` will inherit from your `react_on_rails.rb` initializer, as described [here](../basics/configuration.md).
+- **general options:**
+  - **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.
+  - **prerender:** enable server-side rendering of a component. Set to false when debugging!
+  - **id:** Id for the div, will be used to attach the React component. This will get assigned automatically if you do not provide an id. Must be unique.
+  - **html_options:** Any other HTML options get placed on the added div for the component. For example, you can set a class (or inline style) on the outer div so that it behaves like a span, with the styling of `display:inline-block`. You may also use an option of `tag: "span"` to replace the use of the default DIV tag to be a SPAN tag.
+  - **trace:** set to true to print additional debugging information in the browser. Defaults to true for development, off otherwise. Only on the **client side** will you will see the `railsContext` and your props.
+  - **random_dom_id:** True to automatically generate random dom ids when using multiple instances of the same React component on one Rails view.
+- **options if prerender (server rendering) is true:**
+  - **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 configuration of `logging_on_server` set to true, you'll still see the errors on the server.
+  - **logging_on_server:** Default is true. True will log JS console messages and errors to the server.
+  - **raise_on_prerender_error:** Default is false. True will throw an error on the server side rendering. Your controller will have to handle the error.
+
+-------------
+
+### react_component_hash
+
+`react_component_hash` is used to return multiple HTML strings for server rendering, such as for
+adding meta-tags to a page. It is exactly like react_component except for the following:
+
+1. `prerender: true` is automatically added to options, as this method doesn't make sense for 
+   client only rendering.
+2. Your JavaScript render function for server rendering must return an Object rather than a React Component.
+3. Your view code must expect an object and not a string.
+
+Here is an example of ERB view code:
+
+```erb
+  <% react_helmet_app = react_component_hash("ReactHelmetApp", prerender: true,
+                                             props: { helloWorldData: { name: "Mr. Server Side Rendering"}},
+                                             id: "react-helmet-0", trace: true) %>
+  <% content_for :title do %>
+    <%= react_helmet_app['title'] %>
+  <% end %>
+  <%= react_helmet_app["componentHtml"] %>
+```
+
+And here is the JavaScript code:
+
+```js
+export default (props, _railsContext) => {
+  const componentHtml = renderToString(<ReactHelmet {...props} />);
+  const helmet = Helmet.renderStatic();
+
+  const renderedHtml = {
+    componentHtml,
+    title: helmet.title.toString(),
+  };
+  return { renderedHtml };
+};
+```
+
+------------
+
+### cached_react_component and cached_react_component_hash
+Fragment caching is a [React on Rails Pro](https://github.com/shakacode/react_on_rails/wiki) feature. The API is the same as the above, but for 2 differences:
+
+1. The `cache_key` takes the same parameters as any Rails `cache` view helper.
+1. The **props** are passed via a block so that evaluation of the props is not done unless the cache is broken. Suppose you put your props calculation into some method called `some_slow_method_that_returns_props`:
+
+```ruby
+<%= cached_react_component("App", cache_key: [@user, @post], prerender: true) do
+  some_slow_method_that_returns_props
+end %>
+```
+------------
+
+### rails_context
+
+You can call `rails_context` or `rails_context(server_side: true|false)` from your controller or view to see what values are are in the Rails Context. Pass true or false depending on whether you want to see the server side or the client side rails_context. Typically, for computing cache keys, you should leave server_side as the default true. When calling this from a controller method, use `helpers.rails_context`.
+
+------------
+
+### Renderer Functions (function that will call ReactDOM.render or ReactDOM.hydrate)
+
+A "renderer function" is a render function that accepts three arguments (rather than 2): `(props, railsContext, domNodeId) => { ... }`. Instead of returning a React component, a renderer is responsible for installing a callback that will call `ReactDOM.render` (in React 16+, `ReactDOM.hydrate`) to render a React component into the DOM. The "renderer function" is called at the same time the document ready event would instantate the React components into the DOM.
+
+Why would you want to call `ReactDOM.hydrate` yourself? One possible use case is [code splitting](docs/outdated/code-splitting.md). In a nutshell, you don't want to load the React component on the DOM node yet. So you want to install some handler that will call `ReactDOM.hydrate` at a later time. In the case of code splitting with server rendering, the server rendered code has any async code loaded and used to server render. Thus, the client code must also fully load any asynch code before server rendering. Otherwise, the client code would first render partially, not matching the server rendering, and then a second later, the full code would render, resulting in an unpleasant flashing on the screen.
+
+Renderer functions are not meant to be used on the server since there's no DOM on the server. Instead, use a render function. Attempting to server render with a renderer function will throw an error.
+
+------------
+
+### React Router
+
+[React Router](https://github.com/reactjs/react-router) is supported, including server-side rendering! See:
+
+1. [React on Rails docs for react-router](../additional-reading/react-router.md)
+2. Examples in [spec/dummy/app/views/react_router](../../spec/dummy/app/views/react_router) and follow to the JavaScript code in the [spec/dummy/client/app/startup/ServerRouterApp.jsx](../../spec/dummy/client/app/startup/ServerRouterApp.jsx).
+3. [Code Splitting docs](docs/outdated/code-splitting.md) for information about how to set up code splitting for server rendered routes.
+
+------------
+
+## 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 will be 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.
+
+------------
+
+# More details
+
+See the [lib/react_on_rails/helper.rb](../../lib/react_on_rails/helper.rb) source.
+

data/docs/articles.md

@@ -0,0 +1,20 @@
+# Articles, Videos, and Podcasts
+
+## Articles
+
+* [Introducing React on Rails v9 with Webpacker Support](https://blog.shakacode.com/introducing-react-on-rails-v9-with-webpacker-support-f2584c6c8fa4) for an overview of the integration of React on Rails with Webpacker.
+* [Webpacker Lite: Why Fork Webpacker?](https://blog.shakacode.com/webpacker-lite-why-fork-webpacker-f0a7707fac92)
+* [React on Rails, 2000+ 🌟 Stars](https://medium.com/shakacode/react-on-rails-2000-stars-32ff5cfacfbf#.6gmfb2gpy)
+* [The React on Rails Doctrine](https://medium.com/@railsonmaui/the-react-on-rails-doctrine-3c59a778c724)
+* [Simple Tutorial](docs/tutorial.md).
+
+## Videos
+
+*  [Video of running the v9 installer with Webpacker v3](https://youtu.be/M0WUM_XPaII). History, motivations, philosophy, and overview.
+1. [GORUCO 2017: Front-End Sadness to Happiness: The React on Rails Story by Justin Gordon](https://www.youtube.com/watch?v=SGkTvKRPYrk)
+2. [egghead.io: Creating a component with React on Rails](https://egghead.io/lessons/react-creating-a-component-with-react-on-rails)
+3. [egghead.io: Creating a redux component with React on Rails](https://egghead.io/lessons/react-add-redux-state-management-to-a-react-on-rails-project)
+4. [React On Rails Tutorial Series](https://www.youtube.com/playlist?list=PL5VAKH-U1M6dj84BApfUtvBjvF-0-JfEU)
+  1. [History and Motivation](https://youtu.be/F4oymbUHvoY)
+  2. [Basic Tutorial Walkthrough](https://youtu.be/_bjScw60FBk)
+  3. [Code Walkthrough](https://youtu.be/McQ9UM-_ocQ)

data/docs/basics/client-vs-server-rendering.md

@@ -0,0 +1,23 @@
+# Client-Side Rendering vs. Server-Side Rendering
+
+In most cases, you should use the `prerender: false` (default behavior) with the provided helper method to render the React component from your Rails views. In some cases, such as when SEO is vital, or many users will not have JavaScript enabled, you can enable server-rendering by passing `prerender: true` to your helper, or you can simply change the default in `config/initializers/react_on_rails`.
+
+Now the server will interpret your JavaScript. The default is to use [ExecJS](https://github.com/rails/execjs) and pass the resulting HTML to the client. We recommend using [mini_racer](https://github.com/discourse/mini_racer) as ExecJS's runtime.
+ 
+If you want to maximize the perfomance of your server rendering, then you want to use React on Rails Pro which uses NodeJS to do the server rendering. See the [docs for React on Rails Pro](https://github.com/shakacode/react_on_rails/wiki).
+
+If you open the HTML source of any web page using React on Rails, you'll see the 3 parts of React on Rails rendering:
+
+1. A script tag containing the properties of the React component, such as the registered name and any props. A JavaScript function runs after the page loads, using this data to build and initialize your React components.
+2. The wrapper div `<div id="HelloWorld-react-component-0">` specifies the div where to place the React rendering. It encloses the server-rendered HTML for the React component.
+3. Additional JavaScript is placed to console-log any messages, such as server rendering errors. Note: these server side logs can be configured only to be sent to the server logs.
+
+**Note**: If server rendering is not used (prerender: false), then the major difference is that the HTML rendered for the React component only contains the outer div: `<div id="HelloWorld-react-component-0"/>`. The first specification of the React component is just the same.
+
+# Different Server-Side Rendering Code (and a Server-Specific Bundle)
+
+You may want different code for your server-rendered components running server side versus client side. For example, if you have an animation that runs when a component is displayed, you might need to turn that off when server rendering. One way to handle this is conditional code like `if (window) { doClientOnlyCode() }`. 
+
+Another way is to use a separate webpack configuration file that can use a different server side entry file, like  'serverRegistration.js' as opposed to 'clientRegistration.js.' That would set up different code for server rendering.
+
+For details on techniques to use different code for client and server rendering, see: [How to use different versions of a file for client and server rendering](https://forum.shakacode.com/t/how-to-use-different-versions-of-a-file-for-client-and-server-rendering/1352). _Requires creating a free account._

data/docs/basics/configuration.md

@@ -1,66 +1,78 @@
 Here is the full set of config options. This file is `/config/initializers/react_on_rails.rb`
 
+First, you should have a `/config/webpacker.yml` setup.
+
+Here is the setup when using the recommended `/client` directory for your node_modules and source files:
+
+```yaml
+# Note: Base output directory of /public is assumed for static files
+default: &default
+  compile: false
+  # Used in your webpack configuration. Must be created in the
+  # public_output_path folder
+  manifest: manifest.json
+  cache_manifest: false
+  
+  # Source path is used to check if webpack compilation needs to be run for `compile: true`
+  source_path: client/app
+
+development:
+  <<: *default
+  # Generated files for development, in /public/webpack/dev
+  public_output_path: webpack/dev
+
+test:
+  <<: *default
+  # Ensure that webpacker invokes webpack to build files for tests if not using the
+  #   ReactOnRails rspec helper. 
+  compile: true
+
+  # Generated files for tests, in /public/webpack/test
+  public_output_path: webpack/test
+
+production:
+  <<: *default
+  # Generated files for production, in /public/webpack/production
+  public_output_path: webpack/production
+  cache_manifest: true
+```
+
+Here's a representative `/config/initializers/react_on_rails.rb` setup when using this `/client` directory
+for all client files, including your sources and node_modules.
+
+
 ```ruby
 # frozen_string_literal: true
 
 # NOTE: you typically will leave the commented out configurations set to their defaults.
 # Thus, you only need to pay careful attention to the non-commented settings in this file.
-
 ReactOnRails.configure do |config|
   # `trace`: General debugging flag.
   # The default is true for development, off otherwise.
   # With true, you get detailed logs of rendering and stack traces if you call setTimout, 
   # setInterval, clearTimout when server rendering.
-  config.trace = Rails.env.development?
-
-
-  # defaults to "" (top level)
-  #
-  config.node_modules_location = ""
-
-  # This configures the script to run to build the production assets by webpack. Set this to nil
-  # if you don't want react_on_rails building this file for you.
+  config.trace = Rails.env.development? # default
+
+  # Configure if default DOM IDs have a random value or are fixed.
+  # false ==> Sets the dom id to "#{react_component_name}-react-component"
+  # true ==> Adds "-#{SecureRandom.uuid}" to that ID
+  # If you might use multiple instances of the same React component on a Rails page, then
+  # it is convenient to set this to true or else you have to either manually set the ids to 
+  # avoid collisions. Most newer apps will have only one instance of a component on a page,
+  # so this should be false in most cases.
+  # This value can be overridden for a given call to react_component
+  config.random_dom_id = true # default
+
+  # defaults to "" (top level)	
+  config.node_modules_location = "client" # If using webpacker you should use "".	
+  
+  # This configures the script to run to build the production assets by webpack . Set this to nil	
+  # if you don't want react_on_rails building this file for you.	
+  # Note, if you want to use this command then you should remove the file	
+  # config/webpack/production.js	
+  # If that file exists, React on Rails thinks that you'll use the rails/webpacker bin/webpack compiler.	
   config.build_production_command = "RAILS_ENV=production bin/webpack"
 
-  ################################################################################
-  ################################################################################
-  # TEST CONFIGURATION OPTIONS
-  # Below options are used with the use of this test helper:
-  # ReactOnRails::TestHelper.configure_rspec_to_compile_assets(config)
-  ################################################################################
-
-  # If you are using this in your spec_helper.rb (or rails_helper.rb):
-  #
-  # ReactOnRails::TestHelper.configure_rspec_to_compile_assets(config)
-  #
-  # with rspec then this controls what yarn command is run
-  # to automatically refresh your webpack assets on every test run.
-  #
-  config.build_test_command = "RAILS_ENV=test bin/webpack"
-
-  # Directory where your generated assets go. All generated assets must go to the same directory.
-  # If you are using webpacker, this value will come from your config/webpacker.yml file. 
-  # This is the default in webpacker.yml:
-  #   public_output_path: packs-test
-  # which means files in /public/packs-test
-  #
-  # Alternately, you may configure this. It is relative to your Rails root directory.
-  # A custom, non-webpacker, config might use something like:
-  #
-  config.generated_assets_dir = File.join(%w[public webpack], Rails.env)
-
-  # The test helper needs to know where your JavaScript files exist. The default is configured
-  # by your config/webpacker.yml soure_path:
-  # source_path: app/javascript
-  #
-  # If you have a non-default `node_modules_location`, that is assumed to be the location of your source
-  # files.
-
-  # Define the files we need to check for webpack compilation when running tests.
-  # The default is `%w( manifest.json )` as will be sufficient for most webpacker builds.
-  #
-  config.webpack_generated_files = %w( manifest.json )
-
   ################################################################################
   ################################################################################
   # SERVER RENDERING OPTIONS
@@ -72,31 +84,43 @@ ReactOnRails.configure do |config|
   # JavaScript execution instances which should handle any component requested.
   #
   # While you may configure this to be the same as your client bundle file, this file is typically
-  # different.
-  #
+  # different. Note, be sure to include the exact file name with the ".js" if you are not hashing this file.
+  # If you are hashing this file (supposing you are using the same file for client rendering), then
+  # you should include a name that matches your bundle name in your webpack config.
   config.server_bundle_js_file = "server-bundle.js"
 
+  # THE BELOW OPTIONS FOR SERVER-SIDE RENDERING RARELY NEED CHANGING 
+  #
+  # This value only affects server-side rendering when using the webpack-dev-server 
+  # If you are hashing the server bundle and you want to use the same bundle for client and server,
+  # you'd set this to `true` so that React on Rails reads the server bundle from the webpack-dev-server.
+  # Normally, you have different bundles for client and server, thus, the default is false.
+  # Furthermore, if you are not hashing the server bundle (not in the manifest.json), then React on Rails
+  # will only look for the server bundle to be created in the typical file location, typically by
+  # a `webpack --watch` process.
+  # If true, ensure that in config/webpacker.yml that you have both dev_server.hmr and
+  # dev_server.inline set to false.
+  config.same_bundle_for_client_and_server = false
+  
   # If set to true, this forces Rails to reload the server bundle if it is modified
   # Default value is Rails.env.development?
-  #
+  # You probably will never change this.
   config.development_mode = Rails.env.development?
 
-  # For server rendering so that it replays in the browser console.
+  # For server rendering so that the server-side console replays in the browser console.
   # This can be set to false so that server side messages are not displayed in the browser.
-  # Default is true. Be cautious about turning this off.
+  # Default is true. Be cautious about turning this off, as it can make debugging difficult.
   # Default value is true
-  # 
   config.replay_console = true
 
   # Default is true. Logs server rendering messages to Rails.logger.info. If false, you'll only
   # see the server rendering messages in the browser console.
-  #
   config.logging_on_server = true
 
-  # Default is to false to NOT raise exception on server if the JS code throws.
-  # Reason is that it's easier to debug this when you get the error over to the client.
-  # 
-  config.raise_on_prerender_error = false
+  # Default is true only for development? to raise exception on server if the JS code throws for
+  # server rendering. The reason is that the server logs will show the error and force you to fix
+  # any server rendering issues immediately during development. 
+  config.raise_on_prerender_error = Rails.env.development? 
 
   ################################################################################
   # Server Renderer Configuration for ExecJS
@@ -120,6 +144,7 @@ ReactOnRails.configure do |config|
   # Replace the following line to the location where you keep translation.js & default.js for use
   # by the npm packages react-intl. Be sure this directory exists!
   # config.i18n_dir = Rails.root.join("client", "app", "libs", "i18n")
+  #
   # If not using the i18n feature, then leave this section commented out or set the value
   # of config.i18n_dir to nil.
   #
@@ -127,8 +152,12 @@ ReactOnRails.configure do |config|
   # that will source for automatic generation on translations.js & default.js
   # By default(without this option) all yaml files from Rails.root.join("config", "locales")
   # and installed gems are loaded
-  config.i18n_yml_dir = Rails.root.join("config", "locales", "client")
+  config.i18n_yml_dir = Rails.root.join("config", "locales")
   
+  # Possible output formats are js and json
+  # The default format is json
+  config.i18n_output_format = 'json'
+
   ################################################################################
   ################################################################################
   # CLIENT RENDERING OPTIONS
@@ -137,6 +166,61 @@ ReactOnRails.configure do |config|
   ################################################################################
   # default is false
   config.prerender = false
+
+  # You can optionally add values to your rails_context. This object is passed
+  # every time a component renders.
+  # See example below for an example definition of RenderingExtension
+  #
+  # config.rendering_extension = RenderingExtension
+
+  ################################################################################
+  ################################################################################
+  # TEST CONFIGURATION OPTIONS
+  # Below options are used with the use of this test helper:
+  # ReactOnRails::TestHelper.configure_rspec_to_compile_assets(config)
+  # 
+  # NOTE:
+  # Instead of using this test helper, you may ensure fresh test files using rails/webpacker via:
+  # 1. Have `config/webpacker/test.js` exporting an array of objects to configure both client and server bundles.
+  # 2. Set the compile option to true in config/webpacker.yml for env test
+  ################################################################################
+  
+  # If you are using this in your spec_helper.rb (or rails_helper.rb):
+  #
+  # ReactOnRails::TestHelper.configure_rspec_to_compile_assets(config)
+  #
+  # with rspec then this controls what yarn command is run
+  # to automatically refresh your webpack assets on every test run.
+  #
+  config.build_test_command = "RAILS_ENV=test bin/webpack"
+
+  # CONFIGURE YOUR SOURCE FILES 
+  # The test helper needs to know where your JavaScript files exist. The value is configured
+  # by your config/webpacker.yml source_path:
+  # source_path: client/app # if using recommended /client directory
+  #
+  # Define the files we need to check for webpack compilation when running tests.
+  # The default is `%w( manifest.json )` as will be sufficient for most webpacker builds.
+  # However, if you are generated a server bundle that is NOT hashed (present in manifest.json),
+  # then include the file in this list like this: 
+  config.webpack_generated_files = %w( server-bundle.js manifest.json )
+  # Note, be sure NOT to include your server-bundle.js if it is hashed, or else React on Rails will
+  # think the server-bundle.js is missing every time for test runs. 
 end
+```
+
+Example of a RenderingExtension for custom values in the `rails_context`:
 
+```ruby
+module RenderingExtension
+
+  # Return a Hash that contains custom values from the view context that will get merged with
+  # the standard rails_context values and passed to all calls to render functions used by the
+  # react_component and redux_store view helpers
+  def self.custom_context(view_context)
+    {
+     somethingUseful: view_context.session[:something_useful]
+    }
+  end
+end
 ```

data/docs/basics/deployment.md

@@ -0,0 +1,4 @@
+# Deployment
+
+- `rails/webpacker` puts the necessary precompile steps automatically in the rake precompile step. 
+- See the [Heroku Deployment](docs/basics/heroku-deployment.md) doc for specifics regarding Heroku. The information for Heroku may apply to other deployments.

data/docs/basics/{generator.md → 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.
 
@@ -41,13 +38,13 @@ Then you may run
 
 More Details:
 
-    `https://github.com/shakacode/react_on_rails/blob/master/docs/basics/generator.md`
+    `https://github.com/shakacode/react_on_rails/blob/master/docs/basics/generator-details.md`
 ```
 
 Another good option is to create a simple test app per the [Tutorial](../tutorial.md).
 
-### 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,7 +54,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/heroku-deployment.md

@@ -0,0 +1,24 @@
+# Heroku Deployment
+## Heroku buildpacks
+
+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.
+
+Assuming you have downloaded and installed the Heroku command-line utility and have initialized the app, you will need to tell Heroku to use both buildpacks via the command-line:
+
+```
+heroku buildpacks:set heroku/ruby
+heroku buildpacks:add --index 1 heroku/nodejs
+```
+
+For more information, see [Using Multiple Buildpacks for an App](https://devcenter.heroku.com/articles/using-multiple-buildpacks-for-an-app)
+
+## assets:precompile
+
+### rails/webpacker webpack configuration
+If you're using the standard rails/webpacker configuration of webpack, then rails/webpacker
+will automatically modify or create an assets:precompile task to build your assets.
+
+### custom webpack configuration
+If you're a custom webpack configuration, and you **do not have the default
+`config/webpack/production.js`** file, then the `config/initializers/react_on_rails.rb`
+configuration `config.build_production_command` will be used.