Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/browserify/browserify-handbook

how to build modular applications with browserify
https://github.com/browserify/browserify-handbook

Last synced: 6 days ago
JSON representation

how to build modular applications with browserify

Awesome Lists containing this project

README 

        
# introduction



This document covers how to use [browserify](http://browserify.org) to build

modular applications.



[![cc-by-3.0](http://i.creativecommons.org/l/by/3.0/80x15.png)](http://creativecommons.org/licenses/by/3.0/)



browserify is a tool for compiling

[node-flavored](http://nodejs.org/docs/latest/api/modules.html) 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](http://nodejs.org) 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](https://npmjs.org) 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](http://maxogden.com/node-packaged-modules.html),

front or backend alike.



# table of contents



- [introduction](#introduction)

- [table of contents](#table-of-contents)

- [node packaged manuscript](#node-packaged-manuscript)

- [node packaged modules](#node-packaged-modules)

  - [require](#require)

  - [exports](#exports)

  - [bundling for the browser](#bundling-for-the-browser)

  - [how browserify works](#how-browserify-works)

  - [how node_modules works](#how-node_modules-works)

  - [why concatenate](#why-concatenate)

- [development](#development)

  - [source maps](#source-maps)

    - [exorcist](#exorcist)

  - [auto-recompile](#auto-recompile)

    - [watchify](#watchify)

    - [beefy](#beefy)

    - [wzrd](#wzrd)

    - [browserify-middleware, enchilada](#browserify-middleware-enchilada)

    - [livereactload](#livereactload)

    - [browserify-hmr](#browserify-hmr)

    - [budo](#budo)

  - [using the api directly](#using-the-api-directly)

  - [grunt](#grunt)

  - [gulp](#gulp)

- [builtins](#builtins)

  - [Buffer](#Buffer)

  - [process](#process)

  - [global](#global)

  - [__filename](#__filename)

  - [__dirname](#__dirname)

- [transforms](#transforms)

  - [writing your own](#writing-your-own)

- [package.json](#packagejson)

  - [browser field](#browser-field)

  - [browserify.transform field](#browserifytransform-field)

- [finding good modules](#finding-good-modules)

  - [module philosophy](#module-philosophy)

- [organizing modules](#organizing-modules)

  - [avoiding ../../../../../../..](#avoiding-)

  - [non-javascript assets](#non-javascript-assets)

  - [reusable components](#reusable-components)

- [testing in node and the browser](#testing-in-node-and-the-browser)

  - [testing libraries](#testing-libraries)

  - [code coverage](#code-coverage)

  - [testling-ci](#testling-ci)

- [bundling](#bundling)

  - [saving bytes](#saving-bytes)

  - [tinyify](#tinyify)

  - [standalone](#standalone)

  - [external bundles](#external-bundles)

  - [ignoring and excluding](#ignoring-and-excluding)

  - [browserify cdn](#browserify-cdn)

- [shimming](#shimming)

  - [browserify-shim](#browserify-shim)

- [partitioning](#partitioning)

  - [factor-bundle](#factor-bundle)

  - [partition-bundle](#partition-bundle)

- [compiler pipeline](#compiler-pipeline)

  - [build your own browserify](#build-your-own-browserify)

  - [labeled phases](#labeled-phases)

    - [deps](#deps)

    - [json](#json)

    - [unbom](#unbom)

    - [syntax](#syntax)

    - [sort](#sort)

    - [dedupe](#dedupe)

    - [label](#label)

    - [emit-deps](#emit-deps)

    - [debug](#debug)

    - [pack](#pack)

    - [wrap](#wrap)

  - [browser-unpack](#browser-unpack)

- [plugins](#plugins)

  - [using plugins](#using-plugins)

  - [authoring plugins](#authoring-plugins)



# 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](http://nodejs.org/docs/latest/api/modules.html)

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](https://npmjs.org):



```

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:



``` js

var foo = require('./foo.js');

console.log(foo(4));

```



If `foo.js` was in the parent directory, you could use `../foo.js` instead:



``` js

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`:



``` js

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:



``` js

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:



``` js

module.exports = 555

```



and so is this:



``` js

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`:



``` js

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

exports.boop = 555

```



This program is the same as:



``` js

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:



``` js

// 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:



``` js

// instead

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

```



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

the background:



``` js

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:



``` js

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

```



main.js:



``` 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:



``` js

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

```



main.js:



``` 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:



``` html



  

    

  



```



Bonus: if you put your script tag right before the `