tessl/npm-stylus

Robust, expressive, and feature-rich CSS superset with dynamic preprocessing capabilities

—

Pending

Overview

Eval results

Files

Middleware Integration

Name: tessl/npm-stylus
Author: tessl

Express/Connect middleware for automatic Stylus compilation in web applications with configurable paths, compression, source maps, and development features.

Capabilities

Basic Middleware

Core middleware function for integrating Stylus compilation into web servers.

/**
 * Create Stylus middleware for Express/Connect applications
 * @param {MiddlewareOptions} options - Middleware configuration
 * @returns {Function} Express/Connect middleware function
 */
function middleware(options);

Middleware Function

The returned middleware function signature.

/**
 * Stylus middleware function (returned by middleware())
 * @param {Request} req - Express request object
 * @param {Response} res - Express response object  
 * @param {Function} next - Next middleware function
 */
function stylusMiddleware(req, res, next);

Configuration Options

interface MiddlewareOptions {
  /** Source directory for Stylus files */
  src: string;
  
  /** Destination directory for compiled CSS (defaults to src) */
  dest?: string;
  
  /** Custom compile function */
  compile?: (str: string, path: string) => string;
  
  /** Compress output CSS */
  compress?: boolean;
  
  /** Include Firebug debug information */
  firebug?: boolean;
  
  /** Include line numbers in output */
  linenos?: boolean;
  
  /** Generate source maps */
  sourcemap?: boolean | SourceMapOptions;
  
  /** Force recompilation on every request */
  force?: boolean;
}

interface SourceMapOptions {
  /** Include source map comment in CSS */
  comment?: boolean;
  /** Inline source map in CSS */
  inline?: boolean;
  /** Include source content in source map */
  sourcesContent?: boolean;
  /** Base path for source map URLs */
  basePath?: string;
}

Usage Examples

Basic Express Integration

const express = require('express');
const stylus = require('stylus');

const app = express();

// Basic middleware setup
app.use(stylus.middleware({
  src: __dirname + '/public'
}));

app.use(express.static(__dirname + '/public'));

app.listen(3000);

Advanced Configuration

const express = require('express');
const stylus = require('stylus');
const path = require('path');

const app = express();

// Advanced middleware with all options
app.use(stylus.middleware({
  // Source directory for .styl files
  src: path.join(__dirname, 'src/styles'),
  
  // Destination directory for .css files
  dest: path.join(__dirname, 'public/css'),
  
  // Compression for production
  compress: process.env.NODE_ENV === 'production',
  
  // Debug information for development
  firebug: process.env.NODE_ENV === 'development',
  linenos: process.env.NODE_ENV === 'development',
  
  // Source maps
  sourcemap: {
    comment: true,
    inline: process.env.NODE_ENV === 'development',
    sourcesContent: true
  },
  
  // Force recompilation in development
  force: process.env.NODE_ENV === 'development'
}));

// Serve static files
app.use(express.static(path.join(__dirname, 'public')));

Custom Compile Function

const express = require('express');
const stylus = require('stylus');
const nib = require('nib');

const app = express();

app.use(stylus.middleware({
  src: __dirname + '/public',
  
  // Custom compilation with plugins
  compile: function(str, path) {
    return stylus(str)
      .set('filename', path)
      .set('compress', true)
      .use(nib())
      .import('nib');
  }
}));

app.use(express.static(__dirname + '/public'));

Different Source and Destination

const express = require('express');
const stylus = require('stylus');

const app = express();

// Compile from src/ to public/css/
app.use(stylus.middleware({
  src: __dirname + '/src/styles',    // .styl files location
  dest: __dirname + '/public/css',   // .css files output
  compress: true
}));

// Serve compiled CSS from public/css/
app.use('/css', express.static(__dirname + '/public/css'));

// Serve other static files
app.use(express.static(__dirname + '/public'));

Development vs Production

const express = require('express');
const stylus = require('stylus');

const app = express();
const isDevelopment = process.env.NODE_ENV === 'development';

app.use(stylus.middleware({
  src: __dirname + '/src/styles',
  dest: __dirname + '/public/css',
  
  // Development settings
  compress: !isDevelopment,
  linenos: isDevelopment,
  firebug: isDevelopment,
  force: isDevelopment,
  
  // Source maps in development
  sourcemap: isDevelopment ? {
    inline: true,
    sourcesContent: true
  } : false
}));

With Plugins and Includes

const express = require('express');
const stylus = require('stylus');
const nib = require('nib');
const autoprefixer = require('autoprefixer-stylus');

const app = express();

app.use(stylus.middleware({
  src: __dirname + '/src/styles',
  dest: __dirname + '/public/css',
  
  compile: function(str, path) {
    return stylus(str)
      .set('filename', path)
      .set('compress', process.env.NODE_ENV === 'production')
      .include(__dirname + '/src/styles/mixins')
      .include(__dirname + '/src/styles/variables')
      .use(nib())
      .use(autoprefixer())
      .import('nib');
  }
}));

Workflow Integration

Express.js Application Structure

project/
├── src/
│   └── styles/
│       ├── main.styl
│       ├── variables.styl
│       └── mixins/
│           └── buttons.styl
├── public/
│   ├── css/           # Generated CSS files
│   ├── js/
│   └── images/
└── app.js

Complete Express Setup

const express = require('express');
const stylus = require('stylus');
const path = require('path');

const app = express();
const port = process.env.PORT || 3000;

// Stylus middleware
app.use(stylus.middleware({
  src: path.join(__dirname, 'src/styles'),
  dest: path.join(__dirname, 'public/css'),
  compress: process.env.NODE_ENV === 'production',
  sourcemap: process.env.NODE_ENV === 'development',
  force: process.env.NODE_ENV === 'development'
}));

// Static file serving
app.use(express.static(path.join(__dirname, 'public')));

// Routes
app.get('/', (req, res) => {
  res.send(`
    <html>
      <head>
        <link rel="stylesheet" href="/css/main.css">
      </head>
      <body>
        <h1>Stylus Middleware Example</h1>
      </body>
    </html>
  `);
});

app.listen(port, () => {
  console.log(`Server running at http://localhost:${port}`);
});

Error Handling

const express = require('express');
const stylus = require('stylus');

const app = express();

app.use(stylus.middleware({
  src: __dirname + '/src/styles',
  dest: __dirname + '/public/css',
  
  compile: function(str, path) {
    try {
      return stylus(str)
        .set('filename', path)
        .render();
    } catch (err) {
      console.error('Stylus compilation error:', err.message);
      throw err;
    }
  }
}));

// Error handling middleware
app.use((err, req, res, next) => {
  if (err && err.name === 'ParseError') {
    console.error('Stylus parse error:', err.message);
    res.status(500).send('CSS compilation error: ' + err.message);
  } else {
    next(err);
  }
});

Caching and Performance

The middleware automatically handles:

File modification checking - Only recompiles when .styl files change
Dependency tracking - Recompiles when imported files change
Output caching - Serves cached CSS when source hasn't changed
Memory efficiency - Doesn't keep compiled output in memory

Performance tips:

// For production - disable force compilation
app.use(stylus.middleware({
  src: __dirname + '/styles',
  force: false,  // Only compile when files change
  compress: true  // Minify output
}));

// For development - enable debugging features
app.use(stylus.middleware({
  src: __dirname + '/styles',
  force: true,    // Always recompile for debugging
  linenos: true,  // Line numbers for debugging
  sourcemap: true // Source maps for debugging
}));

Install with Tessl CLI