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

As of February 21, 2013, @adunkman became the maintainer of this package. The game plan is as follows:

• Address critical issues with version 2.x (master branch) to take care of the open pull requests/issues.
• Begin a version 3.x (v3 branch) that introduces stronger tests and code structure to make contributing easier to manage, reducing dependencies as possible.

• Rewrite in JS
• Cleaner code
  • Shorter files
  • Better defined responsibilities
• No singleton
• Replace connect-file-cache
• Look for replacment for Snockets
• Remove dependence on underscore
• Remove dependence on mime
• Write tests in mocha
• Remove Cakefile

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).

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.

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>

For your purposes you can pass additional attributes to helpers js and css.

!= css('normalize', { media: 'print', 'data-confirm': 'Are you sure to do this?', 'data-delete': true })

Result:

<link rel="stylesheet" href="/css/normalize.css" media="print" data-confirm="Are you sure to do this?" data-delete />

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.

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
• servePath (defaults to ""): Paths in generated tags will be prefixed by servePath. Useful when working with reverse proxies.
• ... 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'>

In addition to setting the "root path" where assets can be found by the server, you can also "mount" your assets behind a base location path by setting servePath, so that path references are generated correctly for tags. This is especially useful when working with reverse proxies, where the server may be receiving external requests for assets at a different path, e.g.

require('connect-assets')(
  servePath: '/foo'
)

then,

css('/style.css')

gives you

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

While the server will still expect that external requests for '/foo/css/style.css' will be rewritten for '/css/style.css' This only applies to absolute paths.

There is generated documentation (created with docco) available here.

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

Look at these awesome people who make this project possible.