react_on_rails 11.1.7 → 11.3.1.beta.0

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/api/view-helpers-api.md

@@ -10,21 +10,25 @@ Once the bundled files have been generated in your `app/assets/webpack` folder a
 ```ruby
 react_component(component_name,
                 props: {},
-                prerender: nil,
-                trace: nil,
-                replay_console: nil,
-                raise_on_prerender_error: nil,
-                id: nil,
+                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 generator 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`.
+  - **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:**
@@ -41,7 +45,7 @@ adding meta-tags to a page. It is exactly like react_component except for the fo
 
 1. `prerender: true` is automatically added to options, as this method doesn't make sense for 
    client only rendering.
-2. Your JavaScript for server rendering must return an Object for the key `server_rendered_html`.
+2. Your JavaScript generator 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:
@@ -89,7 +93,7 @@ end %>
 
 ### rails_context
 
-You can call `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.
+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`.
 
 ------------
 

data/docs/basics/configuration.md

@@ -124,7 +124,6 @@ ReactOnRails.configure do |config|
   # While you may configure this to be the same as your client bundle file, this file is typically
   # 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"
 
@@ -145,10 +144,11 @@ ReactOnRails.configure do |config|
   #
   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.
+  # 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 = false
+  config.raise_on_prerender_error = Rails.env.development? 
 
   ################################################################################
   # Server Renderer Configuration for ExecJS

data/docs/basics/generator-details.md

@@ -44,7 +44,7 @@ More Details:
 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*.
+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:
 

data/docs/basics/minitest-configuration.md

@@ -0,0 +1,31 @@
+# Minitest Configuration
+
+The setup for minitest is the same as for rspec with the following difference.
+
+Rather than calling `ReactOnRails::TestHelper.configure_rspec_to_compile_assets(config)`, instead you will do something like this:
+
+```ruby
+class ActiveSupport::TestCase
+  setup do
+    ReactOnRails::TestHelper.ensure_assets_compiled
+  end
+end    
+```
+
+
+Or maybe something like this, from the [minitest docs](https://github.com/seattlerb/minitest/blob/master/lib/minitest/test.rb#L119):
+
+```ruby
+module MyMinitestPlugin
+  def before_setup
+    super
+    ReactOnRails::TestHelper.ensure_assets_compiled
+  end
+end
+
+class MiniTest::Test
+  include MyMinitestPlugin
+end
+```
+
+ 

data/docs/basics/react-server-rendering.md

@@ -1,5 +1,7 @@
 # React Server Rendering
 
+See also [Client vs. Server Rendering](./client-vs-server-rendering.md)
+
 ## What is Server Rendering?
 
 Here's a [decent article to introduce you to server rendering](https://medium.freecodecamp.org/server-side-rendering-your-react-app-in-three-simple-steps-7a82b95db82e). Note, React on Rails takes care of calling the methods in [ReactDOMServer](https://reactjs.org/docs/react-dom-server.html).
@@ -8,7 +10,7 @@ During the Rails rendering of HTML per a browser request, the Rails server will
 
 The default JavaScript interpretter is [ExecJS](https://github.com/rails/execjs). 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).
 
-See [this note](basics/how-react-on-rails-works.md#client-side-rendering-vs-server-side-rendering)
+See [this note](./how-react-on-rails-works.md#client-side-rendering-vs-server-side-rendering)
 
 
 ## How do you do Server Rendering with React on Rails?

data/docs/basics/recommended-project-structure.md

@@ -17,7 +17,7 @@ app/javascript:
 The problems with this structure and using rails/webpacker to configure Webpack for you:
 
 1. No support for different entry points for server rendering.
-2. Webpacker adds an ex``tra layer of abstraction over Webpack, which you probably don't want.
+2. Webpacker adds an extra layer of abstraction over Webpack, which you probably don't want.
 
 This default rails/webpacker configuration is used for the generator because:
 
@@ -28,6 +28,29 @@ This default rails/webpacker configuration is used for the generator because:
 
 Thus, the generator structure and using rails/webpacker for Webpack configuration **is not recommended** for any commercial projects, especially those that will use server rendering. Instead, the recommended structure is shown in this example app: [github.com/shakacode/react-webpack-rails-tutorial](https://github.com/shakacode/react-webpack-rails-tutorial) and described below.
 
+## Steps to convert from the generator defaults to use the recommended `/client` directory structure.
+
+1. Move the directory:
+
+```
+mv app/javascript client
+```
+
+2. Edit your `/config/webpacker.yml` file. Change the `default/source_path`:
+
+```yml
+  source_path: client
+```
+
+## Moving node_modules from `/` to `/client` with a custom webpack setup.
+
+`rails/webpacker` probably doesn't support having your main node_modules directory under `/client`, so only follow these steps if you want to use your own webpack configuration (which is highly recommended!).
+
+1. Move the `/package.json` to `/client/package.json`
+2. Create a `/package.json` that delegates to `/client/package.json`. See the example in [spec/dummy/package.json](../../spec/dummy/package.json).
+3. See the webpack configuration in [spec/dummy/client](../../spec/dummy/client) for a webpack configuration example.
+
+
 ## JavaScript Assets
 1. `/client`: All client side JavaScript goes under the `/client` directory. Place all the major domains of the client side app under client.
 1. `/client/app`: All application JavaScript. Note the adherence to the [Airbnb JavaScript Style Guide](https://github.com/airbnb/javascript#naming-conventions) where we name the files to correspond to exported Objects (PascalCase) or exported functions (camelCase). We don't use dashes or snake_case for JavaScript files, except for possibly some config files.

data/docs/basics/rspec-configuration.md

@@ -1,4 +1,6 @@
 # RSpec Configuration
+_Click [here for minitest](./minitest-configuration.md)_
+
 Because you will probably want to run RSpec tests that rely on compiled webpack assets (typically, your integration/feature specs where `js: true`), you will want to ensure you don't accidentally run tests on missing or stale webpack assets. If you did use stale Webpack assets, you will get invalid test results as your tests do not use the very latest JavaScript code.
 
 ReactOnRails provides a helper method called `ReactOnRails::TestHelper.configure_rspec_to_compile_assets`. Call this method from inside of the `RSpec.configure` block in your `spec/rails_helper.rb` file, passing the config as an argument. See file [lib/react_on_rails/test_helper.rb](../../lib/react_on_rails/test_helper.rb) for more details. You can customize this to your particular needs by replacing any of the default components used by `ReactOnRails::TestHelper.configure_rspec_to_compile_assets`.
@@ -55,8 +57,6 @@ If you want to speed up the re-compiling process so you don't wait to run your t
 
 [spec/dummy](https://github.com/shakacode/react_on_rails/tree/master/spec/dummy) contains examples of how to set the proc files for this purpose.
 
-If you want to use a testing framework other than RSpec, please submit let us know on the changes you need to do and we'll update the docs.
-
 ![2016-01-27_02-36-43](https://cloud.githubusercontent.com/assets/1118459/12611951/7c56d070-c4a4-11e5-8a80-9615f99960d9.png)
 
 ![2016-01-27_03-18-05](https://cloud.githubusercontent.com/assets/1118459/12611975/a8011654-c4a4-11e5-84f9-1baca4835b4b.png)

data/docs/basics/upgrading-react-on-rails.md

@@ -5,12 +5,22 @@ If you would like help in migrating between React on Rails versions or help with
 
 We specialize in helping companies to quickly and efficiently move from versions before 9 to current. The older versions use the Rails asset pipeline to package client assets. The current and recommended way is to use Webpack 4 for asset preparation. You may also need help migrating from the `rails/webpacker`'s Webpack configuration to a better setup ready for Server Side Rendering.
 
+## Upgrading rails/webpacker from v3 to v4
+### Custom Webpack build file
+The default value for `extract_css` is **false** in `config/webpack.yml`. Custom webpack builds should set this value to true or else no CSS link tags are generated. You have a custom webpack build if you are not using [rails/webpacker](https://github.com/rails/webpacker to setup your Webpack configuration.
+
+  ```yml
+  default: &default
+     # other stuff
+     extract_css: true
+     # by default, extract and emit a css file. The default is false
+  ```
+
 ## Upgrading to version 11
 * Remove `server_render_method` from config/initializers/react_on_rails.rb. Alternate server rendering methods are part of React on Rails Pro. If you want to use a custom renderer, contact justin@shakacode.com. We have a custom node rendering solution in production for egghead.io.
 * Remove your usage of ENV["TRACE_REACT_ON_RAILS"] usage. You can get all tracing with either specifying **`trace`** at your component or in your config/initializers/react_on_rails.rb file.
 * ReactOnRails::Utils.server_bundle_file_name and ReactOnRails::Utils.bundle_file_name were removed. React on Rails Pro contains upgrades to enable component and other types caching with React on Rails.
 
-
 ## Upgrading to version 10
 
 Pretty simple:

data/docs/basics/webpack-configuration.md

@@ -1,5 +1,16 @@
 # Webpack Configuration: custom setup for Webpack or rails/webpacker?
 
+## Webpack vs. rails/webpacker 
+
+[Webpack](https://webpack.js.org) is the JavaScript npm package that prepares all your client-side assets. The Rails asset pipeline used to be the preferable way to prepare client-side assets. 
+
+[rails/webpacker](https://github.com/rails/webpacker) is the Ruby gem that mainly gives us 2 things:
+
+1. View helpers for placing the Webpack bundles on your Rails views. React on Rails depends on these view helpers.
+2. A layer of abstraction on top of Webpack customization. This is great for demo projects, but most real world projects will want a customized version of Webpack.
+
+# React on Rails
+
 Version 9 of React on Rails added support for the rails/webpacker view helpers so that Webpack produced assets would no longer pass through the Rails asset pipeline. As part of this change, React on Rails added a configuration option to support customization of the node_modules directory. This allowed React on Rails to support the rails/webpacker configuration of the Webpack configuration.
 
 A key decision in your use React on Rails is whether you go with the rails/webpacker default setup or the traditional React on Rails setup of putting all your client side files under the `/client` directory. While there are technically 2 independent choices involved, the directory structure and the mechanism of Webpack configuration, for simplicity sake we'll assume that these choices go together.

data/docs/misc-pending/code-splitting.md

@@ -21,7 +21,7 @@ Different markup is generated on the client than on the server. Why does this ha
 
 ### The solution
 
-To prevent this, you have to wait until the code chunk is fetched before doing the initial render on the client side. To accomplish this, react on rails allows you to register a renderer. This works just like registering a generator function, except that the function you pass takes three arguments: `renderer(props, railsContext, domNodeId)`, and is responsible for calling `ReactDOM.render` to render the component to the DOM. React on rails will automatically detect when a generator function takes three arguments, and will not call `ReactDOM.render`, instead allowing you to control the initial render yourself.
+To prevent this, you have to wait until the code chunk is fetched before doing the initial render on the client side. To accomplish this, react on rails allows you to register a renderer. This works just like registering a generator function, except that the function you pass takes three arguments: `renderer(props, railsContext, domNodeId)`, and is responsible for calling `ReactDOM.render` or `ReactDOM.hydrate` to render the component to the DOM. React on rails will automatically detect when a generator function takes three arguments, and will not call `ReactDOM.render` or `ReactDOM.hydrate`, instead allowing you to control the initial render yourself. Note, you have to be careful to call `ReactDOM.hydrate` rather than `ReactDOM.render` if you are are server rendering.
 
 Here's an example of how you might use this in practice:
 
@@ -115,7 +115,7 @@ See:
 
 - [spec/dummy/client/app/startup/clientRegistration.jsx](https://github.com/shakacode/react_on_rails/tree/master/spec/dummy/client/app/startup/clientRegistration.jsx)
 - [spec/dummy/client/app/startup/serverRegistration.jsx](https://github.com/shakacode/react_on_rails/tree/master/spec/dummy/client/app/startup/serverRegistration.jsx)
-- [spec/dummy/client/app/startup/DeferredRenderAppRenderer.jsx](https://github.com/shakacode/react_on_rails/tree/master/spec/dummy/client/app/startup/DeferredRenderAppRenderer.jsx) <-- Code splitting implemented here
+- [spec/dummy/client/app/startup/DeferredRenderAppClient](https://github.com/shakacode/react_on_rails/tree/master/spec/dummy/client/app/startup/DeferredRenderAppClient.jsx)<-- Code splitting implemented here
 - [spec/dummy/client/app/startup/DeferredRenderAppServer.jsx](https://github.com/shakacode/react_on_rails/tree/master/spec/dummy/client/app/startup/DeferredRenderAppServer.jsx)
 - [spec/dummy/client/app/components/DeferredRender.jsx](https://github.com/shakacode/react_on_rails/tree/master/spec/dummy/client/app/components/DeferredRender.jsx)
 - [spec/dummy/client/app/components/DeferredRenderAsyncPage.jsx](https://github.com/shakacode/react_on_rails/tree/master/spec/dummy/client/app/components/DeferredRenderAsyncPage.jsx)

data/docs/misc-pending/manual-installation-overview.md

@@ -24,7 +24,7 @@ The default path: `public/webpack` can be loaded with webpackConfigLoader as sho
 1. Add  `gem "webpacker"` to the Gemfile, run bundle. The gem provides the `stylesheet_pack_tag` and `javascript_pack_tag` helpers which is used to load the bundled assets to your layouts.[Dummy Example](../../spec/dummy/app/views/layouts/application.html.erb)
 1. Configure the `config/initializers/react_on_rails.rb`. You can adjust some necessary settings and defaults. See file [spec/dummy/config/initializers/react_on_rails.rb](../../spec/dummy/config/initializers/react_on_rails.rb) for a detailed example of configuration, including comments on the different values to configure.
 1. Configure your Procfiles per the example apps. These are at the root of your Rails installation.
-1. Configure your top level JavaScript files for inclusion in your layout. You'll want a version that you use for static assets, and you want a file for any files in your setup that are not part of your webpack build. The reason for this is for use with hot-reloading. If you are not using hot reloading, then you only need to configure your `application.js` file to include your Webpack generated files. For more information on hot reloading, see [Hot Reloading of Assets For Rails Development](../additional-reading/hot-reloading-rails-development.md)
+1. Configure your top level JavaScript files for inclusion in your layout. You'll want a version that you use for static assets, and you want a file for any files in your setup that are not part of your webpack build. The reason for this is for use with hot-reloading. If you are not using hot reloading, then you only need to configure your `application.js` file to include your Webpack generated files. For more information on hot reloading, see [Hot Reloading of Assets For Rails Development](../additional-reading/hot-reloading-rails-development-asset-pipeline.md)
 1. If you are deploying to Heroku, see [heroku-deployment.md](/docs/additional-reading/heroku-deployment.md)
 
 If I missed anything, please submit a PR or file an issue.

data/docs/testimonials/hvmn.md

@@ -0,0 +1,25 @@
+# HVMN Testimonial, Written by Paul Benigeri, October 12, 2018
+
+For some years, we used React on Rails for server-side rendering at [HVMN](https://hvmn.com). Our entire backend was already built in Rails, and we love React. As a content & e-commerce site, server-side rendering is critical, for UX performance and SEO crawler indexing.
+
+During the 12 months leading up to our React on Rails Pro transition, our traffic grew 10x. Our team of 2 engineers was focused on shipping features, and we started to face performance issues. We had some fragment caching of our React server rending, but it didn’t work that well.
+
+I discussed our growing pains with Justin, and as it turned out, ShakaCode just came out with React on Rails Pro and set it up on [egghead.io](https://egghead.io). The performance improvements were impressive, and Justin’s team was an ideal partner to help with the integration.
+
+We decided to give it a shot. Over three weeks, the ShakaCode team helped us migrate to React on Rails Pro, set up Webpack v4, migrated our entire asset pipeline to Webpack v4.
+
+Results were great. Our blog and product pages are 80-90% faster after that effort. The improved fragment caching was quick to set up and made a huge dent in our average server response times. We also observed an additional drop in response times when ShakaCode shipped the standalone Node server-side React renderer.
+
+Working with ShakaCode was a pleasure. Justin is one of the smartest Rails architects I know, and his team was responsive and productive.
+
+The price we paid for the consultation + the React on Rails pro license has already been made back a couple of times from hosting fees alone. The entire process was super hands off, and our core team was able to focus on shipping new feature during that sprint.
+
+If you have any questions, please reach out.
+
+Paul Benigeri, Head of E-Commerce
+
+[paul@hvmn.com](mailto:paul@hvmn.com), [LinkedIn](https://www.linkedin.com/in/benigeri/)
+
+Related Article: [HVMN’s 90% Reduction in Server Response Time from React on Rails Pro](https://blog.shakacode.com/hvmns-90-reduction-in-server-response-time-from-react-on-rails-pro-eb08226687db)
+
+[![image](https://user-images.githubusercontent.com/1118459/46911126-577abd00-ceee-11e8-86c6-6703ff80fc2f.png)](https://www.linkedin.com/in/benigeri/)

data/docs/testimonials/resortpass.md

@@ -0,0 +1,13 @@
+# ResortPass Testimonial, by Leora Juster, December 10, 2018
+
+Many can write code that "works." Even fewer can write sophisticated code that both works and reflects a deep understanding of the technologies and paradigms involved. Only a select few can do the aforementioned while assisting in managing the expectations and time constraints of less technically informed members of software product teams to make the best design decisions possible. Justin and his team were instrumental in assisting us in setting design foundations and standards for our transition to a react on rails application. Just three months of work with the team at Shaka code and we have a main page of our application server-side rendering at exponentially improved speeds. The code and CSS files are well-organized and contain repeatable patterns easy to understand, allowing my team to build on what has already been accomplished. I learned a great deal from my interactions with Justin and his team, as they are just as great teachers as they are developers, and feel like I get to continually learn from them as I build on top of their code. Their different support and pro plan options make it easy to build a continuous professional relationship despite fluctuations in my team's funding, and their team is always extremely personable, punctual, and professional. 
+
+Leora Juster, Full-Stack Lead Software Developer
+
+[LinkedIn](https://www.linkedin.com/in/leora-juster-38933050)
+
+![image](https://user-images.githubusercontent.com/1118459/50050877-30399b00-00ab-11e9-9e52-2977de45ccae.png)
+
+[ResortPass](https://resortpass.com/)
+
+[![2018-12-15_20-48-35](https://user-images.githubusercontent.com/1118459/50050866-03858380-00ab-11e9-8588-461112f8045b.png)](https://resortpass.com/)

data/docs/testimonials/testimonials.md

@@ -0,0 +1,28 @@
+# Testimonials
+# [HVMN Testimonial, Written by Paul Benigeri, October 12, 2018](./hvmn.md)
+
+> The price we paid for the consultation + the React on Rails pro license has already been made back a couple of times from hosting fees alone. The entire process was super hands off, and our core team was able to focus on shipping new feature during that sprint.
+
+Full writeup [here](./hvmn.md).
+
+---
+
+# [Leora from ResortPass](./resortpass.md), December 10, 2018
+
+Justin and his team were instrumental in assisting us in setting design foundations and standards for our transition to a react on rails application. Just three months of work with the team at Shaka code and we have a main page of our application server-side rendering at exponentially improved speeds. 
+
+Full writeup [here](./testimonials/resortpass.md).
+
+---
+
+From Joel Hooks, Co-Founder, Chief Nerd at [egghead.io](https://egghead.io/), January 30, 2017:
+
+![2017-01-30_11-33-59](https://cloud.githubusercontent.com/assets/1118459/22443635/b3549fb4-e6e3-11e6-8ea2-6f589dc93ed3.png)
+
+---
+
+From Kyle Maune of Cooper Aerial, May 4, 2018
+
+![image](https://user-images.githubusercontent.com/1118459/40891236-9b0b406e-671d-11e8-80ee-c026dbd1d5a2.png)
+
+For more testimonials, see [Live Projects](PROJECTS.md) and [Kudos](KUDOS.md).

data/docs/tutorial.md

@@ -1,6 +1,6 @@
 # React on Rails Basic Tutorial
 
-This tutorial guides you through setting up a new or existing Rails app with **React on Rails**, demonstrating Rails + React + Redux + Server Rendering. It is updated to 11.1.4.
+This tutorial guides you through setting up a new or existing Rails app with **React on Rails**, demonstrating Rails + React + Redux + Server Rendering. It is updated to 11.2.1.
 
 After finishing this tutorial you will get an application that can do the following (live on Heroku):
 
@@ -47,19 +47,20 @@ cd <directory where you want to create your new Rails app>
 rails new test-react-on-rails --webpack=react 
 
 cd test-react-on-rails
+bundle
 ```
 
-Note: if you are installing React On Rails in an existing app or an app that uses Rails pre 5.1.3, you will need to run these two commands as well:
+Note: if you are installing React On Rails in an existing app or an app that uses **Rails pre 5.1.3** (*not for Rails > 5.2*), you will need to run these two commands as well:
 
 ```
 bundle exec rails webpacker:install
 bundle exec rails webpacker:install:react
 ```
 
-Add the **React On Rails** gem to your Gemfile:
+Add the **React On Rails** gem to your `Gemfile`:
 
 ```
-gem 'react_on_rails', '11.1.4'         # prefer exact gem version to match npm version
+gem 'react_on_rails', '11.2.1'         # prefer exact gem version to match npm version
 ```
 
 Note: Latest released React On Rails version is considered stable. Please use the latest version to ensure you get all the security patches and the best support.
@@ -83,15 +84,40 @@ rails generate react_on_rails:install
 bundle && yarn
 ```
 
-and then run server with
+Then run server with static client side files:
 
 ```
 foreman start -f Procfile.dev
 ```
 
-Visit http://localhost:3000/hello_world and see your **React On Rails** app running!
+To run with the webpack-dev-server:
+```
+foreman start -f Procfile.dev-server
+```
+
+Visit [http://localhost:3000/hello_world](http://localhost:3000/hello_world) and see your **React On Rails** app running!
 Note, foreman defaults to PORT 5000 unless you set the value of PORT in your environment or in the Procfile.
 
+## Using a pre-release of rails/webpacker
+Until `rails/webpacker` v4 ships, or if you ever want to try out the master branch, you can modify the React on Rails tutorial instructions slightly. You can see the sequence of commits here. To summarize:
+
+**Don't run `rails new` with the `--webpack=react` option**. Instead, add the webpacker gem to the Gemfile such that it points to master, like this if `11.2.1` is the version you want.
+
+```ruby
+gem 'webpacker', github: "rails/webpacker"
+gem 'react_on_rails', '11.2.1' # always use exact version
+```
+
+Then run these commands:
+
+```sh
+bundle exec rails webpacker:install
+yarn add "rails/webpacker" # because the installer has a bug that puts in an invalid version in your package.json.
+bundle exec rails webpacker:install:react
+yarn add --dev webpack-dev-server
+run rails generate react_on_rails:install && bundle && yarn
+```
+
 ### Custom IP & PORT setup (Cloud9 example)
 
 In case you are running some custom setup with different IP or PORT you should also edit Procfile.dev. For example to be able to run on free Cloud9 IDE we are putting IP 0.0.0.0 and PORT 8080. The default generated file `Procfile.dev` uses `-p 3000`.
@@ -115,7 +141,7 @@ It's super important to exclude certain directories from RubyMine or else it wil
 ### Create Your Heroku App
 *Assuming you can login to heroku.com and have logged into to your shell for heroku.*
 
-1. Visit https://dashboard.heroku.com/new and create an app, say named `my-name-react-on-rails`:
+1. Visit [https://dashboard.heroku.com/new](https://dashboard.heroku.com/new) and create an app, say named `my-name-react-on-rails`:
 
 ![06](https://cloud.githubusercontent.com/assets/20628911/17465014/1f29bf3c-5cf4-11e6-869f-4215987ae854.png)
 
@@ -137,10 +163,11 @@ Set heroku to use multiple buildpacks:
    gem 'pg'
 ```
 
-![07](https://cloud.githubusercontent.com/assets/20628911/17465015/1f2f4042-5cf4-11e6-8287-2fb077550809.png)
+2. Run `bundle`
 
+![07](https://cloud.githubusercontent.com/assets/20628911/17465015/1f2f4042-5cf4-11e6-8287-2fb077550809.png)
 
-2. Replace your `database.yml` file with this (assuming your app name is "ror").
+3. Replace your `database.yml` file with this (assuming your app name is "ror").
 
 ```yml
 default: &default
@@ -185,11 +212,15 @@ root "hello_world#index"
 
 Next, configure your app for Puma, per the [instructions on Heroku](https://devcenter.heroku.com/articles/deploying-rails-applications-with-the-puma-web-server).
 
+Create `/Procfile`. This is what Heroku uses to start your app.
+
 `Procfile`
 ```
 web: bundle exec puma -C config/puma.rb
 ```
 
+Note, newer versions of Rails create this file automatically. However, the [docs on Heroku](https://devcenter.heroku.com/articles/deploying-rails-applications-with-the-puma-web-server#config) have something a bit different, so please make it conform to those docs. As of 2018-10-13, the docs looked like this:
+
 `config/puma.rb`
 ```rb
 workers Integer(ENV['WEB_CONCURRENCY'] || 2)
@@ -213,8 +244,89 @@ Then after all changes are done don't forget to commit them with git and finally
 
 ```
 git add -A
-git commit -m "Latest changes"
+git commit -m "Changes for Heroku"
+git push heroku master
+```
+
+Then run:
+
+```
+heroku open
+```
+
+and you will see your live app and you can share this URL with your friends. Congrats!
+
+
+## Turning on Server Rendering
+
+You can turn on server rendering by simply changing the `prerender` option to `true`:
+
+```erb
+<%= react_component("HelloWorld", props: @hello_world_props, prerender: true) %>
+```
+
+Then push to Heroku:
+
+```
+git add -A
+git commit -m "Enable server rendering"
 git push heroku master
 ```
 
-Feedback is greatly appreciated! As are stars on github! If you want personalized help, don't hesitate to get in touch with us at [contact@shakacode.com](mailto:contact@shakacode.com).
+When you look at the source code for the page (right click, view source in Chrome), you can see the difference between non-server rendering, where your DIV containing your React looks like this:
+
+```html
+<div id="HelloWorld-react-component-b7ae1dc6-396c-411d-886a-269633b3f604"></div>
+```
+
+versus with server rendering:
+
+```html
+<div id="HelloWorld-react-component-d846ce53-3b82-4c4a-8f32-ffc347c8444a"><div data-reactroot=""><h3>Hello, <!-- -->Stranger<!-- -->!</h3><hr/><form><label for="name">Say hello to:</label><input type="text" id="name" value="Stranger"/></form></div></div>
+```
+
+For more details on server rendering, see:
+
+  + [Client vs. Server Rendering](./basics/client-vs-server-rendering.md)
+  + [React Server Rendering](./basics/react-server-rendering.md)
+
+## Moving from the Rails default `/app/javascript` to the recommended `/client` structure
+
+ShakaCode recommends that you use `/client` for your client side app. This way a non-Rails, front-end developer can be at home just by opening up the `/client` directory.
+
+
+1. Move the directory:
+
+```
+mv app/javascript client
+```
+
+2. Edit your `/config/webpacker.yml` file. Change the `default/source_path`:
+
+```yml
+  source_path: client
+```
+
+## Using HMR with the rails/webpacker setup
+
+Start the app using `foreman start -f Procfile.dev-server`.
+
+When you change a JSX file and save, the browser will automatically refresh!
+
+So you get some basics from HMR with no code changes. If you want to go further, take a look at these links:
+
+* https://github.com/rails/webpacker/blob/master/docs/webpack-dev-server.md
+* https://webpack.js.org/configuration/dev-server/
+* https://webpack.js.org/concepts/hot-module-replacement/
+* https://gaearon.github.io/react-hot-loader/getstarted/
+* https://github.com/gaearon/react-hot-loader
+
+React on Rails will automatically handle disabling server rendering if there is only one bundle file created by the Webpack development server by rails/webpacker.
+
+## Conclusion
+
+* Browse the docs either on the [gitbook](https://shakacode.gitbooks.io/react-on-rails/content/) or in the [docs directory on github](https://github.com/shakacode/react_on_rails/tree/master/docs)
+
+Feedback is greatly appreciated! As are stars on github! 
+
+If you want personalized help, don't hesitate to get in touch with us at [contact@shakacode.com](mailto:contact@shakacode.com). We offer [React on Rails Pro](https://github.com/shakacode/react_on_rails/wiki) and consulting so you can focus on your app and not on how to make Webpack plus Rails work optimally.