react_on_rails 11.3.0 → 12.0.0.pre.beta.4

data/docs/basics/recommended-project-structure.md

@@ -1,7 +1,5 @@
 # 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
@@ -14,21 +12,9 @@ app/javascript:
   │   └── 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 extra 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.
+However, you may wish to move all your client side files to a single directory called something like `/client`.
 
-
-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.
-
-## Steps to convert from the generator defaults to use the recommended `/client` directory structure.
+## Steps to convert from the generator defaults to use a `/client` directory structure.
 
 1. Move the directory:
 
@@ -44,7 +30,7 @@ mv app/javascript 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 (which is highly recommended!).
+`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).
@@ -57,7 +43,7 @@ mv app/javascript client
 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.
@@ -79,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.
@@ -89,6 +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).

data/docs/basics/{generator-functions-and-railscontext.md → render-functions-and-railscontext.md}

@@ -1,45 +1,80 @@
-# Generator Functions and Rails Context 
+# Render-Functions and the Rails Context 
 
-## Generator Functions
+## Render-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:
+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).
+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.
+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 generator functions.
+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 "generator function" called MyAppComponent.
+For example, suppose you create a "render-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>
+  // 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 generator function `MyAppComponent`, it will get called like:
+So if you register your render-function `MyAppComponent`, it will get called like:
 
 ```js
 reactComponent = MyAppComponent(props, railsContext);
 ```
 
-and, similarly, any redux store always initialized with 2 parameters:
+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.
+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.)
 
@@ -76,7 +111,7 @@ Plus, you can add your customizations to this. See "rendering extension" below.
 
 ## 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:
+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: 
 
@@ -91,7 +126,8 @@ This is what your HelloWorld.js file might contain. The railsContext is always a
 import React from 'react';
 
 export default (props, railsContext) => {
-  return (
+  // Note, wrap in a function so this is React function component
+  return () => (
     <div>
       Your locale is {railsContext.i18nLocale}.<br/>
       Hello, {props.name}!
@@ -100,15 +136,17 @@ export default (props, railsContext) => {
 };
 ``` 
 
-## Why is the railsContext is only passed to generator functions?
+## 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 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:
+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) => (
-  <AppComponent {...{...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;
 ```
@@ -153,7 +191,7 @@ See [spec/dummy/config/initializers/react_on_rails.rb](https://github.com/shakac
 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
+  # 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)
     {

data/docs/basics/rspec-configuration.md

@@ -1,9 +1,31 @@
 # 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.
 
-ReactOnRails 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`.
+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|
@@ -22,40 +44,29 @@ If you are using Webpack to build CSS assets, you should do something like this
 ```
 
 Please take note of the following:
-- If you are using Webpacker, be **SURE** to configure the `source_path` in your `config/webpacker.yml` unless you are using the defaults for webpacker. If you are not using webpacker, all files in the node_modules_location are used for your test sources.
+- 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. This is actually a common occurrence when you've built your test generated files and then you sync up your repository files.
+- 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 for the `config.generated_assets_dir` folder for generated files, configured via setting `webpack_generated_files`, in the `config/react_on_rails.rb`. If the `config.generated_assets_dir` 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. You can override the location of these files inside of `config/initializers/react_on_rails.rb` by passing a filepath (relative to the root of the app) to the `generated_assets_dir` configuration option.
+- 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
-  # Directory where your generated assets go. All generated assets must go to the same directory.
-  # Configure this in your webpack config files. This relative to your Rails root directory.
-  # We recommend having different generated assets dirs per Rails env.
-  config.generated_assets_dir = File.join(%w[public webpack], Rails.env)
-
   # Define the files we need to check for webpack compilation when running tests.
-  # Generally, the manifest.json is good enough for this check if using webpacker
   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 )
   
-  # OR if you're not using webpacker, your setup might look like.
-  # config.webpack_generated_files = %w( client-bundle.js server-bundle.js )
-  
   # 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.
-
-[spec/dummy](https://github.com/shakacode/react_on_rails/tree/master/spec/dummy) contains examples of how to set the proc files for this purpose.
+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)
 

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

@@ -5,6 +5,62 @@ If you would like help in migrating between React on Rails versions or help with
 
 We specialize in helping companies to quickly and efficiently move from versions before 9 to current. The older versions use the Rails asset pipeline to package client assets. The current and recommended way is to use Webpack 4 for asset preparation. You may also need help migrating from the `rails/webpacker`'s Webpack configuration to a better setup ready for Server Side Rendering.
 
+## Upgrading to v12
+### Recent versions
+Make sure that you are on a relatively more recent version of rails and webpacker.
+v12 is tested on Rails 6. It should work on Rails v5. If you're on an older version, 
+and v12 doesn't work, please file an issue. 
+
+### i18n default format changed to JSON
+* If you're using the internalization helper, then set `config.i18n_output_format = 'js'`. You can
+  later update to the default JSON format as you will need to update your usage of that file. A JSON
+  format is more efficient.
+
+### Updated API for `ReactOnRails.register()`
+
+In order to solve the issues regarding React Hooks compatibility, the number of parameters
+for functions is used to determine if you have a render function that will get invoked to
+return a React component, or you are registering a React component defined by a function.
+
+##### Correct
+
+Registered Objects are of the following types. Either of these will work:
+1. Take **2 params** and return **a React function or class component**. A function component is a function
+   that takes zero or one params and returns a React Element, like JSX.
+    ```js
+    export default (props, _railsContext) => () => <Component {...props} />;
+    ```
+
+2. Take only zero or one params and you return a React Element, often JSX.
+    ```js
+    export default (props) => <Component {...props} />;
+    ```
+##### Broken, as this function takes two params and it returns a React Element from a JSX Literal
+```js
+export default (props, _railsContext) => <Component {...props} />;
+```
+
+If you make this mistake, you'll get this warning
+`Warning: React.createElement: type is invalid -- expected a string (for built-in components) or a class/function (for composite components) but got: <Fragment />. Did you accidentally export a JSX literal instead of a component?`
+
+And this error:
+`react-dom.development.js:23965 Uncaught Error: Element type is invalid: expected a string (for built-in components) or a class/function (for composite components) but got: object.`
+
+In this example, you need to wrap the `<Component {...props} />` in a function call like this which
+results in the return value being a React function component.
+
+```js
+export default (props, _railsContext) => () => <Component {...props} />;
+```
+
+If you have a pure component, taking one or zero parameters, and you have an unnecessary function
+wrapper such that you're returning a function rather than a React Element, then:
+
+1. You won't see anything render.
+2. You will see this warning in development mode: `Warning: Functions are not valid as a React child. This may happen if you return a Component instead of <Component /> from render. Or maybe you meant to call this function rather than return it.`
+
+---------
+
 ## Upgrading rails/webpacker from v3 to v4
 ### Custom Webpack build file
 The default value for `extract_css` is **false** in `config/webpack.yml`. Custom webpack builds should set this value to true or else no CSS link tags are generated. You have a custom webpack build if you are not using [rails/webpacker](https://github.com/rails/webpacker to setup your Webpack configuration.
@@ -42,8 +98,8 @@ Reason for doing this: This enables your webpack bundles to bypass the Rails ass
 ##### ...while keeping your `client` directory
 *   `.gitignore`: add `/public/webpack/*`
 *   `Gemfile`: bump `react_on_rails` and add `webpacker`
-*   layout views: anything bundled by webpack will need to be requested by a `javascript_pack_tag` or `stylesheet_pack_tag`. 
-  * Search your codebase for javascript_include_tag. Use the 
+*   layout views: anything bundled by webpack will need to be requested by a `javascript_pack_tag` or `stylesheet_pack_tag`.
+  * Search your codebase for javascript_include_tag. Use the
 *   `config/initializers/assets.rb`: we no longer need to modify `Rails.application.config.assets.paths` or append anything to `Rails.application.config.assets.precompile`.
 *   `config/initializers/react_on_rails.rb`:
     *   Delete `config.generated_assets_dir`. Webpacker's config now supplies this information

data/docs/basics/webpack-configuration.md

@@ -17,13 +17,27 @@ A key decision in your use React on Rails is whether you go with the rails/webpa
 
 ## 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  
+Until version 9, all React on Rails apps used the `/client` directory for configuring React on Rails in terms of the configuration of Webpack and location of your JavaScript and Webpack files, including the node_modules directory. Version 9 changed the default to `/` for the `node_modules` location using this value in `config/initializers/react_on_rails.rb`: `config.node_modules_location`. 
 
-The [ShakaCode Team](http://www.shakacode.com) _recommends_ this approach for projects beyond the simplest cases as it provides the greatest transparency in your webpack and overall client-side setup. The *big advantage* to this is that almost everything within the `/client` directory will apply if you wish to convert your client-side code to a pure Single Page Application that runs without Rails. This allows you to google for how to do something with Webpack configuration and what applies to a non-Rails app will apply just as well to a React on Rails app.
+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).
+An examples of this pattern is the [react-webpack-rails-tutorial](https://github.com/shakacode/react-webpack-rails-tutorial).
 
-In this case, you don't need to understand the nuances of customization of your Wepback config via the [Webpacker mechanism](./docs/additional-reading/webpack-tips.md).
+In this case, you don't need to understand the nuances of customization of your Webpack config via the [Webpacker mechanism](./docs/additional-reading/webpack-tips.md).
+
+You can access values in the `config/webpacker.yml`
+
+```js
+const { config, devServer } = require('@rails/webpacker');
+```
+
+You will want consider using some of the same values set in these files:
+
+* https://github.com/rails/webpacker/blob/master/package/environments/base.js
+* https://github.com/rails/webpacker/blob/master/package/environments/development.js
+
+**Note**, if your node_modules directory is not at the top level of the Rails project, then you will need to set the
+ENV value of WEBPACKER_CONFIG to the location of the `config/webpacker.yml` file per [rails/webpacker PR 2561](https://github.com/rails/webpacker/pull/2561).
 
 ## Option 2: Default Generator Setup: rails/webpacker app/javascript
 
@@ -31,10 +45,6 @@ Typical rails/webpacker apps have a standard directory structure as documented [
 
 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/contributor-info/errors-with-hooks.md

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

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

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