VERSION 8 of React on Rails is super close!!! VERSION 8.0.0-beta.3 has shipped with webpacker_helpers support! Please try the 8.0.0-beta.3 beta and please report issues! We're SUPER close as we've also upgraded the shakacode/react-webpack-rails-tutorial with PR #395. That PR shows the changes needed to go to Webpacker Helpers.
A slimmer version of Webpacker
If you like this project, show your support by giving us a star!
Everything should be made as simple as possible, but not simpler.
- Name of the manifest file.
- The directory within
/publicwhere Webpack will create the manifest and output file.
Then you need to configure your Webpack to generate a simple manifest that maps the base output names to the possibly fingerprinted versions. Note, unlike Webpacker, Webpacker Helpers wants your manifest to NOT contain any host information.
Optionally, you can configure the name of the server and port for hot reloading, and if hot reloading is the default for a given Rails.env.
For more details on how this project differs from Webpacker and why we forked, please see Webpacker Helpers: Why Did We Fork Webpacker?
- 2017-05-03: React on Rails 8.0.0 beta defaults to using webpacker_helpers.
The best way to see the installation of webpacker_helpers is to use the generator for React on Rails 8.0.0 or greater. Otherwise, add the gem and create the configuration file described below.
config/webpacker_helpers.ymlfile, as described below. You will specify the name of the manifest file and the output directory used by step 2.
Use the webpack-manifest-plugin to generate a manifest in the output directory (
webpack_public_output_dir) that you configured in your
Use the view helpers on your layouts to provide the webpack generated files. Note, these are the same names used by rails/webpacker. These
outputnames are NOT the actual file names, as the file name may have a fingerprint.<%# app/views/layouts/application.html.erb %>
For more details on the helper documentation, see the Ruby comments in lib/webpacker_helpers/helper.rb and please submit PRs here to help us improve the docs!
Webpacker Helpers takes one configuration file:
config/webpacker_helpers.yml used to configure two required values and a couple optional values. Note, this file is configured like
config/database.yml in that you place the values beneath the name of the Rails.env.
Mandatory Configuration within
manifest: The manifest file name
webpack_public_output_dir: The output directory of both the manifest and the webpack static generated files within the
Note, placing output files within the Rails
/public directory is not configurable.
Optional Configuration within
hot_reloading_host: The name of the hot reloading
webpack-dev-serverincluding the port
hot_reloading_enabled_by_default: If hot reloading should default to true
Hot Reloading Notes
Do not put the output server in your
manifest.json file. The rails view helpers will automatically prepend the hot_reloading_host to the asset path.
This example config shows how we use different output directories for the webpack generated assets per the type of environment. This is extremely convenient when you want to log redux messages in development but not in your tests.
# /config/webpacker_helpers.yml# Note: Base output directory of /public is assumed for static filesdefault: &defaultmanifest: manifest.json# Used in your webpack configuration. Must be created in the# webpack_public_output_dir folder.development:<<: *default# generated files for development, in /public/webpack/developmentwebpack_public_output_dir: webpack/development# Default is localhost:3500. You can specify the protocol if needed. Defaults to http://.hot_reloading_host: localhost:3500# Developer note: considering removing this option so it can ONLY be turned by using an ENV value.# Default is false, ENV 'HOT_RELOADING' will always overridehot_reloading_enabled_by_default: falsetest:<<: *default# generated files for tests, in /public/webpack/testwebpack_public_output_dir: webpack/testproduction:<<: *default# generated files for tests, in /public/webpack/productionwebpack_public_output_dir: webpack/production
Example for Development vs Hot Reloading vs Production Mode
<!-- In test mode --><!-- In development mode --><!-- In development mode with hot reloading, using the webpack-dev-server --><!-- Note, there's no stylesheet tag by default, as your CSS should be inlined in your JS. --><!-- In production mode -->
Other Helpers: Getting the asset path
asset_pack_path helper provides the path of any given asset that's been compiled by webpack.
Note, the real file path is the subdirectory of the public.
For example, if you want to create a
<link rel="prefetch"> or
for an asset used in your pack code you can reference them like this in your view,
You may use the React on Rails NPM Package, react-on-rails/webpackConfigLoader to provide your Webpack config with easy access to the YAML settings. Even if you don't use the NPM package, you can use that file to inspire your Webpack configuration.
To see available webpacker_helpers rake tasks:
If you are using different directories for the output paths per RAILS_ENV, this is how you'd delete the files created for tests:
RAILS_ENV=test rake webpacker_helpers:clobber
Differences from Webpacker
- Configuration setup of an optional single file
- Webpacker helpers expect the manifest to contain the server URL when hot reloading. Webpacker Helpers expects the manifest to never contain any host information.
Tell Rails and Webpacker Helpers that you're hot reloading by setting the ENV value of
HOT_RELOADING=YESif you are not hot reloading by default by setting the
hot_reloading_enabled_by_defaultkey in your config file.
By default, the
- Ruby 2+
- Rails 4.2+