Adding Webpacker 3.0 to Your Ruby on Rails Application

Webpacker is a tool that helps you manage JavaScript, CSS, and assets for Ruby on Rails applications. And now, with Webpacker 3.0, you can configure and use it as an npm package manager as well. This article will show how to configure Webpacker 3.0 in a Ruby on Rails 5 project running on a Mac OS machine.

Creating and configuring your Ruby on Rails project

To start, we need Yarn to use Webpacker. Yarn is a package manager for JavaScript code. With it, it is simple to use any npm package distributed by the community. If you use npm, run the first command line below; if not, run the second command line.

$ brew install yarn
$ brew install yarn --without-node

The next step is to create a Ruby on Rails project with –webpack param. (Please note that this only works with Rails 5+.)

$ rails new webapp --webpack

In your Gemfile, add the Webpacker gem and then run bundle to download Webpacker into your project..

gem 'webpacker', '~> 3.5'

$ bundle

Now, running the following installs Webpacker in your application.

$ bundle exec rails webpacker:install

That’s it. The Ruby on Rails project is now completely functional with Webpacker.

Understanding the Webpacker structure

We can verify that inside the directory, app/assets has a new folder called config, and inside that we have a manifest.js file that links the folders stored in the app/assets directory.

# app/assets/config/manifest.js

//= link_tree ../images
//= link_directory ../javascripts .js
//= link_directory ../stylesheets .css

The difference here is that we have a new folder called javascript inside the app directory. Inside this folder, we will add our assets that will be managed by Webpacker. The recommendation is that we follow the structure shown in the image below.

source: https://www.npmjs.com/package/@rails/webpacker#usage

We can also check inside the layout application that links to the JavaScript and CSS that are already set up.

# app/views/layout/application/html.erb
<%= stylesheet_link_tag    'application', media: 'all', 'data-turbolinks-track': 'reload' %>
<%= javascript_include_tag 'application', 'data-turbolinks-track': 'reload' %>

Inside the config directory, we can see the webpacker.yml file that contains the parameters of the Webpacker configuration used in this application. Here we can see the source_path key that set up app/javascript as the default folder of the Webpacker files.

# config/webpacker.yml
source_path: app/javascript

In the webpacker.yml file, we have the extension key that set up the extension files linked, and here we can define the CSS preprocessors used (SASS/SCSS). And we also have the configuration of the dev-server.

Lastly, we have a webpack folder inside the config directory. There is one file for each environment that could be edited to include the code used when Webpack starts.

Including Webpack files

Let’s create a new controller (called Home) and generate the view (called index) for our project.

$ rails generate controller home index

Create the folders to store the CSS inside the app/javascript directory:

$ mkdir app/javascript/src

Now, move the home.scss file to the app/javascript/src directory:

$ mv app/assets/stylesheets/home.scss app/javascript/src/

Next, add some styles:

# app/assets/stylesheets/home.scss
body {
  color: #fff;
  background: #333;
}

Now, create the SCSS application file:

$ touch app/javascript/src/application.scss
And import home.scss:
# app/javascript/src/application.scss
@import 'home';
We also need to include application.css in our layout template.
# app/views/layout/application.html.erb
<%= stylesheet_pack_tag 'application.css' %>
And to finish the connection with styles, we need to require the loading of SCSS in the JavaScript.
# app/javascript/application.js
require('../src/application.scss')
The next step is setting up the JavaScript. Create a home.js file inside app/javascript/packs:
$ touch app/javascript/packs/home.js
Include the code below to print some of the homepage.
# app/javascript/packs/home.js
import _ from 'lodash';

function component() {
  let element = document.createElement('div');

  element.innerHTML = "Web App";

  return element;
}

document.body.appendChild(component());
To associate our views with JavaScript, we just need to include the script tag to import home.js:
# app/views/home/index.html.erb
<%= javascript_pack_tag 'home.js' %>
That's it! Now, let's see how to run Webpack and view the result.
Starting Webpack
In Webpacker 3.0, the Webpack process can run inside the Rails server. But, we can start the Webpack and pass the watch parameter to listen to any updates in our app/javascript directory.
$ ./bin/webpack --watch --colors --progress
Or we can start the Rails server as usual:
$ rails s
And access our page in the browser with this address: http://localhost:3000/home/index

The result is shown in the image below.


Conclusion
The setup of Webpacker 3.0 is not as easy (as compared to older versions), but it is much more comprehensive, which will be apparent to anyone who is already familiar with npm package configuration. It provides better performance, agility in development, and allows customization of the dev-server — with the promise of more changes with Rails 6.