Rails + webpack - webpacker

Posted Apr 4, 2018 under webpack, javascript and rails

5 minute read

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}"  endend

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]  endend

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>

History

Oct 1, 2019
Refactor lookups to use IDs rather than paths

Dec 2, 2018
Gatsby v2

Apr 19, 2018
Fix date issue

Apr 19, 2018
Publish post

Apr 6, 2018
Add published flag