luowei98 / 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.

The state of the package

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.

Plans for version 3.0

• 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

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'>

Generated documentation

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

Credits

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.