Mincer: a Sprockets style asset pipeline for Node.js

The Sprockets behaviour, kept in JavaScript

Mincer is a port of Sprockets, and the port targets version 2.10.0 of it. The point of the port is not a new asset model but the same one: declarative dependency management with exactly the same language, applied to CSS and JavaScript through a preprocessor pipeline. An asset file states what it needs, and the compiler works out the order, which is what makes it possible to write assets in CoffeeScript, LESS, Stylus and other languages without hand-maintaining a list of includes. The port adds two things the original does not have: source map support, and a macro facility that the documentation describes as a nice alternative to EJS. That combination, familiar authoring rules plus a couple of conveniences, is the whole pitch, and it is aimed at teams who already know how Sprockets style assets behave.

The load path is a virtual filesystem

Assets are never addressed by their location on disk. They are addressed by a logical path, which is the path of the source file relative to the directory in the load path that contains it, so `app/assets/javascripts/models/project.js` inside a load path containing `app/assets/javascripts` is addressed as `models/project.js`. The load path is an ordered list of directories that Mincer searches, and all of those directories are merged into a single virtual filesystem whose entries are logical paths. That merging is what lets you keep JavaScript, CSS and images in separate directories, or put directories outside the application entirely, and still import them as if they lived together. Directories are added with `appendPath` and `prependPath`, and order decides precedence:

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

The guidance is to append by default and to reserve prepending for the case where you deliberately want to override an existing asset.

Mounting the environment as HTTP middleware

The `Mincer.Environment` instance is the centre of the library. It has methods for retrieving and serving assets, for manipulating the load path, and for registering processors, and it is also what `Mincer.Server` is built on. When you mount an environment, every asset in it becomes reachable as a logical path underneath the mount point, so mounting at `/assets` and requesting `/assets/application.js` makes Mincer search the load path for the file named `application.js` and serve it. The server can be mounted directly as a `request` event handler of `http.Server` or used as connect middleware, and the connect route is the short version:

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

Served in development, this means the assets are compiled on request rather than pre-built into a public directory, which is the same split the Sprockets model made between serving and precompiling.

Reading assets from application code

Not every consumer is a browser, so the environment also hands out assets programmatically. The `findAsset` method takes a logical path and returns a `BundledAsset` instance, and that instance exposes the compiled result in four ways: `toString` for the contents, `length` for the size in bytes, `mtime` for the last modified time, and `pathname` for the 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

This is the seam where the compile step stops being a build script and becomes an API, which is how the same environment can serve a request and also hand a string to another part of the process. The bundled asset is a single object with those four accessors, so a caller that needs to know whether the asset changed on disk has `mtime` rather than a diff.

The CLI, and the .mincerrc file that presets it

Mincer is published on the npm registry, and installing it locally is the normal first step:

    $ npm install mincer

To drive it from the command line you install it globally:

    $ npm install mincer -g

The invocation names the include directories, the output directory and the entry assets to compile:

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

If the CLI is used often, the documentation suggests keeping a `.mincerrc` file in the project with the arguments you always pass, so the repeated options live in one place:

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

The repository ships an `examples/` directory that includes its own `.mincerrc`, plus `environment.js`, `server.js` and a `manifest.js`, which is the quickest way to see how the pieces fit together in a running app rather than only in documentation.

Engines are chosen by file extension

The preprocessor step is handled by engines, and an engine is selected by an extra extension on the source filename: a CSS file written in Stylus is named `layout.css.styl`, and a JavaScript file written in CoffeeScript is named `dialog.js.coffee`. The compiler picks the engine from that suffix and produces CSS or JavaScript from it. The list of supported engines is maintained on the project wiki rather than in the main documentation, which is worth knowing before you plan an asset directory around a particular language. Adding a new engine is a separate exercise with its own tutorial, and the documentation points at the existing extensions published on npm under the `mincer-contrib` keyword, so the ecosystem of addons already exists rather than having to be written from scratch. The `mincer-contrib` naming is also a practical signal: if your language is not on the wiki list, check npm before assuming it is missing.

Limited maintenance and a processor upgrade to plan for

The project carries an explicit note that it is now under limited maintenance, and the last push was on 2026-04-10. The package manifest still shows version 2.1.0, the repository has no GitHub releases, and the default branch is `master`, so the usual way to pick up a change is to install a version from npm rather than to track tags. One upgrade note is specific enough to matter: projects using `autoprefixer` or `csswring` processors are told to move to `csswring` 4.x or newer and `autoprefixer` 6.x or newer, to replace the legacy `autoprefixer-core` package with `autoprefixer`, and to include `postcss` 4.1 or newer. The manifest lists `postcss` among the development dependencies, and the test and lint workflow runs through the Makefile targets `make test` and `make lint` with mocha and eslint. The licence is MIT, so nothing here blocks commercial use of the library itself.

Editorial conclusion

Mincer fits a Node.js application that already thinks in Sprockets style declarations, where assets are composed with require-like directives inside the files and the team wants the same authoring model without moving to Ruby. It is a poor fit for a greenfield bundle pipeline, since the project is under limited maintenance with the last push on 2026-04-10, the package still carries a 2.1.0 version string, and the repository publishes no GitHub releases, so an upgrade path has to be planned by hand. Before adopting it, read the upgrade notes for the 1.4.x processors, because autoprefixer needs to be at 6.x or newer, csswring at 4.x or newer and postcss at 4.1 or newer, and check the supported engines page in the project wiki against the languages your assets are written in.

Frequently asked questions

Official sources

1. Issues
2. js-kyle/mincer on GitHub
3. License: MIT
4. Project website
5. README