react_on_rails 5.2.0 → 6.0.0.beta.1

data/app/helpers/react_on_rails_helper.rb

@@ -87,14 +87,7 @@ module ReactOnRailsHelper
   #   raise_on_prerender_error: <true/false> Default to false. True will raise exception on server
   #      if the JS code throws
   # Any other options are passed to the content tag, including the id.
-  def react_component(component_name,
-                      props: {},
-                      prerender: nil,
-                      trace: nil,
-                      replay_console: nil,
-                      raise_on_prerender_error: nil,
-                      id: nil,
-                      html_options: {})
+  def react_component(component_name, raw_options = {})
     # Create the JavaScript and HTML to allow either client or server rendering of the
     # react_component.
     #
@@ -104,44 +97,31 @@ module ReactOnRailsHelper
     # We use this react_component_index in case we have the same component multiple times on the page.
 
     react_component_index = next_react_component_index
-    react_component_name = component_name.camelize # Not sure if we should be doing this (JG)
-    dom_id = id.presence || "#{component_name}-react-component-#{react_component_index}"
+    options = ReactOnRails::ReactComponent::Options.new(name: component_name,
+                                                        index: react_component_index,
+                                                        options: raw_options)
 
     # Setup the page_loaded_js, which is the same regardless of prerendering or not!
     # The reason is that React is smart about not doing extra work if the server rendering did its job.
 
-    props = {} if props.nil?
-
-    prerender = prerender_option(prerender)
-    trace = trace_option(trace)
-    replay_console = replay_console_option(replay_console)
-    raise_on_prerender_error = raise_on_prerender_error_option(raise_on_prerender_error)
-
-    data = {
-      component_name: react_component_name,
-      props: props,
-      trace: trace,
-      dom_id: dom_id
-    }
-
     component_specification_tag =
       content_tag(:div,
                   "",
                   class: "js-react-on-rails-component",
-                  style: ReactOnRails.configuration.skip_display_none ? nil : "display:none",
-                  data: data)
+                  style: options.style,
+                  data: options.data)
 
     # Create the HTML rendering part
-    result = server_rendered_react_component_html(props, react_component_name, dom_id,
-                                                  prerender: prerender,
-                                                  trace: trace,
-                                                  raise_on_prerender_error: raise_on_prerender_error)
+    result = server_rendered_react_component_html(options.props, options.name, options.dom_id,
+                                                  prerender: options.prerender,
+                                                  trace: options.trace,
+                                                  raise_on_prerender_error: options.raise_on_prerender_error)
 
     server_rendered_html = result["html"]
     console_script = result["consoleReplayScript"]
 
-    content_tag_options = html_options
-    content_tag_options[:id] = dom_id
+    content_tag_options = options.html_options
+    content_tag_options[:id] = options.dom_id
 
     rendered_output = content_tag(:div,
                                   server_rendered_html.html_safe,
@@ -151,7 +131,7 @@ module ReactOnRailsHelper
     result = <<-HTML.html_safe
 #{component_specification_tag}
     #{rendered_output}
-    #{replay_console ? console_script : ''}
+    #{options.replay_console ? console_script : ''}
     HTML
 
     prepend_render_rails_context(result)
@@ -290,16 +270,29 @@ module ReactOnRailsHelper
     # On server `location` option is added (`location = request.fullpath`)
     # React Router needs this to match the current route
 
-    # Make sure that we use up-to-date server-bundle
+    # Make sure that we use up-to-date bundle file used for server rendering, which is defined
+    # by config file value for config.server_bundle_js_file
     ReactOnRails::ServerRenderingPool.reset_pool_if_server_bundle_was_modified
 
     # Since this code is not inserted on a web page, we don't need to escape props
+    #
+    # However, as JSON (returned from `props_string(props)`) isn't JavaScript,
+    # but we want treat it as such, we need to compensate for the difference.
+    #
+    # \u2028 and \u2029 are valid characters in strings in JSON, but are treated
+    # as newline separators in JavaScript. As no newlines are allowed in
+    # strings in JavaScript, this causes an exception.
+    #
+    # We fix this by replacing these unicode characters with their escaped versions.
+    # This should be safe, as the only place they can appear is in strings anyway.
+    #
+    # Read more here: http://timelessrepo.com/json-isnt-a-javascript-subset
 
     wrapper_js = <<-JS
 (function() {
   var railsContext = #{rails_context(server_side: true).to_json};
 #{initialize_redux_stores}
-  var props = #{props_string(props)};
+  var props = #{props_string(props).gsub("\u2028", '\u2028').gsub("\u2029", '\u2029')};
   return ReactOnRails.serverRenderReactComponent({
     name: '#{react_component_name}',
     domNodeId: '#{dom_id}',
@@ -358,8 +351,10 @@ ReactOnRails.setStore('#{store_name}', store);
   # second parameter passed to both component and store generator functions.
   def rails_context(server_side:)
     @rails_context ||= begin
-      uri = URI.parse(request.original_url)
-      # uri = URI("http://foo.com:3000/posts?id=30&limit=5#time=1305298413")
+      # Using Addressable instead of standard URI to better deal with
+      # non-ASCII characters (see https://github.com/shakacode/react_on_rails/pull/405)
+      uri = Addressable::URI.parse(request.original_url)
+      # uri = Addressable::URI.parse("http://foo.com:3000/posts?id=30&limit=5#time=1305298413")
 
       result = {
         # URL settings
@@ -387,18 +382,6 @@ ReactOnRails.setStore('#{store_name}', store);
     @rails_context.merge(serverSide: server_side)
   end
 
-  def raise_on_prerender_error_option(val)
-    val.nil? ? ReactOnRails.configuration.raise_on_prerender_error : val
-  end
-
-  def trace_option(val)
-    val.nil? ? ReactOnRails.configuration.trace : val
-  end
-
-  def prerender_option(val)
-    val.nil? ? ReactOnRails.configuration.prerender : val
-  end
-
   def replay_console_option(val)
     val.nil? ? ReactOnRails.configuration.replay_console : val
   end

data/docs/additional-reading/heroku-deployment.md

@@ -26,13 +26,13 @@ If for some reason you need custom buildpacks that are not officially supported
 
 ### Swap out sqlite for postgres by doing the following:
 
-1. Delete the line with `sqlite` and replace it with:
+#### 1. Delete the line with `sqlite` and replace it with:
 
 ```ruby
    gem 'pg'
 ```
 
-2. Replace your `database.yml` file with this (assuming your app name is "ror")
+#### 2. Replace your `database.yml` file with this (assuming your app name is "ror")
 
 ```yml
 default: &default
@@ -64,36 +64,3 @@ bundle
 bin/rake db:migrate
 bin/rake db:setup
 ```
-
-3. Create a rake file to add webpack compilation to asset precompilation. You may already have this file if you used the React on Rails generator.
-
-```ruby
-# lib/tasks/assets.rake
-# The webpack task must run before assets:environment task.
-# Otherwise Sprockets cannot find the files that webpack produces.
-# This is the secret sauce for how a Heroku deployment knows to create the webpack generated JavaScript files.
-Rake::Task["assets:precompile"]
-  .clear_prerequisites
-  .enhance(["assets:compile_environment"])
-
-namespace :assets do
-  # In this task, set prerequisites for the assets:precompile task
-  task compile_environment: :webpack do
-    Rake::Task["assets:environment"].invoke
-  end
-
-  desc "Compile assets with webpack"
-  task :webpack do
-    sh "cd client && npm run build:client"
-    # If you are doing server rendering
-    # sh "cd client && npm run build:server"
-  end
-
-  task :clobber do
-    rm_r Dir.glob(Rails.root.join("app/assets/webpack/*"))
-  end
-end
-```
-
-
-

data/docs/additional-reading/node-server-rendering.md

@@ -0,0 +1,30 @@
+## Node Server Rendering
+
+### Warning: this is an experimental feature
+
+The default server rendering exploits ExecJS to render react components.
+Node server rendering allows you to use separate NodeJS process as a renderer. The process loads your configured server_bundle_js file and
+then executes javascript to render the component inside its environment. The communication between rails and node occurs
+via socket (`client/node/node.sock`)
+
+### Getting started
+
+To use node process just set `server_render_method = "NodeJS"` in `config/initializers/react_on_rails.rb`. To change back
+to ExecJS set `server_render_method = "ExecJS"`
+
+### Configuration
+
+You need to configure the name of the server bundle in two places:
+
+1. JavaScript: Change the name of server bundle adjust npm start script in `client/node/package.json`
+2. Ruby: The configured server bundle file is defined in `config/react_on_rails.rb`, and you'll have a webpack file that creates this. You maybe using the same file for client rendering.
+
+```ruby
+  # 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 = "webpack-bundle.js"
+``` 
+ 
+

data/docs/additional-reading/rails-assets.md

@@ -0,0 +1,19 @@
+## Rails assets
+
+### Problem
+When client js uses images in render methods, e.g. `<img src='...' />` or in css, e.g. `background-image: url(...)` 
+these assets fail to load. This happens because rails adds digest hashes to filenames 
+when compiling assets, e.g. `img1.jpg` becomes `img1-dbu097452jf2v2.jpg`. 
+
+When compiling its native css Rails transforms all urls and links to digested 
+versions, i.e. `background-image: image-url(img1.jpg)` becomes 
+`background-image: url(img1-dbu097452jf2v2.jpg)`. However this doesn't happen for js and 
+css files compiled by webpack on the client side, because they don't use 
+`image-url` and `asset-url` and therefore assets fail to load.
+
+### Solution
+
+Create symlinks of non-digested versions to digested versions when Rails assets compile.
+The solution is implemented using `assets:precompile` after-hook. The assets for symlinking
+are defined by `config.symlink_non_digested_assets_regex` in `config/initializers/react_on_rails.rb`.
+To disable symlinks set this parameter to `nil`.

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

@@ -9,16 +9,50 @@ RSpec.configure do |config|
   ReactOnRails::TestHelper.configure_rspec_to_compile_assets(config)
 ```
 
-You can pass an RSpec metatag as an optional second parameter to this helper method if you want this helper to run on examples other than where `js: true` (default). The helper will compile webpack files at most once per test run. The helper will not compile the webpack files unless they are out of date (stale).
+You can pass an RSpec metatag as an optional second parameter to this helper method if you want this helper to run on examples other than where `js: true` (default). The helper will compile webpack files at most once per test run. The helper will not compile the webpack files unless they are out of date (stale). The helper is configurable in terms of what command is used to prepare the files.
 
 Please take note of the following:
-- This utility assumes your build tasks for the static generated files are `npm run build:client` and `npm run build:server` and do not have the `--watch` option enabled.
-- By default, the webpack processes look for the `app/assets/webpack` folders. If this folder is missing, is empty, or contains files with `mtime`s older than any of the files in your `client` folder, the helper will recompile your assets. You can override this 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.
+- 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.
+- 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.
 
-If you want to speed up the re-compiling process, you can call `npm run build:dev:client` (and `npm run build:dev:server` if doing server rendering) 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.
+The following `config/react_on_rails.rb` settings **must** match your setup:
+```ruby
+  # 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(app assets webpack))
+
+  # Define the files we need to check for webpack compilation when running tests.
+  config.webpack_generated_files = %w( webpack-bundle.js )
+  
+  # If you are using the ReactOnRails::TestHelper.configure_rspec_to_compile_assets(config)
+  # with rspec then this controls what npm command is run
+  # to automatically refresh your webpack assets on every test run.
+  config.npm_build_test_command = "npm run build:test"
+```
+
+If you want to speed up the re-compiling process, you can call `npm 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"
+  },
+```
 
 [spec/dummy](../../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/docs/additional-reading/webpack-dev-server.md

@@ -0,0 +1,16 @@
+## Developing with the Webpack Dev Server
+One of the benefits of using webpack is access to [webpack's dev server](https://webpack.github.io/docs/webpack-dev-server.html) and its [hot module replacement](https://webpack.github.io/docs/hot-module-replacement-with-webpack.html) functionality.
+
+The webpack dev server with HMR will apply changes from the code (or styles!) to the browser as soon as you save whatever file you're working on. You won't need to reload the page, and your data will still be there. Start foreman as normal (it boots up the Rails server *and* the webpack HMR dev server at the same time).
+
+  ```bash
+  foreman start -f Procfile.dev
+  ```
+
+Open your browser to [localhost:3000](http://localhost:3000). Whenever you make changes to your JavaScript code in the `client` folder, they will automatically show up in the browser. Hot module replacement is already enabled by default.
+
+Note that **React-related error messages are possibly more helpful when encountered in the dev server** than the Rails server as they do not include noise added by the React on Rails gem.
+
+### Adding Additional Routes for the Dev Server
+As you add more routes to your front-end application, you will need to make the corresponding API for the dev server in `client/server.js`. See our example `server.js` from our [tutorial](https://github.com/shakacode/react-webpack-rails-tutorial/blob/master/client%2Fserver-express.js).
+

data/docs/additional-reading/webpack.md

@@ -12,8 +12,6 @@ You need both include `react-dom/server` and `react` as values for `entry`, like
     // See use of 'vendor' in the CommonsChunkPlugin inclusion below.
     vendor: [
       'babel-core/polyfill',
-      'jquery',
-      'jquery-ujs',
       'react',
       'react-dom',
     ],
@@ -25,14 +23,6 @@ and you need to expose them:
       // React is necessary for the client rendering:
       {test: require.resolve('react'), loader: 'expose?React'},
       {test: require.resolve('react-dom'), loader: 'expose?ReactDOM'},
-      {test: require.resolve('jquery'), loader: 'expose?jQuery'},
-      {test: require.resolve('jquery'), loader: 'expose?$'},
-```
-
-`webpack.server.config.js` is similar, but substitute:
-
-```
- entry: ['./yourCode', 'react-dom/server', 'react'],
 ```
 
 and use this line rather than `{test: require.resolve('react-dom'), loader: 'expose?ReactDOM'},`:

data/docs/api/javascript-api.md

@@ -0,0 +1,37 @@
+# ReactOnRails JavaScript API
+The best source of docs is the main [ReactOnRails.js](node_package/src/ReactOnRails.js) file. Here's a quick summary. No guarantees that this won't be outdated!
+
+```js
+  /**
+   * Main entry point to using the react-on-rails npm package. This is how Rails will be able to
+   * find you components for rendering.
+   * @param components (key is component name, value is component)
+   */
+  register(components)
+
+  /**
+   * Allows registration of store generators to be used by multiple react components on one Rails
+   * view. store generators are functions that take one arg, props, and return a store. Note that
+   * the setStore API is different in tha it's the actual store hydrated with props.
+   * @param stores (key is store name, value is the store generator)
+   */
+  registerStore(stores)
+
+  /**
+   * Allows retrieval of the store by name. This store will be hydrated by any Rails form props.
+   * Pass optional param throwIfMissing = false if you want to use this call to get back null if the
+   * store with name is not registered.
+   * @param name
+   * @param throwIfMissing Defaults to true. Set to false to have this call return undefined if
+   *        there is no store with the given name.
+   * @returns Redux Store, possibly hydrated
+   */
+  getStore(name, throwIfMissing = true )
+
+  /**
+   * Set options for ReactOnRails, typically before you call ReactOnRails.register
+   * Available Options:
+   * `traceTurbolinks: true|false Gives you debugging messages on Turbolinks events
+   */
+  setOptions(options)
+```

data/docs/api/ruby-api-hot-reload-view-helpers.md

@@ -0,0 +1,42 @@
+## Hot Reloading View Helpers
+The `env_javascript_include_tag` and `env_stylesheet_link_tag` support the usage of a webpack dev server for providing the JS and CSS assets during development mode. See the [shakacode/react-webpack-rails-tutorial](https://github.com/shakacode/react-webpack-rails-tutorial/) for a working example.
+
+The key options are `static` and `hot` which specify what you want for static vs. hot. Both of these params are optional, and support either a single value, or an array.
+
+static vs. hot is picked based on whether `ENV["REACT_ON_RAILS_ENV"] == "HOT"`
+
+```erb
+ <%= env_stylesheet_link_tag(static: 'application_static',
+                             hot: 'application_non_webpack',
+                             media: 'all',
+                             'data-turbolinks-track' => true)  %>
+
+ <!-- These do not use turbolinks, so no data-turbolinks-track -->
+ <!-- This is to load the hot assets. -->
+ 
+ <!-- Note, you can have multiple files here. It's an array. -->
+ <%= env_javascript_include_tag(hot: ['http://localhost:3500/webpack-bundle.js]') %>
+
+ <!-- These do use turbolinks -->
+ <%= env_javascript_include_tag(static: 'application_static',
+                                hot: 'application_non_webpack',
+                                'data-turbolinks-track' => true) %>
+```
+
+See application.html.erb for usage example and [application.html.erb](https://github.com/shakacode/react-webpack-rails-tutorial/blob/master/app%2Fviews%2Flayouts%2Fapplication.html.erb)
+
+Helper to set CSS and JS assets depending on if we want static or "hot", which means from the Webpack dev server.
+
+In this example, `application_non_webpack` is simply a CSS asset pipeline file which includes styles not placed in the webpack build. The same can be said for `application_non_webpack` for JS files. Note, the suffix is not used in the helper calls.
+
+We don't need styles from the webpack build, as those will come via the JavaScript include tags.
+
+The key options are `static` and `hot` which specify what you want for static vs. hot. Both of
+these params are optional, and support either a single value, or an array.
+
+```erb
+ <%= env_stylesheet_link_tag(static: 'application_static',
+                             hot: 'application_non_webpack',
+                             media: 'all',
+                             'data-turbolinks-track' => true)  %>
+```

data/docs/api/ruby-api.md

@@ -0,0 +1,3 @@
+PENDING:
+
+Should we document the view helpers here concisely?

data/docs/basics/generator.md

@@ -0,0 +1,49 @@
+- [Generator](#generator)
+  - [Understanding the Organization of the Generated Client Code](#understanding-the-organization-of-the-generated-client-code)
+  - [Redux](#redux)
+    - [Multiple React Components on a Page with One Store](#multiple-react-components-on-a-page-with-one-store)
+  - [Using Images and Fonts](#using-images-and-fonts)
+
+The `react_on_rails:install` generator combined with the example pull requests of generator runs will get you up and running efficiently. There's a fair bit of setup with integrating Webpack with Rails. Defaults for options are such that the default is for the flag to be off. For example, the default for `-R` is that `redux` is off, and the default of `-b` is that `skip-bootstrap` is off.
+
+Run `rails generate react_on_rails:install --help` for descriptions of all available options:
+
+```
+Usage:
+  rails generate react_on_rails:install [options]
+
+Options:
+  -R, [--redux], [--no-redux]                          # Install Redux gems and Redux version of Hello World Example
+
+Runtime options:
+  -f, [--force]                    # Overwrite files that already exist
+  -p, [--pretend], [--no-pretend]  # Run but do not make any changes
+  -q, [--quiet], [--no-quiet]      # Suppress status output
+  -s, [--skip], [--no-skip]        # Skip files that already exist
+
+Description:
+    Create react on rails files for install generator.
+```
+
+For a clear example of what each generator option will do, see our generator results repo: [Generator Results](https://github.com/shakacode/react_on_rails-generator-results/blob/master/README.md). Each pull request shows a git "diff" that highlights the changes that the generator has made. Another good option is to create a simple test app per the [Tutorial](docs/tutorial.md).
+
+### Understanding the Organization of the Generated Client Code
+The generated client code follows our organization scheme. Each unique set of functionality, is given its own folder inside of `client/app/bundles`. This encourages for modularity of *domains*.
+
+Inside of the generated "HelloWorld" domain you will find the following folders:
+
++  `startup`: This contains the entry point files for webpack. It defaults to a single file that is used for server and client compilation, but if these need to be different, then you can create two webpack configurations with separate endpoints.
++ `containers`: "smart components" (components that have functionality and logic that is passed to child "dumb components").
++ `components`: includes "dumb components", or components that simply render their properties and call functions given to them as properties by a parent component. Ultimately, at least one of these dumb components will have a parent container component.
+
+You may also notice the `app/lib` folder. This is for any code that is common between bundles and therefore needs to be shared (for example, middleware).
+
+### Redux
+If you have used the `--redux` generator option, you will notice the familiar additional redux folders in addition to the aforementioned folders. The Hello World example has also been modified to use Redux.
+
+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.