Starting a project with Express, node.js and Stylus

Node.js gets a lot of attention lately, out of curiosity I decided to try it out. After reading the excellent hands-on node e-book I wanted to port one of my pet projects, a price comparer between different IKEA branches (site is offline) written in ASP.Net MVC to node.js. As a web framework I went for Express. In this blog post I’ll show you how you can get Express to generate a very basic app for you and how you can use Stylus in combination with Express.

First of all make sure that node and the node package manager are installed on your system, it can be downloaded from the node.js website. Once that is done, you can let Express generate a basic application structure for you. You don’t have to use that folder structure but it gives you a nice head start. It’s ridiculously easy, open terminal and browse to the folder where you want to put your new project and type the following command:

$ express

Express has generated a few files and folders for you. But before you can run your newly generated web application you have to install the dependencies that express uses. You can use the node package manager (NPM) for that. Just use the following command:

$ npm install

If all went well, you can now access your application by pointing your browser to http://localhost:3000. Don’t forget to start the app before surfing with the command:

$ node app.js

Now that we have a very basic application up and running it’s time to make our web pages pretty. Because plain CSS is so 2004, I was looking for something like LESS or SASS. I stumbled on Stylus, it’s an expressive CSS language that is specifically built for node. Its syntax is similar to the Jade templating engine’s syntax. Installing it is easy with NPM:

$ npm install stylus

Stylus provides you with Connect middleware that you can use in Express to configure stylus. In the following code snippet you can see the middleware in action, you should add lines 8 to 12 to your app.js:

app.configure(function(){
   app.set('views', __dirname + '/views');
   app.set('view engine', 'jade');
   app.use(express.bodyParser());
   app.use(express.methodOverride());
   app.use(app.router);
   app.use(stylus.middleware(
   				  {
					src: __dirname + '/views',
					dest: __dirname + '/public'
  	              }));
    app.use(express.static(__dirname + '/public'));
});

If you take a closer look to the added lines, you see we give the stylus middleware a source and destination directory where to find the necessary files. Don’t forget to require stylus in your app.js like this:

var stylus = require('stylus');

The middleware will search for *.styl files in the source (src) directory and compile them to *.css in the destination (dest) directory. Look out! At first I wanted to be fancy and place my stylus files in neatly organized folders, you can do that as long as the folder is a subfolder of the src property that you set in your configuration. For example if you put your *.styl files in a stylesheets subfolder under views, your source directory is still __dirname + ‘/views’, __dirname + ‘/views/stylesheets’ will not work!

Now we add a *.styl file in the source folder (or a subfolder of the source folder) and add a link element to the compiled *.css file in our main layout.jade file. The template file looks like this:

!!!
html
	head
		title= title
		link(rel='stylesheet', href='/stylesheets/style.css')
	body!= body

If all went well, rerun the application via the node command and point your browser at http://localhost:3000. The css file will be compiled automatically by stylus and applied to the web page by the browser. You can now start building your app!

All code of this example can be found in a repository in my GitHub account.

'Till next time.