node package manager

bundl

Bundl

Become a master of bundles

What Is Bundl?

Bundl is the best way to manage your frontend codebase. It switches the paradigm of when resources are built vs when they are needed (Bundl On-Demand). Use it as a task manager or use it to package your source code with additional resources (like styles and images) into a JavaScript bundle that can be served to your web browser.

Why Use Bundl?

  • Build resoucres only when requested by your browser (and only if they've changed) (Example)
  • Easily concat, require, and wrap all of your various resources to generate the bundle you really need (Example)
  • Run other tasks like linting, file system operations, etc. (Example)
  • Get unit test coverage fast (without the overhead of PhantomJS) (Example)
  • Write next generation ES6 JavaScript today with a transpiler plugin (Example)

Get Started

Install

$ cd ~/myProject
$ npm install bundl --save-dev

Create Your Build Script

Make a new file at ~/myProject/bundl.js

var bundl = require('bundl');
 
// Plugins 
var pack = require('bundl-pack');
var minify = require('bundl-minify');
var write = require('bundl-write');
 
// Configure 
var bundlOptions = {
    outputDir: 'dist/javascripts',
    clean: true
};
var targets = {
    'my_project_bundle.js': 'src/entry.js'
};
 
// Setup a build pipeline 
var myProjectBundl = bundl(targets, bundlOptions)
    .then(pack())
    .thenif(bundl.args.min, minify())
    .then(write());
 
// Start the build 
myProjectBundl.go();

Run Your Script

$ cd ~/myProject
$ node bundl --min

Run via NPM (optional)

Add scripts to your package.json

{
  "name": "myProject",
  "version": "0.0.1",
  "dependencies": {
    "bundl": "^1.0.0"
  },
  "scripts": {
    "build": "node bundl.js"
  }
}
$ npm run build

Ways to Use


Build Resources Live On-Demand!

When you make a change to one source file, you shouldn't have to switch back to command line to run a command before you can see your changes live in a browser. You also shouldn't need to wait for every bundle to rebuild if you only want to see one or two of them. Use Bundl's dev server instead...

// Setup a build pipeline 
var myProjectBundl = bundl(targets, bundlOptions)
    .then(pack())
    .then(write());
 
// Start live dev mode 
myProjectBundl.webserver();

Now, open a browser to http://localhost:5555

HTTP Requests for a bundled resource will check to see if any of the source files within this bundle have changed since last request. If so, the webserver will rebuild the requested bundle before sending it back to the browser.

Learn how to configure your own webserver on our wiki.


Task Management

Define Tasks

var bundl = require('bundl');
 
bundl.task('doit:sync', function () {
    console.log('  My name is: ' + this.name);
    return 123;
});
 
bundl.task('doit:async', function (done) {
    console.log('  My name is: ' + this.name);
    setTimeout(function(){
        if (typeof done === 'function') {
            done(456);
        }
    }, 100);
});
 
bundl.task('doit', function () {
    bundl.run('doit:async', doitCallback);
    bundl.run('doit:sync', doitCallback);
});
 
function doitCallback (result, name) {
    console.log(name + ' = ' + result);
}
 
bundl.load(); // runs any tasks passed via command line 

Run Tasks

Run using the API

bundl.run('doit');

Run from command line

$ node bundl doit

Debugging

Add .debug() to your build chain to print which src files will be bundled into which dest files

bundl(targets, bundlOptions).debug();

Add --verbose as a command line option to print more info about what's happening

$ node bundl --verbose