react_on_rails 11.0.3 → 12.0.0

data/docs/basics/hmr-and-hot-reloading-with-the-webpack-dev-server.md

@@ -0,0 +1,49 @@
+# HMR and Hot Reloading with the webpack-dev-server
+
+The webpack-dev-server provides:
+
+1. Speedy compilation of client side assets
+2. Optional HMR which means that the page will reload automatically when after
+   compilation completes. Note, some developers do not like this, as you'll
+   abruptly lose any tweaks within the Chrome development tools.
+3. Optional hot-reloading. The older react-hot-loader has been deprecated in 
+   favor of [fast-refresh](https://reactnative.dev/docs/fast-refresh).
+   For use with webpack, see [react-refresh-webpack-plugin](https://github.com/pmmmwh/react-refresh-webpack-plugin).
+
+If you are ***not*** using server-side rendering (***not*** using `prerender: true`),
+then you can follow all the regular docs for using the `bin/webpack-dev-server` 
+during development.
+
+
+# Server Side Rendering with the Default rails/webpacker bin/webpack-dev-server
+
+If you are using server-side rendering, then you have a couple options. The
+recommended technique is to have a different webpack configuration for server
+rendering.  
+
+
+
+
+## If you use the same Webpack setup for your server and client bundles 
+If you do use the webpack-dev-server for prerendering, be sure to set the
+`config/initializers/react_on_rails.rb` setting of 
+
+```
+  config.same_bundle_for_client_and_server = true
+```
+
+`dev_server.hmr` maps to [devServer.hot](https://webpack.js.org/configuration/dev-server/#devserverhot).
+This must be false if you're using the webpack-dev-server for client and server bundles.
+ 
+`dev_server.inline` maps to [devServer.inline](https://webpack.js.org/configuration/dev-server/#devserverinline).
+This must also be false.
+
+If you don't configure these two to false, you'll see errors like:
+
+* "ReferenceError: window is not defined" (if hmr is true)
+* "TypeError: Cannot read property 'prototype' of undefined" (if inline is true)
+
+
+
+
+

data/docs/basics/i18n.md

@@ -1,23 +1,10 @@
-# How to add I18n
+# I18n
 
 Here's a summary of adding the I18n functionality.
 
-You can refer to [react-webpack-rails-tutorial](https://github.com/shakacode/react-webpack-rails-tutorial) and [PR #340](https://github.com/shakacode/react-webpack-rails-tutorial/pull/340), [commmited](https://github.com/shakacode/react-webpack-rails-tutorial/commit/ef369ed9d922aea5116ca7e50208169fd7831389) for a complete example.
+1. Add `config.i18n_dir` in `config/initializers/react_on_rails.rb`
 
-1. Add `react-intl` & `intl` to `client/package.json`, and remember to `bundle && yarn install`.
-
-  ```js
-  "dependencies": {
-    ...
-    "intl": "^1.2.5",
-    "react-intl": "^2.1.5",
-    ...
-  }
-  ```
-
-2. Add `config.i18n_dir` in `config/initializers/react_on_rails.rb`
-
-  `react-intl` requires locale files in json format. React on Rails will generate `translations.js` & `default.js` automatically after you configured your `config.i18n_dir` in `config/initializers/react_on_rails.rb`.
+  React on Rails will generate `translations.json` & `default.json` automatically (see #3) after you configured your `config.i18n_dir` in `config/initializers/react_on_rails.rb`.
 
   ```ruby
   # Replace the following line to the location where you keep translation.js & default.js.
@@ -31,16 +18,50 @@ You can refer to [react-webpack-rails-tutorial](https://github.com/shakacode/rea
   config.i18n_yml_dir = Rails.root.join("PATH_TO", "YOUR_YAML_I18N_FOLDER")
   ```
 
-  `translations.js`: All your locales in json format.
-  `default.js`: Default settings in json format.
+  `translations.json`: All your locales in json format.
+  `default.json`: Default settings in json format.
 
-3. Add `translations.js` and `default.js` to your `.gitignore` and `.eslintignore`.
+2. Add `translations.json` and `default.json` to your `.gitignore`.
+
+3. Javascript locale files must be generated before `yarn build`.
 
-4. Javascript locale files must be generated before `yarn build`.
+  Once you setup `config.i18n_dir` as in the previous step, you will need to make sure `rake react_on_rails:locale` runs before webpack. 
+  
+  For development, you should adjust your startup scripts (Procfiles) so that they run **`bundle exec rake react_on_rails:locale`** before running any webpack watch process (`yarn run build:development`). 
+  
+  You may need to configure your CI to  run **`bundle exec rake react_on_rails:locale`** before any webpack process if you are not using the React on Rails test helper. 
+  
+  Note, if you are try to lint before running tests, and you are depending on the test helper to build your locales, your linting will fail because the translations won't be built yet. 
+  
+  The fix is either to 
+  1) run the rake task to build the translations before running the lint command or 
+  2) to run the tests first.
 
-  Once you setup `config.i18n_dir` as in the previous step, react_on_rails will automatically do this for testing (if using the `ReactOnRails::TestHelper.configure_rspec_to_compile_assets` and for production deployments if using the [default precompile rake hook](../additional-reading/heroku-deployment.md). For development, you should adjust your startup scripts (Procfiles) so that they run **`bundle exec rake react_on_rails:locale`** before running any webpack watch process (`yarn run build:development`). You may need to configure your CI to  run **`bundle exec rake react_on_rails:locale`** before any webpack process if you are not using the React on Rails test helper. Note, if you are try to lint before running tests, and you are depending on the test helper to build your locales, your linting will fail because the translations won't be built yet. The fix is either to 1) run the rake task to build the translations before running the lint command or 2) to run the tests first.
+# Generate locales with react-intl support
 
-5. In React, you need to initialize `react-intl`, and set parameters for it.
+By default the locales generated in json format. If you need to generate files in the prior way
+with `react-intl` supported via js files:
+
+1. Specify i18n output format in `react_on_rails.rb`:
+  ```rb
+    config.i18n_output_format = 'js'
+  ```
+
+2. Add `react-intl` & `intl` to `client/package.json`, and remember to `bundle && yarn install`.
+   Versions should be newer than these:
+
+  ```js
+  "dependencies": {
+    ...
+    "intl": "^1.2.5",
+    "react-intl": "^2.1.5",
+    ...
+  }
+  ```
+
+3. Add `translations.js` and `default.js` to your `.gitignore` and `.eslintignore`.
+
+4. In React, you need to initialize `react-intl`, and set parameters for it.
 
   ```js
   ...
@@ -73,5 +94,6 @@ You can refer to [react-webpack-rails-tutorial](https://github.com/shakacode/rea
   ```
   
   # Notes
-  
+  * See why using JSON could be better compare to JS if amount of data is hure [ https://v8.dev/blog/cost-of-javascript-2019#json]( https://v8.dev/blog/cost-of-javascript-2019#json).
   * See [Support for Rails' i18n pluralization #1000](https://github.com/shakacode/react_on_rails/issues/1000) for a discussion of issues around pluralization.
+  * *Outdated:* You can refer to [react-webpack-rails-tutorial](https://github.com/shakacode/react-webpack-rails-tutorial) and [PR #340](https://github.com/shakacode/react-webpack-rails-tutorial/pull/340), [commmited](https://github.com/shakacode/react-webpack-rails-tutorial/commit/ef369ed9d922aea5116ca7e50208169fd7831389) for a complete example.

data/docs/basics/installation-into-an-existing-rails-app.md

@@ -0,0 +1,59 @@
+# 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", "12.0.0" # Update to the current version
+   gem "webpacker", "~> 5"
+   ```
+
+2. Run the following 2 commands to install Webpacker with React. Note, if 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](docs/outdated/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.

data/docs/basics/minitest-configuration.md

@@ -0,0 +1,31 @@
+# Minitest Configuration
+
+The setup for minitest is the same as for rspec with the following difference.
+
+Rather than calling `ReactOnRails::TestHelper.configure_rspec_to_compile_assets(config)`, instead you will do something like this:
+
+```ruby
+class ActiveSupport::TestCase
+  setup do
+    ReactOnRails::TestHelper.ensure_assets_compiled
+  end
+end    
+```
+
+
+Or maybe something like this, from the [minitest docs](https://github.com/seattlerb/minitest/blob/master/lib/minitest/test.rb#L119):
+
+```ruby
+module MyMinitestPlugin
+  def before_setup
+    super
+    ReactOnRails::TestHelper.ensure_assets_compiled
+  end
+end
+
+class MiniTest::Test
+  include MyMinitestPlugin
+end
+```
+
+ 

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

@@ -0,0 +1,29 @@
+# React Server Rendering
+
+See also [Client vs. Server Rendering](./client-vs-server-rendering.md)
+
+## 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](docs/outdated/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,41 @@
-# 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 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
+```
+
+However, you may wish to move all your client side files to a single directory called something like `/client`.
+
+## Steps to convert from the generator defaults to use a `/client` directory structure.
+
+1. Move the directory:
+
+```
+mv app/javascript client
+```
+
+2. Edit your `/config/webpacker.yml` file. Change the `default/source_path`:
+
+```yml
+  source_path: client
+```
+
+## Moving node_modules from `/` to `/client` with a custom webpack setup.
+
+`rails/webpacker` probably doesn't support having your main node_modules directory under `/client`, so only follow these steps if you want to use your own webpack configuration.
+
+1. Move the `/package.json` to `/client/package.json`
+2. Create a `/package.json` that delegates to `/client/package.json`. See the example in [spec/dummy/package.json](../../spec/dummy/package.json).
+3. See the webpack configuration in [spec/dummy/client](../../spec/dummy/client) for a webpack configuration example.
 
-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)
 
 ## 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.
@@ -10,7 +43,7 @@ The best way to understand these standards is to follow this example: [github.co
 1. `/client/app/bundles`: Top level of different app domains. Use a name within this directory for you app domains. For example, if you had a domain called `widget-editing`, then you would have: `/client/app/bundles/widget-editing`
 1. `/client/app/lib`: Common code for bundles
 1. Within each bundle directory (or the lib directory), such as a domain named "comments"
-`/client/app/bundles/comments`, use following directory structure:
+`/client/app/bundles/comments`, use following directory structure, if you're using redux. However, with React hooks, this will probably be a bit different:
 
   * `/actions`: Redux actions.
   * `/components`: "dumb" components (no connections to Redux or Ajax). These get props and can render themselves and children.
@@ -32,7 +65,7 @@ This isn't really any technique, as you keep handling all your styling assets us
 1. Much simpler! There's no changes really from your current processes.
 
 ### Using Webpack to Manage Styling Assets
-This technique involves customization of the webpack config files to generate CSS, image, and font assets. See [webpack.client.rails.build.config.js](https://github.com/shakacode/react_on_rails/blob/master/spec%2Fdummy%2Fclient%2Fwebpack.client.rails.build.config.js) for an example how to set the webpack part.
+This technique involves customization of the webpack config files to generate CSS, image, and font assets. 
 
 #### Directory structure
 1. `/client/app/assets`: Assets for CSS for client app.
@@ -42,8 +75,3 @@ This technique involves customization of the webpack config files to generate CS
 1. You can use [CSS modules](https://github.com/css-modules/css-modules), which is super compelling once you seen the benefits.
 1. You can do hot reloading of your assets. Thus, you do not have to refresh your web page to see asset change, including changing styles.
 1. You can run your client code on a mocked out express server for super fast prototyping. In other words, your client application can somewhat more easily be move to a different application server.
-
-#### 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/render-functions-and-railscontext.md

@@ -0,0 +1,205 @@
+# Render-Functions and the Rails Context 
+
+## Render-Functions
+
+When you use a render-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).
+
+These 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 render functions.
+
+For example, suppose you create a "render-function" called MyAppComponent.
+
+```js
+import React from 'react';
+const MyAppComponent = (props, railsContext) => (
+  // NOTE: need to wrap in a function so this is proper React function component that can use
+  // hooks
+ 
+  // the props get passed again, but we ignore since we use a closure
+  // or should we
+  () =>
+      <div>
+        <p>props are: {JSON.stringify(props)}</p>
+        <p>railsContext is: {JSON.stringify(railsContext)}
+        </p>
+      </div>
+);
+export default MyAppComponent;
+```
+
+------------------------------
+
+_This would be alternate API where you have to call React.createElement and the React on Rails code doesn't do that._
+
+```js
+import React from 'react';
+const MyAppComponent = (props, railsContext) => (
+  // NOTE: need to wrap in a function so this is proper React function component that can use
+  // hooks
+  React.createElement(
+    () =>
+      <div>
+        <p>props are: {JSON.stringify(props)}</p>
+        <p>railsContext is: {JSON.stringify(railsContext)}
+        </p>
+      </div>,
+  props)
+);
+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 render-function `MyAppComponent`, it will get called like:
+
+```js
+reactComponent = MyAppComponent(props, railsContext);
+```
+
+and, similarly, any redux store is 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. If you don't take a second parameter, then you're probably defining a React function component and you will simply return a React Element, often just JSX.
+
+(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 [ReactOnRails::Helper](https://github.com/shakacode/react_on_rails/tree/master/lib/react_on_rails/helper.rb), method `rails_context` for the definitive list).
+
+```ruby
+  {
+    railsEnv: Rails.env
+    inMailer: in_mailer?,
+    # Locale settings
+    i18nLocale: I18n.locale,
+    i18nDefaultLocale: I18n.default_locale,
+    rorVersion: ReactOnRails::VERSION,
+    rorPro: ReactOnRails::Utils.react_on_rails_pro?
+    
+    # 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
+    httpAcceptLanguage: request.env["HTTP_ACCEPT_LANGUAGE"]
+
+    # 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!
+  }
+```
+
+Plus, you can add your customizations to this. See "rendering extension" below.
+
+## Rails Context
+
+The `railsContext` is a second param passed to your render-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) => {
+  // Note, wrap in a function so this is React function component
+  return () => (
+    <div>
+      Your locale is {railsContext.i18nLocale}.<br/>
+      Hello, {props.name}!
+    </div>
+  );
+};
+``` 
+
+## Why is the railsContext only passed to render-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 render-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 "render-function" to return a new component that takes both:
+
+```js
+import React from 'react';
+import AppComponent from './AppComponent';
+const AppComponentWithRailsContext = (props, railsContext) => (
+  // Create a React Function Component so you can
+  // use the React Hooks API in this React Function Component
+  () => <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 render-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/rspec-configuration.md

@@ -0,0 +1,73 @@
+# RSpec Configuration
+_Click [here for minitest](./minitest-configuration.md)_
+
+# 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
+returned by the files in `/config/webpack`, then you have 2 options to ensure that your files are
+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).
+
+```yml
+  config.build_test_command = "NODE_ENV=test RAILS_ENV=test bin/webpack"
+``` 
+
+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.
+
+# Checking for stale assets using React on Rails
+
+Because you will probably want to run RSpec tests that rely on compiled webpack assets (typically, your integration/feature specs where `js: true`), you will want to ensure you don't accidentally run tests on missing or stale webpack assets. If you did use stale Webpack assets, you will get invalid test results as your tests do not use the very latest JavaScript code.
+
+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`.
+
+```ruby
+RSpec.configure do |config|
+  ReactOnRails::TestHelper.configure_rspec_to_compile_assets(config)
+```
+
+You can pass one or more RSpec metatags as an optional second parameter to this helper method if you want this helper to run on examples other than where `:js`, `:server_rendering`, or `:controller` (those are the defaults). The helper will compile webpack files at most once per test run. The helper will not compile the webpack files unless they are out of date (stale). The helper is configurable in terms of what command is used to prepare the files. If you don't specify these metatags for your relevant JavaScript tests, then you'll need to do the following.
+
+If you are using Webpack to build CSS assets, you should do something like this to ensure that you assets are built for any specs under `specs/requests` or `specs/features`:
+
+```ruby
+  ReactOnRails::TestHelper.configure_rspec_to_compile_assets(config, :requires_webpack_assets)
+  config.define_derived_metadata(file_path: %r{spec/(features|requests)}) do |metadata|
+    metadata[:requires_webpack_assets] = true
+  end
+```
+
+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. 
+
+- 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. 
+
+- 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.
+  config.build_test_command = "yarn run build:test"
+```
+
+If you want to speed up the re-compiling process so you don't wait to run your tests to build the files, you can run your test compilation with the "watch" flags. For example, `yarn run build:test --watch`
+
+![2016-01-27_02-36-43](https://cloud.githubusercontent.com/assets/1118459/12611951/7c56d070-c4a4-11e5-8a80-9615f99960d9.png)
+
+![2016-01-27_03-18-05](https://cloud.githubusercontent.com/assets/1118459/12611975/a8011654-c4a4-11e5-84f9-1baca4835b4b.png)