Posted 7 months ago. Visible to the public.

Upgrade guide for moving a Rails app from Webpack 3 to Webpack 4

Webpacker is Rails' way of integrating Webpack, and version 4 has been released just a few days ago, allowing us to use Webpack 4.

I successfully upgraded an existing real-world Webpack 3 application. Below are notes on everything that I encountered.
Note that we prefer not using the Rails asset pipeline at all and serving all assets through Webpack for the sake of consistency.


  • Remove version locks in Gemfile for webpacker
  • Remove version locks in package.json for webpack and webpack-dev-server
  • Install by calling bundle upgrade webpacker and yarn upgrade

Update file contents

  • Work through the Webpacker 4 migration guide
    • Run npx babel-upgrade --write which will download and run babel-upgrade to auto-fix some config files (including some you may not need)
    • Place supported browsers (might live in .babelrc) into .browserslistrc in your project's root directory
    • Look at the default webpacker.yml and merge any changes to your project's webpacker.yml. Add extract_css: true to the default section make sure CSS files are still built by Webpacker.
    • Replace .babelrc with babel.config.js. I suggest you take the default file and compare it with your .babelrc plugins list and add missing ones. You may remove the environment switches in babel.config.js and function wrapper.
    • Replace .postcssrc with postcss.config.js. Use the default file and add any missing plugins.
    • Webpacker 4 will transpile code inside node_modules. Apparently this could fix some issues but also cause others. Webpack 3 did not do that and if everything was fine before, maybe just restore the previous behavior by adding environment.loaders.delete('nodeModules') to your environment.js.
    • If you used postcss-cssnext before, add it to your package.json (it's no longer provided by default).
  • Read through the Webpack 4 migration guide
    • If your project previously fixed UglifyJs for IE 11 via uglifyOptions.ecma = 5, remove that line from your pack's production.js. Your .browserslistrc should define the required ECMAScript level implicitly.
  • Skim the Babel 7 migration guide.
    • Babel 7 namespaced many packages.
      • You probably used import 'babel-polyfill' before. You now need to say import '@babel/polyfill' to avoid build errors like Module not found: Error: Can't resolve 'babel-polyfill'.
    • Note that options in configuration files may no longer be defined as comma-separated lists.
    • You might not need to change anything (aside from babel-polyfill) since babel-upgrade should have changed package names for you, and the default files also use Babel 7's package names.
    • If you are interested in all the new shiny features, check the Babel 7 release blog post
  • Webpack 4 also namespaces files compiled files inside a pack
    • CSS files are stored inside css, JavaScripts inside js and images inside media
    • If you namespaced your pack's contents like <webpack-root>/your-pack-name/images (which was possible with Webpack 3) note that you can no longer do that because Webpacker's view helpers won't be able to locate files.
      • Basically all your assets should live in <webpack-root>, e.g. <webpack-root>/images.
      • If you want to namespace files, use <webpack-root>/images/your-pack-name.
      • Your pack manifest's import and require statements need to be adjusted accordingly.
      • If you have it, maybe get rid of a <webpack-root>/your-pack-name/index.js and move everything into the pack manifest at <webpack-root>/packs/your-pack-name.js.
    • Note that Webpacker provides more helpers to reach assets, like resolve_path_to_image. See Webpacker::Helper.

Confirm everything works

  • If you're using it, start bin/webpack-dev-server to see if Webpack compiles properly.
  • Boot up rails server and check if your application responds and everything looks okay.
  • Run your application's tests.

makandra has been working exclusively with Ruby on Rails since 2007. Our laser focus on a single technology has made us a leader in this space.

Owner of this card:

Arne Hartherz
Last edit:
7 months ago
by Arne Hartherz
About this deck:
We are makandra and do test-driven, agile Ruby on Rails software development.
License for source code
Posted by Arne Hartherz to makandra dev
This website uses cookies to improve usability and analyze traffic.
Accept or learn more