Rails + webpack - webpacker
Rails is great, webpack is great, abstractions are not always great.
I'm going to start this from a pretty vanilla Rails 5 setup, I started with rails new webpacked --webpack.
Also, for this to work, you'll need webpack > 4.3.0.
Remove the webpacker things
Remove sass-rails, uglifier, coffee-rails, turbolinks, webpacker from Gemfile.
Remove config.webpacker.check_yarn_integrity settings in config/envronments.
Change javascript_pack_tag and stylesheet_pack_tag to javascript_include_tag and stylesheet_link_tag.
Then:
$ rm -r bin/webpack config/webpack* public/packs
$ bundle
$ yarn uninstall @rails/webpacker webpack-dev-server
Disable sprockets
# config/environments/development.rb
Rails.application.configure do
…
config.assets.compile = false
…
end
Install dependencies
$ mkdir public/assets
$ touch public/assets/.keep
$ yarn add --dev webpack webpack-{cli,dev-server}
Check /public/assets into git, then Add /public/assets to your .gitignore. This is where we're going to build assets to for production.
Add build scripts
// package.json
{
"name": "webpacked",
"private": true,
"scripts": {
"server": "webpack-dev-server",
"precompile": "rm -r public/assets/* && NODE_ENV=production webpack"
},
"dependencies": {},
"devDependencies": {
"webpack": "^4.5.0",
"webpack-cli": "^2.0.13",
"webpack-dev-server": "^3.1.1"
}
}
Add a simple webpack config
// webpack.config.js
const DIR = require("path").resolve(__dirname);
const PROD = process.env.NODE_ENV === "production";
module.exports = {
entry: {
application: `${DIR}/app/assets/javascripts/application.js`,
},
mode: PROD ? "production" : "development",
output: {
chunkFilename: "[name].js",
filename: "[name].js",
path: `${DIR}public/assets/`,
},
resolve: {
extensions: [".js", ".json", ".css"],
modules: ["node_modules", `${DIR}/app/assets`],
},
};
Now start the wepback dev server:
$ yarn server
ℹ ｢wds｣: Project is running at http://localhost:8080/
ℹ ｢wds｣: webpack output is served from /
ℹ ｢wdm｣: Hash: ee01dba8920628636a4e
ℹ ｢wdm｣: Compiled successfully.
Go to http://localhost:8080/application.js and you should be able to see the compiled webpack bundle.
Compile CSS
Add the necessary webpack loaders:
$ yarn add -D {file,extract,css,postcss}-loader cssnano
And then set up a rule for them:
// webpack.config.js
module.exports = {
…
module: {
rules: [
{
test: /\.css/,
use: [
{
loader: "file-loader",
options: {
name: "[name].css",
},
},
{ loader: "extract-loader" },
{ loader: "css-loader" },
{
loader: "postcss-loader",
options: {
ident: "postcss",
plugins: loader => [
require("cssnano")({
discardComments: { removeAll: true },
}),
],
},
},
],
},
],
},
…
};
Now, in your JavaScript files, you can require stylesheets like so:
// app/assets/javascripts/application.js
require("stylesheets/application.css")
console.log("Hello from application.js!")
Tell Rails where to find assets from webpack-dev-server
Now if you load up your site, you're probably seeing something like:
Sprockets::Rails::Helper::AssetNotFound in Welcome#index
Add this helper to app/helpers/application_helper.rb:
# app/helpers/application_helper.rb
module ApplicationHelper
def webpack_asset_url(name)
"http://localhost:8080/#{name}"
end
end
Then wrap the paths of any assets you're including in that helper, and don't forget the extensions:
<!-- app/views/layouts/application.html.erb -->
<!DOCTYPE html>
<html>
<head>
<title>Webpacked</title>
<%= csrf_meta_tags %> <%= stylesheet_link_tag
webpack_asset_url('application.css'), media: 'all' %> <%=
javascript_include_tag webpack_asset_url('application.js') %>
</head>
<body>
<%= yield %>
</body>
</html>
Building for production
But wait, production! We need to tell Rails to serve the static assets in production:
# app/helpers/application_helper.rb
module ApplicationHelper
def webpack_asset_url(name)
if Rails.env.production?
"/assets/#{name}"
else
"http://localhost:8080/#{name}"
end
end
end
You can test this by precompiling the assets and then restarting your Rails server in production mode:
$ yarn precompile && \
RAILS_ENV=production \
RAILS_SERVE_STATIC_FILES=true \
SECRET_KEY_BASE=hi \
bin/rails server
Fingerprinting assets
But wait, asset fingerprinting! Change the output filename for CSS and entrypoints:
// webpack.config.js
module.exports = {
…
module: {
rules: [
{
test: /\.css/,
use: [
{
loader: "file-loader",
options: {
name: PROD ? "[name]-[hash].css" : "[name].css",
},
},
{ loader: "extract-loader" },
{ loader: "css-loader" },
{
loader: "postcss-loader",
options: {
ident: "postcss",
plugins: loader => [
require("cssnano")({
discardComments: { removeAll: true },
}),
],
},
},
],
},
],
},
output: {
chunkFilename: PROD ? "[name]-[contenthash].js" : "[name].js",
filename: PROD ? "[name]-[contenthash].js" : "[name].js",
hashDigestLength: 32,
path: `${DIR}public/assets/`,
},
…
}
Now we need to tell Rails about these hashes somehow. First, we'll add the webpack-manifest-plugin (when building for production) to output a JSON map of the names of chunks to their hashed names:
// webpack.config.js
module.exports = {
…
plugins: [
PROD && new (require("webpack-manifest-plugin"))()
].filter(Boolean),
…
};
If you yarn precompile again, you should see it output a file like this, in addition to the other chunks:
// public/assets/manifest.json
{
"application.css": "application-4cf6c42fe4e9a27ee5a758dcf37091f7.css",
"application.js": "application-5689a742f9b3cb6758a6b35164a98ade.js"
}
Now let's update the Rails helper to get everything sorted out:
# app/helpers/application_helper.rb
module ApplicationHelper
def webpack_asset_url(name)
if Rails.env.production?
"/assets/#{webpack_fingerprint_for(name)}"
else
"http://localhost:8080/#{name}"
end
end
def webpack_fingerprint_for(name)
@chunk_manifest ||= JSON.parse(File.read('public/assets/manifest.json'))
if @chunk_manifest[name].nil?
logger.error "chunk_manifest_missing name=#{name}"
logger.error @chunk_manifest.inspect
end
@chunk_manifest[name]
end
end
You might have to restart the Rails server again, but now you should see it loading the fingerprinted assets! Now wherever you run rake assets:precompile during your deployment process, replace it with yarn precompile.
Separate the webpack runtime
For better caching, it's smart to separate the webpack runtime from your application's JavaScript:
// webpack.config.js
module.exports = {
…
optimization: {
runtimeChunk: "single",
},
…
};
Then just include that runtime chunk before any other JavaScript:
<!-- app/views/layouts/application.html.erb -->
<!DOCTYPE html>
<html>
<head>
<title>Webpacked</title>
<%= csrf_meta_tags %> <%= stylesheet_link_tag
webpack_asset_url('application.css'), media: 'all' %> <%=
javascript_include_tag webpack_asset_url('runtime.js') %> <%=
javascript_include_tag webpack_asset_url('application.js') %>
</head>
<body>
<%= yield %>
</body>
</html>