node package manager

reewr-watchify

Build Status Coverage Status

reewr-watchify

A wrapper around Browserify and Watchify to enable running it along side a server.

Installation

The package has now been pushed to NPM and can therefore be easily installed through the following command:

npm install reewr-watchify

Usage

How to use this module is simple and should be ran once. The module can be extended with plugins and transformers. For more advanced usage, take a look at the documentation below.

let watchify = require('reewr-watchify');
 
watchify({
  items: [{
    entryFile: 'path/to/your/main/browserify/file',
    output   : 'path/to/where/you/want/the/output'
  }];
});

Documentation

## reewr-watchify This module watches over specific "main" client JavaScript files and once any changes are done in any of the files or it's dependency tree, the module will recompile the files into a bundle which can be sent to the client. This module utilizes both watchify and browserify. As it uses watchify, it will cache files, allowing for quicker recompilation on changes.

### module.exports(options) ⏏ This is the function to call to start the whole process of watching one main javascript file. This function supports the following options in an object

options.onlyBundleAtStart=false, setting this option to true will cause the module to only bundle once, as the name implies. This can be useful for production builds.

options.items is an array of bundling items, which all have their own options. each of these starts it own watcher and is bundled by it's own browserify instance

options.items[].entryFile is required and indicates which file is the main file. Any changes to any of it's dependencies will cause the watcher to trigger and rebundle.

options.items[].output is required and indicates where to place the output file, which will be rewritten on any rebundle.

options.items[].baseDirectory=[] is a browserify option, and is the directory that browserify starts bundling from for filenames that start with .

options.items[].extensions=[] is a browserify option, and is an array of optional extra extensions for the module lookup machinery to use when the extension has not been specified. By default browserify considersonly .js and .json files in such cases.

options.items[].detectGlobals=true is a browserify option, and will scan all files for process, global, filename, and dirname, defining as necessary. With this option npm modules are more likely to work but bundling takes longer.

options.items[].skipFiles=[] is a browserify option, and is an array which will skip all require() and global parsing for each file in the array. Use this for giant libs like jquery or threejs that don't have any requires or node-style globals but take forever to parse.

options.items[].paths=[] is a browserify option, and is an array of directories that browserify searches when looking for modules which are not referenced using relative path. Can be absolute or relative to basedir. Equivalent of setting NODE_PATH environmental variable when calling browserify command.

options.items[].debug=false is a browserify option, which adds a source map inline to the end of the bundle. This makes debugging easier because you can see all the original files if you are in a modern enough browser.

options.items[].customHandlers=[] allows for several customer handlers for browserify. These functions are called with the browserify object and can be used to attach different handlers that is called prior to bundling. For instance, using babel with this module can be used as follows:

var watchify = require('reewr-watchify');
// Simple example of how to use it together with babelify 
watchify({
  items: [{
    entryFile: 'myFile.js',
    output   : 'output.js',
    customHandlers: babelify.configure({presets: ["es2015"]})
  }];
});
 
// An example of any other type of handler see browserify docs for more, 
// where through is a module that is included by browserify 
// https://github.com/substack/node-browserify#btransformtr-opts 
var through = require('through');
var myCustomHandler = function(file) {
  var data  = '';
  var write = function(buffer) {data += buffer;};
  var end   = function() {
    this.queue(doSomethingWithSource(data));
    this.queue(null);
  };
  return through(write, end);
};
 
watchify({
  items: {
    entryFile: 'myFile.js',
    output   : 'output.js',
    customHandlers: myCustomHandler
  }
});

options.items[].plugins=[] allows for plugins for browserify. The plugin is expected to be an object of type {name: string, args: arguments} where the plugin is initialized with the following:

b.plugin(plugin.name, plugin.args);

An example of how to use this with factor-bundle is below:

var watchify = require('reewr-watchify');
// Example of usage with plugins 
watchify({
  items: [{
    entryFile: ['private.js', 'public.js'],
    output   : 'common.js',
    plugins  : [{
      name: 'factor-bundle',
      args: {outputs: ['bundle/private.js', 'bundle/public.']}
    }]
  }]
});

Kind: Exported function

Param Type Default Description
options object
options.onlyBundleAtStart boolean false If true, only bundles once. Useful for production
options.items Array(object) Is a list of objects with the below options
options.items[].entryFile string Which file that is the main file, required
options.items[].output string Location and name of the output file, required
options.items[].baseDirectory Array(string) [ Base directory of the source files
options.items[].extensions Array(string) [ Extensions to use outside of js and json
options.items[].detectGlobals boolean true whether to detect global variables
options.items[].skipFiles array(string) [ Skip certain files
options.items[].paths Array(string) [ Where to look for files
options.items[].debug boolean false Whether to turn on debugging or not
options.items[].customHandlers Array(function) [ Allows several custom handlers for browserify
options.items[].plugins Array(object) [ Adds a plugin to browserify
options.items[].plugins[].name string Name of the plugin
options.items[].plugins[].args object Arguments of the plugin

#### module.exports.isSupportedEvent(eventType) ⇒ Boolean Checks if the event is supported. This is case-insensitive.

Kind: static method of module.exports

Param Type Description
eventType string name of the event

#### module.exports.on(event, callback) Lets you attach event listeners to the watchers, will apply to current and future watchers Supports the following events

  • error, called on error with writing the bundle or on errors with bundling
  • info, called when the bundling is finished with time taken and bytes written
  • bundle, called prior to bundling. Includes the bundle object
  • close, called when the watcher is closing. No guarentee that it's close, sorry.

Kind: static method of module.exports Throws:

  • TypeError If event is not of the above four types
Param Type Description
event string type of event, case-insensitive
callback function callback to call

#### module.exports.close() Closes all active watchers. Returns a promise

Kind: static method of module.exports Resolve: null