or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

index.md

tile.json

Gulp Stylus

Gulp Stylus is a Gulp plugin that compiles Stylus CSS preprocessor files (.styl) into CSS (.css) using the Accord library wrapper around the Stylus engine. It provides comprehensive support for sourcemaps, compression, variable definition, and all standard Stylus compilation options within Gulp streaming build workflows.

Package Information

Package Name: gulp-stylus
Package Type: npm
Language: JavaScript
Installation: npm install --save-dev gulp-stylus

Core Imports

const stylus = require('gulp-stylus');

For accessing the underlying Stylus engine:

const gulpStylus = require('gulp-stylus');
const originalStylus = gulpStylus.stylus;

Basic Usage

const gulp = require('gulp');
const stylus = require('gulp-stylus');

// Basic Stylus compilation
gulp.task('stylus', function () {
  return gulp.src('./src/**/*.styl')
    .pipe(stylus()) 
    .pipe(gulp.dest('./dist/css'));
});

// With options
gulp.task('stylus-compressed', function () {
  return gulp.src('./src/**/*.styl')
    .pipe(stylus({
      compress: true,
      linenos: true
    }))
    .pipe(gulp.dest('./dist/css'));
});

Architecture

Gulp Stylus is built around several key components:

Stream Transform: Returns a through2 object stream that processes Vinyl files
Accord Integration: Uses the Accord library as a wrapper around the Stylus engine for consistent compilation
File Processing: Automatically handles file extension changes (.styl → .css) and encoding
Sourcemap Support: Integrates with both native Stylus sourcemaps and gulp-sourcemaps
Error Handling: Provides comprehensive error wrapping with PluginError
Data Integration: Supports gulp-data for dynamic variable injection

Capabilities

Stylus Compilation Plugin

Main plugin function that creates a Gulp transform stream for compiling Stylus files to CSS.

/**
 * Creates a Gulp transform stream for Stylus compilation
 * @param {Object} options - Compilation options passed to Accord/Stylus
 * @returns {Transform} through2 transform stream
 */
function gulpStylus(options);

Parameters:

options (Object, optional): Compilation options object supporting all Stylus options

Supported Options:

interface StylusOptions {
  /** Enable output compression */
  compress?: boolean;
  /** Include line numbers in output */
  linenos?: boolean;
  /** Enable sourcemap generation or provide sourcemap options */
  sourcemap?: boolean | {
    /** Base path for sourcemap generation */
    basePath?: string;
  };
  /** Define variables accessible in Stylus files */
  define?: Object;
  /** Pass raw objects to Stylus */
  rawDefine?: Object;
  /** Import additional Stylus files */
  import?: string | string[];
  /** Enable CSS inclusion */
  'include css'?: boolean;
  /** Override filename (automatically set from file.path) */
  filename?: string;
  // All other standard Stylus/Accord options are supported
}

Returns:

Transform stream that processes .styl files to .css files

Stream Behavior:

Streaming input: Not supported - throws PluginError with message "Streaming not supported"
Null files: Passed through unchanged
CSS files: Files with .css extension are passed through unchanged
Stylus files: Files with other extensions (typically .styl) are compiled to CSS

Usage Examples:

// Basic compilation
gulp.src('**/*.styl')
  .pipe(stylus())
  .pipe(gulp.dest('dist'));

// With compression and line numbers
gulp.src('**/*.styl')
  .pipe(stylus({
    compress: true,
    linenos: true
  }))
  .pipe(gulp.dest('dist'));

// With variable definitions
gulp.src('**/*.styl')
  .pipe(stylus({
    define: {
      primaryColor: '#ff0000',
      debug: true
    }
  }))
  .pipe(gulp.dest('dist'));

// With imports
gulp.src('**/*.styl')
  .pipe(stylus({
    import: ['./src/mixins.styl', './src/variables.styl']
  }))
  .pipe(gulp.dest('dist'));

// With gulp-data integration
const data = require('gulp-data');

gulp.src('**/*.styl')
  .pipe(data(function(file) {
    return {
      componentPath: '/' + file.relative.replace(/\/[^\/]*$/, '')
    };
  }))
  .pipe(stylus()) // Automatically uses file.data for variables
  .pipe(gulp.dest('dist'));

Sourcemap Integration

// Native Stylus sourcemaps
gulp.src('**/*.styl')
  .pipe(stylus({
    sourcemap: true
  }))
  .pipe(gulp.dest('dist'));

// With custom sourcemap options
gulp.src('**/*.styl')
  .pipe(stylus({
    sourcemap: {
      basePath: './src'
    }
  }))
  .pipe(gulp.dest('dist'));

// External sourcemaps with gulp-sourcemaps
const sourcemaps = require('gulp-sourcemaps');

gulp.src('**/*.styl')
  .pipe(sourcemaps.init())
  .pipe(stylus())
  .pipe(sourcemaps.write('.'))
  .pipe(gulp.dest('dist'));

Stylus Engine Access

Direct access to the underlying Stylus module for advanced usage scenarios.

/**
 * Direct access to the underlying Stylus module
 * @type {Object} The Stylus module
 */
gulpStylus.stylus;

Usage Example:

const gulpStylus = require('gulp-stylus');
const stylus = gulpStylus.stylus;

// Use original Stylus directly for advanced configuration
const stylusRenderer = stylus('./input.styl')
  .set('filename', './input.styl')
  .define('url', stylus.url());

Error Handling

The plugin provides comprehensive error handling for common scenarios:

Parse Errors: Stylus compilation errors are wrapped in PluginError and emitted to the stream
Stream Errors: Streaming input throws immediate PluginError: "Streaming not supported"
File Errors: File processing errors are caught and wrapped appropriately

gulp.src('**/*.styl')
  .pipe(stylus())
  .on('error', function(err) {
    console.error('Stylus compilation error:', err.message);
    // Handle error appropriately
  })
  .pipe(gulp.dest('dist'));

Integration Patterns

With gulp-data

Automatically consumes data attached to Vinyl files for variable definition:

const data = require('gulp-data');

gulp.src('components/**/*.styl')
  .pipe(data(function(file) {
    return {
      componentPath: '/' + file.path.replace(file.base, '').replace(/\/[^\/]*$/, '')
    };
  }))
  .pipe(stylus()) // Uses file.data automatically
  .pipe(gulp.dest('dist'));

With gulp-sourcemaps

Full integration support for external sourcemap generation:

const sourcemaps = require('gulp-sourcemaps');

gulp.src('**/*.styl')
  .pipe(sourcemaps.init())
  .pipe(stylus({
    compress: process.env.NODE_ENV === 'production'
  }))
  .pipe(sourcemaps.write('./maps'))
  .pipe(gulp.dest('dist'));

Build Pipeline Integration

const gulp = require('gulp');
const stylus = require('gulp-stylus');
const autoprefixer = require('gulp-autoprefixer');
const cssnano = require('gulp-cssnano');
const sourcemaps = require('gulp-sourcemaps');

gulp.task('css', function() {
  return gulp.src('src/styles/**/*.styl')
    .pipe(sourcemaps.init())
    .pipe(stylus({
      'include css': true,
      import: ['src/styles/variables.styl']
    }))
    .pipe(autoprefixer())
    .pipe(cssnano())
    .pipe(sourcemaps.write('.'))
    .pipe(gulp.dest('dist/css'));
});