0
# Stylus
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: stylus
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install stylus`
10
- **Node.js**: >=16
11

12
## Core Imports
13

14
```javascript
15
const stylus = require('stylus');
16
```
17

18
For ES modules:
19

20
```javascript
21
import stylus from 'stylus';
22
```
23

24
Individual components:
25

26
```javascript
27
const { render, Renderer, Parser, nodes, functions, utils } = require('stylus');
28
```
29

30
## Basic Usage
31

32
```javascript
33
const stylus = require('stylus');
34

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

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

51
// Synchronous compilation
52
const css = stylus('body\n  color red').render();
53
```
54

55
## Architecture
56

57
Stylus is built around several key components:
58

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

67
## Capabilities
68

69
### Core Compilation
70

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

73
```javascript { .api }
74
// Primary render function - returns new Renderer instance
75
function stylus(str, options);
76

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

80
// Renderer class for advanced compilation control
81
class Renderer {
82
  constructor(str, options);
83
  render(fn);
84
  set(key, value);
85
  get(key);
86
  include(path);
87
  import(file);
88
  define(name, node, raw);
89
  use(plugin);
90
  deps();
91
}
92
```
93

94
[Core Compilation](./core-compilation.md)
95

96
### Parsing & AST System
97

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

100
```javascript { .api }
101
// Parser class for source code analysis
102
class Parser {
103
  constructor(str, options);
104
  parse();
105
  peek();
106
  advance();
107
  accept(type);
108
  expect(type);
109
}
110

111
// Base node class - all AST nodes inherit from this
112
class Node {
113
  constructor();
114
  toJSON();
115
  eval();
116
  clone();
117
  toString();
118
}
119
```
120

121
[Parsing & AST System](./parsing-ast.md)
122

123
### Built-in Functions
124

125
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).
126

127
```javascript { .api }
128
// Color functions
129
function red(color);
130
function green(color);
131
function blue(color);
132
function rgba(r, g, b, a);
133
function lighten(color, amount);
134
function darken(color, amount);
135

136
// Math functions  
137
function abs(n);
138
function ceil(n);
139
function floor(n);
140
function min(a, b);
141
function max(a, b);
142

143
// String functions
144
function length(expr);
145
function substr(string, start, length);
146
function unquote(str);
147
function quote(str);
148
```
149

150
[Built-in Functions](./builtin-functions.md)
151

152
### Utilities & Type System
153

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

156
```javascript { .api }
157
// Path utilities
158
function lookup(path, paths, ignore);
159
function find(path, paths, ignore);
160
function absolute(path);
161
function join(base, path);
162

163
// Type utilities
164
function coerce(left, right);
165
function unwrap(expr);
166
function assertString(node, name);
167
function assertColor(node, name);
168
```
169

170
[Utilities & Type System](./utilities.md)
171

172
### CLI Interface
173

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

176
```bash { .api }
177
# Basic compilation
178
stylus input.styl -o output.css
179

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

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

186
# With plugins and includes
187
stylus -u autoprefixer-stylus -I ./includes input.styl
188
```
189

190
[CLI Interface](./cli-interface.md)
191

192
### Middleware Integration
193

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

196
```javascript { .api }
197
// Middleware function
198
function middleware(options);
199

200
// Middleware options interface
201
interface MiddlewareOptions {
202
  src: string;
203
  dest?: string;
204
  compile?: Function;
205
  compress?: boolean;
206
  firebug?: boolean;
207
  linenos?: boolean;
208
  sourcemap?: boolean;
209
  force?: boolean;
210
}
211
```
212

213
[Middleware Integration](./middleware.md)
214

215
## Types
216

217
```javascript { .api }
218
// Renderer options
219
interface RendererOptions {
220
  filename?: string;
221
  paths?: string[];
222
  compress?: boolean;
223
  linenos?: boolean;
224
  firebug?: boolean;
225
  sourcemap?: boolean | SourceMapOptions;
226
  includeCSS?: boolean;
227
  resolveURL?: boolean;
228
  hoistAtrules?: boolean;
229
  prefix?: string;
230
  imports?: string[];
231
  functions?: object;
232
  globals?: object;
233
}
234

235
// Source map options
236
interface SourceMapOptions {
237
  comment?: boolean;
238
  inline?: boolean;
239
  sourcesContent?: boolean;
240
  basePath?: string;
241
}
242

243
// Parser options
244
interface ParserOptions {
245
  filename?: string;
246
  cache?: boolean;
247
  compress?: boolean;
248
}
249
```