The simple Node.js asset packager.

What if you could watch, compile, concatenate, minify and fingerprint all your web assets using just a simple file written in clear, human-readable YML syntax?

js/app.js|fp|min:
  - lib/bootstrap/js/bootstrap.js
  - lib/moment.js
  - lib/jade/runtime.js
  - scripts/namespaces.coffee | bare
  - templates/item.jade
  - scripts/index.ls          | bare

css/app.css|fp|min:
  - lib/bootstrap/css/bootstrap.css
  - lib/bootstrap/css/bootstrap-theme.css
  - styles/index.styl|nib

favicon.png: images/favicon.png

fonts/bs-glyphs.eot  |fp: lib/bootstrap/fonts/glyphicons-halflings-regular.eot
fonts/bs-glyphs.svg  |fp: lib/bootstrap/fonts/glyphicons-halflings-regular.svg
fonts/bs-glyphs.ttf  |fp: lib/bootstrap/fonts/glyphicons-halflings-regular.ttf
fonts/bs-glyphs.woff |fp: lib/bootstrap/fonts/glyphicons-halflings-regular.woff

That’s it. No complicated .initConfig(), no redundant code to describe tasks in JavaScript or CoffeeScript, just a simple YML file in your assets folder.

By looking at that file, ASPAX will:

Installation

Most likely you’ll want ASPAX NPM version installed as a global module:

npm install aspax -g

Plugins

To keep the global CLI module lightweight and dependency-free, ASPAX is using a plugin system to handle different source types such as CoffeeScript, LiveScript, client-side Jade templates, Stylus or LESS files, etc.

ASPAX will look for plugins in ./node_modules folder, so you’ll have to install the necessary source handlers like this:

npm install aspax-coffee-handler

If you’re running ASPAX in a Node.js application root folder, consider using the --save-dev option to avoid deploying the plugins to your production environment:

npm install aspax-coffee-handler --save-dev

Available plugins

So far, the available plugins are:

If you need something else, please let me know and maybe I can do it, or better yet, feel free to do it yourself and notify me so I can list it here.

Developing additional plugins

Each plugin npm should be named aspax-xyz-handler, where xyz is the file extension it refers to.

Each plugin npm should export a compile() method with this signature (see example here):

exports.compile = function(file, flags, callback) {
  ...
};

…and optionally a findImports() method to recursively find imported/referred files (see examples here and here):

exports.findImports = function(imports, file, callback) {
  ...
};

Usage

The two main options are:

You can type aspax --help in the console for advanced usage, but here are just a few CLI usage examples:

# watch and build on-the-fly during development
aspax -s ../assets watch

# build for development
aspax -s ../assets build

# pack for production (will compile, concat, minify and fingerprint)
aspax -s ../assets pack

# clean everything
aspax -s ../client clean

Using assets built and packaged by ASPAX in an Express.js application

See this tutorial for a nice step-by-step guide on how to use ASPAX with Express.js.

Config file syntax

The syntax of aspax.yml should be quite simple and human-friendly. Here are just a few tips:

Marking assets for fingerprinting and minification

Just add the appropriate flags after the asset file name (the order is irrelevant):

#         o-- fingerprint
#         |  o---- minify
#         |  |
#         |  |
#         V  V
#         -- ---
js/app.js|fp|min:

The flags will have no effect in development mode, but in production:

Note: fingerprinting will work for anything, while minification only makes sense for JS and CSS files.

Plugin options

Some source-handling plugins are also accepting flags (i.e. bare for CoffeeScript files). Use the same syntax:

#  o---------------------o
#  | compile without the |
#  | top-level function  |--o
#  | safety wrapper      |  |
#  o---------------------o  |
#                           V
#                         ----
  - scripts/source.coffee|bare

Readability

You can add any number of whitespaces around semicolons and flag separators for readability. All of the following are equivalent:

You can also add comments and even format your code like this:

# Main script
js/app.js                             | fp | min :
  - lib/bootstrap.js
  - scripts/script-one.coffee | bare
  - scripts/script-two.coffee | bare
  - scripts/script-three.ls   | bare

# Main CSS
css/app.css                           | fp | min :
  - lib/bootstrap.css
  - styles/style-one.styl     | nib
  - styles/style-two.coffee   | nib
  - styles/style-three.ls     | nib

# Images
favicon.png            : images/favicon.png
logo.png               : images/logo.png

# Fonts
fonts/glyphs.eot  | fp : lib/fonts/glyphicons-halflings-regular.eot
fonts/glyphs.svg  | fp : lib/fonts/glyphicons-halflings-regular.svg
fonts/glyphs.ttf  | fp : lib/fonts/glyphicons-halflings-regular.ttf
fonts/glyphs.woff | fp : lib/fonts/glyphicons-halflings-regular.woff

FAQ

What’s the meaning of the name?

ASset PAckager, and X because ASPAX is an evolution of ASPA, a similar module I’ve built in the past.

So why writing ASPAX instead of just updating ASPA?

ASPAX brings in some breaking changes by simplifying the YML file syntax and introducing a plugin system to handle various source files. Simply updating ASPA wouldn’t have been possible without annoying the happiness of too many users.

How long do you plan to maintain ASPAX?

I’m a strong advocate of open-source philosophy and I’m also using this module in my Node.js projects, so I’ll do my best to keep it up to date. If you notice ASPAX has outdated depencencies, most likely there’s going to be an update soon.

Dependency Status

What projects / websites are using assets packaged by ASPAX?

To name just a few:

If you think your project should be listed here, don’t hesitate to let me know about it.

Endorsing the author

If you find this piece of software useful, please tweet about it and endorse me on LinkedIn:

Ionut-Cristian Florescu on LinkedIn