This project just launched so expect frequent changes. And if you find this project interesting please consider starring it to receive updates. Table of Contents
assemble-less has many more features than we've been able to document thus far. So while we work to improve the docs, please let us know if you have any questions or have any trouble getting assemble-less to work. And feel free to create an Issue, we're here to help.
This plugin requires Grunt ~0.4.1
If you haven't used Grunt before, be sure to read the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins.
Then install the required local dependencies and this plugin with this command:
$ npm install
Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:
grunt.loadNpmTasks('assemble-less');
When completed, you'll be able to run the various grunt
commands provided:
Runs the Less.js compiler to rebuild the specified /test/fixtures/*.less
files.
This is a convenience task to "Run predefined tasks whenever watched file patterns are added, changed or deleted". Requires grunt-contrib-watch, npm i grunt-contrib-watch
.
Should you encounter problems with installing dependencies or running the grunt
commands, be sure to first uninstall any previous versions (global and local) you may have installed, and then rerun npm install
.
In your project's Gruntfile, add a section named less
to the data object passed into grunt.initConfig()
.
grunt.initConfig({
less: {
options: {
// Task-specific options go here.
},
your_target: {
// Target-specific file lists and/or options go here.
}
}
})
Options developed specifically for assemble-less
Type: String
Default: 1.3.3
Specify the path to the Less.js version that you wish to use for compiling to CSS. You may specify a different version for each target, this can be useful for testing if a new version produces different output than the previous.
Type: String
Default: empty string
This string will be prepended to the beginning of the concatenated output. It is processed using grunt.template.process, using the default options.
(Default processing options are explained in the grunt.template.process documentation)
Type: Boolean
Object
Default: false
Process source files as templates before concatenating.
false
- No processing will occur.true
- Process source files using grunt.template.process defaults.options
object - Process source files using grunt.template.process, using the specified options.
(Default processing options are explained in the grunt.template.process documentation)
Type: String
Default: undefined
Path to library of .less
files to use. This feature is in anticipation of the new @import
directives introduced to Less.js in version 1.4.0 and 1.4.1. This feature will be expanded based on feedback.
less: {
options: {
library: ['libs/bootstrap/less']
}
}
Type: String|Array
Default: empty string
Specified files will be concatenated (prepended) to specified source files. This feature is useful for "inlining" globaly-required LESS files, such as variables
or mixins
, so that they do not need to be referenced with @import
statements inside any individual files.
Type: Boolean
Default: true
Concatenate all source files by default. If you change the value to false, all source files will compile into individual files.
These options are native to the Less.js parser and compiler and will be passed through directly to Less.js
See the Less.js documentation for more info about supported options.
Type: String|Array
Default: Directory of input files
Specifies directories to scan for @import
directives when parsing. The default value is the directory of the specified source files. In other words, the paths
option allows you to specify paths for your @import statements in the less
task as an alternative to specifying a path on every @import
statement that appears throughout your LESS files. So instead of doing this:
@import "path/to/my/less/files/mixins/mixins.less";
you can do this:
@import "mixins.less";
Type: Boolean
Default: false
Specifies if we should compress the compiled css by removing some whitespaces.
Type: Boolean
Default: false
Compress output using cssmin.js.
Type: Integer
Default: null
Set the parser's optimization level. The lower the number, the less nodes it will create in the tree. This could matter for debugging, or if you want to access the individual nodes in the tree.
Type: Boolean
Default: false
Force evaluation of imports.
Type: Boolean
Default: true
Force operations to be enclosed within parenthesis, (2 / 6)
.
Type: Boolean
Default: true
Force strict evaluation of units. If set to false
the compiler will not throw an error with operations such as (3 * 1em)
.
Type: String
Default: false
Configures -sass-debug-info support.
Accepts following values: comments
, mediaquery
, all
.
Type: String
Default value: null
A convenience option for externalizing task options into a .lessrc
file. If this file is specified, options defined therein will be used.
less: {
options: grunt.file.readJSON('.lessrc')
}
The .lessrc
file must be valid JSON and looks something like this:
{
"globals": null,
"concat": false,
"compress": false,
"yuicompress": false,
"optimization": 03,
"strictImports": true,
"dumpLineNumbers": false,
"strictMaths": false,
"strictUnits": false
}
Type: Object
Default: null
Data object for defining global variables inside the Gruntfile which will be accessible in LESS files.
Type: String|Array
Default: null
Prepend one or more @import
statements to each src
file in a target. Would also allow specifying new @import
directives planned for release in LESS v1.4.0:
inline
less
css
mixins
This feature would probably replace the globals
feature.
less: {
selectors_test: {
files: {
'selectors.css': ['selectors.less']
}
}
}
As an alternative to using @import
to "inline" .less
files, you can specify an array of src
paths and they will be concatenated.
less: {
dist: {
files: {
'test.css': ['reset.less', 'test.less']
}
}
}
You can specify multiple destination: [source]
items in files
.
less: {
dist: {
files: {
'test.css': ['test.less'],
'mixins.css': ['mixins.less']
}
}
}
In this example, the paths
and requires
options are used:
less: {
development: {
options: {
paths: ['test/fixtures'],
require: [
'globals/variables.less',
'globals/mixins.less'
]
},
files: {
'styles.css': ['styles.less']
}
},
production: {
options: {
paths: ['assets/less'],
yuicompress: true
},
files: {
'styles.min.css': ['styles.less']
}
}
}
Grunt supports filename expansion (also know as globbing) via the built-in node-glob and minimatch libraries. So Templates may be used in filepaths or glob patterns.
debug: {
options: {
paths: ['<%= tests.debug.import %>']
},
src: ['<%= tests.test.imports %>', 'test/fixtures/*.less'],
dest: 'test/result/debug'
}
For more on glob pattern syntax, see the node-glob and minimatch documentation.
In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Please lint and test your code using Grunt.
assemble-less is a powerful and flexible Grunt plugin for compiling LESS to CSS. The less
task leverages JSON and Lo-dash templates for defining any number of LESS "bundles", UI components, compressed stylesheets or themes.
- assemble: a Grunt plugin for quickly launching static web projects by emphasizing a strong separation of concerns between structure, style, content and configuration.
- less-tests: a LESS / CSS test-suite that uses assemble-less to enable you to run any kind of test on LESS stylesheets.
This Grunt.js plugin and some of the documentation on this page, is derived from grunt-contrib-less, authored by Tyler Kellen. This plugin was modified for this project to concat
LESS files first, and then compile them into CSS files. This allows for prepending globally required LESS files, and it also adds the ability to build out individual CSS files, rather than building a single conctatenated file.
Jon Schlinkert
Brian Woodward
Copyright 2013 Assemble
- 2013-04-28 v0.4.5 FixesRenamed "lib" option to "library" for clarity.Improved logging.
- 2013-04-24 v0.4.4 Breaking change. Renamed "require" option to "globals".New "lib" option.
- 2013-03-17 v0.3.0 Adds new option to specify the version of less.js to use for compiling to CSS.
- 2013-03-14 v0.2.3 adds new options from Less.js 1.4.0
- 2013-03-09 v0.2.0 in bootstrap.json, changed the path to bootstrap folder, new globals object.new targets for single component, bootstrap.less lib, ignore pattern.
- 2013-03-08 v0.1.7 Enhanced boostrap.json model.Many task improvements.Greatly improved examples, readme updates.
- 2013-02-27 v0.1.2 Add support for requires option.Add support for concat option
- 2013-02-27 v0.1.0 First commit.
- 2013-05-01 soon Option for adding banners, for comments or any string, like
@import
statements.Options for upcoming features in Less.js, such as 'silentImport'variables option for modifying LESS variables directly inside the Gruntfile.upstage option for importing components from the upstage component library. - 2013-05-15 later .lessrc file for externalizing optionsPossibly allow arrays to be used in banners
Authored by assemble
This file was generated using Grunt and assemble on Fri May 03 2013 01:57:42.