Doc fixes (#933)

NEWS.md

@@ -3,6 +3,7 @@
 *We'll keep a history of the news. A few bullets at the top will also show on the [README.md](./README.md).*
 
 * Always see the [CHANGELOG.md](./CHANGELOG.md) for the latest project changes.
+* [VERSION 8.1.0](https://rubygems.org/gems/react_on_rails/) shipped with [webpacker_lite](https://github.com/shakacode/webpacker_lite) (soon [**webpacker**](https://github.com/rails/webpacker/issues/464#issuecomment-310986140) support! [react-webpack-rails-tutorial PR #395](https://github.com/shakacode/react-webpack-rails-tutorial/pull/395) shows the changes needed to migrate from the Asset Pipeline to Webpacker Lite. For more information, see my article: [Webpacker Lite: Why Fork Webpacker?](https://blog.shakacode.com/webpacker-lite-why-fork-webpacker-f0a7707fac92). Per recent discussions, we [will merge Webpacker Lite changes back into Webpacker](https://github.com/rails/webpacker/issues/464#issuecomment-310986140). There's no reason to wait for this. The upgrade will eventually be trivial.
 * 2017-04-25: 7.0.0 Shipped! Performance improvements! Please upgrade! Only "breaking" change is that you have to update both the node module and the Ruby gem. 
 * 2017-04-09: 8.0.0 beta work to include webpacker_lite gem has begun. See [#786](https://github.com/shakacode/react_on_rails/issues/786).
 * 2017-04-03: 6.9.3 Released! Props rendered in JSON script tag. Page size is smaller now due to less escaping!

README.md

@@ -5,7 +5,7 @@
 [rails/webpacker](https://github.com/rails/webpacker) just shipped 3.0. This now enables me to ship version 9.0. See [PR #908](https://github.com/shakacode/react_on_rails/pull/908) for more details.
 # React on Rails v9 is based on Webpacker 3.0!
 
-* See the article React on Rails plus Webpacker, Peanut Butter and Jelly for an overview of the integration of React on Rails with Webpacker (article coming soon).
+* See the article [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. 
 * See the updated [Tutorial](https://github.com/shakacode/react_on_rails/blob/master/docs/tutorial.md).
 * See the [CHANGELOG.md](https://github.com/shakacode/react_on_rails/blob/master/CHANGELOG.md) for migration instructions.
 
@@ -24,21 +24,15 @@ Given that Webpacker already provides React integration, why would you add React
 ## Steps to a New App with rails/webpacker v3 plus React on Rails v9:
 First be sure to run `rails -v` and check that you are using Rails 5.1.3 or above. If you are using an older version of Rails, you'll need to install webpacker with React per the instructions [here](https://github.com/rails/webpacker).
 
-### Basic installation
+### Basic installation for a new Rails App
+*See below for steps on an existing Rails app*
 
-1. New Rails app: `rails new my-app --webpack=react`. `cd` into the directory.
+1. New Rails app: `rails new my-app --webpack=react`. `cd` into the directory. 
 2. Add gem version: `gem 'react_on_rails', '~> 9.0.1'`
 3. Run the generator: `rails generate react_on_rails:install`
-4. Start the app: `foreman start -f Procfile.dev`
+4. Start the app: `rails s`
 5. Visit http://localhost:3000/hello_world
 
-### Turn on HMR (Hot reloading)
-
-1. Edit `config/webpacker.yml` and set `hmr: true`
-2. Start the app: `foreman start -f Procfile.dev-server`
-3. Visit http://localhost:3000/hello_world
-4. Edit `app/javascript/bundles/HelloWorld/components/HelloWorld.jsx`, hit save, and see the screen update.
-
 ### Turn on server rendering
 
 *Does not work with hot reloading, yet, per [Webpacker issue #732](https://github.com/rails/webpacker/issues/732)*
@@ -126,7 +120,6 @@ For more testimonials, see [Live Projects](PROJECTS.md) and [Kudos](./KUDOS.md).
 
 # NEWS
 * 2017-09-06: **VERSION 9.0.0 shipped!** This version depends on Webpacker directly. See the [CHANGELOG.md](https://github.com/shakacode/react_on_rails/blob/master/CHANGELOG.md) for migration instructions.
-* [VERSION 8.1.0](https://rubygems.org/gems/react_on_rails/) shipped with [webpacker_lite](https://github.com/shakacode/webpacker_lite) (soon [**webpacker**](https://github.com/rails/webpacker/issues/464#issuecomment-310986140) support! [react-webpack-rails-tutorial PR #395](https://github.com/shakacode/react-webpack-rails-tutorial/pull/395) shows the changes needed to migrate from the Asset Pipeline to Webpacker Lite. For more information, see my article: [Webpacker Lite: Why Fork Webpacker?](https://blog.shakacode.com/webpacker-lite-why-fork-webpacker-f0a7707fac92). Per recent discussions, we [will merge Webpacker Lite changes back into Webpacker](https://github.com/rails/webpacker/issues/464#issuecomment-310986140). There's no reason to wait for this. The upgrade will eventually be trivial.
 * The Docs here on `master` refer to 9.x including support for [rails/webpacker](https://github.com/rails/webpacker).
 *Use the [7.0.4 docs](https://github.com/shakacode/react_on_rails/tree/7.0.4) to refer to the older asset pipeline way.*
 * *See [NEWS.md](NEWS.md) for more notes over time.*
@@ -135,9 +128,9 @@ For more testimonials, see [Live Projects](PROJECTS.md) and [Kudos](./KUDOS.md).
 
 # React on Rails
 
-**Project Objective**: To provide an opinionated and optimal framework for integrating Ruby on Rails with modern JavaScript tooling and libraries, including [**Webpack**](http://webpack.github.io/), [**Babel**](https://babeljs.io/), [**React**](https://facebook.github.io/react/), [**Redux**](https://github.com/reactjs/redux), [**React-Router**](https://github.com/reactjs/react-router). This differs significantly from typical Rails architecture. When considering what goes into **react_on_rails**, we ask ourselves, is the functionality related to the intersection of using Rails and modern JavaScript? If so, then the functionality belongs right here. In other cases, we're releasing separate npm packages or Ruby gems. If you are interested in implementing React using traditional Rails architecture, see [react-rails](https://github.com/reactjs/react-rails).
+**Project Objective**: To provide an opinionated and optimal framework for integrating Ruby on Rails with React via the [**Webpacker**](https://github.com/rails/webpacker) gem.
 
-React on Rails integrates Facebook's [React](https://github.com/facebook/react) front-end framework with Rails. React v0.14.x and greater is supported, with server rendering. [Redux](https://github.com/reactjs/redux) and [React-Router](https://github.com/reactjs/react-redux) are supported as well, also with server rendering, using **execJS**. 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!
+React on Rails integrates Facebook's [React](https://github.com/facebook/react) front-end framework with Rails. React v0.14.x and greater is supported, with server rendering. [Redux](https://github.com/reactjs/redux) and [React-Router](https://github.com/reactjs/react-redux) are supported as well, also with server rendering, using **execJS**. 
 
 ## Table of Contents
 
@@ -188,9 +181,9 @@ Universal React with Rails: Part I](https://medium.com/@alexfedoseev/isomorphic-
 
 To upgrade existing apps to React on Rails 8 see the [Installation Overview](docs/basics/installation-overview.md)
 
-## Getting Started
+## Getting Started with an existing Rails app
 
-**For more detailed instructions**, see the [React on Rails Basic Tutorial](docs/tutorial.md).
+**For more detailed instructions on a fresh Rails app**, see the [React on Rails Basic Tutorial](docs/tutorial.md).
 
 1. Add the following to your Gemfile and `bundle install`. We recommend fixing the version of React on Rails, as you will need to keep the exact version in sync with the version in your `client/package.json` file.
 

docs/additional-reading/hot-reloading-rails-development.md

@@ -1,3 +1,16 @@
+# Live Reloading vs. Hot Reloading (aka HMR)
+
+The use of the [webpack-dev-server](https://webpack.js.org/configuration/dev-server/) provides "Live Reloading" by default. The difference between live and hot reloading is that live reloading will act similarly to hitting refresh in the browser. Hot reloading will attempt to preserve the state of any props.
+
+See the Webpack document [Hot Module Replacement](https://webpack.js.org/concepts/hot-module-replacement/) for more details on the concepts of live vs. hot reloading.
+
+The remainder of this document discusses HMR.
+
+# Using the Webpacker Webpack setup
+
+If you are using the default Webpacker setup of running the dev server with `bin/webpack-dev-server`, see the [Webpacker Webpack Dev Server discussion of HMR](https://github.com/rails/webpacker/blob/master/docs/webpack-dev-server.md#hot-module-replacement).
+
+
 # Hot Reloading of Assets For Rails Development
 
 _Note, this document is not yet updated for React on Rails v8+. See [PR #865](https://github.com/shakacode/react_on_rails/pull/865) for a detailed example of doing hot reloading using V8+ with Webpack v2. Any volunteers to update this page? See [#772](https://github.com/shakacode/react_on_rails/issues/772) and [#361](https://github.com/shakacode/react-webpack-rails-tutorial/issues/361)._

docs/basics/generator.md

@@ -32,19 +32,12 @@ can pass the redux option if you'd like to have redux setup for you automaticall
     to integrate the Redux state container framework. The necessary node modules
     will be automatically included for you.
 
-* Node
-
-    Passing the --node generator option sets up the necessary files for node to render the react_components.
-
 *******************************************************************************
 
-After running the generator, you will want to:
-
-    bundle && yarn 
 
 Then you may run
 
-    foreman start -f Procfile.dev
+    `rails s`
 
 More Details:
 

lib/generators/react_on_rails/base_generator.rb

@@ -83,31 +83,33 @@ def self.helpful_message
 
           What to do next:
 
-            - Include your webpack assets to your application layout. Change hello-world-bundle as needed.
+            - See the documentation on https://github.com/rails/webpacker/blob/master/docs/webpack.md
+              for how to customize the default webpack configuration.
 
-                <%= javascript_pack_tag 'hello-world-bundle' %>
+            - Include your webpack assets to your application layout.
 
-            - Run the foreman command to start the rails server and run webpack in watch mode.
+                <%= javascript_pack_tag 'hello-world-bundle' %>
 
-                foreman start -f Procfile.dev
+            - Run `rails s` to start the Rails server and use Webpacker's default lazy compilation.
 
-            - Change this line app/views/hello_world/index.html.erb to `prerender: true` to see
-              server rendering (right click on page and select "view source").
+            - Visit http://localhost:3000/hello_world and see your React On Rails app running!
 
-                <%= react_component("HelloWorldApp", props: @hello_world_props, prerender: true) %>
+            - Run bin/webpack-dev-server to start the Webpack dev server for compilation of Webpack
+              assets assets as soon as you save. This default setup with the dev server does not work
+              for server rendering
 
-            - Run the foreman command to start the rails server and run webpack in HMR mode. Be sure
-              to change your development/dev_server/hmr setting to true to see HMR in action.
-              Note, you cannot use the default Procfile.dev-server setup with server rendering.
+            - Alternately, you may turn off compile in config/webpacker.yml and run the foreman
+              command to start the rails server and run webpack in watch mode.
 
-                foreman start -f Procfile.dev-server
+                foreman start -f Procfile.dev
 
-            - You may run the commands in the Procfiles in separate shells rather than using foreman.
+            - To turn on HMR, edit config/webpacker.yml and set HMR to true. Restart the rails server
+              and bin/webpack-dev-server. Or use Procfile.dev-server.
 
-            - See the documentation on https://github.com/rails/webpacker/blob/master/docs/webpack.md
-              for how to customize the default webpack configuration.
+            - To server render, change this line app/views/hello_world/index.html.erb to
+              `prerender: true` to see server rendering (right click on page and select "view source").
 
-            - Visit http://localhost:3000/hello_world and see your React On Rails app running!
+                <%= react_component("HelloWorldApp", props: @hello_world_props, prerender: true) %>
         MSG
       end
 

lib/generators/react_on_rails/templates/base/base/Procfile.dev

@@ -1,4 +1,7 @@
+# You can run these commands in separate shells
 web: rails s -p 3000
 
-# Next line runs a watch process with webpack
+# Next line runs a watch process with webpack to compile the changed files.
+# When making frequent changes to client side assets, you will prefer building webpack assets
+# upon saving rather than when you refresh your browser page.
 client: sh -c 'rm -rf public/packs/* || true && bundle exec rake react_on_rails:locale && bin/webpack -w'

lib/generators/react_on_rails/templates/base/base/Procfile.dev-server

@@ -1,5 +1,7 @@
+# You can run these commands in separate shells instead of using foreman
 web: rails s -p 3000
 
 # Next line runs the webpack-dev-server
-# You can edit config/webpacker.yml to set HMR to true to see hot reloading
+# You can edit config/webpacker.yml to set HMR to true to see hot reloading.
+# Note,
 client: sh -c 'rm -rf public/packs/* || true && bundle exec rake react_on_rails:locale && bin/webpack-dev-server'

node_package/src/clientStartup.js

@@ -80,7 +80,7 @@ function delegateToRenderer(componentObj, props, railsContext, domNodeId, trace)
     if (trace) {
       console.log(`\
 DELEGATING TO RENDERER ${name} for dom node with id: ${domNodeId} with props, railsContext:`,
-        props, railsContext);
+      props, railsContext);
     }
 
     component(props, railsContext, domNodeId);

node_package/src/createReactElement.js

@@ -19,7 +19,7 @@ export default function createReactElement({
   railsContext,
   domNodeId,
   trace,
-  }) {
+}) {
   const { name, component, generatorFunction } = componentObj;
 
   if (trace) {

node_package/tests/StoreRegistry.test.js

@@ -60,15 +60,15 @@ test('StoreRegistry throws error for retrieving unregistered store', (assert) =>
 
 test('StoreRegistry returns undefined for retrieving unregistered store, ' +
   'passing throwIfMissing = false',
-  (assert) => {
-    assert.plan(1);
-    StoreRegistry.setStore('foobarX', {});
-    const actual = StoreRegistry.getStore('foobar', false);
-    const expected = undefined;
-    assert.equals(actual, expected, 'StoreRegistry.get should return undefined for missing ' +
+(assert) => {
+  assert.plan(1);
+  StoreRegistry.setStore('foobarX', {});
+  const actual = StoreRegistry.getStore('foobar', false);
+  const expected = undefined;
+  assert.equals(actual, expected, 'StoreRegistry.get should return undefined for missing ' +
       'store if throwIfMissing is passed as false',
-    );
-  },
+  );
+},
 );
 
 test('StoreRegistry getStore, setStore', (assert) => {