ForbesLindesayless-file
Middleware for less & express with bonus npm support, sane & simple handling of static assets and sensible defaults for the ultimate in ease of use.
In addition to the basics, less-file also comews witht he following features out of the box:
- less extended with
@import (npm) "package-name"syntax - static assets like fonts and images automatically taken care of
- source-maps are automatically enabled for debugging
- minification automatically enabled in production
- gzip automatically enabled in production
- etags for caching automatically supported
If you think I've missed something, be sure to open an issue or submit a pull request.
If you find it useful, please support me on gittip
Usage
If you have installed twbs via npm install twbs --save you can use the following less file:
@import (npm) "twbs";
//any custom less stuff hereAlong with the server:
var less = require('less-file');
var express = require('express');
var app = express();
// serve CSS for '/style/index.less' at '/style/bundle.css'
app.use('/style', less(__dirname + '/style/index.less'));
app.listen(3000);Then when you fetch http://localhost:3000/style/bundle.css you will get a CSS bundle, but any url("./file.png") style references in the less files will be properly resolved as relative addresses, givena unique ID and then served up from /style so you don't need to manually mess with anything to get twitter bootstrap's glyphicon fonts to just work.
Compatible npm modules
This location will list npm modules that are known to be fully compatible with less-file:
twbs- a tiny modificaion of Twitter's Bootstrap to support both browserify and less-file properly.
If you want to make your own module compatible with less-file, you can just leave an index.less or index.css file in the root of a package and then publish it to npm. Alternatively you can set the "style" field in your package.json file to override that path.
API
less('filename', options) => express middleware app
Less-file takes a filename and some options and returns an express web server. It serves up the css file at /bundle.css so if you do:
app.use('/style', less(__dirname + '/style/index.less'));you can request the file from /style/bundle.css
Options
The options passed to each middleware function override the defaults specified in settings.
Setings has two properties settings.production and settings.development which specify the default settings for each environment. The current environment is specified by settings.mode and defaults to process.env.NODE_ENV || 'development'
Production defaults:
production.cache = true; // equivalent to "public, max-age=60"
production.minify = true;
production.gzip = true;
production.debug = false;To update:
less.settings.production('cache', '7 days');Development defaults:
development.cache = false;
development.minify = false;
development.gzip = false;
development.debug = true;To update:
less.settings.development('gzip', true);cache
The cache setting determines how long content can be cached in the client's web browsers (and any caching proxies) and whether or not to cache bundles server side. Any value other than false will result in them being cached server side.
- If cache is
truethe client will recieve Cache Control of"public, max-age=60", which caches for 60 seconds. - If cache is a string in the form accepted by ms it becomes:
"public, max-age=" + (ms(cache)/1000) - If cache is a number, it is treated as being in milliseconds so becomes:
"public, max-age=" + (cache/1000) - If cache is an object of the form
{private: true || false, maxAge: '10 minutes'}it becomes the apropriate string. - If cache is any other string it will be sent directly to the client.
N.B. that if caching is enabled, the server never times out its cache, no matter what the timeout set for the client.
minify
If minify is true, less will be told to compress its output. This automatically disables debug.
gzip
If gzip is true, GZip will be enabled when clients support it. This increases the memory required for caching by aproximately 50% but the speed boost can be considerable. It is true by default in production.
debug
If debug is true, a source map will be added to the code. This is very useful when debugging. debug is false by default in produciton.
License
MIT