0
# Core Compilation
1

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

4
## Capabilities
5

6
### Primary Render Function
7

8
The main entry point that creates a new Renderer instance for compiling Stylus source code.
9

10
```javascript { .api }
11
/**
12
 * Creates a new Renderer instance for compiling Stylus source
13
 * @param {string} str - Stylus source code to compile
14
 * @param {RendererOptions} options - Compilation options
15
 * @returns {Renderer} New Renderer instance
16
 */
17
function stylus(str, options);
18
```
19

20
**Usage Examples:**
21

22
```javascript
23
const stylus = require('stylus');
24

25
// Basic usage
26
const renderer = stylus('body\n  color red');
27
const css = renderer.render();
28

29
// With options
30
const renderer = stylus('body\n  color red', {
31
  compress: true,
32
  filename: 'styles.styl'
33
});
34
```
35

36
### Static Render Function
37

38
Static method for direct compilation with callback support.
39

40
```javascript { .api }
41
/**
42
 * Render Stylus source to CSS with callback
43
 * @param {string} str - Stylus source code
44
 * @param {RendererOptions|Function} options - Options or callback function
45
 * @param {Function} fn - Callback function (err, css)
46
 */
47
function render(str, options, fn);
48
```
49

50
**Usage Examples:**
51

52
```javascript
53
const stylus = require('stylus');
54

55
// With callback only
56
stylus.render('body\n  color red', (err, css) => {
57
  if (err) throw err;
58
  console.log(css);
59
});
60

61
// With options and callback
62
stylus.render('body\n  color red', { compress: true }, (err, css) => {
63
  if (err) throw err;
64
  console.log(css);
65
});
66
```
67

68
### Renderer Class
69

70
The main compilation class providing fine-grained control over the compilation process.
71

72
```javascript { .api }
73
/**
74
 * Main Stylus renderer for compilation control
75
 * @param {string} str - Stylus source code
76
 * @param {RendererOptions} options - Compilation options
77
 */
78
class Renderer {
79
  constructor(str, options);
80
  
81
  /**
82
   * Render to CSS with optional callback
83
   * @param {Function} fn - Optional callback (err, css)
84
   * @returns {string|undefined} CSS string if no callback, undefined otherwise
85
   */
86
  render(fn);
87
  
88
  /**
89
   * Set a renderer option or global variable
90
   * @param {string} key - Option key or variable name
91
   * @param {any} value - Option or variable value
92
   * @returns {Renderer} This renderer for chaining
93
   */
94
  set(key, value);
95
  
96
  /**
97
   * Get a renderer option or global variable
98
   * @param {string} key - Option key or variable name
99
   * @returns {any} Option or variable value
100
   */
101
  get(key);
102
  
103
  /**
104
   * Add an include path for @import statements
105
   * @param {string} path - Directory path to include
106
   * @returns {Renderer} This renderer for chaining
107
   */
108
  include(path);
109
  
110
  /**
111
   * Import a Stylus file
112
   * @param {string} file - File path to import
113
   * @returns {Renderer} This renderer for chaining
114
   */
115
  import(file);
116
  
117
  /**
118
   * Define a custom function or mixin
119
   * @param {string} name - Function/mixin name
120
   * @param {Node|Function} node - AST node or JavaScript function
121
   * @param {boolean} raw - Whether to return raw value
122
   * @returns {Renderer} This renderer for chaining
123
   */
124
  define(name, node, raw);
125
  
126
  /**
127
   * Use a plugin function
128
   * @param {Function} plugin - Plugin function
129
   * @returns {Renderer} This renderer for chaining
130
   */
131
  use(plugin);
132
  
133
  /**
134
   * Get array of file dependencies
135
   * @returns {string[]} Array of imported file paths
136
   */
137
  deps();
138
}
139
```
140

141
**Usage Examples:**
142

143
```javascript
144
const stylus = require('stylus');
145

146
// Basic renderer usage
147
const renderer = new stylus.Renderer('body\n  color red');
148
const css = renderer.render();
149

150
// Advanced configuration
151
const renderer = stylus('body\n  font-size base-font')
152
  .set('compress', true)
153
  .set('base-font', '16px')
154
  .include('./styles')
155
  .include('./mixins')
156
  .import('variables.styl')
157
  .define('add', (a, b) => a.val + b.val)
158
  .use(somePlugin);
159

160
// Get dependencies
161
const deps = renderer.deps();
162
console.log('Dependencies:', deps);
163

164
// Render with callback
165
renderer.render((err, css) => {
166
  if (err) throw err;
167
  console.log(css);
168
});
169
```
170

171
### CSS Conversion
172

173
Convert existing CSS to Stylus syntax.
174

175
```javascript { .api }
176
/**
177
 * Convert CSS to Stylus syntax
178
 * @param {string} css - CSS source to convert
179
 * @param {ConversionOptions} options - Conversion options
180
 * @returns {string} Stylus source code
181
 */
182
function convertCSS(css, options);
183
```
184

185
**Usage Examples:**
186

187
```javascript
188
const stylus = require('stylus');
189

190
const css = `
191
.header {
192
  color: red;
193
  font-size: 16px;
194
}
195
`;
196

197
const stylusCode = stylus.convertCSS(css);
198
console.log(stylusCode);
199
// Output:
200
// .header
201
//   color red
202
//   font-size 16px
203
```
204

205
## Types
206

207
```javascript { .api }
208
// Main renderer options interface
209
interface RendererOptions {
210
  /** Input filename for error reporting and source maps */
211
  filename?: string;
212
  /** Array of paths to search for @import files */
213
  paths?: string[];
214
  /** Compress output CSS by removing whitespace */
215
  compress?: boolean;
216
  /** Include line numbers in output CSS comments */
217
  linenos?: boolean;
218
  /** Include Firebug-compatible debug information */
219
  firebug?: boolean;
220
  /** Generate source maps (boolean or detailed options) */
221
  sourcemap?: boolean | SourceMapOptions;
222
  /** Include imported CSS files in output */
223
  includeCSS?: boolean;
224
  /** Resolve relative URLs in imports */
225
  resolveURL?: boolean;
226
  /** Hoist @rules to the top level */
227
  hoistAtrules?: boolean;
228
  /** Auto-prefix CSS properties */
229
  prefix?: string;
230
  /** Array of imported file paths */
231
  imports?: string[];
232
  /** Object of custom functions */
233
  functions?: object;
234
  /** Object of global variables */
235
  globals?: object;
236
}
237

238
// Source map generation options
239
interface SourceMapOptions {
240
  /** Include source map comment in CSS */
241
  comment?: boolean;
242
  /** Inline source map in CSS */
243
  inline?: boolean;
244
  /** Include source content in source map */
245
  sourcesContent?: boolean;
246
  /** Base path for source map URLs */
247
  basePath?: string;
248
}
249

250
// CSS conversion options
251
interface ConversionOptions {
252
  /** Property prefix to add */
253
  prefix?: string;
254
  /** Include CSS comments in output */
255
  comment?: boolean;
256
  /** Indentation string for output */
257
  indent?: string;
258
}
259
```