Here are the quick steps on how to use ASPAX with an Express.js application:
1. Create a folder structure similar to this one for your project:
/client -> asset sources
/server -> main Express.js application folder
/server/public -> public static folder
Notice: put all your asset sources in /client
; don’t put anything in /server/public
, as it will be overwritten!
2. Create /client/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.get('/:page', function(req, res) {
...
});
5. Replace the URLs in your views with asset()
function calls, like this:
//- link(rel="shortcut icon", href="/favicon.png")
link(rel="shortcut icon", href=asset('favicon.png'))
6. In /server
folder you can run any of these:
# 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 either 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.
1. To improve performance and responsiveness even more, consider using a specialized static assets module such as st instead of express.static
. Besides server-side caching and gzip compression, since v0.4.1 st is able to leverage client-side browser caching by correctly setting the appropriate Cache-Control
header. See this commit for more info.
2. You can avoid using the additional aspax-express module by implementing your own logic to “adjust” the asset file names in production.
JavaScript:
var assets = require('./aspax.json');
...
app.locals.asset = function(name) {
return assets[name];
};
CoffeeScript:
assets = require './aspax.json'
...
app.locals.asset = (name) -> assets[name]