Compile javascript assets

This will enable us to write javascript in es6+ and compile it into a
bundle for distribution.

.gitignore

@@ -16,3 +16,4 @@ pkg/*
 .internal_test_app
 .vagrant
 /spec/examples.txt
+node_modules/*

.npmignore

@@ -0,0 +1,23 @@
+.*
+Gemfile
+Rakefile
+Vagrantfile
+app/assets/images
+app/controllers
+app/helpers
+app/models
+app/presenters
+app/services
+app/views
+blacklight.gemspec
+config/locales
+config/routes.rb
+coverage
+db
+lib
+pkg
+provision.sh
+solr
+spec
+tasks
+template.demo.rb

README.md

@@ -7,7 +7,7 @@ You can use Blacklight to enable searching and browsing of your collections.
 Blacklight uses the [Apache Solr](http://lucene.apache.org/solr) search engine
 to search full text and/or metadata.  Blacklight has a highly
 configurable Ruby on Rails front-end. Blacklight was originally developed at
-the University of Virginia Library and is made public under an Apache 2.0 license. 
+the University of Virginia Library and is made public under an Apache 2.0 license.
 
 ## Installation
 
@@ -38,5 +38,81 @@ rails generate blacklight:install
 * Bundler
 * Rails 5.0+
 
-## Configuring Apache Solr 
+## Configuring Apache Solr
 You'll also want some information about how Blacklight expects [Apache Solr](http://lucene.apache.org/solr ) to run, which you can find in [README_SOLR](https://github.com/projectblacklight/blacklight/wiki/README_SOLR)
+
+## Building the javascript
+The javascript is built by npm from sources in `app/javascript` into a bundle
+in `app/assets/javascripts/blacklight/blacklight.js`. This file should not be edited
+by hand as any changes would be overwritten.
+
+This is accomplished with the following steps:
+1. [Install npm](https://www.npmjs.com/get-npm)
+1. run `npm install` to download dependencies
+1. run `npm run js-compile-bundle` to build the bundle
+1. run `npm publish` to push the javascript package to https://npmjs.org/package/blacklight-frontend
+
+## Using the javascript
+[Install Webpacker](https://github.com/rails/webpacker#installation)
+Add blacklight-frontend as a dependency by doing:
+```
+yarn add blacklight-frontend
+```
+
+Then add these lines to `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
+
+```js
+const webpack = require('webpack')
+
+environment.plugins.set(
+  'Provide',
+  new webpack.ProvidePlugin({
+    $: 'jquery',
+    jQuery: 'jquery',
+    jquery: 'jquery',
+    'window.jQuery': 'jquery',
+    Popper: ['popper.js', 'default'],
+  })
+)
+
+module.exports = environment
+```
+
+In your pack file (`app/javascript/packs/application.js`), require blacklight:
+```
+require('blacklight-frontend/app/assets/javascripts/blacklight/blacklight')
+```
+Then remove these requires from `app/assets/javascripts/application.js`:
+
+```
+//= require jquery
+//= require popper
+//= require twitter/typeahead
+//= require bootstrap
+```
+
+Add the following to the app/views/layouts/blacklight/base.html.erb (maybe this can be simpler)
+```
+<%= javascript_pack_tag 'application' %>
+```
+You can probably remove the `<%= javascript_include_tag %>`
+
+### Using sprockets (not webpacker)
+
+If you want to use sprockets rather than webpacker, you must ensure these dependencies are in your Gemfile (done automatically by the install generator):
+
+```
+gem 'bootstrap', '~> 4.0'
+gem 'popper_js'
+gem 'twitter-typeahead-rails', '0.11.1.pre.corejavascript'
+```
+
+Then insure these requires are in `app/assets/javascripts/application.js`  (done automatically by the install generator):
+
+```
+//= require jquery
+//= require popper
+//= require twitter/typeahead
+//= require bootstrap
+```