browser-side require() the node.js way



require('modules') in the browser

Use a node-stylerequire() to organize your browser code
and load modules installed by npm.

browserify will recursively analyze all the require() calls in your app in
order to build a bundle you can serve up to the browser in a single `` into your


With npm do:

  1. ```
  2. npm install browserify
  3. ```


  1. ```
  2. Usage: browserify [entry files] {OPTIONS}

  3. Standard Options:

  4.     --outfile, -o  Write the browserify bundle to this file.
  5.                    If unspecified, browserify prints to stdout.

  6.     --require, -r  A module name or file to bundle.require()
  7.                    Optionally use a colon separator to set the target.

  8.       --entry, -e  An entry point of your app

  9.      --ignore, -i  Replace a file with an empty stub. Files can be globs.

  10.     --exclude, -u  Omit a file from the output bundle. Files can be globs.

  11.    --external, -x  Reference a file from another bundle. Files can be globs.

  12.   --transform, -t  Use a transform module on top-level files.

  13.     --command, -c  Use a transform command on top-level files.

  14.   --standalone -s  Generate a UMD bundle for the supplied export name.
  15.                    This bundle works with other module systems and sets the name
  16.                    given as a window global if no module system is found.

  17.        --debug -d  Enable source maps that allow you to debug your files
  18.                    separately.

  19.        --help, -h  Show this message

  20. For advanced options, type `browserify --help advanced`.

  21. Specify a parameter.
  22. ```

  1. ```
  2. Advanced Options:

  3.   --insert-globals, --ig, --fast    [default: false]

  4.     Skip detection and always insert definitions for process, global,
  5.     __filename, and __dirname.

  6.     benefit: faster builds
  7.     cost: extra bytes

  8.   --insert-global-vars, --igv

  9.     Comma-separated list of global variables to detect and define.
  10.     Default: __filename,__dirname,process,Buffer,global

  11.   --detect-globals, --dg            [default: true]

  12.     Detect the presence of process, global, __filename, and __dirname and define
  13.     these values when present.

  14.     benefit: npm modules more likely to work
  15.     cost: slower builds

  16.   --ignore-missing, --im            [default: false]

  17.     Ignore `require()` statements that don't resolve to anything.

  18.   --noparse=FILE

  19.     Don't parse FILE at all. This will make bundling much, much faster for giant
  20.     libs like jquery or threejs.

  21.   --no-builtins

  22.     Turn off builtins. This is handy when you want to run a bundle in node which
  23.     provides the core builtins.

  24.   --no-commondir

  25.     Turn off setting a commondir. This is useful if you want to preserve the
  26.     original paths that a bundle was generated with.

  27.   --no-bundle-external

  28.     Turn off bundling of all external modules. This is useful if you only want
  29.     to bundle your local files.

  30.   --bare

  31.     Alias for both --no-builtins, --no-commondir, and sets --insert-global-vars
  32.     to just "__filename,__dirname". This is handy if you want to run bundles in
  33.     node.

  34.   --no-browser-field, --no-bf

  35.     Turn off package.json browser field resolution. This is also handy if you
  36.     need to run a bundle in node.

  37.   --transform-key

  38.     Instead of the default package.json#browserify#transform field to list
  39.     all transforms to apply when running browserify, a custom field, like, e.g.
  40.     package.json#browserify#production or package.json#browserify#staging
  41.     can be used, by for example running:
  42.     * `browserify index.js --transform-key=production > bundle.js`
  43.     * `browserify index.js --transform-key=staging > bundle.js`

  44.   --node

  45.     Alias for --bare and --no-browser-field.

  46.   --full-paths

  47.     Turn off converting module ids into numerical indexes. This is useful for
  48.     preserving the original paths that a bundle was generated with.

  49.   --deps

  50.     Instead of standard bundle output, print the dependency array generated by
  51.     module-deps.

  52.   --no-dedupe

  53.     Turn off deduping.

  54.   --list

  55.     Print each file in the dependency graph. Useful for makefiles.

  56.   --extension=EXTENSION

  57.     Consider files with specified EXTENSION as modules, this option can used
  58.     multiple times.

  59.   --global-transform=MODULE, -g MODULE

  60.     Use a transform module on all files after any ordinary transforms have run.

  61.   --ignore-transform=MODULE, -it MODULE

  62.     Do not run certain transformations, even if specified elsewhere.

  63.   --plugin=MODULE, -p MODULE

  64.     Register MODULE as a plugin.

  65. Passing arguments to transforms and plugins:

  66.   For -t, -g, and -p, you may use subarg syntax to pass options to the
  67.   transforms or plugin function as the second parameter. For example:

  68.     -t [ foo -x 3 --beep ]

  69.   will call the `foo` transform for each applicable file by calling:

  70.     foo(file, { x: 3, beep: true })

  71. ```


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

Many node built-in modules have been wrapped to work in the browser, but only
when you explicitly require() or use their functionality.

When you require() any of these modules, you will get a browser-specific shim:

Additionally, if you use any of these variables, they
in the bundled output in a browser-appropriate way:

global - top-level scope object (window)
__filename - file path of the currently executing file
__dirname - directory path of the currently executing file

more examples

external requires

You can just as easily create a bundle that will export a require() function so
you can require() modules from another script tag. Here we'll create a
bundle.js with the through
and duplexer modules.

  1. ```
  2. $ browserify -r through -r duplexer -r ./my-file.js:my-module > bundle.js
  3. ```

Then in your page you can do:

  1. ``` html
  2. <script src="bundle.js"></script>
  3. <script>
  4.   var through = require('through');
  5.   var duplexer = require('duplexer');
  6.   var myModule = require('my-module');
  7.   /* ... */
  8. </script>
  9. ```

external source maps

If you prefer the source maps be saved to a separate source map file, you may use
exorcist in order to achieve that. It's as simple as:

  1. ```
  2. $ browserify main.js --debug | exorcist > bundle.js
  3. ```

Learn about additional options here.

multiple bundles

If browserify finds a required function already defined in the page scope, it
will fall back to that function if it didn't find any matches in its own set of
bundled modules.

In this way, you can use browserify to split up bundles among multiple pages to
get the benefit of caching for shared, infrequently-changing modules, while
still being able to use require(). Just use a combination of --external and
--require to factor out common dependencies.

For example, if a website with 2 pages, beep.js:

  1. ``` js
  2. var robot = require('./robot.js');
  3. console.log(robot('beep'));
  4. ```

and boop.js:

  1. ``` js
  2. var robot = require('./robot.js');
  3. console.log(robot('boop'));
  4. ```

both depend on robot.js:

  1. ``` js
  2. module.exports = function (s) { return s.toUpperCase() + '!' };
  3. ```

  1. ```
  2. $ browserify -r ./robot.js > static/common.js
  3. $ browserify -x ./robot.js beep.js > static/beep.js
  4. $ browserify -x ./robot.js boop.js > static/boop.js
  5. ```

Then on the beep page you can have:

  1. ``` html
  2. <script src="common.js"></script>
  3. <script src="beep.js"></script>
  4. ```

while the boop page can have:

  1. ``` html
  2. <script src="common.js"></script>
  3. <script src="boop.js"></script>
  4. ```

This approach using -r and -x works fine for a small number of split assets,
but there are plugins for automatically factoring out components which are
described in the

api example

You can use the API directly too:

  1. ``` js
  2. var browserify = require('browserify');
  3. var b = browserify();
  4. b.add('./browser/main.js');
  5. b.bundle().pipe(process.stdout);
  6. ```


  1. ``` js
  2. var browserify = require('browserify')
  3. ```

browserify([files] [, opts])

Returns a new browserify instance.

String, file object, or array of those types (they may be mixed) specifying entry file(s).

files and opts are both optional, but must be in the order shown if both are

Entry files may be passed in files and / or opts.entries.

External requires may be specified in opts.require, accepting the same formats
that the files argument does.

If an entry file is a stream, its contents will be used. You should pass
opts.basedir when using streaming files so that relative requires can be

opts.entries has the same definition as files.

opts.noParse 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.

opts.transform is an array of transform functions or modules names which will
transform the source code before the parsing.

opts.ignoreTransform is an array of transformations that will not be run,
even if specified elsewhere.

opts.plugin is an array of plugin functions or module names to use. See the
plugins section below for details.

opts.extensions is an array of optional extra extensions for the module lookup
machinery to use when the extension has not been specified.
By default browserify considers only .js and .json files in such cases.

opts.basedir is the directory that browserify starts bundling from for
filenames that start with ..

opts.paths 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.

opts.commondir sets the algorithm used to parse out the common paths. Use
false to turn this off, otherwise it uses the
commondir module.

opts.fullPaths disables converting module ids into numerical indexes. This is
useful for preserving the original paths that a bundle was generated with.

opts.builtins sets the list of built-ins to use, which by default is set in
lib/builtins.js in this distribution.

opts.bundleExternal boolean option to set if external modules should be
bundled. Defaults to true.

When opts.browserField is false, the package.json browser field will be
ignored. When opts.browserField is set to a string, then a custom field name
can be used instead of the default "browser" field.

When opts.insertGlobals is true, always insert process, global,
__filename, and __dirname without analyzing the AST for faster builds but
larger output bundles. Default false.

When opts.detectGlobals is true, 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. Default true.

When opts.ignoreMissing is true, ignore require() statements that don't
resolve to anything.

When opts.debug is true, add 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.

When opts.standalone is a non-empty string, a standalone module is created
with that name and a umd wrapper.
You can use namespaces in the standalone global export using a . in the string
name as a separator, for example 'A.B.C'. The global export will be [sanitized
and camel cased](

Note that in standalone mode the require() calls from the original source will
still be around, which may trip up AMD loaders scanning for require() calls.
You can remove these calls with

  1. ```
  2. $ npm install derequire
  3. $ browserify main.js --standalone Foo | derequire > bundle.js
  4. ```

opts.insertGlobalVars will be passed to
as the opts.vars parameter.

opts.externalRequireName defaults to 'require' in expose mode but you can
use another name.

opts.bare creates a bundle that does not include Node builtins, and does not
replace global Node variables except for __dirname and __filename.

opts.node creates a bundle that runs in Node and does not use the browser
versions of dependencies. Same as passing { bare: true, browserField: false }.

Note that if files do not contain javascript source code then you also need to
specify a corresponding transform for them.

All other options are forwarded along to
and browser-pack directly.

b.add(file, opts)

Add an entry file from file that will be executed when the bundle loads.

If file is an array, each item in file will be added as an entry file.

b.require(file, opts)

Make file available from outside the bundle with require(file).

The file param is anything that can be resolved by require.resolve(),
including files from node_modules. Like with require.resolve(), you must
prefix file with ./ to require a local file (not in node_modules).

file can also be a stream, but you should also use opts.basedir so that
relative requires will be resolvable.

If file is an array, each item in file will be required.
In file array form, you can use a string or object for each item. Object items
should have a file property and the rest of the parameters will be used for
the opts.

Use the expose property of opts to specify a custom dependency name.
require('./vendor/angular/angular.js', {expose: 'angular'}) enables require('angular')


Bundle the files and their dependencies into a single javascript file.

Return a readable stream with the javascript file contents or
optionally specify a cb(err, buf) to get the buffered results.


Prevent file from being loaded into the current bundle, instead referencing
from another bundle.

If file is an array, each item in file will be externalized.

If file is another bundle, that bundle's contents will be read and excluded
from the current bundle as the bundle in file gets bundled.


Prevent the module name or file at file from showing up in the output bundle.

If file is an array, each item in file will be ignored.

Instead you will get a file with module.exports = {}.


Prevent the module name or file at file from showing up in the output bundle.

If file is an array, each item in file will be excluded.

If your code tries to require() that file it will throw unless you've provided
another mechanism for loading it.

b.transform(tr, opts={})

Transform source code before parsing it for require() calls with the transform
function or module name tr.

If tr is a function, it will be called with tr(file) and it should return a
that takes the raw file contents and produces the transformed source.

If tr is a string, it should be a module name or file path of a
with a signature of:

  1. ``` js
  2. var through = require('through');
  3. module.exports = function (file) { return through() };
  4. ```

You don't need to necessarily use the
through module.
Browserify is compatible with the newer, more verbose
built into Node v0.10.

Here's how you might compile coffee script on the fly using .transform():

  1. ``` js
  2. var coffee = require('coffee-script');
  3. var through = require('through');

  4. b.transform(function (file) {
  5.     var data = '';
  6.     return through(write, end);

  7.     function write (buf) { data += buf }
  8.     function end () {
  9.         this.queue(coffee.compile(data));
  10.         this.queue(null);
  11.     }
  12. });
  13. ```

Note that on the command-line with the -c flag you can just do:

  1. ```
  2. $ browserify -c 'coffee -sc' > bundle.js
  3. ```

Or better still, use the coffeeify

  1. ```
  2. $ npm install coffeeify
  3. $ browserify -t coffeeify > bundle.js
  4. ```

If is true, the transform will operate on ALL files, despite
whether they exist up a level in a node_modules/ directory. Use global
transforms cautiously and sparingly, since most of the time an ordinary
transform will suffice. You can also not configure global transforms in a
package.json like you can with ordinary transforms.

Global transforms always run after any ordinary transforms have run.

Transforms may obtain options from the command-line with
subarg syntax:

  1. ```
  2. $ browserify -t [ foo --bar=555 ] main.js
  3. ```

or from the api:

  1. ```
  2. b.transform('foo', { bar: 555 })
  3. ```

In both cases, these options are provided as the second argument to the
transform function:

  1. ```
  2. module.exports = function (file, opts) { /* === 555 */ }
  3. ```

Options sent to the browserify constructor are also provided under
opts._flags. These browserify options are sometimes required if your transform
needs to do something different when browserify is run in debug mode, for

b.plugin(plugin, opts)

Register a plugin with opts. Plugins can be a string module name or a
function the same as transforms.

plugin(b, opts) is called with the browserify instance b.

For more information, consult the plugins section below.


There is an internal
pipeline with these labels:

'record' - save inputs to play back later on subsequent bundle() calls
'deps' - module-deps
'json' - adds module.exports= to the beginning of json files
'unbom' - remove byte-order markers
'unshebang' - remove #! labels on the first line
'syntax' - check for syntax errors
'sort' - sort the dependencies for deterministic bundles
'dedupe' - remove duplicate source contents
'label' - apply integer labels to files
'emit-deps' - emit 'dep' event
'debug' - apply source maps
'pack' - browser-pack
'wrap' - apply final wrapping, require= and a newline and semicolon

You can call b.pipeline.get() with a label name to get a handle on a stream pipeline
that you can push(), unshift(), or splice() to insert your own transform


Reset the pipeline back to a normal state. This function is called automatically
when bundle() is called multiple times.

This function triggers a 'reset' event.


browserify uses the package.json in its module resolution algorithm, just like
node. If there is a "main" field, browserify will start resolving the package
at that point. If there is no "main" field, browserify will look for an
"index.js" file in the module root directory. Here are some more
sophisticated things you can do in the package.json:

browser field

There is a special "browser" field you can
set in your package.json on a per-module basis to override file resolution for
browser-specific versions of files.

For example, if you want to have a browser-specific module entry point for your
"main" field you can just set the "browser" field to a string:

  1. ``` json
  2. "browser": "./browser.js"
  3. ```

or you can have overrides on a per-file basis:

  1. ``` json
  2. "browser": {
  3.   "fs": "level-fs",
  4.   "./lib/ops.js": "./browser/opts.js"
  5. }
  6. ```

Note that the browser field only applies to files in the local module, and like
transforms, it doesn't apply into node_modules directories.


You can specify source transforms in the package.json in the
browserify.transform field. There is more information about how source
transforms work in package.json on the

For example, if your module requires brfs, you
can add

  1. ``` json
  2. "browserify": { "transform": [ "brfs" ] }
  3. ```

to your package.json. Now when somebody require()s your module, brfs will
automatically be applied to the files in your module without explicit
intervention by the person using your module. Make sure to add transforms to
your package.json dependencies field.


b.on('file', function (file, id, parent) {})

b.pipeline.on('file', function (file, id, parent) {})

When a file is resolved for the bundle, the bundle emits a 'file' event with
the full file path, the id string passed to require(), and the parent
object used by

You could use the file event to implement a file watcher to regenerate bundles
when files change.

b.on('package', function (pkg) {})

b.pipeline.on('package', function (pkg) {})

When a package file is read, this event fires with the contents. The package
directory is available at pkg.__dirname.

b.on('bundle', function (bundle) {})

When .bundle() is called, this event fires with the bundle output stream.

b.on('reset', function () {})

When the .reset() method is called or implicitly called by another call to
.bundle(), this event fires.

b.on('transform', function (tr, file) {})

b.pipeline.on('transform', function (tr, file) {})

When a transform is applied to a file, the 'transform' event fires on the
bundle stream with the transform stream tr and the file that the transform
is being applied to.


For some more advanced use-cases, a transform is not sufficiently extensible.
Plugins are modules that take the bundle instance as their first parameter and
an option hash as their second.

Plugins can be used to do perform some fancy features that transforms can't do.
For example, factor-bundle is a
plugin that can factor out common dependencies from multiple entry-points into a
common bundle. Use plugins with -p and pass options to plugins with
subarg syntax:

  1. ```
  2. browserify x.js y.js -p [ factor-bundle -o bundle/x.js -o bundle/y.js ] \
  3.   > bundle/common.js
  4. ```

For a list of plugins, consult the
on npm.

list of source transforms

There is a [wiki page that lists the known browserify

If you write a transform, make sure to add your transform to that wiki page and
add a package.json keyword of browserify-transform so that
[people can browse for all the browserify
transforms]( on

third-party tools

There is a [wiki page that lists the known browserify

If you write a tool, make sure to add it to that wiki page and
add a package.json keyword of browserify-tool so that
[people can browse for all the browserify
tools]( on


Releases are documented in