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

Updated . Posted . Visible to the public.

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.

Preparations

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

Update file contents

  • Work through the Webpacker 4 migration guide Show archive.org snapshot

  • Read through the Webpack 4 migration guide Show archive.org snapshot

    • 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 Show archive.org snapshot .

    • Babel 7 namespaced many packages.
      • You probably used import 'babel-polyfill' before. You now need to say this to avoid build errors like Module not found: Error: Can't resolve 'babel-polyfill' (see here Show archive.org snapshot ):
        import "core-js/shim"; // included < Stage 4 proposals
        import "regenerator-runtime/runtime";
        
    • 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 Show archive.org snapshot
  • 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 Show archive.org snapshot .

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.
Arne Hartherz
Last edit
Florian Leinsinger
License
Source code in this card is licensed under the MIT License.
Posted by Arne Hartherz to makandra dev (2019-03-06 13:50)