nap

Node Asset Packager

(nap) Node Asset Packager helps compile, manage, & package stylesheets, javascripts, and javascript templates for node.js.

Example

Declare asset packages

global.nap = require('nap');

nap({
  assets: {
    js: {
      backbone: [
        '/app/coffeescripts/models/**/*', 
        '/app/coffeescripts/views/**/*', 
        '/app/coffeescripts/routers/**/*'
      ]
    },
    css: {
      all: [
        '/public/stylesheets/blueprint.css',
        '/app/stylesheets/**/*'
      ]
    },
    jst: {
      templates: [
        '/app/templates/index.jade',
        '/app/templates/footer.jade'
      ]
    }
  }
});

Include packages in your views by calling one of nap's helpers. (example in jade)

!!!
html
  head
    title= title
    != nap.css('all')
  body
    != body
    #scripts
      != nap.jst('templates')
      != nap.js('backbone')

Concatenate & minify once for production

nap({
  mode: 'production',
  assets: {
    js: //...
    css: //...
    jst: //...
  }
});

nap.package();

Some express.js based examples can be found in the examples folder.

Installation

npm install nap

Usage

To make things easy nap assumes you have a /public folder to serve static assets (like an Express.js or Ruby on Rails public folder) so that nap can generate & reference assets inside /public/assets.

Simply pass a set of options to the main nap function to configure your asset packages. Then use one of nap's helpers (nap.js('package-name'), nap.css('package-name'), nap.jst('package-name')) to output <script> and <style> tags into your server-side templates.

Options

• assets
  • the assets object containing all of your package declarations
• publicDir (defaults to /public)
  • your public directory where you serve static content
• mode (defaults to 'production' on NODE_ENV=staging and NODE_ENV=production, otherwise 'development')
  • the mode you want nap to be in 'production' or 'development'
• cdnUrl
  • If you are using a CDN you can pass the url root of where your asset packages are stored. The nap helpers will point there instead of the local /public/assets dir in 'production' mode.
• embedImages (defaults to false)
  • When true, it embeds image urls in CSS files ending in _embed using data-uri e.g. images_embed.styl
• embedFonts (defaults to false)
  • When true, it embeds font urls in CSS files ending in _embed using data-uri e.g. fonts_embed.styl
• gzip (defaults to false)
  • Gzips .jgz and .cgz asset packages. The nap helpers will point to these gzipped packages in production mode unless you pass false as a second argument nap.js('package-name', false)
• fingerprint (defaults to false)
  • When true will add an md5 hash to the generated asset package allowing assets to be easily cache busted. (production mode only)

nap({
  publicDir: '/public',
  mode: process.env.NODE_ENV === 'production' ? 'production' : 'development',
  cdnUrl: 'http://s3.amazonaws.com/my-bucket/assets/',
  embedImages: true,
  embedFonts: true,
  gzip: true,
  assets: {
    js: {
      backbone: [
        '/app/coffeescripts/models/**/*',
        '/app/coffeescripts/views/**/*',
        '/app/coffeescripts/routers/**/*'
      ]
    },
    css: {
      all: [
        '/public/stylesheets/blueprint.css',
        '/app/stylesheets/**/*'
      ]
    },
    jst: {
      templates: [
        '/app/templates/index.jade',
        '/app/templates/footer.jade'
      ]
    }
  }
});

JS & CSS Pre-processors

Nap will automatically precompile any javascript and css pre-processors based on the file extension.

Nap currently only supports the following pre-processors by default. But please feel free to contribute more.

• Coffeescript (.coffee)
• Stylus (.styl)
• Less (.less)

Adding your own preprocessors

You can add your own preprocessors to nap by extending nap.preprocessors, with a fileExtension: preprocessFunction pair.

e.g.

var nap = require('nap')
  , coffee = require('coffee-script');
nap.preprocessors['.coffee'] = function(contents) { return coffee.compile(contents) };

Client-side Javascript Templating (JSTs)

jst packages will run the appropriate template parser based off the file extension. Nap will then namespace your client-side templates into a global JST['file/path'] function, much like Jammit. The namespace is the directory following templates without the file extension.

e.g. The template app/templates/artwork/detail.jade will be parsed using jade and can be rendered on the client-side by calling JST['artwork/detail']({ title: 'Mona Lisa' })

Nap currently only supports the following template parsers by default. But please feel free to contribute more.

• Jade (.jade)
• Mustache (using Hogan.js) (.mustache)

Adding your own template parsers

You can add your own template parsers to nap by extending nap.templateParsers, with a fileExtension: templateParserFunction pair.

e.g.

var nap = require('nap')
  , jade = require('jade');
nap.templateParsers['.jade'] = function(contents) { 
  return jade.compile(contents, { client: true, compileDebug: true }); 
};

Nap Modes

Nap has two modes 'development' and 'production'.

Development

In development, nap will run any pre-processors and output a bunch of individual <script> and <link> tags using one of it's helpers (nap.js('package-name'), nap.css('package-name'), nap.jst('package-name')). Each time these helpers are called they will re-compile these files, resulting in seamless asset compilation on page refresh.

Production

In production use the nap.package() function once (e.g. upon deployment).

Calling nap.package() will concatenate all of the files, minify, and finally output the result to a single package file (e.g. public/assets/package-name.js).

Calling one of nap's helpers in production mode will simply return a <script> or <link> tag pointing to the concatenated package file.

You may also gzip, embed images & fonts, and point to a CDN. See options above for more info.

Middleware

Use nap as middleware to quickly serve files in memory rather than writing to disk. (In 'development' mode only)

var nap = require('nap')
  , express = require("express")
  , app = express.createServer();

app.use(nap.middleware);

Tests

Nap uses Mocha for testing, simply run mocha.

mocha

License

(The MIT License)

Copyright (c) Craig Spaeth [e-mail], Art.sy, 2011

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.