react_on_rails 11.0.9 → 11.0.10

data/SUMMARY.md

@@ -1,50 +1,63 @@
-# Table of Content
+# Table of Contents
 
-### **Rails**
-  + [Rails Assets](./docs/additional-reading/rails-assets.md)
++ [Home](./README.md)
+
+## **Basics**
+  + [React on Rails Basic Installation Tutorial](./docs/tutorial.md)
+  + [Webpack Configuration](./docs/basics/webpack-configuration.md)
+  + [How React on Rails Works](./docs/basics/how-react-on-rails-works.md)
+  + [Recommended Project Structure](./docs/basics/recommended-project-structure.md)
+  + [Generator Functions and the RailsContext](docs/basics/generator-functions-and-railscontext.md)
+  + [Caching and Performance: React on Rails Pro](https://github.com/shakacode/react_on_rails/wiki).
+  + [Deployment](docs/basics/deployment.md).
+  + [React on Rails Internationalization (I18n, localization)](docs/basics/i18n.md)
+  + [RSpec Test Helpers Configuration](docs/basics/rspec-configuration.md)
+  + [Upgrading React on Rails](docs/basics/upgrading-react-on-rails.md)
+  
+## **API**
+  - [View Helpers API](./docs/api/view-helpers-api.md)
+  - [JavaScript API](./docs/api/javascript-api.md)
+  - [Redux Store API](./docs/api/redux-store-api.md)
+
+## **Additional Details**
+  + [Migration from react-rails](./docs/basics/migrating-from-react-rails.md)
+  + [Generator Details](docs/basics/generator-details.md)
+  + [Updating Dependencies](./docs/additional-reading/updating-dependencies.md)
+  + [Manual Installation Overview](docs/misc-pending/manual-installation-overview.md)
+  
+## **Rails**
   + [Rails Engine Integration](./docs/additional-reading/rails-engine-integration.md)
   + [Rails View Rendering from Inline JavaScript](./docs/additional-reading/rails_view_rendering_from_inline_javascript.md)
-  + [RSpec Configuration](./docs/additional-reading/rspec-configuration.md)
   + [Turbolinks](./docs/additional-reading/turbolinks.md)
-  + [React on Rails Internationalization (I18n)](https://github.com/shakacode/react_on_rails/blob/master/docs/basics/i18n.md)
+  + [Rails Assets](docs/misc-pending/rails-assets.md)
+  + [Converting a Rails 5 API only app to a Rails app](./docs/additional-reading/convert-rails-5-api-only-app.md)
 
-### **Javascript**
+## **Javascript**
   + [Node Dependencies, NPM, and Yarn](./docs/additional-reading/node-dependencies-and-npm.md)
   + [Babel](./docs/additional-reading/babel.md)
   + [React Router](./docs/additional-reading/react-router.md)
   + [React & Redux](./docs/additional-reading/react-and-redux.md)
-  + [Webpack](./docs/additional-reading/webpack.md)
-  + [Webpack Configuration](./docs/additional-reading/webpack.md)
-  + [Webpack Cookbook](https://christianalfoni.github.io/react-webpack-cookbook/index.html)
-  + [Developing with the Webpack Dev Server](docs/additional-reading/webpack-dev-server.md)
-  + [Node Server Rendering](./docs/additional-reading/node-server-rendering.md)
+  + [Webpack Tips](./docs/additional-reading/webpack-tips.md)
   + [Server Rendering Tips](./docs/additional-reading/server-rendering-tips.md)
-  + [Code Splitting](./docs/additional-reading/code-splitting.md)
+  + [Code Splitting](docs/misc-pending/code-splitting.md)
   + [AngularJS Integration and Migration to React on Rails](./docs/additional-reading/angular-js-integration-migration.md)
-  + [Webpack, the Asset Pipeline, and Using Assets w/ React](./docs/additional-reading/rails-assets-relative-paths.md)
 
-### **Development**
-  + [React on Rails Basic Installation Tutorial](./docs/tutorial.md)
-  + [Installation Overview](./docs/basics/installation-overview.md)
-  + [Migration from react-rails](./docs/basics/migrating-from-react-rails.md)
-  + [Recommended Project Structure](./docs/additional-reading/recommended-project-structure.md)
-  + [Generator Tips](./docs/basics/generator.md)
-  + [Hot Reloading of Assets For Rails Development](./docs/additional-reading/hot-reloading-rails-development.md)
+## **Deployment**
   + [Heroku Deployment](./docs/additional-reading/heroku-deployment.md)
   + [Elastic Beanstalk Deployment](./docs/additional-reading/elastic-beanstalk.md)
-  + [Updating Dependencies](./docs/additional-reading/updating-dependencies.md)
 
-### **API**
-  + [JavaScript API](./docs/api/javascript-api.md)
-  + [Ruby API](./docs/api/ruby-api.md)
+## Older, Non-Webpack Docs
   + [Setting up Hot Reloading during Rails Development, API docs](./docs/api/ruby-api-hot-reload-view-helpers.md)
+  + [Developing with the Webpack Dev Server](./docs/additional-reading/webpack-dev-server.md)
+  + [Webpack, the Asset Pipeline, and Using Assets w/ React](./docs/additional-reading/rails-assets-relative-paths.md)
+  + [Hot Reloading of Assets For Rails Development](./docs/additional-reading/hot-reloading-rails-development.md)
 
-### **[CONTRIBUTING](CONTRIBUTING.md)**
+## **[CONTRIBUTING](CONTRIBUTING.md)**
   + [Generator Testing](./docs/contributor-info/generator-testing.md)
   + [Linting](./docs/contributor-info/linters.md)
   + [Releasing](./docs/contributor-info/releasing.md)
 
-### **Misc**
+## **Misc**
   + [Tips](./docs/additional-reading/tips.md)
   + [Changelog](./CHANGELOG.md)
   + [Projects](./PROJECTS.md)

data/docs/additional-reading/convert-rails-5-api-only-app.md

@@ -0,0 +1,19 @@
+# Convert Rails 5 API only app to a Rails app
+
+1. Go to the directory where you created your app
+
+```bash
+$ rails new your-current-app-name
+```
+
+Rails will start creating the app and will skip the files you have already created. If there is some conflict then it will stop and you need to resolve it manually. be careful at this step as it might replace you current code in conflicted files.
+
+2. Resolve conflicts
+
+```
+1. Press "d" to see the difference
+2. If it is only adding lines then press "y" to continue
+3. If it is removeing some of your code then press "n" and add all additions manually
+```
+
+3. Run `bundle install` and follow [the instructions for installing into an existing Rails app](../basics/installation-into-an-existing-rails-app.md).*

data/docs/additional-reading/credits.md

@@ -0,0 +1,10 @@
+## Authors
+
+[The Shaka Code team!](http://www.shakacode.com/about/)
+
+The origins of the project began with the need to do a rich JavaScript interface for a ShakaCode's client. The choice to use Webpack and Rails is described in [Fast Rich Client Rails Development With Webpack and the ES6 Transpiler](http://www.railsonmaui.com/blog/2014/10/03/integrating-webpack-and-the-es6-transpiler-into-an-existing-rails-project/).
+
+The gem project started with [Justin Gordon](https://github.com/justin808/) pairing with [Samnang Chhun](https://github.com/samnang) to figure out how to do server rendering with Webpack plus Rails. [Alex Fedoseev](https://github.com/alexfedoseev) then joined in. [Rob Wise](https://github.com/robwise), [Aaron Van Bokhoven](https://github.com/aaronvb), and [Andy Wang](https://github.com/yorzi) did the bulk of the generators. Many others have [contributed](https://github.com/shakacode/react_on_rails/graphs/contributors).
+
+The gem was initially inspired by the [react-rails gem](https://github.com/reactjs/react-rails).
+

data/docs/additional-reading/rails-assets-relative-paths.md

@@ -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](../misc-pending/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](../misc-pending/rails-assets.md).

data/docs/additional-reading/server-rendering-tips.md

@@ -9,10 +9,8 @@ Be sure to use mini_racer. See [issues/428](https://github.com/shakacode/react_o
 - You can conditionally avoid running code that references document by passing in a boolean prop to your top level react
   component. Since the passed in props Hash from the view helper applies to client and server side code, the best way to
   do this is to use a generator function.
-- If you're serious about server rendering, it's worth the effort to have different entry points for client and server rendering. It's worth the extra complexity.
-- You can enable node server rendering if you want. See more information here: https://github.com/shakacode/react_on_rails/blob/master/docs/additional-reading/node-server-rendering.md
-
-The point is that you have separate files for top level client or server side, and you pass some extra option indicating that rendering is happening server side.
+- If you're serious about server rendering, it's worth the effort to have different entry points for client and server rendering. It's worth the extra complexity. The point is that you have separate files for top level client or server side, and you pass some extra option indicating that rendering is happening server side.
+- You can enable Node.js server rendering via [React on Rails Pro](https://github.com/shakacode/react_on_rails/wiki).
 
 ## Troubleshooting Server Rendering
 

data/docs/additional-reading/webpack.md

@@ -18,5 +18,5 @@ Webpack v2 makes this very convenient! See:
 * [Implicit Common Vendor Chunk](https://webpack.js.org/guides/code-splitting-libraries/#implicit-common-vendor-chunk)
 * [Manifest File](https://webpack.js.org/guides/code-splitting-libraries/#manifest-file)
 
-
-
+## Webpack v4
+Webpack v4 is heartily recommended. If you need help with migrating your project to Webpack v4, please contact me, [justin@shakacode.com](mailto:justin@shakacode.com).

data/docs/api/javascript-api.md

@@ -1,5 +1,25 @@
 # ReactOnRails JavaScript API
-The best source of docs is the main [ReactOnRails.js](../../node_package/src/ReactOnRails.js) file. Here's a quick summary. No guarantees that this won't be outdated!
+## CSRF protection
+
+Rails has built-in protection for Cross-Site Request Forgery (CSRF), see [Rails Documentation](http://guides.rubyonrails.org/security.html#cross-site-request-forgery-csrf). To nicely utilize this feature in JavaScript requests, React on Rails provides two helpers that can be used as following for POST, PUT or DELETE requests:
+
+```js
+import ReactOnRails from 'react-on-rails';
+
+// reads from DOM csrf token generated by Rails in <%= csrf_meta_tags %>
+csrfToken = ReactOnRails.authenticityToken();
+
+// compose Rails specific request header as following { X-CSRF-Token: csrfToken, X-Requested-With: XMLHttpRequest }
+header = ReactOnRails.authenticityHeaders(otherHeader);
+```
+
+If you are using [jquery-ujs](https://github.com/rails/jquery-ujs) for AJAX calls, then these helpers are not needed because the [jquery-ujs](https://github.com/rails/jquery-ujs) library updates header automatically, see [jquery-ujs documentation](https://robots.thoughtbot.com/a-tour-of-rails-jquery-ujs#cross-site-request-forgery-protection).
+
+
+
+## API
+
+The best source of docs is the main [ReactOnRails.js](https://github.com/shakacode/react_on_rails/node_package/src/ReactOnRails.js) file. Here's a quick summary. No guarantees that this won't be outdated!
 
 ```js
   /**

data/docs/api/redux-store-api.md

@@ -0,0 +1,100 @@
+# Redux Store
+
+First things first. You don't need to use the `redux_store` api to use redux. This api was setup to support multiple calls to `react_component` on one page that all talk to the same redux store.
+
+If you are only rendering one react component on a page, as is typical to do a "Single Page App" in React, then you should _probably_ pass the props to your React component in a "generator function."
+
+Consider using the `redux_store` helper for the two following use cases:
+
+1. You want to have multiple React components accessing the same store at once.
+2. You want to place the props to hydrate the client side stores at the very end of your HTML, probably server rendered, so that the browser can render all earlier HTML first. This is particularly useful if your props will be large. However, you're probably better off using [React on Rails Pro](https://github.com/shakacode/react_on_rails/wiki) if you're at all concerned about performance.
+
+## Multiple React Components on a Page with One Store
+
+You may wish to have 2 React components share the same the Redux store. For example, if your navbar is a React component, you may want it to use the same store as your component in the main area of the page. You may even want multiple React components in the main area, which allows for greater modularity. Also, you may want this to work with Turbolinks to minimize reloading the JavaScript. 
+
+A good example of this would be something like a notifications counter in a header. As each notification is read in the body of the page, you would like to update the header. If both the header and body share the same Redux store, then this is trivial. Otherwise, we have to rely on other solutions, such as the header polling the server to see how many unread notifications exist.
+
+Suppose the Redux store is called `appStore`, and you have 3 React components that each needs to connect to a store: `NavbarApp`, `CommentsApp`, and `BlogsApp`. I named them with `App` to indicate that they are the registered components.
+
+You will need to make a function that can create the store you will be using for all components and register it via the `registerStore` method. Note: this is a **storeCreator**, meaning that it is a function that takes (props, location) and returns a store:
+
+```js
+function appStore(props, railsContext) {
+  // Create a hydrated redux store, using props and the railsContext (object with
+  // Rails contextual information).
+  return myAppStore;
+}
+
+ReactOnRails.registerStore({
+  appStore
+});
+```
+
+When registering your component with React on Rails, you can get the store via `ReactOnRails.getStore`:
+
+```js
+// getStore will initialize the store if not already initialized, so creates or retrieves store
+const appStore = ReactOnRails.getStore("appStore");
+return (
+  <Provider store={appStore}>
+    <CommentsApp />
+  </Provider>
+);
+```
+
+From your Rails view, you can use the provided helper `redux_store(store_name, props)` to create a fresh version of the store (because it may already exist if you came from visiting a previous page). Note: for this example, since we're initializing this from the main layout, we're using a generic name of `@react_props`. In other words, the Rails controller would set `@react_props` to the properties to hydrate the Redux store.
+
+**app/views/layouts/application.html.erb**
+
+```erb
+...
+<%= redux_store("appStore", props: @react_props) %>;
+<%= react_component("NavbarApp") %>
+yield
+...
+```
+
+Components should be created as [stateless function(al) components](https://facebook.github.io/react/docs/reusable-components.html#stateless-functions). Since you can pass in initial props via the helper `redux_store`, you do not need to pass any props directly to the component. Instead, the component hydrates by connecting to the store.
+
+**_comments.html.erb**
+
+```erb
+<%= react_component("CommentsApp") %>
+```
+
+**_blogs.html.erb**
+
+```erb
+<%= react_component("BlogsApp") %>
+```
+
+*Note:* You will not be doing any partial updates to the Redux store when loading a new page. When the page content loads, React on Rails will rehydrate a new version of the store with whatever props are placed on the page.
+
+## Controller Extension
+
+Include the module `ReactOnRails::Controller` in your controller, probably in ApplicationController. This will provide the following controller method, which you can call in your controller actions:
+
+`redux_store(store_name, props: {})`
+
+- **store_name:** A name for the store. You'll refer to this name in 2 places in your JavaScript:
+  1. You'll call `ReactOnRails.registerStore({storeName})` in the same place that you register your components.
+  2. In your component definition, you'll call `ReactOnRails.getStore('storeName')` to get the hydrated Redux store to attach to your components.
+- **props:**  Named parameter `props`. ReactOnRails takes care of setting up the hydration of your store with props from the view.
+
+For an example, see [spec/dummy/app/controllers/pages_controller.rb](https://github.com/shakacode/react_on_rails/tree/master/spec/dummy/app/controllers/pages_controller.rb). Note: this is preferable to using the equivalent view_helper `redux_store` in that you can be assured that the store is initialized before your components.
+
+## View Helper
+
+`redux_store(store_name, props: {})`
+
+This method has the same API as the controller extension. **HOWEVER**, we recommend the controller extension instead because the Rails executes the template code in the controller action's view file (`erb`, `haml`, `slim`, etc.) before the layout. So long as you call `redux_store` at the beginning of your action's view file, this will work. However, it's an easy mistake to put this call in the wrong place. Calling `redux_store` in the controller action ensures proper load order, regardless of where you call this in the controller action. Note: you won't know of this subtle ordering issue until you server render and you find that your store is not hydrated properly.
+
+`redux_store_hydration_data`
+
+Place this view helper (no parameters) at the end of your shared layout so ReactOnRails will render the redux store hydration data. Since we're going to be setting up the stores in the controllers, we need to know where on the view to put the client-side rendering of this hydration data, which is a hidden div with a matching class that contains a data props. For an example, see [spec/dummy/app/views/layouts/application.html.erb](https://github.com/shakacode/react_on_rails/tree/master/spec/dummy/app/views/layouts/application.html.erb).
+
+# More Details
+
+* [lib/react_on_rails/controller.rb](../../lib/react_on_rails/controller.rb) source
+* [lib/react_on_rails/helper.rb](../../lib/react_on_rails/helper.rb) source

data/docs/api/view-helpers-api.md

@@ -0,0 +1,115 @@
+# View and Controller Helpers
+##  View Helpers API
+
+Once the bundled files have been generated in your `app/assets/webpack` folder and you have registered your components, you will want to render these components on your Rails views using the included helper method, `react_component`.
+
+### react_component
+
+```ruby
+react_component(component_name,
+                props: {},
+                prerender: nil,
+                trace: nil,
+                replay_console: nil,
+                raise_on_prerender_error: nil,
+                id: nil,
+                html_options: {})
+```
+
+- **component_name:** Can be a React component, created using an ES6 class or a generator function that returns a React component (or, only on the server side, an object with shape { redirectLocation, error, renderedHtml }), or a "renderer function" that manually renders a React component to the dom (client side only).
+  All options except `props, id, html_options` will inherit from your `react_on_rails.rb` initializer, as described [here](../basics/configuration.md).
+- **general options:**
+  - **props:** Ruby Hash which contains the properties to pass to the react object, or a JSON string. If you pass a string, we'll escape it for you.
+  - **prerender:** enable server-side rendering of a component. Set to false when debugging!
+  - **id:** Id for the div, will be used to attach the React component. This will get assigned automatically if you do not provide an id. Must be unique.
+  - **html_options:** Any other HTML options get placed on the added div for the component. For example, you can set a class (or inline style) on the outer div so that it behaves like a span, with the styling of `display:inline-block`.
+  - **trace:** set to true to print additional debugging information in the browser. Defaults to true for development, off otherwise. Only on the **client side** will you will see the `railsContext` and your props.
+- **options if prerender (server rendering) is true:**
+  - **replay_console:** Default is true. False will disable echoing server-rendering logs to the browser. While this can make troubleshooting server rendering difficult, so long as you have the configuration of `logging_on_server` set to true, you'll still see the errors on the server.
+  - **logging_on_server:** Default is true. True will log JS console messages and errors to the server.
+  - **raise_on_prerender_error:** Default is false. True will throw an error on the server side rendering. Your controller will have to handle the error.
+
+
+### react_component_hash
+
+`react_component_hash` is used to return multiple HTML strings for server rendering, such as for
+adding meta-tags to a page. It is exactly like react_component except for the following:
+
+1. `prerender: true` is automatically added to options, as this method doesn't make sense for 
+   client only rendering.
+2. Your JavaScript for server rendering must return an Object for the key `server_rendered_html`.
+3. Your view code must expect an object and not a string.
+
+Here is an example of ERB view code:
+
+```erb
+  <% react_helmet_app = react_component_hash("ReactHelmetApp", prerender: true,
+                                             props: { helloWorldData: { name: "Mr. Server Side Rendering"}},
+                                             id: "react-helmet-0", trace: true) %>
+  <% content_for :title do %>
+    <%= react_helmet_app['title'] %>
+  <% end %>
+  <%= react_helmet_app["componentHtml"] %>
+```
+
+And here is the JavaScript code:
+
+```js
+export default (props, _railsContext) => {
+  const componentHtml = renderToString(<ReactHelmet {...props} />);
+  const helmet = Helmet.renderStatic();
+
+  const renderedHtml = {
+    componentHtml,
+    title: helmet.title.toString(),
+  };
+  return { renderedHtml };
+};
+
+```
+
+### cached_react_component and cached_react_component_hash
+Fragment caching is a [React on Rails Pro](https://github.com/shakacode/react_on_rails/wiki) feature. The API is the same as the above, but for 2 differences:
+
+1. The `cache_key` takes the same parameters as any Rails `cache` view helper.
+1. The **props** are passed via a block so that evaluation of the props is not done unless the cache is broken. Suppose you put your props calculation into some method called `some_slow_method_that_returns_props`:
+
+```ruby
+<%= cached_react_component("App", cache_key: [@user, @post], prerender: true) do
+  some_slow_method_that_returns_props
+end %>
+```
+### rails_context
+
+You can call `rails_context(server_side: true | false)` from your controller or view to see what values are are in the Rails Context. Pass true or false depending on whether you want to see the server side or the client side rails_context.
+
+
+### Renderer Functions (function that will call ReactDOM.render or ReactDOM.hydrate)
+
+A "renderer function" is a generator function that accepts three arguments (rather than 2): `(props, railsContext, domNodeId) => { ... }`. Instead of returning a React component, a renderer is responsible for installing a callback that will call `ReactDOM.render` (in React 16+, `ReactDOM.hydrate`) to render a React component into the DOM. The "renderer function" is called at the same time the document ready event would instantate the React components into the DOM.
+
+Why would you want to call `ReactDOM.hydrate` yourself? One possible use case is [code splitting](../misc-pending/code-splitting.md). In a nutshell, you don't want to load the React component on the DOM node yet. So you want to install some handler that will call `ReactDOM.hydrate` at a later time. In the case of code splitting with server rendering, the server rendered code has any async code loaded and used to server render. Thus, the client code must also fully load any asynch code before server rendering. Otherwise, the client code would first render partially, not matching the server rendering, and then a second later, the full code would render, resulting in an unpleasant flashing on the screen.
+
+Renderer functions are not meant to be used on the server since there's no DOM on the server. Instead, use a generator function. Attempting to server render with a renderer function will throw an error.
+
+### React Router
+
+[React Router](https://github.com/reactjs/react-router) is supported, including server-side rendering! See:
+
+1. [React on Rails docs for react-router](../additional-reading/react-router.md)
+2. Examples in [spec/dummy/app/views/react_router](../../spec/dummy/app/views/react_router) and follow to the JavaScript code in the [spec/dummy/client/app/startup/ServerRouterApp.jsx](../../spec/dummy/client/app/startup/ServerRouterApp.jsx).
+3. [Code Splitting docs](../misc-pending/code-splitting.md) for information about how to set up code splitting for server rendered routes.
+
+## server_render_js
+
+`server_render_js(js_expression, options = {})`
+
+- js_expression, like 2 + 3, and not a block of js code. If you have more than one line that needs to be executed, wrap it in an [IIFE](https://en.wikipedia.org/wiki/Immediately-invoked_function_expression). JS exceptions will be caught, and console messages will be handled properly
+- Currently, the only option you may pass is `replay_console` (boolean)
+
+This is a helper method that takes any JavaScript expression and returns the output from evaluating it. If you have more than one line that needs to be executed, wrap it in an IIFE. JS exceptions will be caught and console messages handled properly.
+
+# More details
+
+See the [lib/react_on_rails/helper.rb](../../lib/react_on_rails/helper.rb) source.
+

data/docs/articles.md

@@ -0,0 +1,20 @@
+# Articles, Videos, and Podcasts
+
+## Articles
+
+* [Introducing React on Rails v9 with Webpacker Support](https://blog.shakacode.com/introducing-react-on-rails-v9-with-webpacker-support-f2584c6c8fa4) for an overview of the integration of React on Rails with Webpacker.
+* [Webpacker Lite: Why Fork Webpacker?](https://blog.shakacode.com/webpacker-lite-why-fork-webpacker-f0a7707fac92)
+* [React on Rails, 2000+ 🌟 Stars](https://medium.com/shakacode/react-on-rails-2000-stars-32ff5cfacfbf#.6gmfb2gpy)
+* [The React on Rails Doctrine](https://medium.com/@railsonmaui/the-react-on-rails-doctrine-3c59a778c724)
+* [Simple Tutorial](docs/tutorial.md).
+
+## Videos
+
+*  [Video of running the v9 installer with Webpacker v3](https://youtu.be/M0WUM_XPaII). History, motivations, philosophy, and overview.
+1. [GORUCO 2017: Front-End Sadness to Happiness: The React on Rails Story by Justin Gordon](https://www.youtube.com/watch?v=SGkTvKRPYrk)
+2. [egghead.io: Creating a component with React on Rails](https://egghead.io/lessons/react-creating-a-component-with-react-on-rails)
+3. [egghead.io: Creating a redux component with React on Rails](https://egghead.io/lessons/react-add-redux-state-management-to-a-react-on-rails-project)
+4. [React On Rails Tutorial Series](https://www.youtube.com/playlist?list=PL5VAKH-U1M6dj84BApfUtvBjvF-0-JfEU)
+  1. [History and Motivation](https://youtu.be/F4oymbUHvoY)
+  2. [Basic Tutorial Walkthrough](https://youtu.be/_bjScw60FBk)
+  3. [Code Walkthrough](https://youtu.be/McQ9UM-_ocQ)

data/docs/basics/client-vs-server-rendering.md

@@ -0,0 +1,17 @@
+# Client-Side Rendering vs. Server-Side Rendering
+
+In most cases, you should use the `prerender: false` (default behavior) with the provided 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. We recommend using [mini_racer](https://github.com/discourse/mini_racer) as ExecJS's runtime.
+ 
+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).
+
+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. 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.
+2. 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.
+3. 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.
+
+**Note**:
+
+- 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.

data/docs/basics/deployment.md

@@ -0,0 +1,6 @@
+# Deployment
+
+- React on Rails puts the necessary precompile steps automatically in the rake precompile step. You can, however, disable this by setting certain values to nil in the [config/initializers/react_on_rails.rb](./configuration.md).
+  - `build_production_command`: Set to nil to turn off the precompilation of the js assets.
+  - `config.symlink_non_digested_assets_regex`: Default is nil, turning off the setup of non-js assets. This should be nil except when when using Sprockets rather than Webpacker. 
+- See the [Heroku Deployment](../additional-reading/heroku-deployment.md) doc for specifics regarding Heroku. The information for Heroku may apply to other deployments.

data/docs/basics/{generator.md → generator-details.md}

@@ -1,7 +1,4 @@
-- [Generator](#generator)
-  - [Understanding the Organization of the Generated Client Code](#understanding-the-organization-of-the-generated-client-code)
-  - [Redux](#redux)
-  - [Using Images and Fonts](#using-images-and-fonts)
+# Generator Details
 
 The `react_on_rails:install` generator combined with the example pull requests of generator runs will get you up and running efficiently. There's a fair bit of setup with integrating Webpack with Rails. Defaults for options are such that the default is for the flag to be off. For example, the default for `-R` is that `redux` is off, and the default of `-b` is that `skip-bootstrap` is off.
 
@@ -41,12 +38,12 @@ 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`
 ```
 
 Another good option is to create a simple test app per the [Tutorial](../tutorial.md).
 
-### Understanding the Organization of the Generated Client Code
+# Understanding the Organization of the Generated Client Code
 The generated client code follows our organization scheme. Each unique set of functionality, is given its own folder inside of `client/app/bundles`. This encourages for modularity of *domains*.
 
 Inside of the generated "HelloWorld" domain you will find the following folders:
@@ -57,7 +54,7 @@ Inside of the generated "HelloWorld" domain you will find the following folders:
 
 You may also notice the `app/lib` folder. This is for any code that is common between bundles and therefore needs to be shared (for example, middleware).
 
-### Redux
+## Redux
 If you have used the `--redux` generator option, you will notice the familiar additional redux folders in addition to the aforementioned folders. The Hello World example has also been modified to use Redux.
 
 Note the organizational paradigm of "bundles". These are like application domains and are used for grouping your code into webpack bundles, in case you decide to create different bundles for deployment. This is also useful for separating out logical parts of your application. The concept is that each bundle will have it's own Redux store. If you have code that you want to reuse across bundles, including components and reducers, place them under `/client/app/lib`.