LESS CSS Gradle Plugin

Warning

Active development of this project has stopped There are two alternatives: asset pipeline gradle plugin use the original javascript lesscss via the gradle grunt or gulp plugins

A gradle plugin for compiling LESS to CSS, compatible with less v1.7.0

Features

The plugin is based on lesscss, which:

• can start a daemon that automatically compiles when the source is modified

• caches information about imported source files to avoid unnecessary compilations

• supports all LESS options

• is the fastest Java based LESS compiler

• supports multiple underlying engines: rhino, nashorn and node.js

Installation

The plugin is available in the maven central repository. You can add it to your gradle build as follows:

buildscript {
    repositories {
        mavenCentral()
    }

    dependencies {
        classpath "com.github.houbie:lesscss-gradle-plugin:1.0.3-less-1.7.0"
    }
}

apply plugin: "lesscss"

lessc task

The plugin adds a lessc task that requires a destinationDir and at least one sourceDir with optional include(s) and exclude(s):

lessc {
    sourceDir "customized/less", "standard/less"
    include "**/*.less", "**/*.js"
    exclude "imports/**/*"
    destinationDir = "$buildDir/css"
}

• An (imported) less file is searched in the source directories in the order they are defined. This makes it possible to keep your standard less files outside of your version control system, and only check-in the less files that you actually want to override.

• By not including or explicitly excluding the less sources that are only used as imports, you can avoid unnecessary compilations.

• You can define additional tasks with type com.github.houbie.gradle.lesscss.LesscTask

Configuration

The lesscss plugin supports all the options of the standard less:

lessc {
    //plugin configuration
    ////////////////////////
    engine = "commandline" //Either 'rhino', 'nashorn' (requires jdk8) or 'commandline' (requires local node.js). Default: 'rhino'
    lesscExecutable = "$userHome\\AppData\\Roaming\\npm\\lessc.cmd" //The executable to use for the commandline engine. Default: 'lessc' (typically OK on UN*X)
    customJavaScript = file("custom.js").text //javascript that can provide functions to the less compiler. Default: null
    encoding = "utf-8" //encoding used to read less files. Default: null (platform encoding)

    //standard LESS options
    /////////////////////////
    options.compress = true //Compress output by removing some whitespaces. Default: false
    options.strictImports = true //Force evaluation of imports. Default: false
    options.rootpath = /root/path //Set rootpath for url rewriting in relative imports and urls. Works with or without the relative-urls option. Default: null
    options.relativeUrls = true //Re-write relative urls to the base less file. Default: false
    options.minify = true //Compress output using YUI minifier (standard LESS uses clean-css, which is only available in node.js). Default: false
    options.strictMath = true //In strict mode, math requires brackets. Default: false
    options.strictUnits = true //Disallow mixed units, e.g. 1px+1em or 1px*1px which have units that cannot be represented. Default: false
    options.ieCompat = false //Enable IE compatibility checks. Default: true
    options.javascriptEnabled = false //Enable JavaScript in less files. Default: true
    options.sourceMap = true //Outputs a v3 sourcemap.  Default: false
    options.sourceMapRootpath = "/path/to/sourcemaps" //adds this path onto the sourcemap filename and less file paths. Default: null
    options.sourceMapBasepath = file("$buildDir/css").absolutePath //Sets sourcemap base path (will be subtracted from generated paths). Default: null
    options.sourceMapLessInline = true //Puts the less files into the map instead of referencing them. Default: false
    options.sourceMapMapInline = true //Puts the map (and any less files) into the output css file. Default: false
    options.sourceMapURL = "http://localhost:8080/myApp/css/source.map" //The complete url and filename put in the less file. Default: null (calculated)
    options.globalVars = [fancyColor: "#123456"] //Defines a variable that can be referenced in the less. Default: empty Map
    options.modifyVars = ["btn-warning-bg": "red"] //Modifies a variable already declared in the less. Default: empty Map

    //deprecated options
    options.optimizationLevel = 1 //Set the parser's optimization level. The lower the number, the less nodes it will create in the tree
    options.dumpLineNumbers= NONE //Outputs filename and line numbers in comments (COMMENTS) or in a fake media query (MEDIA_QUERY). Use source maps instead.
}

Tip	When you generate source maps, the Chrome DevTools will automatically show the original less code i.s.o. the generated CSS when inspecting an element.

Warning

The minify option is not compatible with source map generation!

Per file configuration

When different less files require different options (f.e. source map options), they can be configured with a preCompile closure. This closure has to accept 2 parameters: * org.gradle.api.file.FileTreeElement source : the less source file * com.github.houbie.lesscss.builder.CompilationUnit compilationUnit : contains all the options, destination file and source map destination file

Example:

lessc {
    ...
    preCompile { FileTreeElement src, CompilationUnit unit ->
        unit.destination = project.file("css/${src.name}-less.css")
        unit.options.sourceMap = true
        unit.sourceMapFile = project.file("css/${src.name}-less.map")
        unit.options.sourceMapBasepath =  unit.sourceMapFile.parentFile.absolutePath
    }
}

Warning

Changing the preCompile closure doesn’t mark the lessc task dirty. You will have to execute a clean!

lesscDaemon task

When running gradle lesscDaemon --info, your less source files will be monitored for changes. During development, you only have to save your less file and refresh your browser. The CSS will be re-compiled automatically.

The gradle process keeps running until you hit the enter key.

Tip	By adding the --info argument, you can see when compilation is started and finished.

The lesscDaemon has two configuration parameters: lesscTaskName and interval. It also allows to override engine and lesscExecutable.

lesscDaemon {
    lesscTaskName = "customLesscTask" //When you defined additional lessc tasks. Default: 'lessc'
    interval = 200 //Scan interval in milliseconds. Default: 500
    engine = "commandline"
    lesscExecutable = "/opt/local/bin/lessc"
}

Tip	Using the default engine in the lessc task makes sure that your builds always use the same LESS version and that your builds are reproducible. Use the commandline engine in the lesscDaemon task to speed up development of style sheets.

Performance

The supported engines perform quite different:

rhino

although it’s the fastest compiler in Java land, it still takes several seconds to compile the Twitter Bootstrap stylesheets.

nashorn

expected to be faster then rhino, but in fact a lot slower because the rhino less engine runs with the highest optimization level.

commandline

by far the fastest, but it requires node.js to be installed. Useful in dev mode. Typically compiles Twitter Bootstrap in less then a second.