Webpacker Lite: Why Fork Webpacker?

Update September 10, 2017. Webpacker Lite has been merged into v3 of Webpacker. If you’re using React on Rails, see the CHANGELOG for migration instructions to update to v9 of React on Rails which uses v3 of Webpacker.

See PR 601 on rails/webpacker for the merge of Webpacker Lite into Webpacker, as well as the PR 908 for v9.0.0 of React on Rails that is based on Webpacker.

I’m the creator and owner of the React on Rails gem, arguably the most popular and successful integration of Ruby on Rails with the React/Redux/ React-Router/Webpack ecosystem.

Before the 8.0.0 release, React on Rails used Webpack to create assets for deployment within the Rails Asset Pipeline. Webpack was mainly used for bundling the modules, leaving minification, fingerprinting, etc. to the Asset Pipeline.

In early 2017, with Webpack Tree Shaking (Webpack’s elimination of dead-code), I hit a serious issue in that running Asset Pipeline minifier would break the JavaScript. Essentially, this “double minification” was not only unnecessary, but broken!

At about this same time, I discovered that Rails would soon officially embrace the Webpack module bundler for preparation of client side assets, completely bypassing the Rails Asset Pipeline. The new gem, called Webpacker, introduced helpers so that Rails views would get the right URL for Webpack deployed assets. Thus, I embarked on integrating React on Rails with the official Webpacker gem. I spent a good number of hours to influence the Webpacker project with what React on Rails needed. If you’re curious, you can read a summary that work here.

So why did I fork the Webpacker gem to create the Webpacker Lite gem (shakacode/webpacker_lite)?

1. React on Rails needed only a tiny bit of Webpacker, the helpers to obtain the URL or file path for Webpack created assets. React on Rails did not need the rest of what Webpacker provided, as described below.
2. Discussions with other React on Rails maintainers, namely Rob Wise, convinced me that a much simpler and leaner webpacker would benefit React on Rails, and that justified the costs of maintaining a fork. This was prescient, as during the integration of React on Rails with Webpacker Lite, I ended up making many small changes in functionality. These differences are outlined in the Webpacker Lite readme.
3. As the owner of React on Rails, I needed (and will continue to need) the ability to make quick changes to the helpers without a long discussion of how the changes would affect the overall community.

React on Rails: Minimal Integration

The design of React on Rails intentionally avoids overly tight integration with other quickly evolving tools, especially Webpack. React on Rails assumes only:

1. Your client side app is entirely within the /client directory. This allows a non-Rails-programmer to essentially tune out the non JavaScript world.
2. You configure your /config/initializers/react_on_rails.rb with a few details that link back to how you will invoke your build scripts and configure your Webpack output directories.
3. Your JavaScript will use a minimal API to register your React components and Redux stores.
4. Your Rails code will use a minimal API to mount your React components on Rails views and possibly hydrate your Redux stores, including seamless server rendering.

We’ve got some other cool optional features that leverage the combination of Rails and React, such as internationalization, convenient test helpers, deployment automation.

We don’t make any assumptions on how you will configure Webpack or how you will organize the files within your /client directory.

What React on Rails Did Not Want from Webpacker

Webpacker overlaps quite a bit with React on Rails. React on Rails users would not want the following features from Webpacker:

• Strongly opinionated (auto-) configuration of webpack, such as putting entry point files in a directory. Why? How would you specify different entry points for your server side-rendering? Then you can override some defaults from Webpacker, but maybe it’s just simpler to have your own configuration?
• Installers for UI frameworks, like React, Angular, Elm, Vue, etc. We already picked deep support for React.
• Ruby binstubs to call the JavaScript executables, like webpack and yarn. This is a well-solved problem in the node ecosystem, and we don’t want React on Rails to be opinionated on this.
• A structure imposed on how to organize Webpack and JavaScript files. We already decided that the only structure is to have all client side JavaScript under /client.

What New Assumptions Does Webpacker Lite bring to React on Rails?

With the addition of Webpacker Lite support in React on Rails 8.x+, you may optionally use Webpacker Lite provided you:

1. Configure Webpack to output files to the directory you configured in your /config/webpacker_lite.yml. Use the webpack-manifest-plugin to generate a simple manifest that maps the bundle name, like webpack-bundle.js, to the possibly hashed file name, like webpack-bundle-fefd77bc.js. See these instructions for more details.
2. Use the Webpacker Lite helpers in your Rails views.

How do you choose between Webpacker and Webpacker Lite?

The Webpacker gem configures the Webpack module bundler** via “convention over configuration”**, via the generated files and the setup of the configuration files. React on Rails, on the other hand, is intentionally designed to have the most minimal and simple requirements for an app’s JavaScript and Webpack setup. Note, the React on Rails generator only serves as an example of the simplest possible setup.

You can choose either the simplicity and limitations of the default webpacker Webpack config, or you can choose the flexibility of handling the Webpack configuration on your own, and thus prefer Webpacker Lite. The Rails Doctrine itself advocated Provide Sharp Knives. Configuring Webpack yourself is definitely the “sharp knife” approach compared to using the default webpacker configuration.

If you want the quickest way to include ES6 style JavaScript snippets in your Rails app, then Webpacker is a great start. If you want the full power of Webpack and the React front-end architecture, then consider Webpacker Lite and React on Rails.

Did I Really Need to Fork?

At ShakaCode, our main principles regarding open source are:

• Run with the herd. For that, I should have just stayed with basic Webpacker.
• Pick your battles carefully with where you don’t run with the herd, and have good reason to do so, as you’ll be maintaining it. Since I already maintain React on Rails,_ it’s easier for me to maintain the simplified webpacker_lite_.

I hope the above discussion makes it clear on why I decided to create the webpacker_lite “fork” of webpacker.** Overall, my number one goal is to make React on Rails as easy to use as possible, with the goal being “It just works.”** If you consider the projects using React on Rails and the kudos we’ve received for React on Rails, you might agree that we’ve been achieving this goal. Plus, any commits we add to shakacode/webpacker_lite can be merged into rails/webpacker.

Please note, Webpacker Lite will work just fine for any project that wants the Webpacker view helpers without any opinions on how to configure your Webpack file.