Skip to content

Latest commit

 

History

History
173 lines (129 loc) · 5.35 KB

README.markdown

File metadata and controls

173 lines (129 loc) · 5.35 KB
Raw

browserify

Make node-style require() work in the browser with a server-side build step, as if by magic!

build status

browserify!

example

Just write an entry.js to start with some require()s in it:

// use relative requires
var foo = require('./foo');
var bar = require('../lib/bar');

// or use modules installed by npm in node_modules/
var domready = require('domready');

domready(function () {
    var elem = document.getElementById('result');
    elem.textContent = foo(100) + bar('baz');
});

Now just use the browserify command to build a bundle starting at entry.js:

$ browserify entry.js -o bundle.js

All of the modules that entry.js needs are included in the final bundle from a recursive walk using detective.

To use the bundle, just toss a <script src="bundle.js"></script> into your html!

usage

Usage: browserify [entry files] {OPTIONS}

Options:
  --outfile, -o  Write the browserify bundle to this file.
                 If unspecified, browserify prints to stdout.                   
  --require, -r  A module name or file to bundle.require()
                 Optionally use a colon separator to set the target.            
  --entry, -e    An entry point of your app                                     
  --exports      Export these core objects, comma-separated list
                 with any of: require, process. If unspecified, the
                 export behavior will be inferred.
                                                                                
  --ignore, -i   Ignore a file                                                  
  --alias, -a    Register an alias with a colon separator: "to:from"
                 Example: --alias 'jquery:jquery-browserify'                    
  --cache, -c    Turn on caching at $HOME/.config/browserling/cache.json or use
                 a file for caching.
                                                                 [default: true]
  --debug, -d    Switch on debugging mode with //@ sourceURL=...s.     [boolean]
  --plugin, -p   Use a plugin.
                 Example: --plugin aliasify                                     
  --prelude      Include the code that defines require() in this bundle.
                                                      [boolean]  [default: true]
  --watch, -w    Watch for changes. The script will stay open and write updates
                 to the output every time any of the bundled files change.
                 This option only works in tandem with -o.                      
  --verbose, -v  Write out how many bytes were written in -o mode. This is
                 especially useful with --watch.                                
  --help, -h     Show this message

compatibility

Many npm modules that don't do IO will just work after being browserified. Others take more work.

coffee script should pretty much just work. Just do browserify entry.coffee or require('./foo.coffee').

Many node built-in modules have been wrapped to work in the browser. All you need to do is require() them like in node.

  • events
  • path
  • vm
  • http
  • crypto
  • assert
  • url
  • buffer
  • buffer_ieee754
  • util
  • querystring
  • stream

process

Browserify makes available a faux process object to modules with these attributes:

  • nextTick(fn) - uses the postMessage trick for a faster setTimeout(fn, 0) if it can
  • title - set to 'browser' for browser code, 'node' in regular node code
  • browser - true, good for testing if you're in a browser or in node

By default the process object is only available inside of files wrapped by browserify. To expose it, use --exports=process

__dirname

The faux directory name, scrubbed of true directory information so as not to expose your filesystem organization.

__filename

The faux file path, scrubbed of true path information so as not to expose your filesystem organization.

package.json

In order to resolve main files for projects, the package.json "main" field is read.

If a package.json has a "browserify" field, you can override the standard "main" behavior with something special just for browsers.

See dnode's package.json for an example of using the "browserify" field.

more

install

With npm do:

npm install -g browserify

test

To run the node tests with tap, do:

npm test

To run the testling tests, create a browserling account then:

cd testling
./test.sh