Frank Perez

Frank Perez

Keep in touch

An experienced Web Developer with years of experience in design, programming and server administration.



© 2024 by Frank Perez.

Configuring Stylus CSS Pre-Processor with Gulp and Sourcemaps

In this article we’ll go over how to configure your project to process Stylus files using Gulp. We’ll also create source map file which your browser will use to help point you in the right direction of your files when developing


If you’re in a new project, with no package.json file present, you’ll want to start off by typing yarn init to get this file setup.

Now let’s get gulp installed.

yarn add gulp

Secondly, we’ll want to install gulp-stylus.

yarn add gulp-stylus

Lastly, let’s install gulp-sourcemaps, this way when we’re developing and using our development tools within the browser we’ll be able easily pin point in which file our code resides.

yarn add gulp-sourcemaps


Now that we have our packages installed, lets start by setting up our base gulpfile.js file.

var gulp = require('gulp');
var stylus = require('gulp-stylus');
var sourcemaps = require('gulp-sourcemaps');

gulp.task('default', function() {
    return gulp.src('./assets/styl/main.styl')
        .pipe(sourcemaps.write('.', {
            includeContent: false,
            sourceRoot: '../../assets/styl/'

Here’s a breakdown of what is going on above.

  1. We pass the source for where our stylus data can be found. ./assets/styl/main.styl
  2. We then initialize our source maps plugin.
  3. Next we’ll write the source maps file as a external file to the current directory, while also changing the root of the document.
  4. Finally, we’ll output to rendered stylus file to our destination in ./build/css/.

Now every time you run the gulp command, the above will generate a new CSS file, along with the new corresponding source map file.