0
# Middleware Integration
1

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

4
## Capabilities
5

6
### Basic Middleware
7

8
Core middleware function for integrating Stylus compilation into web servers.
9

10
```javascript { .api }
11
/**
12
 * Create Stylus middleware for Express/Connect applications
13
 * @param {MiddlewareOptions} options - Middleware configuration
14
 * @returns {Function} Express/Connect middleware function
15
 */
16
function middleware(options);
17
```
18

19
### Middleware Function
20

21
The returned middleware function signature.
22

23
```javascript { .api }
24
/**
25
 * Stylus middleware function (returned by middleware())
26
 * @param {Request} req - Express request object
27
 * @param {Response} res - Express response object  
28
 * @param {Function} next - Next middleware function
29
 */
30
function stylusMiddleware(req, res, next);
31
```
32

33
## Configuration Options
34

35
```javascript { .api }
36
interface MiddlewareOptions {
37
  /** Source directory for Stylus files */
38
  src: string;
39
  
40
  /** Destination directory for compiled CSS (defaults to src) */
41
  dest?: string;
42
  
43
  /** Custom compile function */
44
  compile?: (str: string, path: string) => string;
45
  
46
  /** Compress output CSS */
47
  compress?: boolean;
48
  
49
  /** Include Firebug debug information */
50
  firebug?: boolean;
51
  
52
  /** Include line numbers in output */
53
  linenos?: boolean;
54
  
55
  /** Generate source maps */
56
  sourcemap?: boolean | SourceMapOptions;
57
  
58
  /** Force recompilation on every request */
59
  force?: boolean;
60
}
61

62
interface SourceMapOptions {
63
  /** Include source map comment in CSS */
64
  comment?: boolean;
65
  /** Inline source map in CSS */
66
  inline?: boolean;
67
  /** Include source content in source map */
68
  sourcesContent?: boolean;
69
  /** Base path for source map URLs */
70
  basePath?: string;
71
}
72
```
73

74
## Usage Examples
75

76
### Basic Express Integration
77

78
```javascript
79
const express = require('express');
80
const stylus = require('stylus');
81

82
const app = express();
83

84
// Basic middleware setup
85
app.use(stylus.middleware({
86
  src: __dirname + '/public'
87
}));
88

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

91
app.listen(3000);
92
```
93

94
### Advanced Configuration
95

96
```javascript
97
const express = require('express');
98
const stylus = require('stylus');
99
const path = require('path');
100

101
const app = express();
102

103
// Advanced middleware with all options
104
app.use(stylus.middleware({
105
  // Source directory for .styl files
106
  src: path.join(__dirname, 'src/styles'),
107
  
108
  // Destination directory for .css files
109
  dest: path.join(__dirname, 'public/css'),
110
  
111
  // Compression for production
112
  compress: process.env.NODE_ENV === 'production',
113
  
114
  // Debug information for development
115
  firebug: process.env.NODE_ENV === 'development',
116
  linenos: process.env.NODE_ENV === 'development',
117
  
118
  // Source maps
119
  sourcemap: {
120
    comment: true,
121
    inline: process.env.NODE_ENV === 'development',
122
    sourcesContent: true
123
  },
124
  
125
  // Force recompilation in development
126
  force: process.env.NODE_ENV === 'development'
127
}));
128

129
// Serve static files
130
app.use(express.static(path.join(__dirname, 'public')));
131
```
132

133
### Custom Compile Function
134

135
```javascript
136
const express = require('express');
137
const stylus = require('stylus');
138
const nib = require('nib');
139

140
const app = express();
141

142
app.use(stylus.middleware({
143
  src: __dirname + '/public',
144
  
145
  // Custom compilation with plugins
146
  compile: function(str, path) {
147
    return stylus(str)
148
      .set('filename', path)
149
      .set('compress', true)
150
      .use(nib())
151
      .import('nib');
152
  }
153
}));
154

155
app.use(express.static(__dirname + '/public'));
156
```
157

158
### Different Source and Destination
159

160
```javascript
161
const express = require('express');
162
const stylus = require('stylus');
163

164
const app = express();
165

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

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

176
// Serve other static files
177
app.use(express.static(__dirname + '/public'));
178
```
179

180
### Development vs Production
181

182
```javascript
183
const express = require('express');
184
const stylus = require('stylus');
185

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

189
app.use(stylus.middleware({
190
  src: __dirname + '/src/styles',
191
  dest: __dirname + '/public/css',
192
  
193
  // Development settings
194
  compress: !isDevelopment,
195
  linenos: isDevelopment,
196
  firebug: isDevelopment,
197
  force: isDevelopment,
198
  
199
  // Source maps in development
200
  sourcemap: isDevelopment ? {
201
    inline: true,
202
    sourcesContent: true
203
  } : false
204
}));
205
```
206

207
### With Plugins and Includes
208

209
```javascript
210
const express = require('express');
211
const stylus = require('stylus');
212
const nib = require('nib');
213
const autoprefixer = require('autoprefixer-stylus');
214

215
const app = express();
216

217
app.use(stylus.middleware({
218
  src: __dirname + '/src/styles',
219
  dest: __dirname + '/public/css',
220
  
221
  compile: function(str, path) {
222
    return stylus(str)
223
      .set('filename', path)
224
      .set('compress', process.env.NODE_ENV === 'production')
225
      .include(__dirname + '/src/styles/mixins')
226
      .include(__dirname + '/src/styles/variables')
227
      .use(nib())
228
      .use(autoprefixer())
229
      .import('nib');
230
  }
231
}));
232
```
233

234
## Workflow Integration
235

236
### Express.js Application Structure
237

238
```
239
project/
240
├── src/
241
│   └── styles/
242
│       ├── main.styl
243
│       ├── variables.styl
244
│       └── mixins/
245
│           └── buttons.styl
246
├── public/
247
│   ├── css/           # Generated CSS files
248
│   ├── js/
249
│   └── images/
250
└── app.js
251
```
252

253
### Complete Express Setup
254

255
```javascript
256
const express = require('express');
257
const stylus = require('stylus');
258
const path = require('path');
259

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

263
// Stylus middleware
264
app.use(stylus.middleware({
265
  src: path.join(__dirname, 'src/styles'),
266
  dest: path.join(__dirname, 'public/css'),
267
  compress: process.env.NODE_ENV === 'production',
268
  sourcemap: process.env.NODE_ENV === 'development',
269
  force: process.env.NODE_ENV === 'development'
270
}));
271

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

275
// Routes
276
app.get('/', (req, res) => {
277
  res.send(`
278
    <html>
279
      <head>
280
        <link rel="stylesheet" href="/css/main.css">
281
      </head>
282
      <body>
283
        <h1>Stylus Middleware Example</h1>
284
      </body>
285
    </html>
286
  `);
287
});
288

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

294
### Error Handling
295

296
```javascript
297
const express = require('express');
298
const stylus = require('stylus');
299

300
const app = express();
301

302
app.use(stylus.middleware({
303
  src: __dirname + '/src/styles',
304
  dest: __dirname + '/public/css',
305
  
306
  compile: function(str, path) {
307
    try {
308
      return stylus(str)
309
        .set('filename', path)
310
        .render();
311
    } catch (err) {
312
      console.error('Stylus compilation error:', err.message);
313
      throw err;
314
    }
315
  }
316
}));
317

318
// Error handling middleware
319
app.use((err, req, res, next) => {
320
  if (err && err.name === 'ParseError') {
321
    console.error('Stylus parse error:', err.message);
322
    res.status(500).send('CSS compilation error: ' + err.message);
323
  } else {
324
    next(err);
325
  }
326
});
327
```
328

329
## Caching and Performance
330

331
The middleware automatically handles:
332

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

338
Performance tips:
339

340
```javascript
341
// For production - disable force compilation
342
app.use(stylus.middleware({
343
  src: __dirname + '/styles',
344
  force: false,  // Only compile when files change
345
  compress: true  // Minify output
346
}));
347

348
// For development - enable debugging features
349
app.use(stylus.middleware({
350
  src: __dirname + '/styles',
351
  force: true,    // Always recompile for debugging
352
  linenos: true,  // Line numbers for debugging
353
  sourcemap: true // Source maps for debugging
354
}));
355
```