react_on_rails 9.0.0.beta.11 → 9.0.0.beta.12

data/docs/additional-reading/rspec-configuration.md

@@ -5,7 +5,6 @@ ReactOnRails provides a helper method called `ReactOnRails::TestHelper.configure
 
 ```ruby
 RSpec.configure do |config|
-  # Next line will ensure that assets are built if webpack -w is not running to build the bundles
   ReactOnRails::TestHelper.configure_rspec_to_compile_assets(config)
 ```
 
@@ -24,7 +23,9 @@ If you are using Webpack to build CSS assets, you should do something like this
 ```
 
 Please take note of the following:
-- This utility uses your `npm_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.
+- 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.
+
 - By default, the webpack processes look for the `app/assets/webpack` folders (configured as setting `webpack_generated_files` in the `config/react_on_rails.rb`. If this 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.
 
 The following `config/react_on_rails.rb` settings **must** match your setup:
@@ -35,37 +36,19 @@ The following `config/react_on_rails.rb` settings **must** match your setup:
   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( hello-world-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.npm_build_test_command = "yarn run build:test"
+  config.build_test_command = "yarn run build:test"
 ```
 
-If you want to speed up the re-compiling process, you can call `yarn run build:development` (per below script) to have webpack run in "watch" mode and recompile these files in the background, which will be much faster when making incremental changes than compiling from scratch, assuming you have your setup like this:
-
-```
-  "scripts": {
-    "build:test": "webpack --config webpack.config.js",
-    "build:production": "NODE_ENV=production webpack --config webpack.config.js",
-    "build:development": "webpack -w --config webpack.config.js"
-  },
-```
+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.
 
-## Hot Reloading
-If you're using the hot reloading setup, you'll be running a Webpack development server to provide the JavaScript and mabye CSS assets to your Rails app. If you're doing server rendering, you'll also have a webpack watch process to refresh the server rendering file. **If your server and client bundles are different**, and you run specs, the client bundle files will not be created until React on Rails detects it's out of date. Then your script to create all bundle files will redo the server bundle file. There's a few simple remedies for this situation:
-
-1. Switch to using static compilation of the webpack bundle files. This way, you're running a Webpack watch process to generate the same files used for tests as well as developmentment. You should have a separate Procfile for doing development using a "static" setup, rather than a "hot" setup.
-2. Change your Procfile for starting the hot reloading server to also run a webpack process to automatically rebuild a the client assets while also doing hot reloading for browser testing.
-
-Note, none of these issues matter if you're using the same file for both server and client side rendering.
-
-## Using RubyMine and other IDEs that save files right before invoking tests
-We had previously tried to allow using a process check to see if a Webpack watch process would already be automatically compiling the files. However, we removed this as it proved to be fragile with various setups. Thus, you want to hit the save keystroke when you save a JavaScript file, and then run your tests. Yes, you might not do this in time, and the test runner may be building the same files as you Webpack watch processes. This will probably happen infrequently, but if this does become an issue, we can look into bring back this functionality ([#398](https://github.com/shakacode/react_on_rails/pull/398)).
-
 If you want to use a testing framework other than RSpec, please submit let us know on the changes you need to do and we'll update the docs.
 
 ![2016-01-27_02-36-43](https://cloud.githubusercontent.com/assets/1118459/12611951/7c56d070-c4a4-11e5-8a80-9615f99960d9.png)

data/{lib/generators/react_on_rails/templates/base/base/config/initializers/react_on_rails.rb.tt → docs/basics/configuration.md}

@@ -1,54 +1,92 @@
-# Shown below are the defaults for configuration
-ReactOnRails.configure do |config|
-  # Client bundles are configured in application.js
+Here is the full set of config options.
 
-  # 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.
-  config.generated_assets_dir = File.join(%w[public webpack], Rails.env)
+```yaml
+# frozen_string_literal: true
 
-  # Define the files we need to check for webpack compilation when running tests.
-  config.webpack_generated_files = %w( hello-world-bundle.js )
+# NOTE: you typically will leave the commented out configurations set to their defaults.
+# Thus, you only need to pay careful attention to the non-commented settings in this file.
 
-  # This is the file used for server rendering of React when using `(prerender: true)`
-  # If you are never using server rendering, you may set this to "".
-  # If you are using the same file for client and server rendering, having this set probably does
-  # not affect performance.
-  config.server_bundle_js_file = "hello-world-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.npm_build_test_command = "yarn run build:test"
+ReactOnRails.configure do |config|
+  # defaults to "" (top level)
+  #
+  config.node_modules_location = ""
 
   # This configures the script to run to build the production assets by webpack. Set this to nil
   # if you don't want react_on_rails building this file for you.
-  config.npm_build_production_command = "yarn run build:production"
+  config.npm_build_production_command = "RAILS_ENV=production bin/webpack"
 
   ################################################################################
-  # CLIENT RENDERING OPTIONS
-  # Below options can be overriden by passing options to the react_on_rails
-  # `render_component` view helper method.
   ################################################################################
-  # default is false
-  config.prerender = false
+  # TEST CONFIGURATION OPTIONS
+  # Below options are used with the use of this test helper:
+  # ReactOnRails::TestHelper.configure_rspec_to_compile_assets(config)
+  ################################################################################
 
-  # default is true for development, off otherwise
-  config.trace = Rails.env.development?
+  # If you are using this in your spec_helper.rb (or rails_helper.rb):
+  #
+  # 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 = "RAILS_ENV=test bin/webpack"
 
+  # Directory where your generated assets go. All generated assets must go to the same directory.
+  # If you are using webpacker, this value will come from your config/webpacker.yml file. 
+  # This is the default in webpacker.yml:
+  #   public_output_path: packs-test
+  # which means files in /public/packs-test
+  #
+  # Alternately, you may configure this. It is relative to your Rails root directory.
+  # A custom, non-webpacker, config might use something like:
+  #
+  config.generated_assets_dir = File.join(%w[public webpack], Rails.env)
+
+  # The test helper needs to know where your JavaScript files exist. The default is configured
+  # by your config/webpacker.yml soure_path:
+  # source_path: app/javascript
+  #
+  # If you have a non-default `node_modules_location`, that is assumed to be the location of your source
+  # files.
+
+  # Define the files we need to check for webpack compilation when running tests.
+  # The default is `%w( manifest.json )` as will be sufficient for most webpacker builds.
+  #
+  config.webpack_generated_files = %w( manifest.json )
+
+  ################################################################################
   ################################################################################
   # SERVER RENDERING OPTIONS
   ################################################################################
+  # This is the file used for server rendering of React when using `(prerender: true)`
+  # If you are never using server rendering, you should set this to "".
+  # Note, there is only one server bundle, unlike JavaScript where you want to minimize the size
+  # of the JS sent to the client. For the server rendering, React on Rails creates a pool of
+  # JavaScript execution instances which should handle any component requested.
+  #
+  # While you may configure this to be the same as your client bundle file, this file is typically
+  # different.
+  config.server_bundle_js_file = "server-bundle.js"
+
   # If set to true, this forces Rails to reload the server bundle if it is modified
+  # Default value is Rails.env.development?
+  #
   config.development_mode = Rails.env.development?
 
   # For server rendering. This can be set to false so that server side messages are discarded.
   # Default is true. Be cautious about turning this off.
+  # Default value is true
+  #
   config.replay_console = true
 
   # Default is true. Logs server rendering messages to Rails.logger.info
+  #
   config.logging_on_server = true
 
-  config.raise_on_prerender_error = false # change to true to raise exception on server if the JS code throws
+  # Default is to false to NOT raise exception on server if the JS code throws.
+  # Reason is that it's easier to debug this when you get the error over to the client.
+  # 
+  config.raise_on_prerender_error = false
 
   # Server rendering only (not for render_component helper)
   # You can configure your pool of JS virtual machines and specify where it should load code:
@@ -70,22 +108,21 @@ ReactOnRails.configure do |config|
   #
   # Replace the following line to the location where you keep your client i18n yml files
   # that will source for automatic generation on translations.js & default.js
-  # By default(without this option) all yaml files from Rails.root.join("config", "locales") and installed gems are loaded
-  # config.i18n_yml_dir = Rails.root.join("config", "locales", "client")
+  # By default(without this option) all yaml files from Rails.root.join("config", "locales")
+  # and installed gems are loaded
+  config.i18n_yml_dir = Rails.root.join("config", "locales", "client")
 
   ################################################################################
-  # MISCELLANEOUS OPTIONS
   ################################################################################
+  # CLIENT RENDERING OPTIONS
+  # Below options can be overriden by passing options to the react_on_rails
+  # `render_component` view helper method.
+  ################################################################################
+  # default is false
+  config.prerender = false
 
-  # The server render method - either ExecJS or NodeJS
-  <%- if options.node? -%>
-  config.server_render_method = "NodeJS"
-  <%- else -%>
-  config.server_render_method = "ExecJS"
-  <%- end -%>
-
-  # If you want to use webpack for CSS and images, and still use the asset pipeline,
-  # see https://github.com/shakacode/react_on_rails/blob/master/docs/additional-reading/rails-assets.md
-  # And you will use a setting like this.
-  # config.symlink_non_digested_assets_regex = /\.(png|jpg|jpeg|gif|tiff|woff|ttf|eot|svg|map)/
+  # default is true for development, off otherwise
+  config.trace = Rails.env.development?
 end
+
+```

data/docs/basics/generator.md

@@ -13,7 +13,6 @@ Usage:
 
 Options:
   -R, [--redux], [--no-redux]                      # Install Redux gems and Redux version of Hello World Example. Default: false
-  -N, [--node], [--no-node]                        # Sets up node as a server rendering option. Default: false
       [--ignore-warnings], [--no-ignore-warnings]  # Skip warnings. Default: false
 
 Runtime options:
@@ -70,7 +69,3 @@ If you have used the `--redux` generator option, you will notice the familiar ad
 
 Note the organizational paradigm of "bundles". These are like application domains and are used for grouping your code into webpack bundles, in case you decide to create different bundles for deployment. This is also useful for separating out logical parts of your application. The concept is that each bundle will have it's own Redux store. If you have code that you want to reuse across bundles, including components and reducers, place them under `/client/app/lib`.
 
-### Using Images and Fonts
-The generator has amended the folders created in `client/assets/` to Rails's asset path. We recommend that if you have any existing assets that you want to use with your client code, you should move them to these folders and use webpack as normal. This allows webpack's development server to have access to your assets, as it will not be able to see any assets in the default Rails directories which are above the `/client` directory.
-
-Alternatively, if you have many existing assets and don't wish to move them, you could consider creating symlinks from client/assets that point to your Rails assets folders inside of `app/assets/`. The assets there will then be visible to both Rails and webpack.

data/docs/basics/installation-overview.md

@@ -4,11 +4,14 @@ Here's an overview of installation if you're not using the generator.
 
 Note, the best way to understand how to use ReactOnRails is to study the examples:
 
-1. [spec/dummy](../../spec/dummy): Simple, no DB example.
-2. [github.com/shakacode/react-webpack-rails-tutorial](https://github.com/shakacode/react-webpack-rails-tutorial): Full featured example.
+1. Run the generator per the [Tutorial](../../tutorial.md).
+2. [spec/dummy](../../spec/dummy): Simple, no DB example.
+3. [github.com/shakacode/react-webpack-rails-tutorial](https://github.com/shakacode/react-webpack-rails-tutorial): Full featured example.
 
 ## Configure the `/client` Directory
 
+Note, version 9.0 of React on Rails removed the requirement to place all client side files in the `/client` directory.
+
 This directory has no references to Rails outside of the destination directory for the files created by the various Webpack config files.
 
 The only requirements within this directory for basic React on Rails integration are:
@@ -27,8 +30,6 @@ The default path: `public/webpack` can be loaded with webpackConfigLoader as sho
 1. Configure the `config/initializers/react_on_rails.rb`. You can adjust some necessary settings and defaults. See file [spec/dummy/config/initializers/react_on_rails.rb](../../spec/dummy/config/initializers/react_on_rails.rb) for a detailed example of configuration, including comments on the different values to configure.
 1. Configure your Procfiles per the example apps. These are at the root of your Rails installation.
 1. Configure your top level JavaScript files for inclusion in your layout. You'll want a version that you use for static assets, and you want a file for any files in your setup that are not part of your webpack build. The reason for this is for use with hot-reloading. If you are not using hot reloading, then you only need to configure your `application.js` file to include your Webpack generated files. For more information on hot reloading, see [Hot Reloading of Assets For Rails Development](../additional-reading/hot-reloading-rails-development.md)
-
-1. Configure your `lib/tasks/assets.rake` file to run webpack during asset precompilation.
 1. If you are deploying to Heroku, see [heroku-deployment.md](/docs/additional-reading/heroku-deployment.md)
 
 If I missed anything, please submit a PR or file an issue.

data/docs/tutorial.md

@@ -1,6 +1,6 @@
 # React on Rails Basic Tutorial
 
-This tutorial setups up a new Rails app with **React on Rails**, demonstrating Rails + React + Redux + Server Rendering. It is updated to 8.0.0.
+This tutorial setups up a new Rails app with **React on Rails**, demonstrating Rails + React + Redux + Server Rendering. It is updated to 9.0.0.
 
 After finishing this tutorial you will get an application that can do the following (live on Heroku):
 
@@ -28,47 +28,59 @@ nvm list                        # check
 
 brew install yarn               # you can use other installer if desired
 
-rvm install 2.3.1               # download and install latest stable Ruby (update to exact version)
-rvm use 2.3.1 --default         # use it and make it default
+rvm install 2.4.1               # download and install latest stable Ruby (update to exact version)
+rvm use 2.4.1 --default         # use it and make it default
 rvm list                        # check
 
 gem install rails               # download and install latest stable Rails
 gem install foreman             # download and install Foreman
 ```
 
-Then we need to create a fresh Rails application as following:
+Then we need to create a fresh Rails application with webpacker react support as following:
 
 ```
-cd <basic directory where you want to create your new Rails app>
+cd <directory where you want to create your new Rails app>
 
-rails new test-react-on-rails       # any name you like
+# any name you like for the rails app
+rails new test-react-on-rails --webpack=react 
 
 cd test-react-on-rails
 ```
 
+Note: you can do the following two commands in an existing Rails app:
+
+```
+bundle exec rails webpacker:install
+bundle exec rails webpacker:install:react
+```
+
+
 ![01](https://cloud.githubusercontent.com/assets/20628911/17464917/3c29e55a-5cf2-11e6-8754-046ba3ee92d9.png)
 
-Add **React On Rails** gem to your Gemfile (`vim Gemfile` or `nano Gemfile` or in IDE):
+
+Add the **React On Rails** gem to your Gemfile:
 
 ```
-gem 'react_on_rails', '8.0.0'         # use latest gem version, prefer exact version 
+gem 'react_on_rails', '9.0.0'         # use latest gem version, prefer exact version 
 ```
 
+
 ![02](https://cloud.githubusercontent.com/assets/20628911/17464919/3c2d74c2-5cf2-11e6-8704-a84958832fbb.png)
 
-put everything under git repository (or `rails generate` will not work properly)
+Then run `bundle` and commit the git repository (or `rails generate` will not work properly)
 
 ```
-# Here are git commands to make a new git repo and commit everything
-git init
+bundle
+
+# Here are git commands to make a new git repo and commit everything.
+# Newer versions of Rails create the git repo by default.
 git add -A
 git commit -m "Initial commit"
 ```
 
-update dependencies and generate empty app via `react_on_rails:install` or `react_on_rails:install --redux`. You need to first git commit your files before running the generator, or else it will generate an error.
+Install React on Rails: `rails generator react_on_rails:install` or `rails generate react_on_rails:install --redux`. You need to first git commit your files before running the generator, or else it will generate an error.
 
 ```
-bundle
 rails generate react_on_rails:install
 bundle && yarn
 ```

data/lib/generators/USAGE

@@ -9,10 +9,6 @@ can pass the redux option if you'd like to have redux setup for you automaticall
     to integrate the Redux state container framework. The necessary node modules
     will be automatically included for you.
 
-* Node
-
-    Passing the --node generator option sets up the necessary files for node to render the react_components.
-
 *******************************************************************************
 
 After running the generator, you will want to:

data/lib/generators/react_on_rails/base_generator.rb

@@ -22,63 +22,28 @@ module ReactOnRails
         route "get 'hello_world', to: 'hello_world#index'"
       end
 
-      def update_git_ignore
-        data = <<-DATA.strip_heredoc
-          # React on Rails
-          npm-debug.log*
-          node_modules
-
-          # Generated js bundles
-          /public/webpack/*
-        DATA
-
-        if dest_file_exists?(".gitignore")
-          append_to_file(".gitignore", data)
-        else
-          GeneratorMessages.add_error(setup_file_error(".gitignore", data))
-        end
-      end
-
       def create_react_directories
-        dirs = %w[components containers startup]
-        dirs.each { |name| empty_directory("client/app/bundles/HelloWorld/#{name}") }
+        dirs = %w[components]
+        dirs.each { |name| empty_directory("app/javascript/bundles/HelloWorld/#{name}") }
       end
 
       def copy_base_files
         base_path = "base/base/"
         base_files = %w[app/controllers/hello_world_controller.rb
-                        config/webpacker.yml
-                        client/.babelrc
-                        client/webpack.config.js
-                        client/REACT_ON_RAILS_CLIENT_README.md]
+                        app/views/layouts/hello_world.html.erb
+                        config/initializers/react_on_rails.rb
+                        Procfile.dev
+                        Procfile.dev-server]
         base_files.each { |file| copy_file("#{base_path}#{file}", file) }
       end
 
-      def template_base_files
-        base_path = "base/base/"
-        %w[app/views/layouts/hello_world.html.erb
-           config/initializers/react_on_rails.rb
-           Procfile.dev
-           client/package.json].each { |file| template("#{base_path}#{file}.tt", file) }
-      end
-
-      def template_package_json
-        if dest_file_exists?("package.json")
-          add_yarn_postinstall_script_in_package_json
-        else
-          template("base/base/package.json", "package.json")
-        end
+      def add_base_gems_to_gemfile
+        gem "mini_racer", platforms: :ruby
+        run "bundle"
       end
 
-      def add_base_gems_to_gemfile
-        gems = <<-GEMS.strip_heredoc
-
-        gem 'mini_racer', platforms: :ruby
-        gem 'webpacker', git: "https://github.com/shakacode/webpacker.git",
-                         branch: "issue-464-merge-webpacker-lite-into-webpacker-v5"
-        GEMS
-        append_to_file("Gemfile",
-                       gems)
+      def add_yarn_dependencies
+        run "yarn add react-on-rails"
       end
 
       def append_to_spec_rails_helper
@@ -92,10 +57,14 @@ module ReactOnRails
           else
             GeneratorMessages.add_info(
               <<-MSG.strip_heredoc
-              Did not find spec/rails_helper.rb or spec/spec_helper.rb to add
-                # Ensure that if we are running js tests, we are using latest webpack assets
-                # This will use the defaults of :js and :server_rendering meta tags
-                ReactOnRails::TestHelper.configure_rspec_to_compile_assets(config)
+
+              We did not find a spec/rails_helper.rb or spec/spec_helper.rb to add
+              the React on Rails Test helper, which ensures that if we are running
+              js tests, then we are using latest webpack assets. You can later add
+              this to your rspec config:
+
+              # This will use the defaults of :js and :server_rendering meta tags
+              ReactOnRails::TestHelper.configure_rspec_to_compile_assets(config)
               MSG
             )
           end
@@ -109,8 +78,8 @@ module ReactOnRails
           ReactOnRails::TestHelper.configure_rspec_to_compile_assets(config)
       STR
 
-      def print_helpful_message
-        message = <<-MSG.strip_heredoc
+      def self.helpful_message
+        <<-MSG.strip_heredoc
 
           What to do next:
 
@@ -118,45 +87,36 @@ module ReactOnRails
 
                 <%= javascript_pack_tag 'hello-world-bundle' %>
 
-            - Ensure your bundle and yarn installs of dependencies are up to date.
-
-                bundle && yarn
-
             - Run the foreman command to start the rails server and run webpack in watch mode.
 
                 foreman start -f Procfile.dev
 
+            - Change this line app/views/hello_world/index.html.erb to `prerender: true` to see
+              server rendering (right click on page and select "view source").
+                
+                <%= react_component("HelloWorldApp", props: @hello_world_props, prerender: true) %>
+
+            - Run the foreman command to start the rails server and run webpack in HMR mode. Be sure
+              to change your development/dev_server/hmr setting to true to see HMR in action.
+              Note, you cannot use the default Procfile.dev-server setup with server rendering.
+                
+                foreman start -f Procfile.dev-server
+
+            - You may run the commands in the Procfiles in separate shells rather than using foreman.
+
+            - See the documentation on https://github.com/rails/webpacker for how the default webpack
+              configuration works.
+
             - Visit http://localhost:3000/hello_world and see your React On Rails app running!
         MSG
-        GeneratorMessages.add_info(message)
       end
 
-      private
-
-      def add_yarn_postinstall_script_in_package_json
-        client_package_json = File.join(destination_root, "package.json")
-        contents = File.read(client_package_json)
-        postinstall = %("postinstall": "cd client && yarn install")
-        if contents =~ /"scripts" *:/
-          replacement = <<-STRING
-  "scripts": {
-    #{postinstall},
-STRING
-          regexp = / {2}"scripts": {/
-        else
-          regexp = /^{/
-          replacement = <<-STRING.strip_heredoc
-            {
-              "scripts": {
-                #{postinstall}
-              },
-          STRING
-        end
-
-        contents.gsub!(regexp, replacement)
-        File.open(client_package_json, "w+") { |f| f.puts contents }
+      def print_helpful_message
+        GeneratorMessages.add_info(self.class.helpful_message)
       end
 
+      private
+
       # From https://github.com/rails/rails/blob/4c940b2dbfb457f67c6250b720f63501d74a45fd/railties/lib/rails/generators/rails/app/app_generator.rb
       def app_name
         @app_name ||= (defined_app_const_base? ? defined_app_name : File.basename(destination_root))