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
```