Hit me with the basics

To get started, include the Boxjs library (only 2kb) in your page.

 
<script src="http://www.boxjs.com/box.js"></script>

Then just call Box with your site host URL and an array of files you wish to load.

 
Box('http://mywebsite.com/scripts/', [
	'plugins/jquery.js',
	'plugins/json2.js',
	'plugins/jquery-class.js'
]);

Boxjs will grab your files, compress them and then deliver one minified and cached JS file to your page.

NOTE: The Box library merely passes your files to the Boxjs service as a query string, but provides a nice way to manage your files whilst adding a few additional options. BoxJs runs on Amazon EC2 which states "The Amazon EC2 Service Level Agreement commitment is 99.95% availability", so its pretty reliable. As boxjs is currently free, we can support about 50 requests per second and about 20 000 js files until we clear the cache. We can, however, set up your own instance of boxjs with the above specs which would be more than you will ever need. This will also be free as long as we can keep up with demand. Find us on twitter below to request your own instance.

Want some coffee with that?

Boxjs will compile your CoffeeScript files, compress and minify them too!

 
Box('http://mywebsite.com/scripts/', [
	'plugins/jquery.js',
	'plugins/json2.js',
	'plugins/mycoffeescriptfile.coffee',
	'plugins/mycoffeescriptfile2.coffee'
]);

For using 'Dev' mode you may need to use a gem such as Barista or similar to compile your CoffeeScript files locally.

Using Boxjs

An options object can be passed as the third argument to a Box instance.

 
Box('http://mywebsite.com/scripts/', [
	'plugins/jquery.js',
	'plugins/json2.js'
], { minify: false });

Setting global options

Alternatively, you can declare a Box options object before Boxjs is loaded and this will be used by all instances as default options.

 
var Box = {
	root: 'http://website.com/scripts/',
	defer: true,
	minify: false
}			

<script src="http://boxjs.com/box.js"></script>

If you set the root property then you only need to pass your array of files to a Box instance.

 
var Box = {
	root: 'http://website.com/scripts/'
}			

Box(['plugins/jquery.js', 'plugins/jquery-ui.js']);

Loading assets from different domains

If you have a bunch of files that are hosted elsewhere you can just pass an array of files to Box that contain the full path.

 		
Box(['https://ajax.googleapis.com/ajax/libs/jquery/1.6.2/jquery.min.js', 'https://ajax.googleapis.com/ajax/libs/jqueryui/1.8.14/jquery-ui.min.js']);

If you've already set a global root option for your Box instances you will need to pass false as the first argument so that it is ignored.

 
var Box = {
	root: 'http://website.com/scripts/'
}
							
Box( false, ['https://ajax.googleapis.com/ajax/libs/jquery/1.6.2/jquery.min.js'] );

Duplicate requests

Box keeps track of all the files you've asked for, compares new requests and will remove any duplicates before fetching your files. This leaves you free to include Box instances without fear of duplicate file requests.

This is matched purely on the string value of your files, so 'lib/jquery.js' is not the same as 'http://website.com/lib/jquery.js'.

Available Boxjs options

  • dev

    When left as the default (false), all requested scripts will be returned as one file via boxjs.com. However, this is a problem whilst working locally as those files cannot be passed to the boxjs service. Setting dev to true means each file will be appended as a separate script element that doesn't call the boxjs service at all.

     

var Box = {
	root: 'http://localhost:8888/scripts/',
	dev: true
}
			
// Resulting HTML
<script src="http://localhost:8888/scripts/jquery.js"></script>
<script src="http://localhost:8888/scripts/jquery-ui.js"></script>
    Values
    false (default) | true
    Type
    Boolean

  • defer

    Normally, Boxjs will fetch your scripts as soon as you call it. But there may be times when you'd like to control when the scripts are requested, perhaps based on some kind of condition for example.

     
// Create an instance					
var box = Box('http://mywebsite.com/scripts/', [
		'plugins/jquery.js',
		'plugins/json2.js'
		], { defer: true });
			
// Do some stuff

// Get your scripts!
box.get();
    Values
    false (default) | true
    Type
    Boolean

  • append

    By default, Boxjs will append the script element to the bottom of the page. Setting this to false will add your scripts to the DOM using document.write. Useful if you need your JS evaluated before the page finishes loading.

    Values
    true (default) | false
    Type
    Boolean

  • minify

    Does what it says on the tin using Uglify. If Boxjs fails to minify your script, it will be returned unminified.

    Values
    true (default) | false
    Type
    Boolean

  • cache

    This is set to true by default. It works in conjunction with the version option. Your files will be packaged and cached for a few days. If you want to reload the cache, you should provide a new version

    Values
    true (default) | false
    Type
    Boolean

  • version

    Use this property to control which version to load from cache. A package will be cached for a few days by default. Incrementing the version number with each release will keep your files fresh.

    Values
    1 (default) | 1.1, 2
    Type
    Number