webpack-rails-helper
This gem integrates assets from webpack into a Ruby on Rails application. It basically converts between the asset name and the asset name as emitted by webpack with hashes and stuff added.
This works by using a JSON manifest file. When using together with
webpack-dev-server
, the manifest is re-read on every call to one of the
helpers. This isn't exactly efficient but isn't much of a problem in development
mode. In production mode, the manifest is read once from file.
Installation
Add this to
Gemfile
:gem 'webpack-rails-helper'
Run
bundle
Add this to
"devDependencies"
ofpackage.json
:"webpack-manifest-plugin": "^1.2.1"
Run
yarn
(ornpm install
if you must)In
webpack.config.js
, add the plugin... plugins: [ // other plugins here new ManifestPlugin() ] ...
Configuration
In config/application.rb
or in a config/environments/*.rb
, configure it.
Defaults are as follows:
config.webpack.dev_server.host = 'localhost'
config.webpack.dev_server.port = 3808
# The host and port to use when fetching the manifest
# This is helpful for e.g. docker containers, where the host and port you
# use via the web browser is not the same as those that the containers use
# to communicate among each other. Uses 'host' and 'port' when set to nil.
config.webpack.dev_server.manifest_host = nil
config.webpack.dev_server.manifest_port = nil
config.webpack.dev_server.https = false # note - this will use OpenSSL::SSL::VERIFY_NONE
config.webpack.dev_server.enabled = ::Rails.env.development?
config.webpack.output_dir = 'public/webpack'
config.webpack.public_path = 'webpack'
config.webpack.manifest_filename = 'manifest.json'
Running
It's recommended to use foreman
or something similar to start Rails and the
webpack server during development. When using foreman
, the Procfile
could
look like this:
rails: ./bin/rails server
webpack: ./node_modules/.bin/webpack-dev-server --hot --inline --config config/webpack.config.js
API
The gem provides helper methods, available in views and controllers:
Generic asset:
webpack_asset_path(source, optional = false)
When using this method, the full name must be specified, including the file extension. When
optional
is set totrue
, a non-existing asset will not raise an exception. This is useful when some assets are only available in production mode, e.g. extracted CSS.Javascript tag:
javascript_webpack_tag(*names, **)
This creates a javascript include tag, just like
javascript_include_tag
would, but using an asset from webpack. The.js
extension is added automatically if required.Stylesheet tag:
stylesheet_webpack_tag(*names, **)
This creates a stylesheet link tag, just like
stylesheet_link_tag
would, but using an asset from webpack. The.css
extension is added automatically if required. CSS assets are considered optional when the dev_server is running for reasons stated above.
Acknowledgements
This started as a fork of https://github.com/mipearson/webpack-rails.git
The reason for the fork is the usage of a different webpack manifest format. The original depends on 'stats-webpack-plugin' while this uses 'webpack-manifest-plugin'. Since the file formats are so different, it results in an incompatible API.
This code has lived inside an application and has been extracted back out into this gem.
License
This gem is released under the MIT license.