grunt-bundles
v0.2.2grunt-bundles
Finer control over the browserify and neat aliasing of multiple dependent bundles
Why?
Browserify is an amazing tool and it gives you all the features you need to manage a large project which may be broken up
into several sharable components. In fact, there are a bunch
of great
articles and
tutorials that show you how to do it. When you have a few files
it's pretty cool, but when you have a large library of modules managing the external
definitions is a real hassle and
not very scalable. Consider this:
/authorization
/ui-lib
/controls
/transitions
/validation
/widgets
/communications
/app
/home
/contacts
/news
/reporting
Now, let's assume that each of those folders contain at least 4 files each. Now, your goal is to create a re-usable
library for authorization
, another for ui-lib
and one more for communications
. app
is your application and each of
its child folders will also be compiled into seperate bundles which may take advantage of any of the top level libraries.
Let's say that contacts
and news
take advantage of authorization
and ui-lib
. Recall that each library contains
multiple modules.
So, from contacts, we'd have to report each module from authorization
and ui-lib
as externals and with each
new modules, we'd have to update the externals. But in the event that have taken advantage of the alias capabilities of the modules, then you have a real problem, because externals
don't know what the aliases were when you defined it.
Those are the problems that grunt-bundles
are intended to solve.
tl;dr
bundles : {
authorization : {
dest : "bundles/authorization.js",
publish : { // publish modules can be called by other modules using `require`
src : ["src/authorization/**/*.js"]
} ,
aliases : [ // aliases make the modules available under a different path
{ // in this case `src/authorization/foo` modules will be published
cwd : "src/authorization", // as just `authorization/foo`
src : ["**/*.js"],
dest : "authorization" // when using `cwd`, `dest` usually means output, but in this case
// it is the name that will be used for the alias
}
]
},
"ui-lib" : {
depends : ["authorization"], // by declaring `authorization` as a dependency, it means that
dest : "bundles/ui-lib.js", // any references to `src/authorization` will be replaced by
publish : { // authorization's alias.
src : ["src/ui-lib/**/*.js"]
},
aliases : [
{
cwd : "src/ui-lib",
src : ["**/*.js"],
dest : "ui" // `ui` will be how we call modules in this bundle
}
]
},
app : {
depends : ["authorization", "ui-lib"],
dest : "bundles/app.js",
exec : { // `exec` means that whatever files are here will be executed when the
src : ["src/app/main.js"] // bundle loads
}
}
}
Getting Started
This plugin requires Grunt ~0.4.5
If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:
npm install grunt-bundles --save-dev
Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:
grunt.loadNpmTasks('grunt-bundles');
The "bundles" task
In your project's Gruntfile, add a section named bundles
to the data object passed into grunt.initConfig()
.
grunt.initConfig({
bundles: {
options: {
// Task-specific options go here.
},
your_target: {
// Target-specific file lists and/or options go here.
},
},
});
task definition
depends
Type: [string]
An array of subtasks to be used to resolve external alias names.
aliases
aliases : [
{
cwd : "fixtures",
src : ["lib2*.js"],
dest : "lib2"
}
]
Type: [object]
aliases.src
Type: [string]
An array of paths to be aliased
aliases.cwd
Type: string
A directory name that will be used to locate the files and used to identify the alias
aliases.dest
Type: string
The name that will be used when the module is published. It is used to replace the value of aliases.cwd
exec
exec:{
src:["foo/bar.js", "pond/**.*.js"]
}
Type: object
The modules that you want to execute when the bundle is loaded
exec.src
Type: [string]
An array of paths to be executed when loaded
externals
externals:{
src:["foo/bar.js", "williams/**.*.js"]
}
Type: object
Generally grunt-bundles
should work out the externals stuff for you,
but you may want to declare some stuff on your own
externals.src
Type: [string]
An array of paths to be marked external
ignore
ignore:{
src:["foo/bar.js", "vastra/**.*.js"]
}
Type: object
These modules will be ignored by browserify
ignore.src
Type: [string]
An array of paths to be ignored
modules
ignore:{
src:["foo/bar.js", "soufle/**.*.js"]
}
Type: object
Generally you depend on browserify to work out what belongs in your bundles
by traversing the require tree. But there are times when you just want to
tell it to use this file right here. And so we have modules
modules.src
Type: [string]
An array of paths to be included
noParse
publish:{
src:["foo/bar.js", "tardis/**.*.js"]
}
Type: object
These modules will not be parsed by browserify at all
noParse.src
Type: [string]
An array of paths that will not be parsed
publish
publish:{
src:["foo/bar.js", "strax/**.*.js"]
}
Type: object
These modules will be made available to other modules via require
publish.src
Type: [string]
An array of paths to be published
Options
These options are all passed through to browserify:
// When true, aliases are are resolved against dependencies and formatted so that they can compile
resolveAliases : true,
// When insertGlobals is true, always insert process, global, __filename, and __dirname without
// analyzing the AST for faster builds but larger output bundles. Default false.
insertGlobals : false,
// When 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.
detectGlobals : true,
// When 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.
debug : false,
// When 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'
standalone : null,
// Creates global variables in the bundle
insertGlobalVars : null,
// When true all `depends` entries are automatically made external
autoExternals : true,
// When true creates an envelope listing all kinds of useless information to the log,
envelope : false,
// 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.
extensions : null,
// is the directory that browserify starts bundling from for filenames that start with ..,
basedir : ".",
//sets the algorithm used to parse out the common paths. Use false to turn this off,
// otherwise it uses the commondir module.
commondir : null,
// disables converting module ids into numerical indexes. This is useful for preserving the
// original paths that a bundle was generated with.
fullPaths : false,
// sets the list of builtins to use, which by default is set in lib/builtins.js in this distribution.
builtins : null,
// boolean option to set if external modules should be bundled. Defaults to true.
bundleExternal : true,
// sets the browser-pack implementation to use.
pack : null,
// defaults to 'require' in expose mode but you can use another name.
externalRequireName : null
Contributing
Yes! Contribute! Test! Share your ideas! Report Bugs!
Release History
- 0.2.0 Initial release
License
grunt-bundles Copyright (c) 2014 Terry Weiss. All rights reserved.
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Metadata
- Unknown
- >= 0.10.28
- Terry Weiss
- released 7/16/2014