A generic interface to various JavaScript and CSS preprocessors. Autodetects formats based on filename and mimetype.

npm install tilt
1 downloads in the last day
4 downloads in the last week
13 downloads in the last month


Build Status

Tilt.js is a generic interface to various JavaScript and CSS preprocessors, like LESS, Jade, CoffeeScript, HAML and so on, written in CoffeeScript for the node.js platform. Tilt.js autodetects file formats based on path and mimetype.

For template languages that support it, Tilt.js can also do precompilation, which parses the template and turns it into a JavaScript function for faster client-side rendering. Compile with tilt.compile and precompile with tilt.preCompile, both of which take a tilt.File object, a context object (mainly useful for templates languages) and a callback with the result.

When rendering a template, you pass Tilt.js a context object containing all the variables your template depends on and you get rendered html (or precompiled JavaScript, so you desire) in return.


Install with npm install tilt.


var tilt = require('tilt');
var file = new tilt.File({path: 'homepage.jade'});
tilt.compile(file, {page_title: 'Hello world'}, function(template){
    // this is the rendered html template
    // (or css, or javascript)

Tilt.js has a small, legible codebase, so feel free to browse through the code for more information.


Supported formats


Compile-to-JavaScript languages

CSS preprocessors


  • JSON
  • YAML
  • CSV (soon)


  • Markdown (soon)
  • Textile (soon)

Adding new handlers

Handlers are little wrappers for (pre)compilers, written in CoffeeScript. All handlers are in src/handlers and you can easily add your own.

A handler looks like this:

stylus = require 'stylus'

module.exports =
    extensions: ['styl']
        source: 'stylesheet/stylus'
        output: 'text/css'
    compiler: (file, context, send) ->
        stylus(file.content).render (err, css) ->
            if err
                send err
                send css

The requested file (in its plain/uncompiled state) will be available to you in file.content, and the file path is accessible through file.path.

The second parameter, context includes data you should pass to your template as context. Of course, this only applies to template engines, not CSS preprocessors and the like.

The third parameter, send, is a function you should call with the compiled code.

Draughtsman automatically picks up any and all handlers in the handlers directory, though you'll need to run make on the app to recompile the code to JavaScript to include your handlers.

Tilt.js is a library for node.js, but handlers' processing doesn't need to happen in node.js itself. Handlers can spawn child processes to do the heavy lifting. That way, you can make a handler for anything that has a command-line tool, regardless of the language it's implemented in. For example, here's an alternative implementation of a CoffeeScript handler:

exec = require('child_process').exec

module.exports =
    extensions: ['coffee']
        source: 'text/coffeescript'
        output: 'application/javascript'
    compiler: (file, context, send) ->
        exec 'coffee -cp #{file.path}', (error, stdout, stderr) ->
            if error
                send error
                send stdout

Using exec is particularly useful for compilers that are intended to be used through the shell, such as for the SASS stylesheet preprocessor, or when you need to write your own precompiler, for example a Python script that renders a file using the Jinja or Django template language.

Tilt.js is a cousin of Tilt, an unaffiliated but very similar library for Ruby.

Extracted from (and used in) the Draughtsman front-end prototyping server.

Tilt.js works really well together with Espy, a context finder which is a useful building block for static site generators and is also useful if you need to prototype without a database.

npm loves you