react_on_rails_pro 16.2.0.beta.8

data/docs/caching.md

@@ -0,0 +1,234 @@
+# Caching
+
+Caching at the React on Rails level can greatly speed up your app and reduce the load on your servers, allowing more requests for a given level of hardware.
+
+Consult the [Rails Guide on Caching](http://guides.rubyonrails.org/caching_with_rails.html#cache-stores) for details on:
+
+* [Cache Stores and Configuration](http://guides.rubyonrails.org/caching_with_rails.html#cache-stores)
+* [Determination of Cache Keys](http://guides.rubyonrails.org/caching_with_rails.html#cache-keys)
+* [Caching in Development](http://guides.rubyonrails.org/caching_with_rails.html#caching-in-development): **To toggle caching in development**, run `rails dev:cache`.
+
+See the [bottom note on confirming and debugging cache keys](#confirming-and-debugging-cache-keys).
+
+## Overview
+React on Rails Pro has caching at 2 levels:
+
+1. "Fragment caching" view helpers, `cached_react_component` and `cached_react_component_hash`.  
+2. Caching of requests for server rendering. 
+
+### Tracing
+If tracing is turned on in your config/initializers/react_on_rails_pro.rb, you'll see timing log messages that begin with `[ReactOnRailsPro:1234]: exec_server_render_js` where 1234 is the process id and `exec_server_render_js` could be a different method being traced.
+
+* **exec_server_render_js**: Timing of server rendering, which may have the prerender_caching turned on.
+* **cached_react_component** and **cached_react_component_hash**: Timing of the cached view helper which maybe calling server rendering.
+
+Here's a sample. Note the second request
+```
+Started GET "/server_side_redux_app_cached" for ::1 at 2018-05-24 22:40:13 -1000
+[ReactOnRailsPro:63422] exec_server_render_js: ReduxApp, 230.7ms
+[ReactOnRailsPro:63422] cached_react_component: ReduxApp, 2483.8ms
+Completed 200 OK in 3613ms (Views: 3407.5ms | ActiveRecord: 0.0ms)
+
+
+Started GET "/server_side_redux_app_cached" for ::1 at 2018-05-24 22:40:36 -1000
+Processing by PagesController#server_side_redux_app_cached as HTML
+  Rendering pages/server_side_redux_app_cached.html.erb within layouts/application
+[ReactOnRailsPro:63422] cached_react_component: ReduxApp, 1.1ms
+Completed 200 OK in 19ms (Views: 16.4ms | ActiveRecord: 0.0ms)
+```
+
+## Prerender (Server Side Rendering) Caching
+
+### Why?
+1. Server side rendering is typically done like a stateless functional component, meaning that the result should be idempotent from based on props passed in. 
+1. It's much easier than configuring fragment caching. So long as you have some space in your Rails cache, "it should just work."
+
+### Why not?
+If you're using regular caching for most componentas (cached_react_component_hash), and you don't want to use caching for other components, then having prerender caching still results in caching for all your rendering calls, increasing the liklihood of premature cache ejection.
+
+In the future, React on Rails will allow stateful server rendering. Thus, your server side JavaScript depend on externalities, such as AJAX calls for
+GraphQL. In that case, you will set this caching to false.
+
+### When?
+The largest percentage gains will come from saving the time of server rendering. However, even when not doing server rendering, caching can be effective as the caching will prevent the calculation of the props and the conversion to a string of the prop values.
+
+### How?
+
+To enable caching server rendering requests to the JavaScript calculation engine (ExecJS or Node Renderer), set this config
+value in `config/initializers/react_on_rails_pro.rb` to true (default is false):
+
+```ruby
+  config.prerender_caching = true
+```
+
+Server rendering JavaScript evaluation requests are cached by a cache key that considers the following:
+
+1. Hash of the server bundle.
+2. The JavaScript code to evaluate.
+
+### Diagnostics
+if you're using `react_component_hash`, you'll get 2 extra keys returned:
+
+1. RORP_CACHE_KEY: the prerender cache key
+2. RORP_CACHE_HIT: whether or not there was a cache hit.
+
+It can be useful to log these to the rendered HTML page to debug caching issues.
+
+## React on Rails Fragment Caching
+
+This is very similar to Rails fragment caching. 
+
+From the [Rails docs](http://guides.rubyonrails.org/caching_with_rails.html#fragment-caching):
+
+> Fragment Caching allows a fragment of view logic to be wrapped in a cache block and served out of the cache store when the next request comes in.
+
+It is similar in that the most important parts that you need to consider are:
+
+1. Determining the optimal cache keys that minimize any cost such as database queries.
+2. Clearing the Rails.cache on some deployments.
+
+If you're already familiar with Rails fragment caching, the React on Rails implementation should feel familiar.
+
+The reasons "why" and "why not" are the same as for basic Rails fragment caching:
+
+### Why Use Fragment Caching?
+1. Next to caching at the controller or HTTP level, this is the fastest type of caching.
+2. The additional complexity to add this with React on Rails Pro is minimal.
+3. The performance gains can be huge.
+4. The load on your Rails server can be far lessened.
+
+### Why Not Use Fragment Caching?
+1. It's tricky to get all the right cache keys. You have to consider any values that can change and cause the rendering to change. See the [Rails docs for cache keys](http://guides.rubyonrails.org/caching_with_rails.html#cache-keys)
+2. Testing is a bit tricky or just not done for fragment caching.
+3. Some deployments require you to clear caches.
+
+### Considerations for Determining Your Cache Key
+1. Consult the [Rails docs for cache keys](http://guides.rubyonrails.org/caching_with_rails.html#cache-keys) for help with cache key definitions.
+2. If your React code depends on any values from the [Rails Context](https://github.com/shakacode/react_on_rails/blob/master/docs/basics/generator-functions-and-railscontext.md#rails-context), such as the `locale` or the URL `location`, then be sure to include such values in your cache key. In other words, if you are using some JavaScript such as `react-router` that depends on your URL, or on a call to `toLocalString(locale)`, then be sure to include such values in your cache key. To find the values that React on Rails uses, use some code like this:
+
+```ruby
+the_rails_context = rails_context
+i18nLocale = the_rails_context[:i18nLocale]
+location = the_rails_context[:location]
+```
+
+If you are calling `rails_context` from your controller method, then prefix it like this: `helpers.rails_context` so long as you have react_on_rails > 11.2.2. If less than that, call `helpers.send(:rails_context, server_side: true)`
+
+
+If performance is particulary sensitive, consult the view helper definition for `rails_context`. For example, you can save the cost of calculating the rails_context by directly getting a value:
+
+```ruby
+i18nLocale = I18n.locale
+```
+ 
+### How: API
+Here is the doc for helpers `cached_react_component` and `cached_react_component_hash`. Consult the [docs in React on Rails](https://www.shakacode.com/react-on-rails/docs/api/view-helpers-api/) for the non-cached analogies `react_component` and `react_component_hash`. These docs only show the differences.
+
+```ruby
+  # Provide caching support for react_component in a manner akin to Rails fragment caching.
+  # All the same options as react_component apply with the following difference:
+  #
+  # 1. You must pass the props as a block. This is so that the evaluation of the props is not done
+  #    if the cache can be used.
+  # 2. Provide the cache_key option
+  #    cache_key: String or Array (or Proc returning a String or Array) containing your cache keys. 
+  #    If prerender is set to true, the server bundle digest will be included in the cache key. 
+  #    The cache_key value is the same as used for conventional Rails fragment caching.
+  # 3. Optionally provide the `:cache_options` key with a value of a hash including as 
+  #    :compress, :expires_in, :race_condition_ttl as documented in the Rails Guides
+  # 4. Provide boolean values for `:if` or `:unless` to conditionally use caching.
+```
+
+You can find the `:cache_options` documented in the [Rails docs for ActiveSupport cache store](https://guides.rubyonrails.org/caching_with_rails.html#activesupport-cache-store).
+
+#### API Usage examples
+
+The fragment caching for `react_component`:
+```ruby
+<%= cached_react_component("App", cache_key: [@user, @post], prerender: true) do
+  some_slow_method_that_returns_props
+end %>
+```
+
+Suppose you only want to cache when `current_user.nil?`. Use the `:if` option (`unless:` is analogous):
+```ruby
+<%= cached_react_component("App", cache_key: [@user, @post], prerender: true, if: current_user.nil?) do
+  some_slow_method_that_returns_props
+end %>
+```
+
+And a fragment caching version for the `react_component_hash`:
+
+```ruby
+<% result = cached_react_component_hash("ReactHelmetApp", cache_key: [@user, @post],
+                                           id: "react-helmet-0") do
+    some_slow_method_that_returns_props
+   end %>
+
+<% content_for :title do %>
+  <%= react_helmet_app['title'] %>
+<% end %>
+
+<%= react_helmet_app["componentHtml"] %>
+
+<% printable_cache_key = ReactOnRailsPro::Utils.printable_cache_key(result[:RORP_CACHE_KEY]) %>
+<!-- <%= "CACHE_HIT: #{result[:RORP_CACHE_HIT]}, RORP_CACHE_KEY: #{printable_cache_key}" %> -->
+````
+Note in the above example, React on Rails Pro returns both the raw cache key and whether or not there was a cache hit.
+
+
+### Your JavaScript Bundles and Cache Keys 
+
+When doing fragment caching of server rendering with React on Rails Pro, the cache key must reflect
+your React. This is analogous to how Rails puts an MD5 hash of your views in
+the cache key so that if the views change, then your cache is busted. In the case
+of React code, if your React code changes, then your bundle name will
+change if you are doing the inclusion of a hash in the name. However, if you are
+using a separate webpack configuration to generate the server bundle file,
+then you **must not** include the hash in the output filename or else you will
+have a race condition overwriting your `manifest.json`. Regardless of which
+case you have, React on Rails handles it.
+
+# Confirming and Debugging Cache Keys
+
+Cache key composition can be confirmed in development mode with the following steps. THe goal is to confirm that some change that should  trigger new cached data actually triggers a new cache key. For example, when the server bundle changes, does that trigger a new cache key for any server rendering?
+
+1. Run `Rails.cache.clear` to clear the cache.
+1. Run `rails dev:cache` to toggle caching in development mode. 
+
+You will see a message like:
+> Development mode is now being cached.
+
+You might need to check your `config/development.rb`contains the following:
+```ruby
+  # Enable/disable caching. By default caching is disabled.
+  if Rails.root.join("tmp/caching-dev.txt").exist?
+    config.action_controller.perform_caching = true
+
+    config.cache_store = :memory_store
+    config.public_file_server.headers = {
+      "Cache-Control" => "public, max-age=172800"
+    }
+    
+    # For Rails >= 5.1 determines whether to log fragment cache reads and writes in verbose format as follows:
+    config.action_controller.enable_fragment_cache_logging
+  else
+    config.action_controller.perform_caching = false
+
+    config.cache_store = :null_store
+  end
+```
+
+3. Start your server in development mode. You should see cache entries in the console log. Fetch the page that uses the cache. Make a note of the cache key used for the cached component.
+
+4. Suppose you want to confirm that updated JavaScript causes a cache key change. Make any change to the JavaScript that's server rendered or change the version of any package in the bundle.
+
+5. Check the cache entry again. You should have noticed that it changed.
+
+
+To avoid seeing the cache calls to the prerender_caching, you can temporarily set:
+```
+config.prerender_caching = false
+```
+
+

data/docs/code-splitting-loadable-components.md

@@ -0,0 +1,313 @@
+# Server-side rendering with code-splitting using Loadable/Components
+by ShakaCode
+
+*Last updated September 19, 2022*
+
+## Introduction
+The [React library recommends](https://loadable-components.com/docs/getting-started/) the use of React.lazy for code splitting with dynamic imports except
+when using server-side rendering. In that case, as of February 2020, they recommend [Loadable Components](https://loadable-components.com)
+for server-side rendering with dynamic imports. 
+
+Note, in 2019 and prior, the code-splitting feature was implemented using `react-loadable`. The React
+team no longer recommends that library. The new way is far preferable.
+
+## Installation
+
+```
+yarn add  @loadable/babel-plugin @loadable/component @loadable/server @loadable/webpack-plugin
+```
+
+### Summary
+- [`@loadable/babel-plugin`](https://loadable-components.com/docs/getting-started/) - The plugin transforms your code to be ready for Server Side Rendering. 
+- `@loadable/component` - Main library for creating loadable components.
+- `@loadable/server` - Has functions for collecting chunks and provide style, script, link tags for the server.
+- `@loadable/webpack-plugin` - The plugin to create a stats file with all chunks, assets information.
+
+## Configuration
+
+These instructions mainly repeat the [server-side rendering steps from the official documentation for Loadable Components](https://loadable-components.com/docs/server-side-rendering/), but with some additions specifically to react_on_rails_pro.
+
+### Webpack
+
+#### Server Bundle Configuration
+
+See example of server configuration differences in the loadable-components [example of the webpack.config.babel.js
+for server-side rendering](https://github.com/gregberge/loadable-components/blob/master/examples/server-side-rendering/webpack.config.babel.js)
+
+You need to configure 3 things:
+1. `target` 
+  a. client-side: `web`
+  b. server-side: `node`
+2. `output.libraryTarget`
+  a. client-side: `undefined`
+  b. server-side: `commonjs2`
+3. babel-loader options.caller = 'node' or 'web'   
+3. `plugins`
+  a. server-side:  `new webpack.optimize.LimitChunkCountPlugin({ maxChunks: 1 })`
+
+```js
+{
+  target: 'node',
+  plugins: [
+    ...,
+    new webpack.optimize.LimitChunkCountPlugin({ maxChunks: 1 })
+  ]
+}
+```
+
+Explanation:
+
+- `target: 'node'` is required to be able to run the server bundle with the dynamic import logic on nodejs.
+If that is not done, webpack will add and invoke browser-specific functions to fetch the chunks into the bundle, which throws an error on server-rendering.
+
+- `new webpack.optimize.LimitChunkCountPlugin({ maxChunks: 1 })`
+The react_on_rails_pro node-renderer expects only one single server-bundle. In other words, we cannot and do not want to split the server bundle.
+
+#### Client config
+
+For the client config we only need to add the plugin:
+```js
+{
+  plugins: [
+    ...,
+     new LoadablePlugin({ filename: 'loadable-stats.json' })
+  ]
+}
+```
+This plugin collects all the information about entrypoints, chunks, and files, that have these chunks and creates a stats file during client bundle build.
+This stats file is used later to map rendered components to file assets. While you can use any filename, our documentation will use the default name.
+
+### Babel
+
+Per [the docs](https://loadable-components.com/docs/babel-plugin/#transformation):
+> The plugin transforms your code to be ready for Server Side Rendering
+
+Add this to `babel.config.js`:
+```js
+{
+  "plugins": ["@loadable/babel-plugin"]
+}
+```
+https://loadable-components.com/docs/babel-plugin/
+
+
+### Convert components into loadable components
+
+Instead of importing the component directly, use a dynamic import:
+
+```js
+import load from '@loadable/component'
+const MyComponent = load(() => import('./MyComponent'))
+```
+
+### Resolving issue with ChunkLoadError
+
+Sometimes chunks might not be loaded (network issues or others). You may get errors like this:
+
+```js
+ChunkLoadError: Loading chunk 6 failed.
+(error: https://www.cityfalcon.com/packs/js/News-58215546ef43bc340bac.chunk.js)
+```
+
+This can be fixed by using a retry loop:
+
+```js
+// https://gist.github.com/briancavalier/842626
+const consoleDebug = (fn) => {
+  if (typeof console.debug !== 'undefined') {
+    console.debug(fn());
+  }
+};
+const retry = (fn, retryMessage = '', retriesLeft = 3, interval = 500) => new Promise((resolve, reject) => {
+  fn()
+    .then(resolve)
+    .catch(() => {
+      setTimeout(() => {
+        if (retriesLeft === 1) {
+          console.warn(`Maximum retries exceeded, retryMessage: ${retryMessage}. Reloading page...`);
+          window.location.reload();
+          return;
+        }
+        // Passing on "reject" is the important part
+        consoleDebug(() => `Trying request, retryMessage: ${retryMessage}, retriesLeft: ${retriesLeft - 1}`);
+        retry(fn, retryMessage, retriesLeft - 1, interval).then(resolve, reject);
+      }, interval);
+    });
+});
+export default retry;
+```
+
+Then use it in your component:
+
+```js
+import retry from 'utils/retry';
+const HomePage = loadable(() => retry(() => import('./HomePage')));
+```
+
+**Please note that babel must not be configured to strip comments, since the chunk name is defined in a comment.**
+
+### Server and client entries
+
+#### Client
+
+In the client bundle, we need to wrap the `hydrateRoot` call into a `loadableReady` function.
+So, hydration will be fired only after all necessary chunks preloads. In this example below,
+`ClientApp` is registering as `App`. 
+
+```js
+import React from 'react';
+import ReactOnRails from 'react-on-rails';
+import { hydrateRoot } from 'react-dom/client'
+import { loadableReady } from '@loadable/component'
+import App from './App';
+
+const ClientApp = (props, railsContext, domId) => {
+  loadableReady(() => {
+    const root = document.getElementById(domId)
+    hydrateRoot(root, <App {...props} />);
+  })
+}
+
+ReactOnRails.register({
+  App: ClientApp,
+});
+```
+
+#### Server
+
+The purpose of the server function is to collect all rendered chunks and pass them as script, link, 
+style tags to the Rails view. In this example below, `ServerApp` is registering as `App`. 
+
+```js
+import React from 'react';
+import ReactOnRails from 'react-on-rails';
+import { ChunkExtractor } from '@loadable/server'
+import App from './App'
+import path from 'path'
+
+const ServerApp = (props, railsContext) => {
+  // This loadable-stats file was generated by `LoadablePlugin` in client webpack config.
+  // You must configure the path to resolve per your setup. If you are copying the file to
+  // a remote server, the file should be a sibling of this file. 
+  // __dirname is going to be the directory where the server-bundle.js exists
+  // Note, React on Rails Pro automatically copies the loadable-stats.json to the same place as the
+  // server-bundle.js. Thus, the __dirname of this code is where we can find loadable-stats.json.
+  // Be sure to configure ReactOnRailsPro.config.assets_top_copy to this file.
+  const statsFile = path.resolve(__dirname, 'loadable-stats.json');
+
+  // This object is used to search filenames by corresponding chunk names.
+  // See https://loadable-components.com/docs/api-loadable-server/#chunkextractor
+  // for the entryPoints, pass an array of all your entryPoints using dynamic imports
+  const extractor = new ChunkExtractor({ statsFile, entrypoints: ['client-bundle'] })
+
+  // It creates the wrapper `ChunkExtractorManager` around `App` to collect chunk names of rendered components.
+  const jsx = extractor.collectChunks(<App {...props} railsContext={railsContext} />)
+
+  const componentHtml = renderToString(jsx);
+
+  return {
+    renderedHtml: {
+      componentHtml,
+      // Returns all the files with rendered chunks for furture insert into rails view.
+      linkTags: extractor.getLinkTags(),
+      styleTags: extractor.getStyleTags(),
+      scriptTags: extractor.getScriptTags()
+    }
+  };
+};
+
+ReactOnRails.register({
+  App: ServerApp,
+});
+```
+
+## Configure react_on_rails_pro
+
+### React on Rails Pro
+You must set `config.assets_top_copy` so that the node-renderer will have access to the loadable-stats.json.
+
+```ruby
+  config.assets_to_copy = Rails.root.join("public", "webpack", Rails.env, "loadable-stats.json")
+```
+
+Your server rendering code, per the above, will find this file like this:
+
+```js
+  const statsFile = path.resolve(__dirname, 'loadable-stats.json');
+``` 
+
+Note, if `__dirname` is not working in your webpack build, that's because you didn't set `node: false`
+in your webpack configuration. That turns off the polyfills for things like `__dirname`.
+
+
+### Node Renderer
+In your `node-renderer.js` file which runs node renderer, you need to specify `supportModules` options as follows:
+```js
+const path = require('path');
+const env = process.env;
+const { reactOnRailsProNodeRenderer } = require('react-on-rails-pro-node-renderer');
+
+const config = {
+  ...
+  supportModules: env.RENDERER_SUPPORT_MODULES || null,
+};
+...
+
+reactOnRailsProNodeRenderer(config);
+```
+
+## Rails View
+
+```erb
+<% res = react_component_hash("App", props: {}, prerender: true) %>
+<%= content_for :link_tags, res['linkTags'] %>
+<%= content_for :style_tags, res['styleTags'] %> 
+
+<%= res['componentHtml'].html_safe %>
+
+<%= content_for :script_tags, res['scriptTags'] %>
+```
+
+## Making HMR Work
+To make HMR work, it's best to disable loadable-components when using the Dev Server.
+Note: you will need access to our **private** React on Rails Pro repository to open the following links.
+
+Take a look at the code searches for ['imports-loadable'](https://github.com/shakacode/react_on_rails_pro/search?q=imports-loadable&type=code) and ['imports-hmr'](https://github.com/shakacode/react_on_rails_pro/search?q=imports-hmr&type=code)
+
+The general concept is that we have a non-loadable, HMR-ready, file that substitutes for the loadable-enabled one, with the suffixes `imports-hmr.js` instead of `imports-loadable.js`
+
+### Webpack configuration
+Use the [NormalModuleReplacement plugin](https://webpack.js.org/plugins/normal-module-replacement-plugin/):
+
+[code](https://github.com/shakacode/react_on_rails_pro/blob/a361f4e163b9170f180ae07ee312fb9b4c719fc3/spec/dummy/config/webpack/environment.js#L81-L91)
+```js
+if (isWebpackDevServer) {
+  environment.plugins.append(
+    'NormalModuleReplacement',
+    new webpack.NormalModuleReplacementPlugin(/(.*)\.imports-loadable(\.jsx)?/, (resource) => {
+      // eslint-disable-next-line no-param-reassign
+      resource.request = resource.request.replace(/imports-loadable/, 'imports-hmr');
+      return resource.request;
+    }),
+  );
+}
+```
+
+And compare:
+
+### Routes file
+
+Note: you will need access to our **private** React on Rails Pro repository to open the following links.
+
+- [spec/dummy/client/app/components/Loadable/routes/Routes.imports-hmr.jsx](https://github.com/shakacode/react_on_rails_pro/blob/master/spec/dummy/client/app/components/Loadable/routes/Routes.imports-hmr.jsx)
+- [spec/dummy/client/app/components/Loadable/routes/Routes.imports-loadable.jsx](https://github.com/shakacode/react_on_rails_pro/blob/master/spec/dummy/client/app/components/Loadable/routes/Routes.imports-loadable.jsx)
+
+### Client-Side Startup
+
+- [spec/dummy/client/app/loadable/loadable-client.imports-hmr.js](https://github.com/shakacode/react_on_rails_pro/blob/master/spec/dummy/client/app/loadable/loadable-client.imports-hmr.js)
+- [spec/dummy/client/app/loadable/loadable-client.imports-loadable.js](https://github.com/shakacode/react_on_rails_pro/blob/master/spec/dummy/client/app/loadable/loadable-client.imports-loadable.js)
+
+### Server-Side Startup
+
+- [spec/dummy/client/app/loadable/loadable-server.imports-hmr.jsx](https://github.com/shakacode/react_on_rails_pro/blob/master/spec/dummy/client/app/loadable/loadable-server.imports-hmr.jsx)
+- [spec/dummy/client/app/loadable/loadable-server.imports-loadable.jsx](https://github.com/shakacode/react_on_rails_pro/blob/master/spec/dummy/client/app/loadable/loadable-server.imports-loadable.jsx)