air-drop

AirDrop

AirDrop is a tool for packaging assets in one of two ways:

1. Use the Node.js Connect middleware for compiling, concatenating, minimizing and delivering your JS and CSS source files to the browser on-the-fly. Personally I think this approach is preferable to using build scripts, file watchers, etc.
2. For projects that don't use a Node.js server, the air-drop shell command gives you the same features on the command line as part of your build process.

Install

Install with npm:

npm install air-drop

If you are using AirDrop on the command line, you will want to install it globally so that the command is available everywhere:

npm install -g air-drop

You can run the specs with npm as well:

cd node_modules/air-drop
npm test

Including JS Files

All the following examples assume you have some kind of a Connect-compatible server:

var server = require("connect").createServer();

AirDrop objects are instantiated with a package url. To simply include JS files, use the include method. Files will be added to the package in the order you include them.

var package = AirDrop("/my-package.js")
                .include("public/js/jquery.js")
                .include("public/js/file1.js")
                .include("public/js/file2.js");
server.use(package);

Making It Available

In your client-side code, you can load your JS package with a script tag; by default, your package will be available at the given URL:

<script type="text/javascript" src="/my-package.js"></script>

Globbing Paths

Rather than including paths one by one, you can use glob wildcards:

var package = AirDrop("/my-package.js")
                .include("public/js/jquery.js")
                .include("public/js/**/*.js")

This will first add jquery.js, then any other JS files nested inside public/js. NOTE: Because jquery.js has already been included, it will not be included a second time by the glob include.

Requiring JS Modules

Sharing JS source files between Node and the browser is difficult because the browser does not natively implement Node's file loading system using require and exports. This is easy with AirDrop, though; it will wrap your modules in an AMD define blocks for use in the browser.

To explicitly add a file to your package that can be accessed using require, you can use the require method:

// in lib/my-module.js
exports.helloWorld = function() { return "Hello World!"; };

// in index.html
<script src="/my-package.js" type="text/javascript"></script>
<script type="text/javascript">
  var MyModule = require("lib/my-module");
  console.log(MyModule.helloWorld());
</script>

// in your Node script
var package = AirDrop("/my-package.js").require("lib/my-module.js")
server.use(package);

When any file is included or required by AirDrop, the code is analyzed for dependencies. AirDrop will automatically read any uses of require in the file and load the dependent code. This also works for modules located in your node_modules directory. For example:

// in public/main.js
var _ = require("underscore"),
    a = require("./a.js");
a.sayHello();

// in public/a.js
var b = require("./b.js");
exports.sayHello = function() {
  b.sayHello();
  console.log("Hello from A");
};

// in public/b.js
exports.sayHello = function() {
  console.log("Hello from B");
};

// in server.js
var package = AirDrop("/my-package.js")
                .include("./public/main.js");
server.use(package);

Whenever a file is required with AirDrop (explicitly with require or implicitly as a dependency), AirDrop will automatically include the browser-require library that makes all these require statements work in the browser. If you have multiple packages being loaded onto a page, you will only need browser-require included in one of them, so you will want to prevent its inclusion in the others with useBrowserRequire(false):

var package1 = AirDrop("/package1.js")
                 .require("lib/mod1");
var package2 = AirDrop("/package2.js")
                 .require("lib/mod2")
                 .useBrowserRequire(false);

Using useBrowserRequire(true) includes browser-require into the package even if its require method was never used.

Packaging Your Code

By default, AirDrop does not package your code, as this makes debugging difficult in development. Rather, /air-drop/my-package.js will dynamically add a script tag for each of your included scripts so that they will be loaded individually.

When you are ready for your code to be packaged, use the package method:

var package = AirDrop("/my-package.js")
                .require("lib/my-module.js")
                .include("public/js/demo.js")
                .package();

The package method accepts an optional boolean so that you can package conditionally. For example, you may only want to package your code if the NODE_ENV environment variable is set to production:

var package = AirDrop("/my-package.js")
                .require("lib/my-module.js")
                .include("public/js/demo.js")
                .package(process.env.NODE_ENV === "production");

Minimizing Your Code

Minimizing your client code is a good way to reducing file size as well as obfuscating it from prying eyes. Like the package method, the minimize method can be called without an argument, or with a boolean:

var package = AirDrop("/my-package.js")
                .require("lib/my-module.js")
                .include("public/js/demo.js")
                .package(process.env.NODE_ENV === "production")
                .minimize(process.env.NODE_ENV === "production");
                // or just .minimize()

By default, the minimize function will use uglify to minimize your code. If you want to customize how your code is minimized, you can pass minimize a function instead:

function customMinimizer(data, cb) {
  try {
    // do minimization work to data
    cb(null, data);
  } catch(e) {
    cb(e);
  }
}

var package = AirDrop("/my-package.js")
                .require("lib/my-module.js")
                .include("public/js/demo.js")
                .package()
                .minimize(customMinimizer);

Caching Your Packages

Since building these packages can be an expensive operation, you will probably want to cache the built packages in memory so they are only built once while your process is running. You can do this using the cache method, which takes an optional boolean like package and minimize:

var package = AirDrop("/my-package.js")
                .require("lib/my-module.js")
                .include("public/js/demo.js")
                .package(process.env.NODE_ENV === "production")
                .minimize(process.env.NODE_ENV === "production")
                .cache(process.env.NODE_ENV === "production");
                // or just .cache()

By default, the cache method will use a simple in-memory cache. If you want to use a different caching method you can pass your own custom cacher to cache:

function customCacher(key, orig, cb) {
  var cachedData = SomeCache.get(key);
  if(cachedData) {
    cb(null, cachedData);
  } else {
    orig(function(err, data) {
      if(err) { return cb(err); }
      SomeCache.set(key, data);
      cb(null, data);
    });
  }
}

var package = AirDrop("/my-package.js")
                .require("lib/my-module.js")
                .include("public/js/demo.js")
                .package()
                .cache(customCacher);

Compiling CoffeeScript (and more)

Using CoffeeScript? No problem, any CoffeeScripts will be automatically compiled for you!

If you have some other kind of source that needs to be compiled, you can add your own custom compiler. For example, if you need to compile "CrazyScript":

var CrazyScriptCompiler = function(data, cb) {
  try {
    // do work on data
    cb(null, data);
  }
  catch(e) {
    cb(e);
  }
};

// pathObj is an AirDrop.Path object, and the test returns true/false for whether our
// CrazyScriptCompiler should be used for this path object.
var CrazyScriptTest = function(pathObj) {
  return /crazyscript$/.test(pathObj.path);
};

AirDrop.Compilers.add(CrazyScriptCompiler, CrazyScriptTest);

var package = AirDrop("/my-package.js").require("lib/my-module.crazyscript")

You can also explicitly use a custom compiler on a specific include/require:

var package = AirDrop("/my-package.js")
                .require("lib/my-module.js", {
                  compiler: CrazyScriptCompiler
                });

Stripping Out Server-Only Function Calls

When sharing your code libraries between the server and the client, you may find places in your code where you have server-only code mixed in with shared code. While the best solution to this problem is properly modularizing your code and decoupling, it may be convenient or necessary to strip certain function calls out of your code before delivering it to your client. This can be accomplished using the stripFunction method:

// In your shared code
onServer(function() {
  console.log("Shared code run at", new Date());
});

// Somewhere in your server-side code
global.onServer = function(func) {
  // On the server, just run the code passed to onServer.
  return func();
};

var package = AirDrop("/my-package.js")
                .require("lib/shared-code.js")
                .stripFunction("onServer")
                .package();

This will actually strip all uses of onServer out of the source and never deliver its contents to the client. It goes without saying that this feature should be used sparingly and with care. If possible, prefer proper code modularization over source code manipulation.

Packaging CSS Files

AirDrop supports similar features for packaging CSS files. If the URL passed to the AirDrop function ends in .css, the package will be treated as CSS.

Use include to include CSS files into the package, and globs work too:

var package = AirDrop("/my-package.css")
                .include("public/css/vendored/*.css")
                .include("public/css/main.css")
                .package();

Similar to JS packages, using the package function will concatenate all the source files into a single file. Without it, the package file will simply use the CSS @import directive to load the individual files.

CSS Dependencies

The @import CSS directive is convenient but not performant, so AirDrop will replace all @imports with the inline contents of the imported file. For example:

/* in public/main.css */
@import url("partials/a.css");
@import url("partials/b.css");
.c { color: red; }

/* in public/partials/a.css */
.a { color: blue; }

/* in public/partials/b.css */
.b { color: green; }

When packaged, the resulting CSS is:

.a { color: blue; }
.b { color: green; }
.c { color: red; }

Using Stylus and Less

AirDrop ships with compilers for both Stylus and Less out of the box. All .styl and .less files that are included into a package will be compiled automatically.

NOTE: Because Stylus and Less have their own mechanisms for importing source files using @import, AirDrop does not inline the dependencies like it does with straight CSS files.

Using the air-drop Command

For projects that aren't using Node.js, the air-drop command line tool gives you the same features to build packages, which you can then make available on your own server.

The air-drop command has options that map directly to AirDrop methods, so this command:

air-drop --include lib/vendor/**/*.js --require lib/shared-code.js --strip-function onServer --minimize > my-package.js

is equivalent to the code generated by this JS:

AirDrop("/my-package.js")
  .include("lib/vendor/**/*.js")
  .require("lib/shared-code.js")
  .stripFunction("onServer")
  .minimize()
  .package();

For CSS packaging, you have to use the --css flag to tell AirDrop that it should handle the files as CSS files. This command:

air-drop --css --include public/css/vendor/*.css --include public/stylus/main.styl > my-package.css

is equivalent to:

AirDrop("/my-package.css")
  .include("public/css/vendor/*.css")
  .include("public/stylus/main.styl")
  .package();

For syntax help, use air-drop --help.

A few notes about the air-drop command:

• On the command line, files are always packaged like the package() method is used.
• Caching doesn't make sense on the command line, so there is no equivalent to the cache() method.
• Globs, JS dependencies and CSS dependencies are all supported.
• Paths are added to the package in the order they are included/required.
• Currently the built-in compilers (CoffeeScript, Less, Stylus) are supported, but custom compilers are not.

TODO

• Add more robust options parsing and error handling in CLI
• Support modules in $NODE_PATH, not just node_modules
• Integration level tests
• Improve caching mechanism to integrate storage outside of memory (flat files, memcached)
• Inline documentation