Migration 0.1.x 1.0.x

Migrating from 0.1.x to 1.0.x

The upgrade to version 1.0.x involves some changes to the way that the less middleware works. Unfortunately this includes some changes that need to be made to the way you use the middleware.

Changed Middleware Arguments

This is the first and most important change that all users of the middleware will need to update. Previously the source directory was specified in the options argument of the middleware like so:

lessMiddleware({
  src: path.join(__dirname, '/public')
})

Since the source directory is really a required argument this was a bit of a misnomer. So starting in version 1.0.x the first argument to the middleware is the source directory and is required:

lessMiddleware(path.join(__dirname, '/public'))

Splitting Options From Less Options

One of the big pain points with the earlier version of the middleware was the inability to pass options directly to the less parser and compiler. To fix this there are now three different option objects that get passed into the middleware:

lessMiddleware(source, [{options}], [{parserOptions}], [{compilerOptions}])

The options objects contains options that are specific to the middleware and have no bearing on the less parser or compiler. The parserOptions and compilerOptions do not affect the middleware but are passed into the Less parser and compiler directly.

More information on the option objects can be found in the readme.

Changed Options

The following options have been changed from earlier versions:

• compress: Removed from options. Can be specified in the compilerOptions.
• dumpLineNumbers: Removed from options. Can be specified in the parserOptions.
• optimization: Removed from options. Can be specified in the parserOptions.
• paths: Removed from options. Can be specified in the parserOptions.
• preprocessor: Moved to be available at preprocessor.less.
• relativeUrls: Removed from options. Can be specified in the parserOptions.
• sourceMap: Removed from options. Can be specified in the compilerOptions.
• yuicompress: Removed from options. Can be specified in the compilerOptions.

Removed Options

While reorganizing, some options have been removed:

• prefix: Removed in favor of using the preprocess.path option.
• treeFunctions: Removed, see the extending less page for how to add custom tree functions.

New Options

To make thing easier to extend, a few new options have been added: preprocessing and postprocessing. Specific examples are available on the wiki, but in the following are available:

• postprocess.css: Modifies the compiled css output before being stored.
• preprocess.less: Modifies the raw less before being parsed and compiled.
• preprocess.path: Modifies the less pathname before being loaded from the filesystem.

Converting From prefix

Instead of using a prefix option you now need to use the preprocess.path option:

preprocess: {
  path: function(pathname, req) {
    return pathname.replace(/^\/styles\//, '/');
  }
}