How To Use Webpacker

Setup

Instructions to use Webpacker for Blacklight 7 to compile javascript assets, as of 7/19/18, these instructions have some inaccuracies and are in general incomplete, but a good starting point for figuring all this out. (https://www.npmjs.com/package/blacklight-frontend):

1. If Node.js and NPM are not already installed on your machine, this might help http://blog.teamtreehouse.com/install-node-js-npm-mac (basically, use homebrew)

2. Check your Node.js version and upgrade if required since Webpacker requires Node.js >= 6.0.0. Currently my local versions are as below:

   $ npm -v
   6.1.0
   

   $ node -v
   v10.6.0
   

3. Install Yarn

   $ brew install yarn
   

4. To Install Webpacker just ran the below since it is already added in the Gemfile. If it wasn't in the Gemfile, you could run gem add webpacker

   $ bundle
   $ bundle exec rails webpacker:install
   

   TODO: we should be clear about what bundle exec rails webpacker:install does.

5. To install all the dependencies listed within package.json in the local node_modules folder, just run

   $ yarn install
   

You could just use yarn too, which does the same thing as yarn install. Yarn will take the config set in webpacker.yml. We have set check_yarn_integrity: true which generates integrity digests on our yarn.lock file, which will jive well with production deployment which wants to generate these digests too (see desc "Compile JavaScript packs using webpack for production with digests" in compile.rake in the webpacker gem.

Regular day-to-day use

3 terminal tabs:

1. $ rails s
2. $ bin/webpack-dev-server (does live code reloading, nice!)
3. $ bundle exec rails solr:up

or just run

$ bundle exec foreman start -f Procfile.dev

What goes where

All of the scss, images and javascript can be put into the /app/javascript directory. Here's what my directory looks like right now:

.
├── packs
│   └── application.js
├── psulib_blacklight
│   ├── fonts
│   ├── images
│   │   ├── index.js
│   │   └── logo.png
│   ├── index.js
│   └── styles
│       ├── app.scss
│       └── blacklight_marc.scss
└── src
    └── js

The idea is that you set all of the assets needed for your application in one sub-directory with that sub-directory having the name of your app (i.e., psulib_blacklight). Inside this app sub-directory you need fonts, images and styles sub-directories. All of this is compiled into the index.js file. And this is called by the application.js file (under packs) that simply imports psulib_blaclight. In order for blacklight to use webpacker for scss all of the core scss and the blacklight-marc scss have to be added as front-end dependencies in package.json. Then these scss files are called in by app.scss. Because the blacklight_marc scss had some problems, I actually just duplicated the scss file from that repo and moved it into the styles folder with some adjustments. I left blacklight-marc in the package.json file just for clarity in terms of understanding that we rely on it.

For images, you'll see that there is an index.js file in the images directory. That file is a manifest of all the images you want webpacker to bring in.

The last piece is making sure that <%= stylesheet_pack_tag 'application' %> and <%= javascript_pack_tag 'application' %> are being called from an erb file somewhere (base.html.erb in our case). Notice that we say application. Then notice that the file inside the packs directory is called application.js. One could have as many packs as is wanted and include them where ever you want.

And this last point leads into more that could be done. Webpacker is really geared for introducing event-based javascript and web components. So, while we don't ever have to take advantage of that, it'd be easy to add this kind of functionality.

TODO: more documentation on environment.rb and the rest of the config inside config/webpacker.

Troubleshooting

If you get Yarn packages out of date error

Your Yarn packages are out of date!
Please run `yarn install` to update.

This is what solved the above issue for me:

$ brew uninstall --force yarn
$ rm -rf ~/.yarn
$ brew install yarn
$ brew link --overwrite yarn
$ yarn install
$ rails webpacker:install

Note from @cdm32: I just ran yarn install in that case and it worked for me. But, yeah, if there's an underlying issue with brew, that could be a problem.

Bootsnap -- LoadError

Bootsnap is a gem used to speed up local development. We have experienced a problem where clearing the cache that bootsnap builds is necessary. Here's how:

• go to the project home, then cd into tmp/cache
• delete bootsnap-load-path-cache and bootsnap-compile-cache