react_on_rails 12.0.1 → 13.0.0

data/docs/guides/rails-webpacker-react-integration-options.md

@@ -0,0 +1,182 @@
+# Rails/Webpacker React Integration Options
+
+You only _need_ props hydration if you need SSR. However, there's no good reason to
+have your app make a second round trip to the Rails server to get initialization props.
+
+**Server-Side Rendering (SSR)** results in Rails rendering HTML for your React components. The main reasons to use SSR are better SEO and pages display more quickly. 
+
+These gems provide advanced integration of React with [rails/webpacker](https://github.com/rails/webpacker): 
+
+| Gem | Props Hydration | Server-Side-Rendering (SSR) | SSR with HMR | SSR with React-Router | SSR with Code Splitting | Node SSR |
+| --- | --------------- | --- | --------------------- | ----------------------| ------------------------|----|
+| [shakacode/react_on_rails](https://github.com/shakacode/react_on_rails) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| [react-rails](https://github.com/reactjs/react-rails)  | ✅ | ✅ |  | | | | |
+| [webpacker-react](https://github.com/renchap/webpacker-react) | ✅ | | | | | | |
+
+Note, Node SSR for React on Rails requires [React on Rails Pro](https://www.shakacode.com/react-on-rails-pro/).
+
+---
+
+As mentioned, you don't _need_ to use a gem to integrate Rails with React.
+
+If you're not concerned with view helpers to pass props or server rendering, can do it yourself:
+
+```erb
+<%# views/layouts/application.html.erb %>
+
+<%= content_tag :div,
+  id: "hello-react",
+  data: {
+    message: 'Hello!',
+    name: 'David'
+}.to_json do %>
+<% end %>
+```
+
+```js
+// app/javascript/packs/hello_react.js
+
+const Hello = props => (
+  <div className='react-app-wrapper'>
+    <img src={clockIcon} alt="clock" />
+    <h5 className='hello-react'>
+      {props.message} {props.name}!
+    </h5>
+  </div>
+)
+
+// Render component with data
+document.addEventListener('DOMContentLoaded', () => {
+  const node = document.getElementById('hello-react')
+  const data = JSON.parse(node.getAttribute('data'))
+
+  ReactDOM.render(<Hello {...data} />, node)
+})
+```
+
+----
+
+## HMR and React Hot Reloading
+
+Before turning HMR on, consider upgrading to the latest stable gems and packages:
+https://github.com/rails/webpacker#upgrading
+
+Configure `config/webpacker.yml` file:
+
+```yaml
+development:
+  extract_css: false
+  dev_server:
+    hmr: true
+    inline: true
+```
+
+This basic configuration alone will have HMR working with the default webpacker setup. However, an code saves will trigger a full page refresh each time you save a file.
+
+Webpack's HMR allows the replacement of modules for React in-place without reloading the browser. To do this, you have two options:
+
+1. Steps below for the [github.com/pmmmwh/react-refresh-webpack-plugin](https://github.com/pmmmwh/react-refresh-webpack-plugin).
+1. Deprecated steps below for using the [github.com/gaearon/react-hot-loader](https://github.com/gaearon/react-hot-loader).
+
+### React Refresh Webpack Plugin
+[github.com/pmmmwh/react-refresh-webpack-plugin](https://github.com/pmmmwh/react-refresh-webpack-plugin)
+
+You can see an example commit of adding this [here](https://github.com/shakacode/react_on_rails_tutorial_with_ssr_and_hmr_fast_refresh/commit/7e53803fce7034f5ecff335db1f400a5743a87e7).
+
+1. Add react refresh packages:
+   `yarn add @pmmmwh/react-refresh-webpack-plugin react-refresh -D`
+2. Update `babel.config.js` adding
+   ```js
+   plugins: [
+     process.env.WEBPACK_DEV_SERVER && 'react-refresh/babel',
+     // other plugins
+   ```
+3. Update `config/webpack/development.js`, only including the plugin if running the WEBPACK_DEV_SERVER
+   ```js
+   const ReactRefreshWebpackPlugin = require('@pmmmwh/react-refresh-webpack-plugin');
+   const environment = require('./environment')
+   
+   const isWebpackDevServer = process.env.WEBPACK_DEV_SERVER;
+   
+   //plugins
+   if (isWebpackDevServer) {
+       environment.plugins.append(
+           'ReactRefreshWebpackPlugin',
+           new ReactRefreshWebpackPlugin({
+               overlay: {
+                   sockPort: 3035
+               }
+           })
+       );
+   }
+   ```
+
+### React Hot Loader (Deprecated)
+
+1. Add the `react-hot-loader` and ` @hot-loader/react-dom` npm packages.
+  ```sh
+  yarn add --dev react-hot-loader @hot-loader/react-dom
+  ```
+
+2. Update your babel config, `babel.config.js`. Add the plugin `react-hot-loader/babel`
+with option `"safetyNet": false`:
+
+```
+{
+    "plugins": [
+        [
+            "react-hot-loader/babel",
+            {
+            "safetyNet": false
+            }
+        ]
+    ]
+}
+```
+
+3. Add changes like this to your entry points:
+
+```diff
+// app/javascript/app.jsx
+
+import React from 'react';
++ import { hot } from 'react-hot-loader/root';
+
+const App = () => <SomeComponent(s) />
+
+- export default App;
++ export default hot(App);
+```
+
+4. Adjust your webpack configuration for development so that `sourceMapContents` option for the sass
+loader is `false`:
+
+```diff
+// config/webpack/development.js
+
+process.env.NODE_ENV = process.env.NODE_ENV || 'development'
+
+const environment = require('./environment')
+
+// allows for editing sass/scss files directly in browser
++ if (!module.hot) {
++   environment.loaders.get('sass').use.find(item => item.loader === 'sass-loader').options.sourceMapContents = false
++ }
++ 
+module.exports = environment.toWebpackConfig()
+```
+
+5. Adjust your `config/webpack/environment.js` for a 
+
+```diff
+// config/webpack/environment.js
+
+// ...
+
+// Fixes: React-Hot-Loader: react-🔥-dom patch is not detected. React 16.6+ features may not work.
+// https://github.com/gaearon/react-hot-loader/issues/1227#issuecomment-482139583
++ environment.config.merge({ resolve: { alias: { 'react-dom': '@hot-loader/react-dom' } } });
+
+module.exports = environment;
+```
+

data/docs/guides/react-on-rails-overview.md

@@ -0,0 +1,30 @@
+# React on Rails
+
+React on Rails integrates Rails with (server rendering of) Facebook's [React](https://github.com/facebook/react) front-end framework.
+
+---
+
+# Project Objective
+
+To provide a high performance framework for integrating Ruby on Rails with React via the [**Webpacker**](https://github.com/rails/webpacker) gem especially in regards to React Server-Side Rendering for better SEO and improved performance.
+
+# Features and Why React on Rails?
+
+Given that [`rails/webpacker`](https://github.com/rails/webpacker/) gem already provides basic React integration, why would you use "React on Rails"?
+
+1. Easy passing of props directly from your Rails view to your React components rather than having your Rails view load and then make a separate request to your API.
+1. Tight integration with [rails/webpacker](https://github.com/rails/webpacker).
+1. Server-Side Rendering (SSR), often used for SEO crawler indexing and UX performance, is not offered by `rails/webpacker`.
+1. Support for HMR for a great developer experience.
+1. Supports latest versions of React with hooks.
+1. [Redux](https://github.com/reactjs/redux) and [React Router](https://github.com/ReactTraining/react-router#readme) integration including server-side-rendering.
+1. [Internationalization (I18n) and (localization)](https://www.shakacode.com/react-on-rails/docs/guides/i18n/)
+1. A supportive community. This [web search shows how live public sites are using React on Rails](https://publicwww.com/websites/%22react-on-rails%22++-undeveloped.com+depth%3Aall/).
+1. [ReScript (Reason ML) Support](https://github.com/shakacode/reason-react-on-rails-example).
+
+See the [react-webpack-rails-tutorial](https://github.com/shakacode/react-webpack-rails-tutorial) for an example of a live implementation and code.
+----
+
+## Prerequisites
+
+Ruby on Rails >=5 and rails/webpacker 4.2+.

data/docs/{basics → guides}/react-server-rendering.md

@@ -1,6 +1,9 @@
 # React Server Rendering
 
-See also [Client vs. Server Rendering](./client-vs-server-rendering.md)
+See also [Client vs. Server Rendering](https://www.shakacode.com/react-on-rails/docs/guides/client-vs-server-rendering/).
+
+## What is the easiest way to setup a webpack configuration for server-side-rendering?
+See the example webpack setup here: [github.com/shakacode/react_on_rails_tutorial_with_ssr_and_hmr_fast_refresh](https://github.com/shakacode/react_on_rails_tutorial_with_ssr_and_hmr_fast_refresh).
 
 ## What is Server Rendering?
 
@@ -10,13 +13,13 @@ 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](docs/outdated/how-react-on-rails-works.md#client-side-rendering-vs-server-side-rendering)
-
+See [this note](https://www.shakacode.com/react-on-rails/docs/guides/client-vs-server-rendering/).
 
 ## How do you do Server Rendering with React on Rails?
 1. The `react_component` view helper method provides the `prerender:` option to switch on or off server rendering.
 1. Configure your Webpack setup to create a different server bundle per your needs. While you may reuse the same bundle as for client rendering, this is not common in larger apps for many reasons, such as as code splitting, handling CSS and images, different code paths for React Router on the server vs. client, etc.
-1. You need to configure `config.server_bundle_js_file = "my-server-bundle.js"` in your `config/initializers/react_on_rails.rb`
+1. You need to configure `config.server_bundle_js_file = "server-bundle.js"` in your `config/initializers/react_on_rails.rb`
+1. You should ***not*** put a hash on the server-bundle so that you can easily use the webpack-dev-server for client bundles and have the server bundle generated by a watch process.
 
 ## Do you need server rendering?
 
@@ -26,4 +29,4 @@ Server rendering is used for either SEO or performance reasons.
 
 1. Never access `window`. Animations, globals on window, etc. just don't make sense when you're trying to run some JavaScript code to output a string of HTML.
 2. JavaScript calls to `setTimeout`, `setInterval`, and `clearInterval` similarly don't make sense when server rendering.
-3. Promises don't work when server rendering. Anything to be done in a promise will never complete. This includes concepts such as asynchronous code loading and AJAX calls. If you want to do server rendering with asynchronous calls, [get in touch](mailto:justin@shakacode.com) as we're working on a Node renderer that handles asynchronous calls.
+3. Promises and file system access don't work when server rendering with ExecJS. Instead, you can use the Node renderer or [React on Rails Pro](https://www.shakacode.com/react-on-rails-pro/).

data/docs/{basics → guides}/rspec-configuration.md

@@ -1,5 +1,5 @@
 # RSpec Configuration
-_Click [here for minitest](./minitest-configuration.md)_
+_Click [here for minitest](https://www.shakacode.com/react-on-rails/docs/guides/minitest-configuration/)_
 
 # If your webpack configurations correspond to rails/webpacker's default setup
 If you're able to configure your webpack configuration to be run by having your webpack configuration
@@ -8,12 +8,12 @@ compiled by webpack before running tests and during production deployment:
 
 1. **Use rails/webpacker's compile option**: Configure your `config/webpacker.yml` so that `compile: true` is for `test` and `production`
    environments. Ensure that your `source_path` is correct, or else `rails/webpacker` won't correctly
-   detect changes. 
-2. **Use the react_on_rails settings and helpers**. Use the settings in `config/initializers/react_on_rails.rb`. Refer to [docs/configuration](./configuration.md).
+   detect changes.
+2. **Use the react_on_rails settings and helpers**. Use the settings in `config/initializers/react_on_rails.rb`. Refer to [docs/configuration](https://www.shakacode.com/react-on-rails/docs/guides/configuration/).
 
 ```yml
-  config.build_test_command = "NODE_ENV=test RAILS_ENV=test bin/webpack"
-``` 
+  config.build_test_command = "NODE_ENV=test RAILS_ENV=test bin/webpacker"
+```
 
 Which should you use? If you're already using the `rails/webpacker` way to configure webpack, then
 you can keep things simple and use the `rails/webpacker` options.
@@ -25,7 +25,7 @@ Because you will probably want to run RSpec tests that rely on compiled webpack
 As mentioned above, you can configure `compile: true` in `config/webpacker.yml` _if_ you've got configuration for
 your webpack in the standard `rails/webpacker` spot of `config/webpack/<NODE_ENV>.js`
 
-ReactOnRails also 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`.
+ReactOnRails also 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](https://github.com/shakacode/react_on_rails/tree/master/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`.
 
 ```ruby
 RSpec.configure do |config|
@@ -44,22 +44,22 @@ If you are using Webpack to build CSS assets, you should do something like this
 ```
 
 Please take note of the following:
-- If you are using Webpacker, be **SURE** to configure the `source_path` in your `config/webpacker.yml` unless you are using the defaults for webpacker. 
+- If you are using Webpacker, be **SURE** to configure the `source_path` in your `config/webpacker.yml` unless you are using the defaults for webpacker.
 
 - This utility uses your `build_test_command` to build the static generated files. This command **must not** include the `--watch` option. If you have different server and client bundle files, this command **must** create all the bundles. If you are using webpacker, the default value will come from the `config/webpacker.yml` value for the `public_output_path` and the `source_path`
 
-- If you add an older file to your source files, that is already older than the produced output files, no new recompilation is done. The solution to this issue is to clear out your directory of webpack generated files when adding new source files that may have older dates. 
+- If you add an older file to your source files, that is already older than the produced output files, no new recompilation is done. The solution to this issue is to clear out your directory of webpack generated files when adding new source files that may have older dates.
 
-- By default, the webpack processes look in the webpack generated files folder, configured via the `config/webpacker.yml` config values of `public_root_path` and `public_output_path`. If the webpack generated files folder is missing, is empty, or contains files in the `config.webpack_generated_files` list with `mtime`s older than any of the files in your `client` folder, the helper will recompile your assets. 
+- By default, the webpack processes look in the webpack generated files folder, configured via the `config/webpacker.yml` config values of `public_root_path` and `public_output_path`. If the webpack generated files folder is missing, is empty, or contains files in the `config.webpack_generated_files` list with `mtime`s older than any of the files in your `client` folder, the helper will recompile your assets.
 
 The following `config/react_on_rails.rb` settings **must** match your setup:
 ```ruby
   # Define the files we need to check for webpack compilation when running tests.
   config.webpack_generated_files = %w( manifest.json )
-  
+
   # OR if you're not hashing the server-bundle.js, then you should include your server-bundle.js in the list.
   # config.webpack_generated_files = %w( server-bundle.js manifest.json )
-  
+
   # If you are using the ReactOnRails::TestHelper.configure_rspec_to_compile_assets(config)
   # with rspec then this controls what yarn command is run
   # to automatically refresh your webpack assets on every test run.

data/docs/{tutorial.md → guides/tutorial.md}

@@ -1,6 +1,10 @@
 # React on Rails Basic Tutorial
 
-*Updated for Ruby 2.7.1, Rails 6.0.3.1, and React on Rails v12.0.0*
+**November 11, 2020**: See the example repo of [React on Rails Tutorial With SSR, HMR fast refresh, and TypeScript](https://github.com/shakacode/react_on_rails_tutorial_with_ssr_and_hmr_fast_refresh) for a new way to setup the creation of your SSR bundle with `rails/webpacker`. This file will be update shortly. Most of it is still relevant.
+
+-----
+
+*Updated for Ruby 2.7.1, Rails 6.0.3.1, React on Rails v12.5.0, and Shakapacker v6*
 
 This tutorial guides you through setting up a new or existing Rails app with **React on Rails**, demonstrating Rails + React + Redux + Server Rendering.
 
@@ -17,18 +21,16 @@ By the time you read this, the latest may have changed. Be sure to check the ver
 * https://rubygems.org/gems/react_on_rails
 * https://www.npmjs.com/package/react-on-rails
 
-_Note: some of the screen images below show the "npm" command. react_on_rails 6.6.0 and greater uses `yarn`._
-
 ## Setting up your environment
 
-Trying out **React on Rails** is super easy, so long as you have the basic prerequisites. This includes the basics for Rails 6.x and node version 13+. I recommend `rvm` and `nvm` to install Ruby and Node, and [brew](https://brew.sh/) to install [yarn](https://yarnpkg.com/en/docs/install#mac-tab). Rails can be installed as an ordinary gem.
+Trying out **React on Rails** is super easy, so long as you have the basic prerequisites. This includes the basics for Rails 6.x and node version 14+. I recommend `rvm` or `rbevn` and `nvm` to install Ruby and Node. Rails can be installed as an ordinary gem.
 
 ```
 nvm install node                # download and install latest stable Node
 nvm alias default node          # make it default version
 nvm list                        # check
 
-brew install yarn               # you can use other installer if desired
+brew install yarn               # you can use other installer if desired, such as yvm
 rvm install 2.7                 # download and install latest stable Ruby (update to exact version)
 rvm use 2.7 --default           # use it and make it default
 rvm list                        # check
@@ -38,36 +40,41 @@ gem install foreman             # download and install Foreman
 ```
 
 ## Create a new Ruby on Rails App
-Then we need to create a fresh Rails application with webpacker react support as following.
+Then we need to create a fresh Rails application as following.
 
 First be sure to run `rails -v` and check 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).
 
-```
+```bash
 cd <directory where you want to create your new Rails app>
 
 # Any name you like for the rails app
-# Skip javascript so will add that next and get the current version 
-rails new --skip-sprockets -J --skip-turbolinks test-react-on-rails-v12-no-sprockets
+# Skip javascript so will add that next and get the current version
+rails new --skip-turbolinks --skip-javascript test-react-on-rails
 
 cd test-react-on-rails
-bundle
 ```
 
-## Add the webpacker gem
+## Add the shakapacker and react_on_rails gems
+To avoid issues regarding inconsistent gem and npm versions, you should specify the exact versions
+of both the gem and npm package. In other words, don't use the `^` or `~` in the version specifications.
+_Use the latest version for `react_on_rails` and `shakapacker`._
 
 ```
-bundle add webpacker                 
-bundle add react_on_rails
+gem 'react_on_rails', '13.0.0'         # prefer exact gem version to match npm version
+gem 'shakapacker', '6.1.1'             # prefer exact gem version to match npm version
+
 ```
 
-## Run the webpacker generator
+Note: The 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.
 
-```
+## Run the webpacker (shakapacker) generator
+
+```terminal
 bundle exec rails webpacker:install
-bundle exec rails webpacker:install:react
 ```
 
-Let's commit everything before installing React on Rails.
+**Let's commit everything before installing React on Rails.**
 
 ```
 # Here are git commands to make a new git repo and commit everything.
@@ -76,45 +83,32 @@ git add -A
 git commit -m "Initial commit"
 ```
 
-## Add the **React On Rails** gem to your `Gemfile`:
-
-To avoid issues regarding inconsistent gem and npm versions, you should specify the exact versions
-of both the gem and npm package. In other words, don't use the `^` or `~` in the version specifications.
-
-```
-gem 'react_on_rails', '12.0.0'         # prefer exact gem version to match npm version
-```
-
-Note: The 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.
-
-Run `bundle` and commit the changes.
-
-```
-bundle
-
-git commit -am "Added React on Rails Gem"
-```
+## Run the React on Rails Generator
 
 Install React on Rails: `rails generate react_on_rails:install`. You need to first git commit your files before running the generator, or else it will generate an error.
 
-Note, using `redux` is no longer recommended as the basic installer uses React Hooks. 
+Note, using `redux` is no longer recommended as the basic installer uses React Hooks.
 If you want the redux install: `rails generate react_on_rails:install --redux`
 
+The generator will add `mini_racer`'s latest version. If you're using linux & encounter issues installing `libv8`, here's [a common solution](https://github.com/rubyjs/mini_racer/issues/218).
+
 ```
-rails generate react_on_rails:install
+bundle exec rails generate react_on_rails:install
 ```
 
-Then run server with a static client bundle. Static means that the bundle is saved in your
-public/webpack/packs directory.
+Enter `a` to replace all configuration files required by the project. You can check the diffs
+before you commit to see what changed.
+
+Then run the server with one of the following options:
 
+## Running with HMR
 ```
 foreman start -f Procfile.dev
 ```
 
-## To run with the webpack-dev-server:
+## Running without HMR, statically creating the bundles
 ```
-foreman start -f Procfile.dev-hmr
+foreman start -f Procfile.dev-static
 ```
 
 Visit [http://localhost:3000/hello_world](http://localhost:3000/hello_world) and see your **React On Rails** app running!
@@ -125,7 +119,7 @@ First, check that the `hmr` and the `inline` options are `true` in your `config/
 
 The basic setup will have HMR working with the default webpacker setup. The basic
 [HMR](https://webpack.js.org/concepts/hot-module-replacement/), without a special
-React setup, will cause a full page refresh each time you save a file. 
+React setup, will cause a full page refresh each time you save a file.
 
 ## Deploying to Heroku
 
@@ -254,6 +248,8 @@ heroku open
 
 and you will see your live app and you can share this URL with your friends. Congrats!
 
+A deployed version of the project `spec/dummy` which demonstrates several uses of `react_on_rails` is available on heroku [through this link](https://ror-spec-dummy.herokuapp.com/)
+
 ## Turning on Server Rendering
 
 You can turn on server rendering by simply changing the `prerender` option to `true`:
@@ -294,8 +290,8 @@ versus with server rendering:
 
 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)
+  + [Client vs. Server Rendering](https://www.shakacode.com/react-on-rails/docs/guides/client-vs-server-rendering/)
+  + [React Server Rendering](https://www.shakacode.com/react-on-rails/docs/guides/react-server-rendering/)
 
 ## Moving from the Rails default `/app/javascript` to the recommended `/client` structure
 
@@ -316,13 +312,13 @@ mv app/javascript client
 
 ## Using HMR with the rails/webpacker setup
 
-Start the app using `foreman start -f Procfile.dev-hmr`.
+Start the app using `foreman start -f Procfile.dev`.
 
 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://github.com/rails/webpacker/blob/5-x-stable/docs/webpack-dev-server.md
 * https://webpack.js.org/configuration/dev-server/
 * https://webpack.js.org/concepts/hot-module-replacement/
 
@@ -337,7 +333,7 @@ In case you are running some custom setup with different IP or PORT you should a
 web: rails s -p 8080 -b 0.0.0.0
 ```
 
-Then visit https://your-shared-addr.c9users.io:8080/hello_world 
+Then visit https://your-shared-addr.c9users.io:8080/hello_world
 
 ## RubyMine
 
@@ -351,8 +347,8 @@ It's super important to exclude certain directories from RubyMine or else it wil
 
 ## 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)
+* Browse the docs on [our documentation website](https://www.shakacode.com/react-on-rails/docs/)
 
-Feedback is greatly appreciated! As are stars on github! 
+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.

data/docs/{basics → guides}/upgrading-react-on-rails.md

@@ -1,15 +1,30 @@
 # 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).
+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 more information about our [React on Rails Pro Support](https://www.shakacode.com/react-on-rails-pro).
 
-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.
+We specialize in helping companies to quickly and efficiently upgrade. 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 v13
+
+### Breaking Change
+Previously, the gem `webpacker` was a Gem dependency.
+
+v13 has changed slightly to switch to `shakapacker`.
+
+For details, see see the [Shakapacker guide to upgrading](https://github.com/shakacode/shakapacker/blob/master/docs/v6_upgrade.md)
+
+In summary:
+
+1. Change the gem reference from 'webpacker' to 'shakapacker'
+2. Change the npm reference from '@rails/webpacker' to 'shakapacker'
+3. Other updates, depending on what version of rails/webpacker that you had.
 
 ## Upgrading to v12
 ### Recent versions
-Make sure that you are on a relatively more recent version of rails and webpacker.
+Make sure that you are on a relatively more recent version of rails and webpacker. Yes, the [rails/webpacker](https://github.com/rails/webpacker) gem is required!
 v12 is tested on Rails 6. It should work on Rails v5. If you're on any older version,
-and v12 doesn't work, please file an issue. 
+and v12 doesn't work, please file an issue.
 
 ### Removed Configuration config.symlink_non_digested_assets_regex
 Remove `config.symlink_non_digested_assets_regex` from your `config/initializers/react_on_rails.rb`.
@@ -25,33 +40,56 @@ If you still need that feature, please file an issue.
 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.
-Please see [Render-Functions and the Rails Context](./render-functions-and-railscontext.md) for
+Please see [Render-Functions and the Rails Context](https://www.shakacode.com/react-on-rails/docs/guides/render-functions-and-railscontext/) for
 more information on what a Render-Function is.
 
-##### Correct
+##### Update required for registered functions taking exactly 2 params.
 
-Registered Objects are of the following types. Either of these will work:
-1. Takes only zero or one params and you return a React Element, often JSX.
+Registered Objects are of the following type:
+1. **Function that takes only zero or one params and you return a React Element**, often JSX.  If the function takes zero or one params, there is **no migration needed** for that function.
     ```js
     export default (props) => <Component {...props} />;
-    ```       
-2. Takes **2 params** and returns **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.
+    ```
+
+2. **Function that takes only zero or one params and you return an Object (_not a React Element_)**.  If the function takes zero or one params, **you need to add one or two unused params so you have exactly 2 params** and then that function will be treated as a render function and it can return an Object rather than a React element. If you don't do this, you'll see this obscure error message:
+
+```
+  [SERVER] message: Objects are not valid as a React child (found: object with keys {renderedHtml}). If you meant to render a collection of children, use an array instead.
+  in YourComponentRenderFunction
+```
+
+  So look in YourComponentRenderFunction and do this change
+
+```js
+   export default (props) => { renderedHTML: getRenderedHTML };
+```
+
+   To have exactly 2 arguments:
+
+```js
+    export default (props, _railsContext) => { renderedHTML: getRenderedHTML };
+```    
+
+3. Function that takes **2 params** and returns **a React function or class component**. _Migration is needed as the older syntax returned a React Element._
+   A function component is a function that takes zero or one params and returns a React Element, like JSX. The correct syntax
+   looks like:
     ```js
-    export default (props, _railsContext) => () => <Component {...props} />;
+    export default (props, railsContext) => () => <Component {{...props, railsContext}} />;
     ```
-   Note, you cannot return a React Element (JSX).
-3. Takes **3 params** and uses the 3rd param, `domNodeId`, to call `ReactDOM.hydrate`
-  
+   Note, you cannot return a React Element (JSX). See below for the migration steps. If your function that took **two params returned
+   an Object**, then no migration is required.
+4. Function that takes **3 params** and uses the 3rd param, `domNodeId`, to call `ReactDOM.hydrate`. If the function takes 3 params, there is **no migration needed** for that function.
+5. ES6 or ES5 class. There is **no migration needed**.
+
 Previously, with case number 2, you could return a React Element.
 
 The fix is simple. Here is an example of the change you'll do:
 
 ![2020-07-07_09-43-51 (1)](https://user-images.githubusercontent.com/1118459/86927351-eff79e80-c0ce-11ea-9172-d6855c45e2bb.png)
- 
+
 ##### Broken, as this function takes two params and it returns a React Element from a JSX Literal
 ```js
-export default (props, _railsContext) => <Component {...props} />;
+export default (props, railsContext) => <Component {{...props, railsContext} />;
 ```
 
 If you make this mistake, you'll get this warning
@@ -77,7 +115,7 @@ wrapper such that you're returning a function rather than a React Element, then:
 
 ## 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.
+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