rebuild ujs, add some docs, simplify reloading

Author: rmosolgo

lib/react/jsx.rb

@@ -17,6 +17,8 @@ module JSX
     # - #transform(code) => new code
     self.transformer_class = DEFAULT_TRANSFORMER
 
+    # @param code [String] JSX code to transform into JavaScript
+    # @return [String] plain, browser-ready JavaScript code
     def self.transform(code)
       self.transformer ||= transformer_class.new(transform_options)
       self.transformer.transform(code)

lib/react/rails/railtie.rb

@@ -18,25 +18,27 @@ class Railtie < ::Rails::Railtie
       config.react.server_renderer            = nil # defaults to BundleRenderer
       config.react.server_renderer_options    = {}  # BundleRenderer provides defaults
       # Changing files with these extensions in these directories will cause the server renderer to reload:
-      config.react.server_renderer_directories = ["/app/assets/javascripts/"]
-      config.react.server_renderer_extensions = ["jsx"]
-      if defined?(Webpacker)
-        config.react.server_renderer_directories << "app/javascript"
-        config.react.server_renderer_extensions << "js"
-      end
+      config.react.server_renderer_directories = ["/app/assets/javascripts/", "app/javascript"]
+      config.react.server_renderer_extensions = ["jsx", "js"]
       # View helper implementation:
       config.react.view_helper_implementation = nil # Defaults to ComponentMount
 
       # Watch .jsx files for changes in dev, so we can reload the JS VMs with the new JS code.
       initializer "react_rails.add_watchable_files", group: :all do |app|
+        # Watch files ending in `server_renderer_extensions` in each of `server_renderer_directories`
         reload_paths = config.react.server_renderer_directories.reduce({}) do |memo, dir|
           app_dir = File.join(app.root, dir)
           memo[app_dir] = config.react.server_renderer_extensions
           memo
         end
 
-        app.reloaders << ActiveSupport::FileUpdateChecker.new([], reload_paths) do
-          React::ServerRendering.reset_pool
+        # Rails checks these objects for changes:
+        app.reloaders << ActiveSupport::FileUpdateChecker.new([], reload_paths)
+        # Reload renderers in dev when files change
+        if Gem::Version.new(::Rails::VERSION::STRING) >= Gem::Version.new("5.x")
+          ActiveSupport::Reloader.to_prepare { React::ServerRendering.reset_pool }
+        else
+          ActionDispatch::Reloader.to_prepare { React::ServerRendering.reset_pool }
         end
       end
 
@@ -102,14 +104,7 @@ class Railtie < ::Rails::Railtie
         React::ServerRendering.pool_timeout     = app.config.react.server_renderer_timeout
         React::ServerRendering.renderer_options = app.config.react.server_renderer_options
         React::ServerRendering.renderer         = app.config.react.server_renderer
-
         React::ServerRendering.reset_pool
-        # Reload renderers in dev when files change
-        if Gem::Version.new(::Rails::VERSION::STRING) >= Gem::Version.new("5.x")
-          ActiveSupport::Reloader.to_prepare { React::ServerRendering.reset_pool }
-        else
-          ActionDispatch::Reloader.to_prepare { React::ServerRendering.reset_pool }
-        end
       end
 
       initializer "react_rails.setup_engine", :group => :all do |app|

lib/react/server_rendering.rb

@@ -9,13 +9,18 @@ module ServerRendering
 
     self.renderer_options = {}
 
-    # Discard the old ConnectionPool & create a new one
+    # Discard the old ConnectionPool & create a new one.
+    # This will clear all state such as loaded code, JS VM state, or options.
+    # @return [void]
     def self.reset_pool
       options = {size: pool_size, timeout: pool_timeout}
       @@pool = ConnectionPool.new(options) { self.renderer.new(self.renderer_options) }
     end
 
     # Check a renderer out of the pool and use it to render the component.
+    # @param component_name [String] Component identifier, looked up by UJS
+    # @param props [String, Hash] Props for this component
+    # @param prerender_options [Hash] Renderer-specific options
     # @return [String] Prerendered HTML from `component_name`
     def self.render(component_name, props, prerender_options)
       @@pool.with do |renderer|
@@ -28,6 +33,7 @@ def self.with_renderer
       @@pool.with { |renderer| yield(renderer) }
     end
 
+    # Raised when something went wrong during server rendering.
     class PrerenderError < RuntimeError
       def initialize(component_name, props, js_message)
         message = ["Encountered error \"#{js_message.inspect}\" when prerendering #{component_name} with #{props}",

lib/react/server_rendering/bundle_renderer.rb

@@ -91,6 +91,9 @@ def assets_precompiled?
         !::Rails.application.config.assets.compile
       end
 
+      # Detect what kind of asset system is in use and choose that container.
+      # Or, if the user has provided {.asset_container_class}, use that.
+      # @return [Class] suitable for {#asset_container}
       def asset_container_class
         if self.class.asset_container_class.present?
           self.class.asset_container_class

lib/react/server_rendering/webpacker_manifest_container.rb

@@ -2,19 +2,25 @@
 
 module React
   module ServerRendering
-    CLIENT_REQUIRE = %r{__webpack_require__\(.*webpack-dev-server\/client\/index\.js.*\n}
-
-    # Get a compiled file from Webpacker
+    # Get a compiled file from Webpacker. It may come from:
+    #
+    # - webpack-dev-server
+    # - compiled pack
     class WebpackerManifestContainer
+      # This pattern matches the code that initializes the dev-server client.
+      CLIENT_REQUIRE = %r{__webpack_require__\(.*webpack-dev-server\/client\/index\.js.*\n}
+
       def find_asset(logical_path)
         # raises if not found
         asset_path = Webpacker::Manifest.lookup(logical_path).to_s
         if asset_path.start_with?("http")
-          # this includes `webpack-dev-server/client/index.js` code which causes ExecJS to 💥
+          # Get a file from the webpack-dev-server
           dev_server_asset = open(asset_path).read
+          # Remove `webpack-dev-server/client/index.js` code which causes ExecJS to 💥
           dev_server_asset.sub!(CLIENT_REQUIRE, '//\0')
           dev_server_asset
         else
+          # Read the already-compiled pack:
           full_path = Webpacker::Manifest.lookup_path(logical_path).to_s
           File.read(full_path)
         end

react_ujs/index.js

@@ -55,8 +55,11 @@ var ReactRailsUJS = {
   // the default is ReactRailsUJS.ComponentGlobal
   getConstructor: constructorFromGlobal,
 
-  useContext: function(req) {
-    this.getConstructor = constructorFromRequireContextWithGlobalFallback(req)
+  // Given a Webpack `require.context`,
+  // try finding components with `require`,
+  // then falling back to global lookup.
+  useContext: function(requireContext) {
+    this.getConstructor = constructorFromRequireContextWithGlobalFallback(requireContext)
   },
 
   // Render `componentName` with `props` to a string,

react_ujs/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react_ujs",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Rails UJS for the react-rails gem",
   "main": "index.js",
   "repository": "reactjs/react-rails",

react_ujs/readme.md

@@ -1,3 +1,3 @@
 # react-rails UJS
 
-UJS driver for [`react-rails`](https://github.com/reactjs/react-rails).
+UJS driver for [`react-rails`](https://github.com/reactjs/react-rails). See the Ruby gem for license, documentation and changelog.

test/dummy/package.json

@@ -21,7 +21,7 @@
     "rails-erb-loader": "^4.0.0",
     "react": "^15.4.2",
     "react-dom": "^15.4.2",
-    "react_ujs": "^0.2.0",
+    "react_ujs": "^0.3.0",
     "sass-loader": "^6.0.3",
     "style-loader": "^0.16.1",
     "webpack": "^2.3.3",

test/dummy/yarn.lock

@@ -3450,9 +3450,9 @@ react@^15.4.2:
     loose-envify "^1.1.0"
     object-assign "^4.1.0"
 
-react_ujs@^0.2.0:
-  version "0.2.0"
-  resolved "https://registry.yarnpkg.com/react_ujs/-/react_ujs-0.2.0.tgz#4eb5141e6bd1cb6a220db7154843aabbfe1b4199"
+react_ujs@^0.3.0:
+  version "0.3.0"
+  resolved "https://registry.yarnpkg.com/react_ujs/-/react_ujs-0.3.0.tgz#078298dca3116b813b6813419b4825c6e2b5b57f"
 
 read-cache@^1.0.0:
   version "1.0.0"