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.

• reewr-watchify
  • module.exports(options) ⏏
    • static
      • .isSupportedEvent(eventType) ⇒ Boolean
      • .on(event, callback)
      • .close()

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