tessl/npm-stylus

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

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Stylus

Name: tessl/npm-stylus
Author: tessl

Stylus is a dynamic CSS preprocessor that provides an expressive and feature-rich language for generating CSS. It offers both indented syntax (similar to Sass) and regular CSS syntax, supporting variables, mixins, conditionals, loops, built-in functions, and advanced features like transparent mixins and property lookup.

Package Information

Package Name: stylus
Package Type: npm
Language: JavaScript
Installation: npm install stylus
Node.js: >=16

Core Imports

const stylus = require('stylus');

For ES modules:

import stylus from 'stylus';

Individual components:

const { render, Renderer, Parser, nodes, functions, utils } = require('stylus');

Basic Usage

const stylus = require('stylus');

// Simple compilation with callback
stylus.render('.foo { color: red; }', (err, css) => {
  if (err) throw err;
  console.log(css); // Output: CSS string
});

// Using Renderer for more control
const renderer = stylus('body\n  font 12px Helvetica, Arial, sans-serif')
  .set('compress', true)
  .include('/path/to/styles');
  
renderer.render((err, css) => {
  if (err) throw err;
  console.log(css);
});

// Synchronous compilation
const css = stylus('body\n  color red').render();

Architecture

Stylus is built around several key components:

Renderer: Main compilation class that processes Stylus source into CSS
Parser: Converts Stylus source code into an Abstract Syntax Tree (AST)
Evaluator: Evaluates AST nodes, resolving variables and function calls
Compiler: Transforms evaluated AST into final CSS output
Node System: 40+ AST node types representing language constructs
Built-in Functions: 60+ functions for color manipulation, math, strings, lists, and utilities
Middleware: Express/Connect integration for automatic compilation

Capabilities

Core Compilation

Main entry points for compiling Stylus source code to CSS, including the primary render function and Renderer class with extensive configuration options.

// Primary render function - returns new Renderer instance
function stylus(str, options);

// Static render with callback
function render(str, options, fn);

// Renderer class for advanced compilation control
class Renderer {
  constructor(str, options);
  render(fn);
  set(key, value);
  get(key);
  include(path);
  import(file);
  define(name, node, raw);
  use(plugin);
  deps();
}

Core Compilation

Parsing & AST System

Comprehensive parsing system that converts Stylus source into a structured Abstract Syntax Tree, with 40+ node types representing all language constructs.

// Parser class for source code analysis
class Parser {
  constructor(str, options);
  parse();
  peek();
  advance();
  accept(type);
  expect(type);
}

// Base node class - all AST nodes inherit from this
class Node {
  constructor();
  toJSON();
  eval();
  clone();
  toString();
}

Parsing & AST System

Built-in Functions

Over 60 built-in functions organized into categories: color manipulation (rgba, hsl, lighten), mathematical operations (abs, ceil, min), string processing (substr, split, unquote), list operations (push, pop, keys), and utility functions (json, lookup, image-size).

// Color functions
function red(color);
function green(color);
function blue(color);
function rgba(r, g, b, a);
function lighten(color, amount);
function darken(color, amount);

// Math functions  
function abs(n);
function ceil(n);
function floor(n);
function min(a, b);
function max(a, b);

// String functions
function length(expr);
function substr(string, start, length);
function unquote(str);
function quote(str);

Built-in Functions

Utilities & Type System

Comprehensive utility functions for path handling, value coercion, type checking, and development support including file lookup, type assertions, and object manipulation.

// Path utilities
function lookup(path, paths, ignore);
function find(path, paths, ignore);
function absolute(path);
function join(base, path);

// Type utilities
function coerce(left, right);
function unwrap(expr);
function assertString(node, name);
function assertColor(node, name);

Utilities & Type System

CLI Interface

Complete command-line interface for file compilation, watching, CSS conversion, and build integration with options for compression, source maps, debugging, and plugin support.

# Basic compilation
stylus input.styl -o output.css

# Watch mode with compression
stylus -w -c input.styl -o output.css

# CSS to Stylus conversion
stylus --css < input.css > output.styl

# With plugins and includes
stylus -u autoprefixer-stylus -I ./includes input.styl

CLI Interface

Middleware Integration

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

// Middleware function
function middleware(options);

// Middleware options interface
interface MiddlewareOptions {
  src: string;
  dest?: string;
  compile?: Function;
  compress?: boolean;
  firebug?: boolean;
  linenos?: boolean;
  sourcemap?: boolean;
  force?: boolean;
}

Middleware Integration

Types

// Renderer options
interface RendererOptions {
  filename?: string;
  paths?: string[];
  compress?: boolean;
  linenos?: boolean;
  firebug?: boolean;
  sourcemap?: boolean | SourceMapOptions;
  includeCSS?: boolean;
  resolveURL?: boolean;
  hoistAtrules?: boolean;
  prefix?: string;
  imports?: string[];
  functions?: object;
  globals?: object;
}

// Source map options
interface SourceMapOptions {
  comment?: boolean;
  inline?: boolean;
  sourcesContent?: boolean;
  basePath?: string;
}

// Parser options
interface ParserOptions {
  filename?: string;
  cache?: boolean;
  compress?: boolean;
}