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,43 @@ 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
+Blacklight ships with Javascript that can be compiled either by webpacker or by
+sprockets. To use Webpacker see the directions at https://github.com/projectblacklight/blacklight/wiki/Using-Webpacker-to-compile-javascript-assets
+
+
+### Using sprockets (not Webpacker)
+
+If you want to use sprockets rather than Webpacker, you must ensure these
+dependencies are in your Gemfile. The Blacklight install generator does this for
+you:
+
+```
+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
+```