react_on_rails 11.0.3 → 12.0.0

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

@@ -1,11 +1,82 @@
 # Upgrading React on Rails
 
+## Need Help Migrating?
+If you would like help in migrating between React on Rails versions or help with implementing server rendering, please contact [justin@shakacode.com](mailto:justin@shakacode.com) for information about our [ShakaCode Pro Support](https://www.shakacode.com/work/shakacode-pro-support.pdf).
+
+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 to v12
+### Recent versions
+Make sure that you are on a relatively more recent version of rails and webpacker.
+v12 is tested on Rails 6. It should work on Rails v5. If you're on an older version, 
+and v12 doesn't work, please file an issue. 
+
+### i18n default format changed to JSON
+* If you're using the internalization helper, then set `config.i18n_output_format = 'js'`. You can
+  later update to the default JSON format as you will need to update your usage of that file. A JSON
+  format is more efficient.
+
+### Updated API for `ReactOnRails.register()`
+
+In order to solve the issues regarding React Hooks compatibility, the number of parameters
+for functions is used to determine if you have a render function that will get invoked to
+return a React component, or you are registering a React component defined by a function.
+
+##### Correct
+
+Registered Objects are of the following types. Either of these will work:
+1. Take **2 params** and return **a React function or class component**. A function component is a function
+   that takes zero or one params and returns a React Element, like JSX.
+    ```js
+    export default (props, _railsContext) => () => <Component {...props} />;
+    ```
+
+2. Take only zero or one params and you return a React Element, often JSX.
+    ```js
+    export default (props) => <Component {...props} />;
+    ```
+##### Broken, as this function takes two params and it returns a React Element from a JSX Literal
+```js
+export default (props, _railsContext) => <Component {...props} />;
+```
+
+If you make this mistake, you'll get this warning
+`Warning: React.createElement: type is invalid -- expected a string (for built-in components) or a class/function (for composite components) but got: <Fragment />. Did you accidentally export a JSX literal instead of a component?`
+
+And this error:
+`react-dom.development.js:23965 Uncaught Error: Element type is invalid: expected a string (for built-in components) or a class/function (for composite components) but got: object.`
+
+In this example, you need to wrap the `<Component {...props} />` in a function call like this which
+results in the return value being a React function component.
+
+```js
+export default (props, _railsContext) => () => <Component {...props} />;
+```
+
+If you have a pure component, taking one or zero parameters, and you have an unnecessary function
+wrapper such that you're returning a function rather than a React Element, then:
+
+1. You won't see anything render.
+2. You will see this warning in development mode: `Warning: Functions are not valid as a React child. This may happen if you return a Component instead of <Component /> from render. Or maybe you meant to call this function rather than return it.`
+
+---------
+
+## 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:
@@ -25,10 +96,10 @@ Reason for doing this: This enables your webpack bundles to bypass the Rails ass
 #### From version 7 or lower
 
 ##### ...while keeping your `client` directory
-Unfortunately, this requires quite a few steps:
 *   `.gitignore`: add `/public/webpack/*`
 *   `Gemfile`: bump `react_on_rails` and add `webpacker`
-*   layout views: anything bundled by webpack will need to be requested by a `javascript_pack_tag` or `stylesheet_pack_tag`
+*   layout views: anything bundled by webpack will need to be requested by a `javascript_pack_tag` or `stylesheet_pack_tag`.
+  * Search your codebase for javascript_include_tag. Use the
 *   `config/initializers/assets.rb`: we no longer need to modify `Rails.application.config.assets.paths` or append anything to `Rails.application.config.assets.precompile`.
 *   `config/initializers/react_on_rails.rb`:
     *   Delete `config.generated_assets_dir`. Webpacker's config now supplies this information

data/docs/basics/webpack-configuration.md

@@ -0,0 +1,50 @@
+# 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.
+
+## Option 1: Recommended: Traditional React on Rails using the /client directory
+
+Until version 9, all React on Rails apps used the `/client` directory for configuring React on Rails in terms of the configuration of Webpack and location of your JavaScript and Webpack files, including the node_modules directory. Version 9 changed the default to `/` for the `node_modules` location using this value in `config/initializers/react_on_rails.rb`: `config.node_modules_location`. 
+
+The [ShakaCode Team](http://www.shakacode.com) _recommends_ this approach for projects beyond the simplest cases as it provides the greatest transparency in your webpack and overall client-side setup. The *big advantage* to this is that almost everything within the `/client` directory will apply if you wish to convert your client-side code to a pure Single Page Application that runs without Rails. This allows you to Google for how to do something with Webpack configuration and what applies to a non-Rails app will apply just as well to a React on Rails app.
+
+An examples of this pattern is the [react-webpack-rails-tutorial](https://github.com/shakacode/react-webpack-rails-tutorial).
+
+In this case, you don't need to understand the nuances of customization of your Webpack config via the [Webpacker mechanism](./docs/additional-reading/webpack-tips.md).
+
+You can access values in the `config/webpacker.yml`
+
+```js
+const { config, devServer } = require('@rails/webpacker');
+```
+
+You will want consider using some of the same values set in these files:
+
+* https://github.com/rails/webpacker/blob/master/package/environments/base.js
+* https://github.com/rails/webpacker/blob/master/package/environments/development.js
+
+**Note**, if your node_modules directory is not at the top level of the Rails project, then you will need to set the
+ENV value of WEBPACKER_CONFIG to the location of the `config/webpacker.yml` file per [rails/webpacker PR 2561](https://github.com/rails/webpacker/pull/2561).
+
+## Option 2: Default Generator Setup: rails/webpacker app/javascript
+
+Typical rails/webpacker apps have a standard directory structure as documented [here](https://github.com/rails/webpacker/blob/master/docs/folder-structure.md). If you follow the steps in the the [basic tutorial](../../docs/tutorial.md), you will see this pattern in action. In order to customize the Webpack configuration, you need to consult with the [rails/webpacker Webpack configuration](https://github.com/rails/webpacker/blob/master/docs/webpack.md). 
+
+The *advantage* of using rails/webpacker to configure Webpack is that there is very little code needed to get started and you don't need to understand really anything about Webpack customization. The *big disadvantage* to this is that you will need to learn the ins and outs of the [rails/webpacker way to customize Webpack](https://github.com/rails/webpacker/blob/master/docs/webpack.md) which differs from the plain [Webpack way](https://webpack.js.org/).
+
+You can find more details on this topic in [Recommended Project Structure](./recommended-project-structure.md). 
+ 
+See [Issue 982: Tutorial Generating Correct Project Structure?](https://github.com/shakacode/react_on_rails/issues/982) to discuss this issue.

data/docs/contributor-info/errors-with-hooks.md

@@ -0,0 +1,45 @@
+# Invalid hook call error
+
+```
+react.development.js:1465 Uncaught Error: Invalid hook call. Hooks can only be called inside of the body of a function component. This could happen for one of the following reasons:
+1. You might have mismatching versions of React and the renderer (such as React DOM)
+2. You might be breaking the Rules of Hooks
+3. You might have more than one copy of React in the same app
+See https://fb.me/react-invalid-hook-call for tips about how to debug and fix this problem.
+```
+
+The main reason to get this is due to multiple versions of React installed.
+
+```
+cd <top level>
+npm ls react
+
+cd spec/dummy
+npm ls react
+```
+
+For the second one, you might get:
+
+```
+react_on_rails@ /Users/justin/shakacode/react-on-rails/react_on_rails/spec/dummy
+├── react@16.13.1
+└─┬ react-on-rails@12.0.0 -> /Users/justin/shakacode/react-on-rails/react_on_rails invalid
+  └── react@16.13.1  extraneous
+
+npm ERR! invalid: react-on-rails@12.0.0 /Users/justin/shakacode/react-on-rails/react_on_rails/spec/dummy/node_modules/react-on-rails
+npm ERR! extraneous: react@16.13.1 /Users/justin/shakacode/react-on-rails/react_on_rails/spec/dummy/node_modules/react-on-rails/node_modules/react
+```
+
+Make sure there is only one version of React installed!
+
+If you used yarn link, then you'll have two versions of React installed.
+
+Instead use [Yalc](https://github.com/whitecolor/yalc).
+
+```
+cd <top level>
+yalc publish
+
+cd spec/dummy
+yalc link react-on-rails
+```

data/docs/contributor-info/pull-requests.md

@@ -0,0 +1,44 @@
+# Pull Requests 
+
+## Checklist before Committing
+1. `rake`: runs all linters and specs (you need Docker setup, see below)
+2. Did you need any more tests for your change?
+3. Did you document your change? Update the README.md?
+4. Did you add a CHANGELOG.md entry?
+
+
+For non-doc fixes:
+
+* Provide changelog entry in the [unreleased section of the CHANGELOG.md](https://github.com/shakacode/react_on_rails/blob/master/CHANGELOG.md#unreleased).
+* Ensure CI passes and that you added a test that passes with the fix and fails without the fix.
+* Squash all commits down to one with a nice commit message *ONLY* once final review is given. Make sure this single commit is rebased on top of master.
+* Please address all code review comments.
+* Ensure that docs are updated accordingly if a feature is added.
+
+## Commit Messages
+
+From [How to Write a Git Commit Message](http://chris.beams.io/posts/git-commit/)
+
+#### The seven rules of a great git commit message
+> Keep in mind: This has all been said before.
+
+1. Separate subject from body with a blank line
+1. Limit the subject line to 50 characters
+1. Capitalize the subject line
+1. Do not end the subject line with a period
+1. Use the imperative mood in the subject line
+1. Wrap the body at 72 characters
+1. Use the body to explain what and why vs. how
+
+## Doc Changes
+
+When making doc changes, we want the change to work on both the gitbook and the regular github site. The issue is that non-doc files will not go to the gitbook site, so doc references to non doc files must use the github URL.
+
+### Links to other docs:
+* When making references to doc files, use a relative URL path like:
+`[Installation Overview](docs/basics/installation-overview.md)`
+
+* When making references to source code files, use a full url path like:
+`[spec/dummy/config/initializers/react_on_rails.rb](https://github.com/shakacode/react_on_rails/tree/master/spec/dummy/config/initializers/react_on_rails.rb)`
+
+

data/docs/misc/doctrine.md

@@ -19,13 +19,13 @@ The React on Rails setup provides several key components related to front-end de
 6. Happiness for us is actively participating in open source, so we want to be where the action is, which is with the npm libraries on github.com.
 7. You can get set up on React on Rails **FAST** using our application generator.
 8. By placing all client-side development inside of the `/client` directory, pure JavaScript developers can productively do development separate from Rails. Instead of Rails APIs, stub APIs on an express server can provide a simple backend, allowing for rapid iteration of UI prototypes.
-9. Just because we're not relying on the Rails asset pipeline for ES6 conversion does not mean that we're deploying Rails apps in any different way. We still use the asset pipeline to include our Webpack compiled JavaScript. This only requires a few small modifications, as explained in our doc [Heroku Deployment](../additional-reading/heroku-deployment.md).
+9. Just because we're not relying on the Rails asset pipeline for ES6 conversion does not mean that we're deploying Rails apps in any different way. We still use the asset pipeline to include our Webpack compiled JavaScript. This only requires a few small modifications, as explained in our doc [Heroku Deployment](docs/basics/heroku-deployment.md).
 
 ## Convention over Configuration
 * React on Rails has taken the hard work out of figuring out the JavaScript tooling that works best with Rails. Not only could you spend lots of time researching different tooling, but then you'd have to figure out how to splice it all together. This is where a lot of "JavaScript fatigue" comes from. The following keep the code clean and consistent:
 * [Style Guide](../coding-style/style.md)
 * [linters](../contributor-info/linters.md)
-* [Recommended Project Structure](../additional-reading/recommended-project-structure.md)
+* [Recommended Project Structure](../basics/recommended-project-structure.md)
 
 We're big believers in this quote from the Rails Doctrine: 
 

data/docs/{additional-reading → outdated}/code-splitting.md

@@ -1,4 +1,10 @@
-# Code Splitting
+# Code Splitting (Outdated)
+
+_Note: This document is outdated._ Please email [justin@shakacode.com](mailto:justin@shakacode.com) 
+if you would be interested in help with code splitting using
+[loadable-components.com](https://loadable-components.com/docs) with React on Rails.
+
+-----
 
 What is code splitting? From the webpack documentation:
 
@@ -15,11 +21,11 @@ Let's say you're requesting a page that needs to fetch a code chunk from the ser
 > (server) <div data-reactroot="
 <!--This comment is here because the comment beginning on line 13 messes up Sublime's markdown parsing-->
 
-Different markup is generated on the client than on the server. Why does this happen? When you register a component or generator function with `ReactOnRails.register`, react on rails will render the component as soon as the page loads. However, react-router renders a comment while waiting for the code chunk to be fetched from the server. This means that react will tear all of the server rendered code out of the DOM, and then rerender it a moment later once the code chunk arrives from the server, defeating most of the purpose of server rendering.
+Different markup is generated on the client than on the server. Why does this happen? When you register a component or render function with `ReactOnRails.register`, react on rails will render the component as soon as the page loads. However, react-router renders a comment while waiting for the code chunk to be fetched from the server. This means that react will tear all of the server rendered code out of the DOM, and then rerender it a moment later once the code chunk arrives from the server, defeating most of the purpose of server rendering.
 
 ### 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 render 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 render 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:
 
@@ -32,7 +38,7 @@ Here's an example of how you might use this in practice:
 
 #### clientRegistration.js
 ```js
-import ReactOnRails from 'react-on-rails';
+import ReactOnRails from 'node_package/lib/ReactOnRails';
 import NavigationApp from './NavigationApp';
 
 // Note that we're importing a different RouterApp than in serverRegistration.js
@@ -62,7 +68,7 @@ ReactOnRails.register({
   RouterApp,
 });
 ```
-Note that you should not register a renderer on the server, since there won't be a domNodeId when we're server rendering. Note that the `RouterApp` imported by `serverRegistration.js` is from a different file. For an example of how to set up an app for server rendering, see the [react router docs](react-router.md).
+Note that you should not register a renderer on the server, since there won't be a domNodeId when we're server rendering. Note that the `RouterApp` imported by `serverRegistration.js` is from a different file. For an example of how to set up an app for server rendering, see the [react router docs](../additional-reading/react-router.md).
 
 #### RouterAppRenderer.jsx
 ```jsx
@@ -76,7 +82,7 @@ import { Provider } from 'react-redux';
 
 import routes from '../routes/routes';
 
-
+// NOTE how this function takes 3 params, and is thus responsible for calling ReactDOM.render
 const RouterAppRenderer = (props, railsContext, domNodeId) => {
   const store = ReactOnRails.getStore('applicationStore');
   const history = browserHistory;
@@ -113,18 +119,22 @@ 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)
 
+### Comparison of Server vs. Client Code
+
+![image](https://user-images.githubusercontent.com/1118459/42479546-2296f794-8375-11e8-85ff-52629fcaf657.png)
+
 ### Caveats
 
 If you're going to try to do code splitting with server rendered routes, you'll probably need to use seperate route definitions for client and server to prevent code splitting from happening for the server bundle. The server bundle should be one file containing all the JavaScript code. This will require you to have seperate webpack configurations for client and server.
 
 The reason is we do server rendering with ExecJS, which is not capable of doing anything asynchronous. It would be impossible to asyncronously fetch a code chunk while server rendering. See [this issue](https://github.com/shakacode/react_on_rails/issues/477) for a discussion.
 
-Also, do not attempt to register a renderer on the server. Instead, register either a generator function or a component. If you register a renderer in the server bundle, you'll get an error when react on rails tries to server render the component.
+Also, do not attempt to register a renderer on the server. Instead, register either a render function or a component. If you register a renderer in the server bundle, you'll get an error when react on rails tries to server render the component.
 
 ## How does Webpack know where to find my code chunks?
 
@@ -140,7 +150,7 @@ config = {
 
 This causes Webpack to prepend the code chunk filename with `/assets/` in the request url. The react on rails sets up the webpack config to put webpack bundles in `app/assets/javascripts/webpack`, and modifies `config/initializers/assets.rb` so that rails detects the bundles. This means that when we prepend the request url with `/assets/`, rails will know what webpack is asking for.
 
-See [rails-assets.md](./rails-assets.md) to learn more about static assets.
+See [rails-assets.md](docs/outdated/rails-assets.md) to learn more about static assets.
 
 If you forget to set the public path, webpack will request the code chunk at `/{filename}`. This will cause the request to be handled by the Rails router, which will send back a 404 response, assuming that you don't have a catch-all route. In your javascript console, you'll get the following error:
 

data/docs/outdated/how-react-on-rails-works.md

@@ -0,0 +1,44 @@
+# How React on Rails Works (with rails/webpacker)
+
+*Note, older versions of React on Rails pushed the Webpack bundles through the Asset Pipeline. This older method has *many* disadvantages, such as broken sourcemaps, performance issues, etc. If you need help migrating to the current way of bypassing the Asset Pipeline, [email Justin](mailto:justin@shakacode.com).* 
+
+Webpack is used to generate JavaScript and CSS "bundles" directly to your `/public` directory. [rails/webpacker](https://github.com/rails/webpacker) provides view helpers to access the Webpack generated (and fingerprinted) JS and CSS. These files totally skip the Rails asset pipeline. You are responsible for properly configuring your Webpack output. You will either use the standard Webpack configuration (*recommended*) or the `rails/webpacker` setup for Webpack. 
+
+Ensure these generated bundle files are in your `.gitignore`, as you never want to add the large compiled bundles to git.
+
+Inside your Rails views, you can now use the `react_component` helper method provided by React on Rails. You can pass props directly to the react component helper. 
+
+Optionally, you can also initialize a Redux store with the view or controller helper `redux_store` so that the redux store can be shared amongst multiple React components. 
+
+## Client-Side Rendering vs. Server-Side Rendering
+
+In most cases, you should use the `prerender: false` (default behavior) with the provided `react_component` 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. 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).
+ 
+## HTML Source Code
+
+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. 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. 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.
+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.
+1. 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.
+
+You can see all this on the source for [reactrails.com](https://www.reactrails.com/)
+
+## Building the Bundles
+
+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 example Foreman `Procfile.dev` files will take care of this for you by starting a webpack process with the watch flag. This will watch your JavaScript code files for changes. Alternately, the `rails/webpacker` library also can ensure that your bundles are built. 
+
+For example, you might create a [Procfile.dev](spec/dummy/Procfile.dev).
+
+On production deployments that use asset precompilation, such as Heroku deployments, `rails/webpacker`, by default, will automatically run webpack to build your JavaScript bundles, running the command `bin/webpack` in your app.
+
+However, if you want to run a custom command to run webpack to build your bundles, then you will:
+1. Ensure you do not have a `config/webpack/production.js` file
+1. Define `config.build_production_command` in your [config/initializers/react_on_rails.rb](docs/basics/configuration.md)
+
+Then React on Rails modifies the `assets:precompile` task to run your `build_production_command`.
+
+If you have used the provided generator, these bundles will automatically be added to your `.gitignore` 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.
+

data/docs/{basics/installation-overview.md → outdated/manual-installation-overview.md}

@@ -1,17 +1,12 @@
-# Installation Overview
+# Manual Installation Overview
 
-Here's an overview of installation if you're not using the generator.
+TODO: Review this file
 
-Note, the best way to understand how to use ReactOnRails is to study the examples:
 
-1. Run the generator per the [Tutorial](../tutorial.md).
-2. [spec/dummy](../../spec/dummy): Simple, no DB example.
-3. [github.com/shakacode/react-webpack-rails-tutorial](https://github.com/shakacode/react-webpack-rails-tutorial): Full featured example.
+This file summarizes what the React on Rails generator does.
 
 ## Configure the `/client` Directory
 
-Note, version 9.0 of React on Rails removed the requirement to place all client side files in the `/client` directory.
-
 This directory has no references to Rails outside of the destination directory for the files created by the various Webpack config files.
 
 The only requirements within this directory for basic React on Rails integration are:
@@ -19,17 +14,17 @@ The only requirements within this directory for basic React on Rails integration
 1. Your webpack configuration files:
    1. Create outputs in a directory like `/public/webpack`, which is customizable in your `config/initializers/react_on_rails.rb`.
    1. Provide server rendering if you wish to use that feature.
-1. Your JavaScript code "registers" any components and stores per the ReactOnRails APIs of ReactOnRails.register(components) and ReactOnRails.registerStore(stores). See API docs in [README.md](../../README.md) and the [ReactOnRails.js source](../../node_package/src/ReactOnRails.js).
+1. Your JavaScript code "registers" any components and stores per the ReactOnRails APIs of ReactOnRails.register(components) and ReactOnRails.registerStore(stores). See API docs in [README.md](README.md) and the [ReactOnRails.js source](../../node_package/src/ReactOnRails.js).
 1. Set your registration file as an "entry" point in your Webpack configs.
 1. Add the [Manifest plugin](https://github.com/danethurber/webpack-manifest-plugin) to your config. For examples see [dummy config](../../spec/dummy/client/webpack.client.base.config.js).
 The default path: `public/webpack` can be loaded with webpackConfigLoader as shown in the dummy example.
 1. You create scripts in `client/package.json` per the example apps. These are used for building your Webpack assets. Also do this for your top level `package.json`.
 
 ## Rails Steps (outside of /client)
-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. 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. If you are deploying to Heroku, see [heroku-deployment.md](/docs/additional-reading/heroku-deployment.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. 
+1. If you are deploying to Heroku, see [heroku-deployment.md](/docs/basics/heroku-deployment.md)
 
 If I missed anything, please submit a PR or file an issue.

data/docs/{additional-reading → outdated}/rails-assets-relative-paths.md

@@ -1,4 +1,4 @@
-*Note: this doc needs updating to reflect how v8.x+ no longer puts Webpack generated files through the asset pipeline. PR's welcome!*
+*Note: this doc reflects using Sprockets for assets and has not been updated for rails/webpacker*
 
 # Using Webpack bundled assets with the Rails Asset Pipeline
 
@@ -77,7 +77,7 @@ Note: _You can output these files in the asset pipeline wherever you see fit. My
 
 Lastly, we will set the publicPath to our file(s). This will be the endpoint on our rails web server that you can visit to reach the asset (if you don't know how this works, read the [intro](#using-webpack-bundled-assets-with-the-rails-asset-pipeline)). If you've been following the previous steps, you know that we set our outputPath for our assets to be absolute at `app/assets/webpack/webpack-assets/`, which your rails app should end up hosting at `/assets/webpack-assets/file-name+hash.ext` when the server is run.
 
-Note: _If you're having a hard time figuring out what an asset's path will be on your rails server, simply run `rake assets:precompile` and `cd public/`. The path from there to your file will then be the path/url on your web server to that asset. On top of this, it is also a good idea to check out [this doc](./rails-assets.md) to understand how `react_on_rails` allows us to access these files after precompilation, when Rails applies another hash onto the asset._
+Note: _If you're having a hard time figuring out what an asset's path will be on your rails server, simply run `rake assets:precompile` and `cd public/`. The path from there to your file will then be the path/url on your web server to that asset. On top of this, it is also a good idea to check out [this doc](docs/outdated/rails-assets.md) to understand how `react_on_rails` allows us to access these files after precompilation, when Rails applies another hash onto the asset._
 
 Our publicPath setting will match the path to our outputted assets on our rails web server. Given our assets in this example will be outputted to `/app/assets/webpack/webpack-assets/` and hosted at `/assets/webpack-assets/`, our publicPath would be:
 
@@ -192,4 +192,4 @@ module.exports = {
 };
 ```
 
-If you'd like to understand how react_on_rails handles these bundled assets after asset precompilation and in production mode, check out: [Rails Assets](./rails-assets.md).
+If you'd like to understand how react_on_rails handles these bundled assets after asset precompilation and in production mode, check out: [Rails Assets](docs/outdated/rails-assets.md).

data/docs/{additional-reading → outdated}/rails-assets.md

@@ -1,5 +1,7 @@
 # Rails assets and the Extract Text Plugin
 
+*This doc needs updating for the use of rails/webpacker with React on Rails*
+
 The [Webpack file loader](https://github.com/webpack/file-loader) copies referenced files to
 the destination output directory, with an MD5 hash. The other term for this is a "digest".
 
@@ -28,24 +30,14 @@ will have the Webpack digested name (MD5 hash). Since the Webpack generated CSS
 just one level of "digesting", this "double-digesting" from Rails will cause such these assets
 fail to load.
 
-_If you are interested in learning how to use assets in your React components, read this doc: [Webpack, the Asset Pipeline, and Using Assets w/ React](./rails-assets-relative-paths.md)._
+_If you are interested in learning how to use assets in your React components, read this doc: [Webpack, the Asset Pipeline, and Using Assets w/ React](../additional-reading/rails-assets-relative-paths.md)._
 
 ## The Solution: Symlink Original File Names to New File Names
-React on Rails creates symlinks of non-digested versions (original webpack digested file names) 
-to the Rails deployed digested versions when doing a Rails assets compile. The solution is 
-implemented using `assets:precompile` after-hook in 
-file [lib/tasks/assets.rake](../../lib/tasks/assets.rake)
-The assets for symlinking are defined by `config.symlink_non_digested_assets_regex` in 
-`config/initializers/react_on_rails.rb`.
-
-## Disabling the Symlinking
-To disable symlinks set this parameter to `nil`.
-
+_Note, this solution was removed in v14. If you're intersted in this symlink solution, please create
+a github issue._
 
 ## Example from /spec/dummy
 
-If you run
-
 ```
 cd spec/dummy
 RAILS_ENV=production bundle exec rake assets:precompile

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).