krishedges / connect-assets

A Rails 3.1-style asset pipeline for Node.js

connect-assets

Transparent file compilation and dependency management for Node's connect framework in the spirit of the Rails 3.1 asset pipeline.

Written in CoffeeScript by the author of CoffeeScript: Accelerated JavaScript Development.

What?

connect-assets can:

1. Serve .coffee (CoffeeScript) files as compiled .js
2. Concatenate .coffee and .js together using Snockets
3. Serve .styl (Stylus) as compiled .css with
   • nib
   • Twitter Bootstrap
4. Serve .less (Less) as compiled .css with
   • Twitter Bootstrap
5. Serve files with an MD5 hash suffix and use a far-future expires header for maximum efficiency
6. Avoid redundant git diffs by storing compiled .js and .css files in memory rather than writing them to the disk—except when you want them (e.g. for deployment to a CDN).

How?

First, install it in your project's directory:

npm install connect-assets

Also install any specific compilers you'll need, e.g.:

npm install coffee-script
npm install stylus
npm install nib
npm install bootstrap-stylus
npm install less

Then add this line to your app's configuration:

app.use require('connect-assets')()

Finally, create an assets directory in your project and throw all your .coffee files in /assets/js and .styl, .less files in /assets/css.

Markup functions

connect-assets provides two global functions named js and css. Use them in your views. They tell connect-assets to do any necessary compilation, then return the markup you need. For instance, in a Jade template, the code

!= css('normalize')
!= js('jquery')

(where `!= is Jade's syntax for running JS and displaying its output) results in the markup

<link rel='stylesheet' href='/css/normalize.css'>
<script src='/js/jquery.js'></script>

Sprockets-style concatenation

You can indicate dependencies in your CoffeeScript files using the Sprockets-style syntax

#= require dependency

(or //= require dependency in JavaScript). When you do so, and point the js function at that file, two things can happen:

1. By default, you'll get multiple <script> tags out, in an order that gives you all of your dependencies.
2. If you passed the build: true option to connect-assets (enabled by default when process.env.NODE_ENV == 'production'), you'll just get a single tag, wich will point to a JavaScript file that encompasses the target's entire dependency graph—compiled, concatenated, and minified (with UglifyJS).

If you want to bring in a whole folder of scripts, use

#= require_tree dir

See Snockets for more information.

Note: CSS concatenation is not supported by connect-assets directly, because Stylus and Less already do a fine job of this. Stylus and Less are basically supersets of CSS, so just rename your .css files to .styl or .less and learn about the @import (Stylus, Less) syntax.

Options

If you like, you can pass any of these options to the function returned by require('connect-assets'):

• src (defaults to 'assets'): The directory assets will be read from
• helperContext (defaults to global): The object the css and js helper functions will attach to
• buildDir (defaults to builtAssets): Writes built asset files to disk using this directory in production environment, set to false to disable
• ... see the source (src/assets.coffee) for more.

You can also set the "root path" on the css and js helper functions (by default, /css and /js), e.g.

css.root = '/stylesheets'
js.root  = '/javascripts'

To override these roots, start a path with '/'. So, for instance,

css('style.css')

generates

<link rel='stylesheet' href='/css/style.css'>

while

css('/style.css')

gives you

<link rel='stylesheet' href='/style.css'>

Credits

Borrows heavily from Connect's compiler and static middlewares, and of course sstephenson's Sprockets.

Contributors: hasenj, TrevorBurnham.

License

©2011 Trevor Burnham and available under the MIT license:

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.