Mincer - assets processor

NOTE: This project is now under limited maintenance.

JavaScript port of Sprockets (v2.10.0). It features same declarative dependency management (with exactly same language) for CSS and JavaScript and preprocessor pipeline. Mincer allows you to write assets in the languages like: CoffeeScript, LESS, Stylus and others. Moreover mincer has advanced built-in features, not available in sprockets:

• sourcemaps support
• macros support (nice alternative to EJS)

See Sprockets, Mincer API Documentation and Mincer examples for more details.

Supported engines are described in Wiki. If you wish to add new engine support - read tutorial. Also you can search existing extensions in npm.

Notice on upgrade to 1.4.x

If your project is using autoprefixer or csswring processors:

• upgrade csswring to >=4.x and autoprefixer to >= 6.x
  • if you used legacy autoprefixer-core package, replace it with autoprefixer
• include postcss >= 4.1

Installation

Install Mincer from npm registry:

$ npm install mincer

Using Mincer from CLI

To use Mincer from CLI, you will need to install it globally:

$ npm install mincer -g

Usage is really simple (see mincer -h for details):

$ mincer --include assets/javascripts \
         --include assets/stylesheets \
         --output public/assets \
         application.js application.css

If you are using mincer CLI often, you would probably want to "preset" some of the options/arguments for your project. Just create .mincerrc file and put argument you want in it. For example:

--include assets/javascripts --include assets/stylesheets --output public/assets

Understanding the Mincer Environment

You'll need an instance of the Mincer.Environment class to access and serve assets from your application.

The Environment has methods for retrieving and serving assets, manipulating the load path, and registering processors. It is also used by Mincer.Server which can be mounted directly as request event handler of http.Server or as connect middleware.

The Load Path

The load paths is an ordered list of directories that Mincer uses to search for assets.

In the simplest case, a Mincers environment's load path will consist of a single directory containing your application's asset source files. When mounted, server will serve assets from this directory as if they were static files in your public root.

The power of the load path is that it lets you organize your source files into multiple directories -- even directories that live outside your application -- and combine those directories into a single virtual filesystem. That means you can easily bundle JavaScript, CSS and images into a library and import them into your application.

Manipulating the Load Path

To add a directory to your environment's load path, use the appendPath and prependPath methods. Directories at the beginning of the load path have precedence over subsequent directories.

environment = new Mincer.Environment();
environment.appendPath('app/assets/javascripts');
environment.appendPath('lib/assets/javascripts');
environment.appendPath('vendor/assets/jquery');

In general, you should append to the path by default and reserve prepending for cases where you need to override existing assets.

Accessing Assets

Once you've set up your environment's load path, you can mount the environment as a server and request assets via HTTP. You can also access assets programmatically from within your application.

Logical Paths

Assets in Mincer are always referenced by their logical path.

The logical path is the path of the asset source file relative to its containing directory in the load path. For example, if your load path contains the directory app/assets/javascripts:

<table> <tr> <th>Asset source file</th> <th>Logical path</th> </tr> <tr> <td>app/assets/javascripts/application.js</td> <td>application.js</td> </tr> <tr> <td>app/assets/javascripts/models/project.js</td> <td>models/project.js</td> </tr> </table>

In this way, all directories in the load path are merged to create a virtual filesystem whose entries are logical paths.

Serving Assets Over HTTP

When you mount an environment, all of its assets are accessible as logical paths underneath the mount point. For example, if you mount your environment at /assets and request the URL /assets/application.js, Mincer will search your load path for the file named application.js and serve it.

var connect = require('connect');
var Mincer  = require('mincer');

var environment = new Mincer.Environment();
environment.appendPath('app/assets/javascripts');
environment.appendPath('app/assets/stylesheets');

var app = connect();
app.use('/assets', Mincer.createServer(environment));
app.use(function (req, res) {
  // your application here...
});

Accessing Assets Programmatically

You can use the findAsset method to retrieve an asset from a Mincers environment. Pass it a logical path and you'll get a BundledAsset instance back.

Call toString on the resulting asset to access its contents, length to get its length in bytes, mtime to query its last-modified time, and pathname to get its full path on the filesystem.

var asset = environment.findAsset('application.js');

asset.toString(); // resulting contents
asset.length;     // length in bytes
asset.mtime;      // last modified time
asset.pathname;   // full path on the filesystem

Using Engines

Asset source files can be written in another language, like Stylus or CoffeeScript, and automatically compiled to CSS or JavaScript by Mincer. Compilers for these languages are called engines.

Engines are specified by additional extensions on the asset source filename. For example, a CSS file written in Stylus might have the name layout.css.styl, while a JavaScript file written in CoffeeScript might have the name dialog.js.coffee.

Styling with Stylus

Stylus is a revolutionary new language, providing an efficient, dynamic, and expressive way to generate CSS. Supporting both an indented syntax and regular CSS style.

If the stylus Node module is available to your application, you can use Stylus to write CSS assets in Mincer. Use the extension .css.styl.

Styling with LESS

LESS extends CSS with dynamic behavior such as variables, mixins, operations and functions.

If the less Node module is available to your application, you can use LESS to write CSS assets in Mincer. Use the extension .css.less.

Styling with Sass

Sass is an extension of CSS3, adding nested rules, variables, mixins, selector inheritance, and more.

If the node-sass Node module is available to your application, you can use Sass to write CSS assets in Mincer. Use the extension .css.sass or .css.scss.

Scripting with CoffeeScript

CoffeeScript is a language that compiles to the "good parts" of JavaScript, featuring a cleaner syntax with array comprehensions, classes, and function binding.

If the coffee-script Node module is available to your application, you can use CoffeeScript to write JavaScript assets in Mincer. Use the extension .js.coffee.

JavaScript Templating with Jade

Mincer supports JavaScript templates for client-side rendering of strings or markup. JavaScript templates have the special format extension .jst and are compiled to JavaScript functions.

When loaded, a JavaScript template function can be accessed by its logical path as a property on the global JST object. Invoke a template function to render the template as a string. The resulting string can then be inserted into the DOM.

// templates/hello.jst.jade
div Hello, #{ name }!

// application.js
//= require templates/hello
$("#hello").html(JST["templates/hello"]({ name: "Sam" }));

Mincer supports one template languages: Jade.

If jade Node module is available to your application, you can use Jade templates in Mincer. Jade templates have the extension .jst.jade. To use compiled templates you will need to require Jade runtime before calling renderer functions.

Invoking JavaScript with EJS

Note see macros description for more convenient alternative.

Mincer provides an EJS engine for preprocessing assets using embedded JavaScript code. Append .ejs to a CSS or JavaScript asset's filename to enable the EJS engine.

You will need ejs Node module available to your application.

Note: Mincer processes multiple engine extensions in order from right to left, so you can use multiple engines with a single asset. For example, to have a CoffeeScript asset that is first preprocessed with EJS, use the extension .js.coffee.ejs.

JavaScript code embedded in an asset is evaluated in the context of a Mincer.Context instance for the given asset. Common uses for EJS include:

• embedding another asset as a Base64-encoded data: URI with the asset_data_uri helper
• inserting the URL to another asset, such as with the asset_path helper (you must register your