Using Webpacker to compile javascript assets

This is a work in progress. And should be considered experimental.

Installing Webpacker in Blacklight

This requires Blacklight 7 or higher.

These instructions will show you how to use Webpacker with Blacklight in development mode. They have been tested on as of October 2020. The Webpacker gem will replace the entire sprockets based asset pipeline.

Here's what to do:

1. Install nodejs and npm (they are packaged together)
2. Install yarn
3. Add gem 'webpacker', '~> 5.2' to your Gemfile
4. Run bundle install
5. Run bundle exec rails webpacker:install
6. Run:

yarn add blacklight-frontend
yarn add popper.js
yarn add @rails/ujs
yarn add jquery

Next, change config/webpack/environment.js as per https://getbootstrap.com/docs/4.0/getting-started/webpack/ and https://github.com/rails/webpacker/blob/master/docs/webpack.md#plugins to this:

const { environment } = require('@rails/webpacker')
const webpack = require('webpack')

environment.plugins.prepend(
    'Provide',
    new webpack.ProvidePlugin({
        $: 'jquery',
        jQuery: 'jquery',
        jquery: 'jquery',
        'window.jQuery': 'jquery',
        Popper: ['popper.js', 'default'],
        Rails: ['@rails/ujs'],
    })
)


module.exports = environment

In your pack file (app/javascript/packs/application.js), require blacklight, popper, bootstrap and an in-lined block of JS from a erb file:

// Vendor
require('@rails/ujs').start()
global.Rails = Rails

import "bootstrap/dist/js/bootstrap"
import 'blacklight-frontend/app/assets/javascripts/blacklight/blacklight'

You may delete the contents of app/assets/javascripts as these are no longer being used.

Using just some portions of Blacklight JS

The above example, with import 'blacklight-frontend/app/assets/javascripts/blacklight/blacklight', will import ALL of the Blacklight JS, in one aggregated file. If you'd like to choose just portions of Blacklight JS for local customizations reasons, individual files are also available, beginning with a base core file, eg:

import 'blacklight-frontend/app/javascript/blacklight/core';
import 'blacklight-frontend/app/javascript/blacklight/autocomplete';
import 'blacklight-frontend/app/javascript/blacklight/bookmark_toggle';
import 'blacklight-frontend/app/javascript/blacklight/checkbox_submit';
import 'blacklight-frontend/app/javascript/blacklight/modal';
import 'blacklight-frontend/app/javascript/blacklight/button_focus';
import 'blacklight-frontend/app/javascript/blacklight/facet_load';
import 'blacklight-frontend/app/javascript/blacklight/search_context';

You could leave out individual imports you do not want/need. One risk with this approach is that future versions of Blacklight may introduce additional individual files that you may not be including, but need/want.

Using Webpacker in Blacklight Development

Run bin/webpack-dev-server to have webpacker compile new JavaScript packs (and other assets) on change. Webpacker will also refresh your browser page when this dev server is running.

Add front end javascript dependencies with yarn add package followed by yarn to intall said package. yarn add package will update your package.json, yarn will update your yarn.lock. Note that you probably need to shut off the webpack dev server and rails server when you're adding new packages.

Stuff on the Internet about rails and webpacker

• Rails 5.1 loving javascript (and webpacker/yarn): https://weblog.rubyonrails.org/2017/4/27/Rails-5-1-final/
• http://samuelmullen.com/articles/embracing-change-rails51-adopts-yarn-webpack-and-the-js-ecosystem/
• https://rossta.net/blog/from-sprockets-to-webpack.html
• https://medium.com/statuscode/introducing-webpacker-7136d66cddfb
• https://www.youtube.com/watch?v=I_GGYIWbmg0
• https://www.neontsunami.com/posts/replacing-rails-asset-pipeline-with-webpacker