Why Isn’t Stylus Compiling my CSS?

I ran into this gotcha yesterday and thought I’d post in case anyone else out there is wondering why their Stylus module isn’t compiling their .styl files into CSS.

First off you don’t need to install Stylus globally via :

    npm install stylus -g

You can of course if you want to but I prefer to bind the exact version of Stylus I’m using in a project to the project itself via its package.json file.

// package.json //
"dependencies": {
    "express": "3.1.0",
    "jade": "0.28.1",
    "stylus": "0.32.0",
},

This way everyone on the project is working with the same version of Stylus and you’re free to use other versions of the module on other projects as needed.

Next when you configure your application be sure your static directives comes after the directive to include the stylus middleware.

app.configure(function(){
    app.set('port', 8080);
    app.set('views', __dirname + '/views');
    app.set('view engine', 'jade');
    app.locals.pretty = true;
    app.use(express.bodyParser());
    app.use(express.cookieParser());
    app.use(express.session({ secret: 'super-duper-secret-secret' }));
    app.use(express.methodOverride());
    app.use(require("stylus").middleware({
        compress: true,
        src: __dirname + "/public"
    }));
// this must come after the directive to include the stylus middleware //
    app.use(express.static(__dirname + '/public'));
});

Lastly, and here is the gotcha –

Unless you’re manually telling Stylus to compile your files via the command file, by default Stylus will only compile your .styl files when they are requested by the browser.

I was under the assumption, as I imagine a lot of other people are, that Stylus would compile my file whenever I made some changes to it and hit save.

Not the case, to see Stylus compile your file either navigate to your file in a browser or include it an HTML page and request that page.

    <link rel="stylesheet" href="/style.css" />

Hope this saves someone else out there a bit of head scratching.