aspax-express

What's this?

[![NPM version][npm-image]][npm-url]
[![Dependency Status][david-image]][david-url]
[![License][license-image]][license-url]
[![Downloads][downloads-image]][downloads-url]

A module that enables Express.js to serve assets built and packaged by ASPAX.

Installation

Run this in your application folder:

npm install aspax-express --save

Usage

Quick steps:

1. Create a folder structure similar to this one for your project:

/assets -> asset sources
/server -> main Express.js application folder
/server/public -> public static folder

Notice: put all your asset sources in /assets; don't put anything in /server/public, as it will be overwritten.

2. Create /assets/aspax.yml describing your assets configuration:

js/app.js|fp|min:
- lib/bootstrap/js/bootstrap.js
- lib/moment.js
- lib/jade/runtime.js
- scripts/namespaces.coffee|bare
- templates/now.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

...

3. Install ASPAX globally if you haven’t already, install aspax-express in your application, and also make sure to install any necessary source handling plugins:

# Global ASPAX
npm install aspax -g

cd server

# ASPAX-Express
npm install aspax-express --save

# Source handling plugins
npm install aspax-coffee-handler --save-dev
npm install aspax-ls-handler --save-dev
npm install aspax-jade-handler --save-dev
npm install aspax-styl-handler --save-dev

4. Add require('aspax-express')(app, path.join(__dirname, 'aspax.json')) before handling views in your main application script (usually /server/app.js):

var express = require('express')
, app = express();

...
require('aspax-express')(app, path.join(__dirname, 'aspax.json'));
app.use app.router;
app.get('/:page', function(req, res) {
...
});

5. Wrap the URLs in your views into asset() function calls:

//- link(rel="shortcut icon", href="/favicon.png")
link(rel="shortcut icon", href=asset('favicon.png'))

6. Then, in your /server folder you can run:

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

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

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

# clean everything
aspax -s ../client clean

7. Run your application in development or production mode:

# development
#
NODE_ENV=development node start.js
# ...or
NODE_ENV=development nodemon -e js,json,coffee -x node

# production
#
NODE_ENV=production node start.js

Notice: if you're using nodemon in development mode, add aspax.json to .nodemonignore to avoid restarting the application whenever an asset is rebuilt.

Have a look at this demo repository to see it in action.

What does it actually do?

In plain English, on application startup it reads the map produced by aspax pack and registers an app.locals.asset() method you'll have to use in your views to translate all the asset URLs.

Have a look at the main file here for details.

Endorsing the author

[npm-image]: https://img.shields.io/npm/v/aspax-express.svg?style=flat-square
[npm-url]: https://npmjs.org/package/aspax-express
[david-image]: http://img.shields.io/david/icflorescu/aspax-express.svg?style=flat-square
[david-url]: https://david-dm.org/icflorescu/aspax-express
[license-image]: http://img.shields.io/npm/l/aspax-express.svg?style=flat-square
[license-url]: LICENSE
[downloads-image]: http://img.shields.io/npm/dm/aspax-express.svg?style=flat-square
[downloads-url]: https://npmjs.org/package/aspax-express