Stylus Plugin Use

This document will briefly review a few of the more common ways of using stylus plugins for those who are not familiar. Throughout these examples, we will be using a non-existant stylus plugin called example. Please change example out for whatever plugin you are actually trying to use!

Standalone/Node

First example is for if you are building your own stylus pipeline in node. This is a pretty standard way to do things.

var stylus = require('stylus'),
    example = require('example');

stylus(fs.readFileSync('./example.styl', 'utf8'))
  .use(example())
  .render(function(err, css){
    if (err) return console.error(err);
    console.log(css);
  });

I also made a library called accord that serves as an interface to a number of different compiled js languages, and is very well integrated with stylus. An example is given below using accord:

var accord = require('accord'),
    stylus = accord.load('stylus'),
    example = require('example')

stylus.renderFile('./example.styl', { use: axis() })
  .catch(console.error.bind(console))
  .done(console.log.bind(console))

I'll usually use accord when precompiling anything, because chances are if you are compiling one thing, you'll also need to compile other things. And having a unified interface makes things a lot cleaner and easier in your code.

Command Line

You can use stylus plugins from the command line if you install with npm install example -g. Not recommended, but some people like it this way. When doing it like this, you can use multiple plugins, but cannot specify options for any of them. Example below:

$ stylus -u example -c example.styl

Express

Finally, you might want to use it with the popular node server, express. Example of this shown below:

var express = require('express'),
    stylus = require('stylus'),
    example = require('example');
 
... etc ...

app.configure(function () {
  app.use(stylus.middleware({
    src: __dirname + '/views',
    dest: __dirname + '/public',
    compile: function (str, path, fn) {
      stylus(str)
        .set('filename', path)
        .use(example())
        .render(fn);
    }
  }));
});

... etc ...

Roots

Roots is a versatile static site compiler that works nicely with stylus. If you are looking to build a simple website using stylus, roots is probably a good choice for getting off the ground quickly. To use stylus plugins with roots, you can install through npm, then include them directly through app.coffee.

From the command line: npm install example --save

In your app.coffee file:

example = require('example')

module.exports = 

  stylus:
    use: example()

If you want to use multiple plugins, just give use an array containing the plugins instead. Fairly straightforward stuff.

Other Uses

If you have another way you prefer to use stylus plugins, please let me know and I'll update this document to reflect!

jescalan/stylus-plugins.md