react_on_rails 11.0.5 → 13.4.0

data/docs/guides/how-to-conditionally-server-render-based-on-device-type.md

@@ -0,0 +1,40 @@
+# How to conditionally render server side based on the device type
+
+In general, we want to use CSS to do mobile responsive layouts.
+
+However, sometimes we want to have layouts sufficiently different that we can't do this via CSS. If we didn't do server rendering, we can check the device type on the client side. However, if we're doing server rendering, we need to send this data to the client code from the Rails server so that the server rendering can account for this.
+
+Here's an example:
+
+## config/initializers/react_on_rails.rb
+
+```ruby
+module RenderingExtension
+  # Return a Hash that contains custom values from the view context that will get passed to
+  # all calls to react_component and redux_store for rendering
+  def self.custom_context(view_context)
+    if view_context.controller.is_a?(ActionMailer::Base)
+      {}
+    else
+      {
+        desktop: !(view_context.browser.device.tablet? || view_context.browser.device.mobile?),
+        tablet: view_context.browser.device.tablet?,
+        mobile: view_context.browser.device.mobile? || false
+      }
+    end
+  end
+end
+
+# Shown below are the defaults for configuration
+ReactOnRails.configure do |config|
+  # See https://github.com/shakacode/react_on_rails/blob/master/docs/guides/configuration.md for the rest
+
+  # This allows you to add additional values to the Rails Context. Implement one static method
+  # called `custom_context(view_context)` and return a Hash.
+  config.rendering_extension = RenderingExtension
+end
+```
+
+Note, full details of the React on Rails configuration are [here in docs/basics/configuration.md](https://shakacode.com/react-on-rails/docs/guides/configuration/).
+
+See the doc file [docs/basics/generator-functions-and-railscontext.md](https://shakacode.com/react-on-rails/docs/guides/generator-functions-and-railscontext/#rails-context) for how your client-side code uses the device information

data/docs/guides/how-to-use-different-files-for-client-and-server-rendering.md

@@ -0,0 +1,98 @@
+## How to use different versions of a file for client and server rendering
+
+There are 3 main ways to use different code for server vs. client rendering.
+
+## A. Using different Entry Points
+Many projects will have different entry points for client and server rendering. This only works for a top-level entry point such as the entry point for a react-router app component.
+
+Your Client Entry can look like this:
+
+```js
+import ReactOnRails from 'react-on-rails';
+import App from './ClientApp';
+ReactOnRails.register({ App })
+```
+
+So your Server Entry can look like:
+
+```js
+import ReactOnRails from 'react-on-rails';
+import App from './ServerApp';
+ReactOnRails.register({ App })
+```
+
+Note that the only difference is on the second line of each of these examples.
+
+## B. Two Options for Using Webpack Resolve Alias in the Webpack Config
+Per [Webpack Docs](https://webpack.js.org/configuration/resolve/#resolve-alias).
+
+### 1. Update `webpack/set-resolve.js` to have a different resolution for the exact file:
+
+```js
+function setResolve(builderConfig, webpackConfig) {
+
+  // Use a different resolution for Client and Server file
+  let SomeJsFile;
+  if (builderConfig.serverRendering) {
+    SomeJsFile = path.resolve(__dirname, "../bundles/SomeJsFileServer");
+  } else {
+    SomeJsFile = path.resolve(__dirname, "../bundles/SomeJsFileClient");
+  }
+
+ const resolve = {
+    alias: {
+      ... // blah blah
+      SomeJsFile,
+      ... // blah blah
+    },
+```
+
+Then you have this import:
+
+```js
+import SomeJsFile from 'SomeJsFile';
+```
+
+### 2. Use a different resolution for the right directory of client or server files:
+
+#### a. Update `webpack/set-resolve.js` to have something like:
+```js
+function setResolve(builderConfig, webpackConfig) {
+
+  // Use a different resolution for Client and Server file
+  let variant;
+  if (builderConfig.serverRendering) {
+    variant = path.resolve(__dirname, "../bundles/variant/ClientOnly");
+  } else {
+    variant = path.resolve(__dirname, "../bundles/variant/serverOnly");
+  }
+
+ const resolve = {
+    alias: {
+      ... // blah blah
+      variant
+      ... // blah blah
+    },
+```
+
+#### b. Add different versions of the file to the `bundles/variant/ClientOnly` and `bundles/variant/ServerOnly` directories
+
+#### c. Use the `variant` in import in a file that can be used both for client and server rendering:
+
+```js
+import SomeJsFile from 'variant/SomeJsFile';
+import AnotherJsFile from 'variant/AnotherJsFile';
+```
+
+## C. Conditional code that can check if `window` is defined.
+
+This is probably the ugliest and hackiest way to do this, but it's quick! Essentially you wrap code that cannot execute server side in a conditional:
+
+```js
+if (window) { // window should be falsy on the server side
+  doSomethingClientOnly();
+  
+  // or do an import
+  const foobar = require('foobar').default;
+}
+```

data/docs/guides/i18n.md

@@ -0,0 +1,87 @@
+# Internationalization
+
+You can use [Rails internationalization (i18n)](https://guides.rubyonrails.org/i18n.html) in your client code.
+
+1. Set `config.i18n_dir` in `config/initializers/react_on_rails.rb`:
+
+    ```ruby
+    # Replace the following line by the directory containing your translation.js and default.js files.
+    config.i18n_dir = Rails.root.join("PATH_TO", "YOUR_JS_I18N_FOLDER")
+    ```
+
+    If you do not want to use the YAML files from `Rails.root.join("config", "locales")` and installed gems, you can also set `config.i18n_yml_dir`:
+    ```ruby
+    # Replace the following line by the location of your client i18n yml files
+    # Without this option, all YAML files from Rails.root.join("config", "locales") and installed gems are loaded
+    config.i18n_yml_dir = Rails.root.join("PATH_TO", "YOUR_YAML_I18N_FOLDER")
+    ```
+
+2. Add that directory (or just the generated files `translations.json` and `default.json`) to your `.gitignore`.
+
+3. The locale files must be generated before `yarn build` using `rake react_on_rails:locale`.
+
+    For development, you should adjust your startup scripts (`Procfile`s) so that they run `bundle exec rake react_on_rails:locale` before running any webpack watch process (`yarn run build:development`). 
+
+    If you are not using the React on Rails test helper,
+    you may need to configure your CI to  run `bundle exec rake react_on_rails:locale` before any webpack process as well. 
+
+    Note: if you try to lint before running tests, and you depend on the test helper to build your locales, 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.
+
+By default, the locales are generated as JSON, but you can also generate them as JavaScript with [`react-intl`](https://formatjs.io/docs/getting-started/installation/) support:
+
+1. Specify the i18n output format in `config/initializers/react_on_rails.rb`:
+    ```rb
+    config.i18n_output_format = "js"
+    ```
+
+2. Add `react-intl` & `intl` to `client/package.json`, and remember to `bundle install && yarn install`. The minimum supported versions are:
+
+    ```js
+    "dependencies": {
+      ...
+      "intl": "^1.2.5",
+      "react-intl": "^2.1.5",
+      ...
+    }
+    ```
+
+3. In React, you need to initialize `react-intl`, and set its parameters:
+
+    ```js
+    ...
+    import { addLocaleData } from 'react-intl';
+    import en from 'react-intl/locale-data/en';
+    import de from 'react-intl/locale-data/de';
+    import { translations } from 'path_to/i18n/translations';
+    import { defaultLocale } from 'path_to/i18n/default';
+    ...
+    // Initizalize all locales for react-intl.
+    addLocaleData([...en, ...de]);
+    ...
+    // set locale and messages for IntlProvider.
+    const locale = method_to_get_current_locale() || defaultLocale;
+    const messages = translations[locale];
+    ...
+    return (
+      <IntlProvider locale={locale} key={locale} messages={messages}>
+        <CommentScreen {...{ actions, data }} />
+      </IntlProvider>
+    )
+    ```
+    ```js
+    // In your component.
+    import { defaultMessages } from 'path_to/i18n/default';
+    ...
+    return (
+      { formatMessage(defaultMessages.yourLocaleKeyInCamelCase) }
+    )
+    ```
+
+# Notes
+* See why using JSON can perform better compared to JS for large amounts of data [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/guides/installation-into-an-existing-rails-app.md

@@ -0,0 +1,66 @@
+# 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](https://www.shakacode.com/react-on-rails/docs/guides/tutorial/).
+
+**If you have rails-5 API only project**, first [convert the rails-5 API only app to rails app](https://www.shakacode.com/react-on-rails/docs/rails/convert-rails-5-api-only-app-to-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 `package.json` file.
+
+   ```ruby
+   gem "shakapacker", "7.0.1"     # Use the latest and the exact version
+   gem "react_on_rails", "13.3.1" # Use the latest and the exact version
+   ```
+
+   Or use `bundle add`:
+
+   ```bash
+   bundle add shakapacker --version=7.0.1 --strict
+   bundle add react_on_rails --version=13.3.1 --strict
+   ```
+
+2. Run the following 2 commands to install Shakapacker 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
+   rails shakapacker:install
+   ```
+
+3. Commit this to git (or else you cannot run the generator unless you pass the option `--ignore-warnings`).
+
+4. Run the generator with a simple "Hello World" example (more options below):
+
+   ```bash
+   rails generate react_on_rails:install
+   ```
+
+   For more information about this generator use `--help` option:
+
+   ```bash
+   rails generate react_on_rails:install --help
+   ```
+5. Ensure that you have `overmind` or `foreman` installed.
+
+   Note: `foreman` should be installed on the system not on your project. [Read more](https://github.com/ddollar/foreman/wiki/Don't-Bundle-Foreman)
+
+6. Start your Rails server:
+
+   ```bash
+   ./bin/dev
+   ```
+   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.
+
+7. Visit [localhost:3000/hello_world](http://localhost:3000/hello_world).
+
+## Installation
+
+See the [Installation Overview](https://www.shakacode.com/react-on-rails/docs/additional-details/manual-installation-overview/) 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/guides/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/guides/rails-webpacker-react-integration-options.md

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

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

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

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

@@ -0,0 +1,32 @@
+# React Server Rendering
+
+See also [Client vs. Server Rendering](https://www.shakacode.com/react-on-rails/docs/guides/client-vs-server-rendering/).
+
+## What is the easiest way to setup a webpack configuration for server-side-rendering?
+See the example webpack setup here: [github.com/shakacode/react_on_rails_demo_ssr_hmr](https://github.com/shakacode/react_on_rails_demo_ssr_hmr).
+
+## 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](https://www.shakacode.com/react-on-rails/docs/guides/client-vs-server-rendering/).
+
+## How do you do Server Rendering with React on Rails?
+1. The `react_component` view helper method provides the `prerender:` option to switch on or off server rendering.
+1. Configure your Webpack setup to create a different server bundle per your needs. While you may reuse the same bundle as for client rendering, this is not common in larger apps for many reasons, such as 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 = "server-bundle.js"` in your `config/initializers/react_on_rails.rb`
+1. You should ***not*** put a hash on the server-bundle so that you can easily use the webpack-dev-server for client bundles and have the server bundle generated by a watch process.
+
+## Do you need server rendering?
+
+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 and file system access don't work when server rendering with ExecJS. Instead, you can use the Node renderer or [React on Rails Pro](https://www.shakacode.com/react-on-rails-pro/).