UNPKG

5.95 kBMarkdownView Raw
1This middleware was created to allow processing of [Less](http://lesscss.org) files for [Connect JS](http://www.senchalabs.org/connect/) framework and by extension the [Express JS](http://expressjs.com/) framework.
2
3[![CircleCI](https://circleci.com/gh/emberfeather/less.js-middleware.svg?style=shield)](https://circleci.com/gh/emberfeather/less.js-middleware)
4[![Dependency Status](https://david-dm.org/emberfeather/less.js-middleware.svg)](https://david-dm.org/emberfeather/less.js-middleware)
5
6## Installation
7
8```sh
9npm install less-middleware --save
10```
11
12## Usage
13
14```js
15lessMiddleware(source, [{options}])
16```
17
18### Express
19
20```js
21var lessMiddleware = require('less-middleware');
22
23var app = express();
24app.use(lessMiddleware(__dirname + '/public'));
25app.use(express.static(__dirname + '/public'));
26```
27
28### `options`
29
30The following options can be used to control the behavior of the middleware:
31
32<table>
33 <thead>
34 <tr>
35 <th>Option</th>
36 <th>Description</th>
37 <th>Default</th>
38 </tr>
39 </thead>
40 <tbody>
41 <tr>
42 <th><code>debug</code></th>
43 <td>Show more verbose logging?</td>
44 <td><code>false</code></td>
45 </tr>
46 <tr>
47 <th><code>dest</code></th>
48 <td>Destination directory to output the compiled <code>.css</code> files.</td>
49 <td>Same directory as less source files.</td>
50 </tr>
51 <tr>
52 <th><code>force</code></th>
53 <td>Always re-compile less files on each request.</td>
54 <td><code>false</code></td>
55 </tr>
56 <tr>
57 <th><code>once</code></th>
58 <td>Only recompile once after each server restart. Useful for reducing disk i/o on production.</td>
59 <td><code>false</code></td>
60 </tr>
61 <tr>
62 <th><code>pathRoot</code></th>
63 <td>Common root of the source and destination. It is prepended to both the source and destination before being used.</td>
64 <td><code>null</code></td>
65 </tr>
66 <tr>
67 <th><code>postprocess</code></th>
68 <td>Object containing functions relevant to postprocessing data.</td>
69 <td></td>
70 </tr>
71 <tr>
72 <th><code>postprocess.css</code></th>
73 <td>Function that modifies the compiled css output before being stored.</td>
74 <td><code>function(css, req){...}</code></td>
75 </tr>
76 <tr>
77 <th><code>preprocess</code></th>
78 <td>Object containing functions relevant to preprocessing data.</td>
79 <td></td>
80 </tr>
81 <tr>
82 <th><code>preprocess.less</code></th>
83 <td>Function that modifies the raw less output before being parsed and compiled.</td>
84 <td><code>function(src, req){...}</code></td>
85 </tr>
86 <tr>
87 <th><code>preprocess.path</code></th>
88 <td>Function that modifies the less pathname before being loaded from the filesystem.</td>
89 <td><code>function(pathname, req){...}</code></td>
90 </tr>
91 <tr>
92 <th><code>preprocess.importPaths</code></th>
93 <td>Function that modifies the import paths used by the less parser per request.</td>
94 <td><code>function(paths, req){...}</code></td>
95 </tr>
96 <tr>
97 <th><code>render</code></th>
98 <td>Options for the less render. See the "<code>render</code> Options" section below.</td>
99 <td>&hellip;</td>
100 </tr>
101 <tr>
102 <th><code>storeCss</code></th>
103 <td>Function that is in charge of storing the css in the filesystem.</td>
104 <td><code>function(pathname, css, req, next){...}</code></td>
105 </tr>
106 <tr>
107 <th><code>cacheFile</code></th>
108 <td>Path to a JSON file that will be used to cache less data across server restarts. This can greatly speed up initial load time after a server restart - if the less files haven't changed and the css files still exist, specifying this option will mean that the less files don't need to be recompiled after a server restart.</td>
109 <td></td>
110 </tr>
111 </tbody>
112</table>
113
114## `render` Options
115
116The `options.render` is passed directly into the `less.render` with minimal defaults or changes by the middleware.
117
118The following are the defaults used by the middleware:
119
120<table>
121 <thead>
122 <tr>
123 <th>Option</th>
124 <th>Default</th>
125 </tr>
126 </thead>
127 <tbody>
128 <tr>
129 <th><code>compress</code></th>
130 <td><code>auto</code></td>
131 </tr>
132 <tr>
133 <th><code>yuicompress</code></th>
134 <td><code>false</code></td>
135 </tr>
136 <tr>
137 <th><code>paths</code></th>
138 <td><code>[]</code></td>
139 </tr>
140 </tbody>
141</table>
142
143## Examples
144
145Common examples of using the Less middleware are available in the [wiki](https://github.com/emberfeather/less.js-middleware/wiki/Examples).
146
147## Troubleshooting
148
149### My less never recompiles, even when I use `{force: true}`!
150
151Make sure you're declaring less-middleware before your static middleware, if you're using the same directory, e.g. (with express):
152
153
154```js
155var lessMiddleware = require('less-middleware');
156
157var app = express();
158app.use(lessMiddleware(__dirname + '/public'));
159app.use(express.static(__dirname + '/public'));
160```
161
162not
163
164```js
165var lessMiddleware = require('less-middleware');
166
167var app = express();
168app.use(express.static(__dirname + '/public'));
169app.use(lessMiddleware(__dirname + '/public'));
170```
171
172### IIS
173
174If you are hosting your app on IIS you will have to modify your `web.config` file in order to allow NodeJS to serve your CSS static files. IIS will cache your CSS files, bypassing NodeJS static file serving, which in turn does not allow the middleware to recompile your LESS files.