react_on_rails_pro 16.2.0.beta.8

data/docs/code-splitting.md

@@ -0,0 +1,349 @@
+# Server-side rendering with code-splitting in React on Rails
+by ShakaCode
+
+*Last updated June 13, 2019*
+
+# Deprecated
+
+**Please, see [our new documentation on how to setup code splitting with loadable components](./code-splitting-loadable-components.md).**
+
+# Introduction
+
+Webpack has an interesting feature called dynamic code-splitting, which automatically breaks the bundle into parts where the `import ()` function is used.
+
+For more convenient work with `import ()` there are libraries like react-loadable.
+It provides a special function by which you can turn any react component into a dynamic component.
+
+To use react-loadable in the react on rails project, you do not need to take any additional action until the server-side rendering is used.
+
+If the project includes server rendering, then you need to exclude the use of dynamic imports on the server-rendering side. I.e. it needs to generate a server bundle in which contains statically imported components only. This is due to how the ExecJS renderer and the node-renderer cannot use promises.
+
+# Dependencies
+
+Install following libraries in client folder:
+```
+yarn add react-loadable webpack-conditional-loader
+```
+
+- [react-loadable](https://github.com/jamiebuilds/react-loadable) - take cares of loading and correctly displaying our dynamic components.
+- [webpack-conditional-loader](https://www.npmjs.com/package/webpack-conditional-loader) - allow us conditionally extract parts of our code into different bundles. 
+
+Add `webpack-conditional-loader` to the loaders, like this:
+```js
+{
+  test: /\.jsx?$/,
+  use: {
+  use: [{
+    loader: 'babel-loader',
+    options: {
+      cacheDirectory: true,
+    },
+  },
+  }, 'webpack-conditional-loader'],
+  exclude: /node_modules/,
+},
+```
+
+Optionally. Create alias for `DynamicImports.js` file in `resolve`:
+```js
+alias: {
+  DynamicImports: path.resolve(__dirname, 'client', 'DynamicImports.js'),
+}
+```
+
+# Simple example of using dynamic components
+
+Consider the component that we want to convert to a dynamic:
+```
+components
+  |_ Map
+      |_Map.jsx
+```
+
+Let's create `index.jsx` in `Map` directory with the following contents:
+```jsx
+let Component = null;
+
+/* 
+  the comments `#if` that you see below is a C-like conditional directive
+  used by webpack-conditional-loader. This condition tells webpack's loader
+  to use only one specific code depends on existence of `IS_SSR` env variable
+  So, when `IS_SSR` variable is present, webpack-conditional-loader comments out the
+  code in `#if process.env.IS_SSR !== 'true' .... #end` clause before processing this
+  file by babel-loader.
+*/
+// #if process.env.IS_SSR === 'true'
+import StaticComponent from './Map';
+
+Component = StaticComponent;
+// #endif
+
+// #if process.env.IS_SSR !== 'true'
+import React from 'react';
+import Loadable from 'react-loadable';
+
+import Loading from '../Loading';
+
+const load = opts => Loadable({
+  delay: 10000,
+  loading: () => <Loading />,
+  render(loaded, props) {
+    const LoadedComponent = loaded.default;
+    return <LoadedComponent {...props} />;
+  },
+  ...opts,
+});
+
+
+/* Here we're wrapping our component in react-loadable HOC */
+const DynamicComponent = load({
+  /* 
+    We need to specify these params: `webpackChunkName`, `modules` and `webpack`
+    so react-loadable can load our chunk correctly
+  */
+  loader: () => import(/* webpackChunkName: "Map" */'./Map'),
+  modules: ['./Map'],
+  webpack: () => [require.resolveWeak('./Map')],
+});
+
+Component = DynamicComponent;
+// #endif
+
+/*
+  When `IS_SSR` present, `Component` equals `StaticComponent`, otherwise `DynamicComponent`
+*/
+export default Component;
+```
+
+Now, if we want to use this component we should import it like this:
+```jsx
+import Map from './components/Map'
+```
+in this case, webpack will load `index.jsx` instead of `Map.jsx` if not some other special order specified.
+
+Also, `IS_SSR=true` must added when creating server side bundle, like this:
+```
+NODE_ENV=production IS_SSR=true webpack --config webpack.config.ssr.prod.js
+```
+
+The new chunk `Map.chunk.js` will be automatically extracted due dynamic code-splitting feature.
+
+With this configuration, server rendering will work with static components, and client with dynamic components.
+
+## Flickering
+
+On the client, we can periodically see `Loading ...` instead of the right components.  
+This is due to the fact that react-loadable loads the module with the component only when it is mounted to the DOM.
+
+React-loadable has the ability to preload the required component, for example, when we hover the cursor on the menu item. This will remove `Loading ...` in some situations.  
+More details can be found in the documentation react-loadable.
+[https://github.com/jamiebuilds/react-loadable#preloading](https://github.com/jamiebuilds/react-loadable#preloading)
+
+But we can get rid of annoying flickering `Loading ...` the first time the page loads. The server renderer has already rendered the necessary components. Therefore, we can transfer this information from the server renderer to the client and preload the necessary modules.
+
+Unfortunately, the way specified in the documentation `react-loadable` does not work for us. 
+
+Here is another similar method.
+
+For this we use the function `registerDynamicComponentOnServer`. We will place it in the new file `DynamicImports.js`:
+
+
+```javascript
+export const registerDynamicComponentOnServer = name => {
+  const serverSide = typeof window === 'undefined'
+
+  if (serverSide) {
+    if (typeof global.dynamicComponents === 'undefined') {
+      global.dynamicComponents = []
+    }
+    if (global.dynamicComponents.indexOf(name) === -1) {
+      global.dynamicComponents.push(name)
+    }
+  }
+}
+```
+As you can see from the function body, it runs only for server-side rendering.  
+It simply adds the name of the component to the global array `dynamicComponents` which will be transferred to the client later.
+
+It must be imported into the component that needs to be made dynamic and called in the render method of this component. For example:
+
+components/Map/Map.jsx:
+```javascript
+...
+import { registerDynamicComponentOnServer } from 'DynamicImports';
+
+class Map extends React.Component {
+  constructor(props) {
+    super(props);
+    ...
+    registerDynamicComponentOnServer('Map');
+  }
+  ...
+}
+```
+
+
+Then this global array must be passed to the client.
+To do this, change server entry point as follows:
+
+
+**ServerApp.js**:
+```javascript
+import React from 'react';
+import ReactOnRails from 'react-on-rails';
+
+import App from './App';
+
+const ServerApp = (props, railsContext) => {
+
+  const html = renderToString(
+    <App
+      {...props}
+      components={{ MainPage, AboutPage }}
+    />
+  );
+
+  return {
+    html,
+    dynamicComponents: JSON.stringify(global.dynamicComponents),
+  };
+}
+
+ReactOnRails.register({ App: ServerApp })
+
+export default ServerApp
+```
+
+And add our array to view in rails, where our react_component is displayed
+```slim
+<% component = react_component("App", props: {}, prerender: true) %>
+
+<%= component['html'] %>
+
+<script>
+window.dynamicComponents = '<%= component['dynamicComponents'] %>';
+</script>
+```
+
+Note, the complexity of getting some data from the execution of JS during server rendering into some HTML script tags will eventually be made much simpler in React on Rails Pro.  
+See [https://github.com/shakacode/react_on_rails_pro/issues/67](https://github.com/shakacode/react_on_rails_pro/issues/67) for details on how this work.
+
+In this case, the array is transferred with the names of the dynamic components that were rendered on server-side.
+
+Using this array, we can preload the dynamic components on the client before hydrate. This is critical in the case of when the user has bookmarked a dynamically loaded page.
+
+To do this, we will create an object with the component names as the keys, and the values with functions that dynamically import the component data.
+
+We will add it to `DynamicImports.js` and add a check for the presence of the registered component in this object in the function` registerDynamicComponentOnServer`:
+
+**DynamicImports.js**
+```javascript
+const DynamicImports = {
+  Map: () => import('./components/Map')
+}
+
+export const registerDynamicComponentOnServer = name => {
+  const serverSide = typeof window === 'undefined'
+
+  if (serverSide) {
+    if (typeof global.dynamicComponents === 'undefined') {
+      global.dynamicComponents = []
+    }
+    if (typeof DynamicImports[name] === 'undefined') {
+      throw new Error(`Dynamic import not defined for ${name}`)
+    }
+    if (global.dynamicComponents.indexOf(name) === -1) {
+      global.dynamicComponents.push(name)
+    }
+  }
+}
+
+export default DynamicImports
+```
+
+Now we can load the component we need, knowing its name
+For example:
+```javascript
+DynamicImports ['Map'] ()
+```
+This function will return Promise, which can be used for client rendering.
+
+Change the Client.js to add the preloading of the required components:
+
+
+**Client.js**
+```javascript
+import React from 'react';
+import { hydrateRoot } from 'react-dom/client';
+import Loadable from 'react-loadable'
+
+import App from './App';
+
+import DynamicImports from 'DynamicImports'
+
+const App = (props, railsContext, domNodeId) => {
+
+  const dynamicComponents =
+    typeof window.dynamicComponents !== 'undefined'
+      ? JSON.parse(window.dynamicComponents)
+      : []
+
+
+  const dynamicImports = []
+  dynamicComponents.map(name => {
+    const dynamicImportInvoked = DynamicImports[name]()
+    dynamicImports.push(dynamicImportInvoked)
+  })
+
+  Promise.all(dynamicImports)
+    .then(() => Loadable.preloadReady())
+    .then(() => {
+      hydrateRoot(
+        <App
+          {...props}
+          components={{ MainPage, AboutPage }}
+        />,
+        document.getElementById(domNodeId),
+      )
+    })
+}
+
+export default App
+```
+
+This code requires explanation.
+
+The array with names of rendered components called `dynamicComponents` is used in the map function.  
+In this function, the dynamic import invoked and the result (promise) is added to `dynamicImports` array.
+```javascript
+  const dynamicImports = []
+  dynamicComponents.map(name => {
+    const dynamicImportInvoked = DynamicImports[name]()
+    dynamicImports.push(dynamicImportInvoked)
+  })
+```
+
+This array is used in the function `Promise.all`
+
+```javascript
+  Promise.all(dynamicImports).then(() => ...)
+```
+
+Then fires `Loadable.preloadReady()`
+
+```javascript
+.then(() => Loadable.preloadReady())
+```
+As in the doc:
+Check for modules that are already loaded in the browser and call the matching LoadableComponent.preload methods.
+
+We need to call this method to initialize already preloaded components.
+
+In addition, note that in the creation of dynamic modules, the `modules` and` webpack` options are used, per the docs for react-loadable.
+```javascript
+  modules: ['./AboutPage'],
+  webpack: () => [require.resolveWeak('./AboutPage')],
+```
+They are needed to make .preload method work properly
+
+Thus, all dynamic modules will be loaded up to hydrate, and there will be no flicker.

data/docs/configuration.md

@@ -0,0 +1,165 @@
+# Configuration
+
+`config/initializers/react_on_rails_pro.rb`  
+
+1. You don't need to create a initializer if you are satisfied with the defaults as described below.
+1. Values beginning with `renderer` pertain only to using an external rendering server. You will need to ensure these values are consistent with your configuration for the external rendering server, as given in [JS configuration](https://www.shakacode.com/react-on-rails-pro/docs/node-renderer/js-configuration/)
+1. `config.prerender_caching` works for standard mini_racer server rendering and using an external rendering server.
+
+## Example of Configuration
+
+Also see [spec/dummy/config/initializers/react_on_rails_pro.rb](https://github.com/shakacode/react_on_rails_pro/blob/master/spec/dummy/config/initializers/react_on_rails_pro.rb) for how the testing app is setup.
+
+The below example is a typical production setup, using the separate `NodeRenderer`, where development takes the defaults when the ENV values are not specified.
+
+```ruby
+ReactOnRailsPro.configure do |config|
+  # If true, then capture timing of React on Rails Pro calls including server rendering and
+  # component rendering.
+  # Default for `tracing` is false.
+  config.tracing = true
+
+  # Array of globs to find any files for which changes should bust the fragment cache for
+  # cached_react_component and cached_react_component_hash. This should include any files used to
+  # generate the JSON props, webpack and/or webpacker configuration files, and npm package lockfiles.
+  # Default for `dependency_globs` is an empty array
+  config.dependency_globs = [ File.join(Rails.root, "app", "views", "**", "*.jbuilder") ]
+
+  # Array of globs to exclude from config.dependency_globs for ReactOnRailsPro cache key hashing
+  # Default for `excluded_dependency_globs` is an empty array
+  config.excluded_dependency_globs = [ File.join(Rails.root, "app", "views", "**", "dont_hash_this.jbuilder") ]
+
+  # Remote bundle caching saves deployment time by caching bundles.
+  # See /docs/bundle-caching.md for usage and an example of a module called S3BundleCacheAdapter.
+  config.remote_bundle_cache_adapter = nil
+  
+  # ALL OPTIONS BELOW ONLY APPLY IF SERVER RENDERING
+
+  # If true, then cache the evaluation of JS for prerendering using the standard Rails cache.
+  # Applies to all rendering engines.
+  # Default for `prerender_caching` is false.  
+  config.prerender_caching = true
+
+  # Retry request in case of time out on the node-renderer side
+  # 5 - default, if not specified
+  # 0 - no retry
+  config.renderer_request_retry_limit = 5
+
+  # NodeRenderer is for a renderer that is stateless. It does not need restarting when the JS bundles
+  # are updated. It is the only custom renderer currently supported. Leave blank to use the standard
+  # mini_racer rendering. Other option is NodeRenderer
+  # Default for `server_renderer` is "ExecJS"
+  config.server_renderer = "NodeRenderer"
+
+  # React on Rails Node Renderer now support render functions returning promises! To enable this optional functionality,
+  # toggle the following option.
+  # Default is false.
+  config.rendering_returns_promises = false
+
+  # If you're using the NodeRenderer, a value of true allows errors to be thrown from the bundle
+  # code for SSR so that an error tracking system on the NodeRender can use the exceptions.
+  # If you are using ExecJS as your rendering method, set this to false.
+  # Default is true.
+  config.throw_js_errors = true
+
+  # You may provide a password and/or a port that will be sent to renderer for simple authentication.
+  # `https://:<password>@url:<port>`. For example: https://:myPassword1@renderer:3800. Don't forget
+  # the leading `:` before the password. Your password must also not contain certain characters that
+  # would break calling URI(config.renderer_url). This includes: `@`, `#`, '/'.
+  # **Note:** Don't forget to set up **SSL** connection (https) otherwise password will useless
+  # since it will be easy to intercept it.
+  # If you provide an ENV value (maybe only for production) and there is no value, then you get the default.
+  # Default for `renderer_url` is "http://localhost:3800".
+  config.renderer_url = ENV["RENDERER_URL"]
+
+  # If you don't want to worry about special characters in your password within the url, use this config value
+  # Default for `renderer_password` is ""
+  # config.renderer_password = ENV["RENDERER_PASSWORD"]
+
+  # Set the `ssr_timeout` configuration so the Rails server will not wait more than this many seconds
+  # for a SSR request to return once issued. 
+  config.ssr_timeout = 5
+  
+  # If false, then crash if no backup rendering when the remote renderer is not available
+  # Can be useful to set to false in development or testing to make sure that the remote renderer
+  # works and any non-availability of the remote renderer does not just do ExecJS.
+  # Suggest setting this to false if the SSR JS code cannot run in ExecJS
+  # Default for `renderer_use_fallback_exec_js` is false.
+  config.renderer_use_fallback_exec_js = false
+
+  # The maximum size of the http connection pool,
+  # Set +pool_size+ to limit the maximum number of connections allowed.
+  # Defaults to 1/4 the number of allowed file handles.  You can have no more
+  # than this many threads with active HTTP transactions.
+  # Default for `renderer_http_pool_size` is 10
+  config.renderer_http_pool_size = 10
+
+  # Seconds to wait for an available connection before a timeout error is raised
+  # Default for `renderer_http_pool_timeout` is 5
+  config.renderer_http_pool_timeout = 5
+
+  # warn_timeout  - Displays an error message if a request takes longer than the given time in seconds
+  # (used to give hints to increase the pool size). Default is 0.25
+  config.renderer_http_pool_warn_timeout = 0.25 # seconds
+
+  # Snippet of JavaScript to be run right at the beginning of the server rendering process. The code
+  # to be executed must either be self contained or reference some globally exposed module.  
+  # For example, suppose that we had to call `SomeLibrary.clearCache()`between every call to server
+  # renderer to ensure no leakage of state between calls. Note, SomeLibrary needs to be globally
+  # exposed in the server rendering webpack bundle. This code is visible in the tracing of the calls
+  # to do server rendering. Default is nil.
+  config.ssr_pre_hook_js = "SomeLibrary.clearCache();"
+
+  # When using the Node Renderer, you may require some extra assets in addition to the bundle.
+  # The assets_to_copy option allows the Node Renderer to have assets copied at the end of
+  # the assets:precompile task or directly by the
+  # react_on_rails_pro:copy_assets_to_remote_vm_renderer task.
+  # These assets are also transferred any time a new bundle is sent from Rails to the renderer.
+  # The value should be a file_path or an Array of file_paths. The files should have extensions
+  # to resolve the content types, such as "application/json".
+  config.assets_to_copy = [
+     Rails.root.join("public", "webpack", Rails.env, "loadable-stats.json"),
+     Rails.root.join("public", "webpack", Rails.env, "manifest.json")
+  ]
+
+  ################################################################################
+  # REACT SERVER COMPONENTS (RSC) CONFIGURATION
+  ################################################################################
+
+  # Enable React Server Components support
+  # When enabled, React on Rails Pro will support RSC rendering and streaming
+  # Default is false
+  config.enable_rsc_support = true
+
+  # Path to the RSC bundle file (relative to webpack output directory or absolute path)
+  # The RSC bundle contains only server components and references to client components.
+  # It's generated using the RSC Webpack Loader which transforms client components into
+  # references. This bundle is specifically used for generating RSC payloads and is
+  # configured with the 'react-server' condition.
+  # Default is "rsc-bundle.js"
+  config.rsc_bundle_js_file = "rsc-bundle.js"
+
+  # Path to the React client manifest file (typically in your webpack output directory)
+  # This manifest contains mappings for client components that need hydration.
+  # It's automatically generated by the React Server Components Webpack plugin and is
+  # required for client-side hydration of components.
+  # Only set this if you've configured the plugin to use a different filename.
+  # Default is "react-client-manifest.json"
+  config.react_client_manifest_file = "react-client-manifest.json"
+
+  # Path to the React server-client manifest file (typically in your webpack output directory)
+  # This manifest is used during server-side rendering with RSC to properly resolve
+  # references between server and client components.
+  # It's automatically generated by the React Server Components Webpack plugin.
+  # Only set this if you've configured the plugin to use a different filename.
+  # Default is "react-server-client-manifest.json"
+  config.react_server_client_manifest_file = "react-server-client-manifest.json"
+
+  # These RSC configuration files are crucial when implementing React Server Components
+  # with streaming, which offers benefits like:
+  # - Reduced JavaScript bundle sizes
+  # - Faster page loading
+  # - Selective hydration of client components
+  # - Progressive rendering with Suspense boundaries
+end
+```

data/docs/contributors-info/onboarding-customers.md

@@ -0,0 +1,6 @@
+# Creating a github OAuth Token
+
+*[Document for ShakaCode Staff](https://docs.google.com/document/d/10snzXEWgkorcai76_OxlhjQcDae_WoxRfBCdVbmcQoU/edit)*
+
+# Customer Steps
+See [Installation](../installation.md).

data/docs/contributors-info/releasing.md

@@ -0,0 +1,40 @@
+# Releasing React on Rails Pro
+
+⚠️ **This documentation is outdated.**
+
+React on Rails Pro is now released together with React on Rails using a unified release script.
+
+## Current Release Process
+
+Please refer to the main release documentation:
+
+👉 **[/docs/contributor-info/releasing.md](../../../docs/contributor-info/releasing.md)**
+
+Or run from the repository root:
+
+```bash
+cd .. && rake -D release
+```
+
+## Quick Reference
+
+```bash
+# From repository root (not from react_on_rails_pro/)
+cd /path/to/react_on_rails
+
+# Release with version bump
+rake release[17.0.0]
+
+# Dry run first (recommended)
+rake release[17.0.0,true]
+
+# Test with local Verdaccio
+rake release[17.0.0,false,verdaccio]
+```
+
+This unified script releases all 5 packages together:
+- react-on-rails (NPM)
+- react-on-rails-pro (NPM)
+- react-on-rails-pro-node-renderer (NPM)
+- react_on_rails (RubyGem)
+- react_on_rails_pro (RubyGem)

data/docs/contributors-info/style.md

@@ -0,0 +1,33 @@
+# Code Style
+This document describes the coding style of [ShakaCode](http://www.shakacode.com). Yes, it's opinionated, as all style guidelines should be. We shall put as little as possible into this guide and instead rely on:
+
+* Use of linters with our standard linter configuration.
+* References to existing style guidelines that support the linter configuration.
+* Anything additional goes next.
+
+## Client Side JavaScript and React
+* See the [Shakacode JavaScript Style Guide](https://github.com/shakacode/style-guide-javascript)
+
+## Style Guides to Follow
+Follow these style guidelines per the linter configuration. Basically, lint your code and if you have questions about the suggested fixes, look here:
+
+### Ruby Coding Standards
+* [ShakaCode Ruby Coding Standards](https://github.com/shakacode/style-guide-ruby)
+* [Ruby Documentation](http://guides.rubyonrails.org/api_documentation_guidelines.html)
+
+### JavaScript Coding Standards
+* [ShakaCode Javascript](https://github.com/shakacode/style-guide-javascript)
+* Use the [eslint-config-shakacode](https://github.com/shakacode/style-guide-javascript/tree/master/packages/eslint-config-shakacode) npm package with eslint.
+* [JSDoc](http://usejsdoc.org/)
+
+### Git coding Standards
+* [Git Coding Standards](http://chlg.co/1GV2m9p)
+
+### Sass Coding Standards
+* [Sass Guidelines](http://sass-guidelin.es/) by [Hugo Giraudel](http://hugogiraudel.com/)
+* [Github Front End Guidelines](http://primercss.io/guidelines/)
+
+# Git Usage
+* Follow a github-flow model where you branch off of master for features.
+* Before merging a branch to master, rebase it on top of master, by using command like `git fetch; git checkout my-branch; git rebase -i origin/master`. Clean up your commit message at this point. Be super careful to communicate with anybody else working on this branch and do not do this when others have uncommitted changes. Ideally, your merge of your feature back to master should be one nice commit.
+* Run hosted CI and code coverage.