Grunt task for node-browserify.
This plugin requires Grunt ~0.4.0
.
Install this grunt plugin with:
npm install grunt-browserify --save-dev
Then add this line to your project's grunt.js
Gruntfile:
grunt.loadNpmTasks('grunt-browserify');
Most simply, Browserify is a tool for taking your CommonJS-style Javascript code and packaging it for use in the browser. Grunt-Browserify provides the glue to better integrate Browserify into your Grunt-based development workflow.
For JavaScripters unfamiliar with CJS-style code and the Node ecosystem, moving to Browserify can be a bit confusing. Writing your client-side code as CJS modules allows for smaller, easier to understand files that perform one task well. These modules, because of their simplicity, will be significantly easier to use across projects. CJS modules also help to expose the dependency graph inherent in your code, allowing you to write cleaner, more-maintainable modules. As Alex MacCaw writes:
CommonJS modules are one of the best solutions to JavaScript dependency management.
CommonJS modules solve JavaScript scope issues by making sure each module is executed in its own namespace. Modules have to explicitly export variables they want to expose to other modules, and explicitly import other modules; in other words, there's no global namespace.
(A note to AMD fans that the benefits above are not unique to the CJS style of writing JavaScript modules, but the ease-of-interoperality with Node.JS code is a plus of CJS.)
As you begin to write your client-side code in small, reusable modules, you start to have a lot more files to manage. At the same time, you need to integrate these files with other client-side libraries, some of which do not play particularly nicely with a CJS module system. The simplicity provided by CJS modules can be lost as build complexity is increased and Browserify compilation time gets out of control.
Run this task with the grunt browserify
command. As with other Grunt plugins, the src
and dest
properties are most important: src
will use the Grunt glob pattern to specify files for inclusion in the browserified package, and dest
will specify the outfile for the compiled module.
The current version of grunt-browserify sticks as close to the core browserify API as possible. Additional functionality can be added via the rich ecosystem of browserify transforms and plugins.
The following task options are supported:
Type: [String:String]
Browserify can alias files or modules to a certain name. For example, require(‘./foo’)
can be aliased to be used as require(‘foo’)
. Aliases should be specified as fileName:alias
. Filenames are parsed into their full paths with path.resolve
.
Type: [String]
Specifies files to be required in the browserify bundle. String filenames are parsed into their full paths with path.resolve
.
Type: [String]
Specifies files to be ignored in the browserify bundle. String filenames are parsed into their full paths with path.resolve
.
Type: [String]
Specifies files to be excluded in the browserify bundle. String filenames are parsed into their full paths with path.resolve
.
Type: [String]
or [String:String]
.
Specifies id strings which will be loaded from a previously loaded, “common” bundle. That is to say, files in the bundle that require the target String will assume that the target is provided externally. The secondary form of this option follows the format of alias
above, and will externalise the ids specified in the alias array. This second form allows for the declaration of a single alias array which can be supplied to one bundle's alias
option and another option's external
option.
Type: [String || Function]
or [[String || Function, Object]]
Specifies a pipeline of functions (or modules) through which the browserified bundle will be run. The transform can either be a literal function, or a string referring to a NPM module. The browserify docs themselves explain transform well, but below is an example of transform used with grunt-browserify
to automatically compile coffeescript files for use in a bundle:
browserify: {
dist: {
files: {
'build/module.js': ['client/scripts/**/*.js', 'client/scripts/**/*.coffee'],
},
options: {
transform: ['coffeeify']
}
}
}
Transforms can also be provided with an options hash; in this case, the transform should be specified as an array of [transformStringOrFn, optionsHash]
.
Type: [String || Function]
Register a browserify plugin with the bundle. As with transforms, plugins are identified with either their NPM name (String) or a function literal.
Type: Object A hash of options that are passed to browserify during instantiation.
Type: Object
A hash of options that are passed to browserify. bundle
. If you are interested in generating
source maps, you can pass debug: true
here. Other bundleOptions
can be found on the
Browserify Github README.
Type: Boolean If true, invoke watchify instead of browserify.
Type: Boolean
If true and if watch
above is true, keep the Grunt process alive (simulates grunt-watch functionality).
Type: Function (b)
An optional callback function, that will be called before bundle completion.
b
is the browerify
instance that will output the bundle.
Type: Function (err, src, next)
An optional callback function, which will be called after bundle completion and
before writing of the bundle. The err
and src
arguments are provided
directly from browserify. The next
callback should be called with (err, modifiedSrc)
; the modifiedSrc
is what will be written to the output file.
In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code.
- Initial release
- Properly support compact and full grunt task syntax
- Add support for Browserify 2
- Add externalize option, to expose modules to external bundles
- Add browserify-shim support
- Completely rewrote and significantly improved tests
- Various fixes
- Update externalize to expose npm modules to external bundles
- Really should've been released at v0.2, but better late than never!
- Move away from browserify-stream to callback approach
- Add new aliasMappings functionality
- Adding directory support for
external
parameter
- Bumping to latest Browserify (2.18.x)
- Added support for noParse option
- Change browserify() call to pass files as opts.entries
- Fix regression where shimmed modules not being parsed
Externalize
has been deprecated in favor ofalias
(#69)- Allow
external
to use module names, in addition to file paths (#68). Waiting on Browserify changes for this to actually work. - Much improved docs (#67)
- Allow non-files to be ignored (#50), via @joshuarubin
- Bumping dependency versions
- Change
alias
destination behavior to only treat the destination as a filepath if it exists
- Allow aliasing with arbitrary ids. For example, you could alias
./vendor/client/jquery/jquery.js
to/vendor/jquery
for consumption by other bundles. See the updatedcomplex
andexternals
examples
- Flatten options arrays, to prevent any weird behavior (via @joeybaker)
- Documentation fix (via @alanshaw)
- Allow aliasing inner modules (via @bananushka)
- Fix multitask shim bug (via @byronmwong)
- Move browserify to a peer dependency, to allow custom versions (via @nrn)
- Add support for browserify extension flag (from browserify v2.31)
- Fix bug in sharing shimmed files across bundles (#89)
- Add postBundle callback support (via @Bockit)
- Fix peerDependency version requirements
- Fix #106
- Move to browserify 2.35 for upstream dedupe fix
- Add
preBundleCB
option (via @alexstrat)
- Bump to Browserify v3
- Adding support for Browserify 3.2 paths (via @trevordixon)
- Adding
require
and globaltransform
options.
- Complete rewrite of grunt-browserify internals, and update of the API. (2.0.0 was mis-published to NPM and removed).
Copyright (c) 2013-2014 Justin Reidy Licensed under the MIT license.