Proposal for the new Bokeh.js build process

1. Folder Structure

├── **build**/
│ ├── css/ *Compiled LESS stylesheets (Optional, you may use regular CSS for demo pages)*
│ ├── js/ *Compiled coffee-script files*
│ └── vendor/ *Third-party libs like jQuery, Bootstrap, Requirejs, etc.*
├── **release**/ *Compiled unminified and minified bokeh.js libraries*

├── **demo**/ *Static HTML files with Bokeh.js examples*
├── **docs**/ *Documentation files*
└── **src**    /
├── coffee/ *Source files*
    ├── less/ *LESS stylesheets*

├── **test**/ *Jasmine or Mocha.js + Chai.js specs*

├── .gitignore

├── .travis.yml Tavis-CI continuous integration

├── .jshintrc JS Hint style enforcement

├── .bowerrc Tells Bower where to install 3rd-party libs (if not present defaults to components/ folder)

├── bower.json Specify which packages you would like to install



├── Build tool for compilation, minification of LESS/Coffee files + watch mode


├── package.json Node.js packages: r.js (requirejs optimizer), grunt, grunt plugins and bower


**2. Grunt**
This is a build tool that you use to compile your LESS and Coffeescript files. It comes with a lot of plugins such as grunt-contrib-copy for copying, moving, and grunt-contrib-cleanup for deleting folders that you no longer need after the build process. For example after generating production-ready minified javascript file you may want to remove vendor folder or perform other cleanup tasks. Grunt can also execute arbitrary Bash shell commands via a plugin **Grunt-Shell**.

To watch for changes you simply run **grunt watch.** You will need grunt-contrib-watch plugin and create your own Grunt task to specify which folders you would like to watch. See this github repo as an example: [](

**3. Bower**

This step is completely optional. Bower is a package manager like npm and pip, but for front-end libraries like Angular.js, Backbone, Bootstrap, jQuery, and many others.

If you don't want to use Bower you can simply place vendor dependencies inside the github repo for Bokeh.js.

**4. Require.js **

This is probably the biggest change of them all. Require.js allows you to write modular javascript using the AMD pattern. It might seem strange at first (my initial reaction was WTF!?, but once you understand it require.js is quite amazing).

If you would like to see full example of Backbone + Require.js check out TodoMVC repo: [](

The idea is to have an entry-point file main.js (or before **grunt build**) that sets up require.js, this is where you want to include library dependencies: jquery, backbone, underscore and others. And then you call it via index.html via:

**<script data-main="js/main.js" src="js/require.js"></script>**

I have modified Gruntfile to also include require.js inside main.js, so when you generate **main.js** or **bokeh.min.js** you can simply call it via  **<script src="js/bokeh.min.js"></script>** and require.js will be included inside, it's only extra 16kb. There is an alternative called almond.js which only adds an extra 1kb, but I haven't figured out how to use it.

Rather than explaining in details how require.js works, I recommend watching this 15min video tutorial. I knew absolutely nothing about the require.js prior to watching this video. I think it's very informative and very easy to understand: [](