react_on_rails 11.0.9 → 11.0.10

data/docs/basics/generator-functions-and-railscontext.md

@@ -0,0 +1,157 @@
+# Generator Functions and Rails Context 
+
+## Generator Functions
+
+When you use a "generator function" to create react components (or renderedHtml on the server), or you used shared redux stores, you get two params passed to your function that creates a React component:
+
+1. `props`: Props that you pass in the view helper of either `react_component` or `redux_store`
+2. `railsContext`: Rails contextual information, such as the current pathname. You can customize this in your config file. **Note**: The `railsContext` is not related to the concept of a ["context" for React components](https://facebook.github.io/react/docs/context.html#how-to-use-context).
+
+This parameters (`props` and `railsContext`) will be the same regardless of either client or server side rendering, except for the key `serverSide` based on whether or not you are server rendering.
+
+While you could manually configure your Rails code to pass the "`railsContext` information" with the rest of your "props", the `railsContext` is a convenience because it's passed consistently to all invocations of generator functions.
+
+For example, suppose you create a "generator function" called MyAppComponent.
+
+```js
+import React from 'react';
+const MyAppComponent = (props, railsContext) => (
+  <div>
+    <p>props are: {JSON.stringify(props)}</p>
+    <p>railsContext is: {JSON.stringify(railsContext)}
+    </p>
+  </div>
+);
+export default MyAppComponent;
+```
+
+*Note: you will get a React browser console warning if you try to serverRender this since the value of `serverSide` will be different for server rendering.*
+
+So if you register your generator function `MyAppComponent`, it will get called like:
+
+```js
+reactComponent = MyAppComponent(props, railsContext);
+```
+
+and, similarly, any redux store always initialized with 2 parameters:
+
+```js
+reduxStore = MyReduxStore(props, railsContext);
+```
+
+Note: you never make these calls. React on Rails makes these calls when it does either client or server rendering. You will define functions that take these 2 params and return a React component or a Redux Store. Naturally, you do not have to use second parameter of the railsContext if you do not need it.
+
+(Note: see below [section](#multiple-react-components-on-a-page-with-one-store) on how to setup redux stores that allow multiple components to talk to the same store.)
+
+The `railsContext` has: (see implementation in file [react_on_rails_helper.rb](https://github.com/shakacode/react_on_rails/tree/master/app/helpers/react_on_rails_helper.rb), method `rails_context` for the definitive list).
+
+```ruby
+  {
+    railsEnv: Rails.env
+    # URL settings
+    href: request.original_url,
+    location: "#{uri.path}#{uri.query.present? ? "?#{uri.query}": ""}",
+    scheme: uri.scheme, # http
+    host: uri.host, # foo.com
+    port: uri.port,
+    pathname: uri.path, # /posts
+    search: uri.query, # id=30&limit=5
+
+    # Other
+    serverSide: boolean # Are we being called on the server or client? Note: if you conditionally
+     # render something different on the server than the client, then React will only show the
+     # server version!
+  }
+```
+
+## Rails Context
+
+The `railsContext` is a second param passed to your generator functions for React components. This is in addition to the props that are passed from the `react_component` Rails helper. For example:
+
+ERB view file: 
+
+```ruby
+  # Rails View
+  <%= react_component("HelloWorld", props: { name: "Stranger" }) %>
+```
+
+This is what your HelloWorld.js file might contain. The railsContext is always available for any parameters that you _always_ want available for your React components. It has _nothing_ to do with the concept of the [React Context](https://reactjs.org/docs/context.html).
+
+```js
+import React from 'react';
+
+export default (props, railsContext) => {
+  return (
+    <div>
+      Your locale is {railsContext.i18nLocale}.<br/>
+      Hello, {props.name}!
+    </div>
+  );
+};
+``` 
+
+## Why is the railsContext is only passed to generator functions?
+
+There's no reason that the railsContext would ever get passed to your React component unless the value is explicitly put into the props used for rendering. If you create a react component, rather than a generator function, for use by React on Rails, then you get whatever props are passed in from the view helper, which **does not include the Rails Context**. It's trivial to wrap your component in a "generator function" to return a new component that takes both:
+
+```js
+import React from 'react';
+import AppComponent from './AppComponent';
+const AppComponentWithRailsContext = (props, railsContext) => (
+  <AppComponent {...{...props, railsContext}}/>
+)
+export default AppComponentWithRailsContext;
+```
+
+Consider this line in depth:
+
+```js
+  <AppComponent {...{ ...props, railsContext }}/>
+```
+
+The outer `{...` is for the [JSX spread operator for attributes](https://facebook.github.io/react/docs/jsx-in-depth.html#spread-attributes) and the innner `{...` is for the [Spread in object literals](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Spread_operator#Spread_in_object_literals).
+
+## Use Cases
+
+### Heroku Preboot Considerations
+
+[Heroku Preboot](https://devcenter.heroku.com/articles/preboot) is a feature on Heroku that allows for faster deploy times. When you promote your staging app to production, Preboot simply switches the production server to point at the staging app's container. This means it can deploy much faster since it doesn't have to rebuild anything. However, this means that if you use the [Define Plugin](https://github.com/webpack/docs/wiki/list-of-plugins#defineplugin) to provide the rails environment to your client code as a variable, that variable will erroneously still have a value of `Staging` instead of `Production`. The `Rails.env` provided at runtime in the railsContext is, however, accurate.
+
+### Needing the current URL path for server rendering
+
+Suppose you want to display a nav bar with the current navigation link highlighted by the URL. When you server-render the code, your code will need to know the current URL/path. The new `railsContext` has this information. Your application will apply something like an "active" class on the server rendering.
+
+### Configuring different code for server side rendering
+
+Suppose you want to turn off animation when doing server side rendering. The `serverSide` value is just what you need.
+
+## Customization of the rails_context
+
+You can customize the values passed in the `railsContext` in your `config/initializers/react_on_rails.rb`. Here's how.
+
+Set the config value for the `rendering_extension`:
+
+```ruby
+  config.rendering_extension = RenderingExtension
+```
+
+Implement it like this above in the same file. Create a class method on the module called `custom_context` that takes the `view_context` for a param.
+
+See [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) for a detailed example.
+
+```ruby
+module RenderingExtension
+
+  # Return a Hash that contains custom values from the view context that will get merged with
+  # the standard rails_context values and passed to all calls to generator functions used by the
+  # react_component and redux_store view helpers
+  def self.custom_context(view_context)
+    {
+     somethingUseful: view_context.session[:something_useful]
+    }
+  end
+end
+```
+
+In this case, a prop and value for `somethingUseful` will go into the railsContext passed to all react_component and redux_store calls. You may set any values available in the view rendering context.
+

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

@@ -0,0 +1,40 @@
+# 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. 
+
+Simply run `foreman start -f Procfile.dev`. [Example](spec/dummy/Procfile.static).
+
+On production deployments that use asset precompilation, such as Heroku deployments, React on Rails, by default, will automatically run webpack to build your JavaScript bundles. You configure the command used as `config.build_production_command` in your [config/initializers/react_on_rails.rb](./configuration.md).
+
+You can see the source code for what gets added to your precompilation [here](https://github.com/shakacode/react_on_rails/tree/master/lib/tasks/assets.rake). For more information on this topic, see [the doc on Heroku deployment](docs/additional-reading/heroku-deployment.md#more-details-on-precompilation-using-webpack-to-create-javascript-assets).
+
+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-into-an-existing-rails-app.md

@@ -0,0 +1,64 @@
+# Getting Started with an existing Rails app
+
+**Also consult the instructions for installing on a fresh Rails app**, see the [React on Rails Basic Tutorial](../../docs/tutorial.md).
+
+**If you have rails-5 API only project**, first [convert the rails-5 API only app to rails app](#convert-rails-5-api-only-app-to-rails-app) before [getting started](#getting-started-with-an-existing-rails-app).
+
+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.
+
+   ```ruby
+   gem "react_on_rails", "11.0.0" # Update to the current version
+   gem "webpacker", "~> 3" # Newer versions might be supported
+   ```
+
+2. Run the following 2 commands to install Webpacker with React. Note, f you are using an older version of Rails than 5.1, you'll need to install webpacker with React per the instructions [here](https://github.com/rails/webpacker).
+
+
+   ```bash
+   $ bundle exec rails webpacker:install
+   $ bundle exec rails webpacker:install:react
+   ```
+
+3. Commit this to git (or else you cannot run the generator unless you pass the option `--ignore-warnings`).
+
+4. See help for the generator:
+
+   ```bash
+   $ rails generate react_on_rails:install --help
+   ```
+
+5. Run the generator with a simple "Hello World" example (more options below):
+
+   ```bash
+   $ rails generate react_on_rails:install
+   ```
+
+6. Ensure that you have `foreman` installed: `gem install foreman`.
+
+7. Start your Rails server:
+
+   ```bash
+   $ foreman start -f Procfile.dev
+   ```
+
+8. Visit [localhost:3000/hello_world](http://localhost:3000/hello_world). Note: `foreman` defaults to PORT 5000 unless you set the value of PORT in your environment. For example, you can `export PORT=3000` to use the Rails default port of 3000. For the hello_world example this is already set.
+
+## Installation
+
+See the [Installation Overview](../misc-pending/manual-installation-overview.md) for a concise set summary of what's in a React on Rails installation.
+
+
+## NPM
+
+All JavaScript in React On Rails is loaded from npm: [react-on-rails](https://www.npmjs.com/package/react-on-rails). To manually install this (you did not use the generator), assuming you have a standard configuration, run this command (assuming you are in the directory where you have your `node_modules`):
+
+```bash
+$ yarn add react-on-rails --exact
+```
+
+That will install the latest version and update your package.json. **NOTE:** the `--exact` flag will ensure that you do not have a "~" or "^" for your react-on-rails version in your package.json.
+
+## Webpacker Configuration
+
+React on Rails users should set configuration value `compile` to false, as React on Rails handles compilation for test and production environments.
+

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

@@ -0,0 +1,27 @@
+# React Server Rendering
+
+## What is Server Rendering?
+
+Here's a [decent article to introduce you to server rendering](https://medium.freecodecamp.org/server-side-rendering-your-react-app-in-three-simple-steps-7a82b95db82e). Note, React on Rails takes care of calling the methods in [ReactDOMServer](https://reactjs.org/docs/react-dom-server.html).
+
+During the Rails rendering of HTML per a browser request, the Rails server will execute some JavaScript to create a string of HTML used for React server rendering. This resulting HTML is placed with in your Rails view's output.
+
+The default JavaScript interpretter is [ExecJS](https://github.com/rails/execjs). If you want to maximize the perfomance of your server rendering, then you want to use React on Rails Pro which uses NodeJS to do the server rendering. See the [docs for React on Rails Pro](https://github.com/shakacode/react_on_rails/wiki).
+
+See [this note](basics/how-react-on-rails-works.md#client-side-rendering-vs-server-side-rendering)
+
+
+## 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`
+
+## Do you need server rendering?
+
+Server rendering is used for either SEO or performance reasons.
+
+## Considerations for what code can run on in server rendering
+
+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.

data/docs/{additional-reading → basics}/recommended-project-structure.md

@@ -1,8 +1,32 @@
-# Project structure
+# Recommended Project structure
 
 While React On Rails does not *enforce* a specific project structure, we do *recommend* a standard organization. The more we follow standards as a community, the easier it will be for all of us to move between various Rails projects that include React On Rails.
 
-The best way to understand these standards is to follow this example: [github.com/shakacode/react-webpack-rails-tutorial](https://github.com/shakacode/react-webpack-rails-tutorial)
+The React on Rails generator uses the standard `rails/webpacker` convention of this structure:
+
+```yml
+app/javascript:
+  ├── bundles:
+  │   # Logical groups of files that can be used for code splitting
+  │   └── hello-world-bundle.js
+  ├── packs:
+  │   # only webpack entry files here
+  │   └── hello-world-bundle.js
+```
+
+The problems with this structure and using rails/webpacker to configure Webpack for you:
+
+1. No support for different entry points for server rendering.
+2. Webpacker adds an ex``tra layer of abstraction over Webpack, which you probably don't want.
+
+This default rails/webpacker configuration is used for the generator because:
+
+1. Minimizes the amount of generated code to get up and running with React on Rails.
+2. Good enough for very simple projects.
+3. Configuration of Webpack is not the goal of this library, React on Rails.
+
+
+Thus, the generator structure and using rails/webpacker for Webpack configuration **is not recommended** for any commercial projects, especially those that will use server rendering. Instead, the recommended structure is shown in this example app: [github.com/shakacode/react-webpack-rails-tutorial](https://github.com/shakacode/react-webpack-rails-tutorial) and described below.
 
 ## JavaScript Assets
 1. `/client`: All client side JavaScript goes under the `/client` directory. Place all the major domains of the client side app under client.
@@ -45,5 +69,3 @@ This technique involves customization of the webpack config files to generate CS
 
 #### Updates 2017-03-04 Regarding CSS handled by Webpack
 * See article [Best practices for CSS and CSS Modules using Webpack](https://forum.shakacode.com/t/best-practices-for-css-and-css-modules-using-webpack/799).
-* In the near future, all docs will be updated to Webpack v2 and probably recommended to move all CSS handling to Webpack v2 for advanced users. In the near term, global CSS handled by Rails will be best for simple projects. Another data point is that Rails is moving in direction of handling JavaScript, but not CSS, with [Webpacker](https://github.com/rails/webpacker).
-

data/docs/basics/webpack-configuration.md

@@ -0,0 +1,29 @@
+# Webpack Configuration: custom setup for Webpack or rails/webpacker?
+
+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  
+
+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.
+
+The two best examples of this pattern are the [react-webpack-rails-tutorial](https://github.com/shakacode/react-webpack-rails-tutorial) and the integration test example in [spec/dummy](https://github.com/shakacode/react_on_rails/tree/master/spec/dummy).
+
+In this case, you don't need to understand the nuances of customization of your Wepback config via the [Webpacker mechanism](./docs/additional-reading/webpack-tips.md).
+
+## 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/).
+
+Overall, consider carefully if you prefer the `rails/webpacker` directory structure and Webpack configuration, over the placement of all client side files within the `/client` directory along with conventional Webpack configuration. Once again, the `/client` directory setup is recommended.
+
+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.
+
+For more details on project setup, see [Recommended Project Structure](./docs/basics/recommended-project-structure.md).

data/docs/misc/doctrine.md

@@ -25,7 +25,7 @@ The React on Rails setup provides several key components related to front-end de
 * 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 → misc-pending}/code-splitting.md

@@ -1,5 +1,7 @@
 # Code Splitting
 
+*Note: This document needs updating for Webpack v4, React-Router v4, and using webpacker.*
+
 What is code splitting? From the webpack documentation:
 
 > For big web apps it’s not efficient to put all code into a single file, especially if some blocks of code are only required under some circumstances. Webpack has a feature to split your codebase into “chunks” which are loaded on demand. Some other bundlers call them “layers”, “rollups”, or “fragments”. This feature is called “code splitting”.
@@ -62,7 +64,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
@@ -118,6 +120,10 @@ See:
 - [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.
@@ -140,7 +146,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](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/{basics/installation-overview.md → misc-pending/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:

data/docs/{additional-reading → misc-pending}/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,7 +30,7 @@ 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) 

data/docs/testimonials.md

@@ -0,0 +1,11 @@
+# Testimonials
+
+From Joel Hooks, Co-Founder, Chief Nerd at [egghead.io](https://egghead.io/), January 30, 2017:
+
+![2017-01-30_11-33-59](https://cloud.githubusercontent.com/assets/1118459/22443635/b3549fb4-e6e3-11e6-8ea2-6f589dc93ed3.png)
+
+From Kyle Maune of Cooper Aerial, May 4, 2018
+
+![image](https://user-images.githubusercontent.com/1118459/40891236-9b0b406e-671d-11e8-80ee-c026dbd1d5a2.png)
+
+For more testimonials, see [Live Projects](PROJECTS.md) and [Kudos](KUDOS.md).

data/docs/tutorial.md

@@ -1,6 +1,6 @@
 # React on Rails Basic Tutorial
 
-This tutorial guides you through setting up a new or existing Rails app with **React on Rails**, demonstrating Rails + React + Redux + Server Rendering. It is updated to 10.0.2.
+This tutorial guides you through setting up a new or existing Rails app with **React on Rails**, demonstrating Rails + React + Redux + Server Rendering. It is updated to 11.0.8.
 
 After finishing this tutorial you will get an application that can do the following (live on Heroku):
 
@@ -28,8 +28,8 @@ nvm list                        # check
 
 brew install yarn               # you can use other installer if desired
 
-rvm install 2.4.1               # download and install latest stable Ruby (update to exact version)
-rvm use 2.4.1 --default         # use it and make it default
+rvm install 2.5.0               # download and install latest stable Ruby (update to exact version)
+rvm use 2.5.0 --default         # use it and make it default
 rvm list                        # check
 
 gem install rails               # download and install latest stable Rails
@@ -59,7 +59,7 @@ bundle exec rails webpacker:install:react
 Add the **React On Rails** gem to your Gemfile:
 
 ```
-gem 'react_on_rails', '10.0.2'         # prefer exact gem version to match npm version
+gem 'react_on_rails', '11.0.8'         # prefer exact gem version to match npm version
 ```
 
 Note: Latest released React On Rails version is considered stable. Please use the latest version to ensure you get all the security patches and the best support.

data/lib/generators/USAGE

@@ -21,4 +21,4 @@ Then you may run
 
 More Details:
 
-    `https://github.com/shakacode/react_on_rails/blob/master/docs/basics/generator.md`
+    `https://github.com/shakacode/react_on_rails/blob/master/docs/basics/generator-details.md`

data/lib/react_on_rails/{react_on_rails_helper.rb → helper.rb}

@@ -472,14 +472,14 @@ module ReactOnRails
     end
 
     def initialize_redux_stores
-      return "" unless @registered_stores.present? || @registered_stores_defer_render.present?
-      declarations = "var reduxProps, store, storeGenerator;\n".dup
-      all_stores = (@registered_stores || []) + (@registered_stores_defer_render || [])
-
       result = <<-JS.dup
       ReactOnRails.clearHydratedStores();
       JS
 
+      return result unless @registered_stores.present? || @registered_stores_defer_render.present?
+      declarations = "var reduxProps, store, storeGenerator;\n".dup
+      all_stores = (@registered_stores || []) + (@registered_stores_defer_render || [])
+
       result << all_stores.each_with_object(declarations) do |redux_store_data, memo|
         store_name = redux_store_data[:store_name]
         props = props_string(redux_store_data[:props])

data/lib/react_on_rails/prerender_error.rb

@@ -3,6 +3,7 @@
 # rubocop:disable: Layout/IndentHeredoc
 module ReactOnRails
   class PrerenderError < ::ReactOnRails::Error
+    MAX_ERROR_SNIPPET_TO_LOG = 1000
     # TODO: Consider remove providing original `err` as already have access to `self.cause`
     # http://blog.honeybadger.io/nested-errors-in-ruby-with-exception-cause/
     attr_reader :component_name, :err, :props, :js_code, :console_messages
@@ -58,9 +59,12 @@ Encountered error: \"#{err}\"
       end
       # rubocop:disable Layout/IndentHeredoc
       message << <<-MSG
-when prerendering #{component_name} with props: #{props}
-js_code was:
-#{js_code}
+when prerendering #{component_name} with props: #{Utils.smart_trim(props, MAX_ERROR_SNIPPET_TO_LOG)}
+
+code:
+
+#{Utils.smart_trim(js_code, MAX_ERROR_SNIPPET_TO_LOG)}
+
       MSG
       # rubocop:enable Layout/IndentHeredoc
 

data/lib/react_on_rails/server_rendering_pool.rb

@@ -5,7 +5,6 @@ require_relative "server_rendering_pool/ruby_embedded_java_script"
 
 # Based on the react-rails gem.
 # None of these methods should be called directly.
-# See app/helpers/react_on_rails_helper.rb
 module ReactOnRails
   module ServerRenderingPool
     class << self

data/lib/react_on_rails/utils.rb

@@ -8,6 +8,8 @@ require "active_support/core_ext/string"
 
 module ReactOnRails
   module Utils
+    TRUNCATION_FILLER = "\n... TRUNCATED ...\n"
+
     # https://forum.shakacode.com/t/yak-of-the-week-ruby-2-4-pathname-empty-changed-to-look-at-file-size/901
     # return object if truthy, else return nil
     def self.truthy_presence(obj)
@@ -152,5 +154,20 @@ exitstatus: #{status.exitstatus}#{stdout_msg}#{stderr_msg}
     def self.react_on_rails_pro?
       @react_on_rails_pro ||= gem_available?("react_on_rails_pro")
     end
+
+    def self.smart_trim(str, max_length = 1000)
+      # From https://stackoverflow.com/a/831583/1009332
+      str = str.to_s
+      return str unless str.present? && max_length >= 1
+      return str if str.length <= max_length
+
+      return str[0, 1] + TRUNCATION_FILLER if max_length == 1
+
+      midpoint = (str.length / 2.0).ceil;
+      to_remove = str.length - max_length;
+      lstrip = (to_remove / 2.0).ceil;
+      rstrip = to_remove - lstrip;
+      str[0..(midpoint - lstrip - 1)] + TRUNCATION_FILLER + str[(midpoint + rstrip)..-1]
+    end
   end
 end

data/lib/react_on_rails/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ReactOnRails
-  VERSION = "11.0.9".freeze
+  VERSION = "11.0.10".freeze
 end

data/lib/react_on_rails.rb

@@ -5,7 +5,7 @@ require "rails"
 require "react_on_rails/error"
 require "react_on_rails/prerender_error"
 require "react_on_rails/json_parse_error"
-require "react_on_rails/react_on_rails_helper"
+require "react_on_rails/helper"
 require "react_on_rails/controller"
 require "react_on_rails/version"
 require "react_on_rails/version_checker"

data/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-on-rails",
-  "version": "11.0.9",
+  "version": "11.0.10",
   "description": "react-on-rails JavaScript for react_on_rails Ruby gem",
   "main": "node_package/lib/ReactOnRails.js",
   "directories": {

data/react_on_rails.gemspec

@@ -48,7 +48,7 @@ Gem::Specification.new do |s|
 
   s.add_development_dependency "rake", "~> 10.0"
   s.add_development_dependency "rspec"
-  s.add_development_dependency "rubocop", "0.55.0"
+  s.add_development_dependency "rubocop", "~> 0.58.1"
 
   s.post_install_message = '
 --------------------------------------------------------------------------------