browserify-handbook

by browserify

how to build modular applications with browserify

4.4K Stars 328 Forks Last release: Not found Other 177 Commits 10 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

introduction

This document covers how to use browserify to build modular applications.

cc-by-3.0

browserify is a tool for compiling node-flavored commonjs modules for the browser.

You can use browserify to organize your code and use third-party libraries even if you don't use node itself in any other capacity except for bundling and installing packages with npm.

The module system that browserify uses is the same as node, so packages published to npm that were originally intended for use in node but not browsers will work just fine in the browser too.

Increasingly, people are publishing modules to npm which are intentionally designed to work in both node and in the browser using browserify and many packages on npm are intended for use in just the browser. npm is for all javascript, front or backend alike.

table of contents

node packaged manuscript

You can install this handbook with npm, appropriately enough. Just do:

npm install -g browserify-handbook

Now you will have a

browserify-handbook
command that will open this readme file in your
$PAGER
. Otherwise, you may continue reading this document as you are presently doing.

node packaged modules

Before we can dive too deeply into how to use browserify and how it works, it is important to first understand how the node-flavored version of the commonjs module system works.

require

In node, there is a

require()
function for loading code from other files.

If you install a module with npm:

npm install uniq

Then in a file

nums.js
we can
require('uniq')
:
var uniq = require('uniq');
var nums = [ 5, 2, 1, 3, 2, 5, 4, 2, 0, 1 ];
console.log(uniq(nums));

The output of this program when run with node is:

$ node nums.js
[ 0, 1, 2, 3, 4, 5 ]

You can require relative files by requiring a string that starts with a

.
. For example, to load a file
foo.js
from
main.js
, in
main.js
you can do:
var foo = require('./foo.js');
console.log(foo(4));

If

foo.js
was in the parent directory, you could use
../foo.js
instead:
var foo = require('../foo.js');
console.log(foo(4));

or likewise for any other kind of relative path. Relative paths are always resolved with respect to the invoking file's location.

Note that

require()
returned a function and we assigned that return value to a variable called
uniq
. We could have picked any other name and it would have worked the same.
require()
returns the exports of the module name that you specify.

How

require()
works is unlike many other module systems where imports are akin to statements that expose themselves as globals or file-local lexicals with names declared in the module itself outside of your control. Under the node style of code import with
require()
, someone reading your program can easily tell where each piece of functionality came from. This approach scales much better as the number of modules in an application grows.

exports

To export a single thing from a file so that other files may import it, assign over the value at

module.exports
:
module.exports = function (n) {
    return n * 111
};

Now when some module

main.js
loads your
foo.js
, the return value of
require('./foo.js')
will be the exported function:
var foo = require('./foo.js');
console.log(foo(5));

This program will print:

555

You can export any kind of value with

module.exports
, not just functions.

For example, this is perfectly fine:

module.exports = 555

and so is this:

var numbers = [];
for (var i = 0; i < 100; i++) numbers.push(i);

module.exports = numbers;

There is another form of doing exports specifically for exporting items onto an object. Here,

exports
is used instead of
module.exports
:
exports.beep = function (n) { return n * 1000 }
exports.boop = 555

This program is the same as:

module.exports.beep = function (n) { return n * 1000 }
module.exports.boop = 555

because

module.exports
is the same as
exports
and is initially set to an empty object.

Note however that you can't do:

// this doesn't work
exports = function (n) { return n * 1000 }

because the export value lives on the

module
object, and so assigning a new value for
exports
instead of
module.exports
masks the original reference.

Instead if you are going to export a single item, always do:

// instead
module.exports = function (n) { return n * 1000 }

If you're still confused, try to understand how modules work in the background:

var module = {
  exports: {}
};

// If you require a module, it's basically wrapped in a function (function(module, exports) { exports = function (n) { return n * 1000 }; }(module, module.exports))

console.log(module.exports); // it's still an empty object :(

Most of the time, you will want to export a single function or constructor with

module.exports
because it's usually best for a module to do one thing.

The

exports
feature was originally the primary way of exporting functionality and
module.exports
was an afterthought, but
module.exports
proved to be much more useful in practice at being more direct, clear, and avoiding duplication.

In the early days, this style used to be much more common:

foo.js:

exports.foo = function (n) { return n * 111 }

main.js:

var foo = require('./foo.js');
console.log(foo.foo(5));

but note that the

foo.foo
is a bit superfluous. Using
module.exports
it becomes more clear:

foo.js:

module.exports = function (n) { return n * 111 }

main.js:

var foo = require('./foo.js');
console.log(foo(5));

bundling for the browser

To run a module in node, you've got to start from somewhere.

In node you pass a file to the

node
command to run a file:
$ node robot.js
beep boop

In browserify, you do this same thing, but instead of running the file, you generate a stream of concatenated javascript files on stdout that you can write to a file with the

>
operator:
$ browserify robot.js > bundle.js

Now

bundle.js
contains all the javascript that
robot.js
needs to work. Just plop it into a single script tag in some html:
<script src="bundle.js"></script>

Bonus: if you put your script tag right before the

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.