Overview

Easily work with LESS files in Visual Studio Code.

"Compile-on-save" for LESS stylesheets without using a build task.

Features

Generates a .css file each time you save a .less file.
e.g. styles.less --> styles.css
Compile errors integrate with the standard Errors and Warnings list.
Has reasonable default settings, but...
Configurable, as needed:
- Configurable at user, workspace and per-file level (see Advanced Usage below)
- Main file support
- Alternative output file
- Output suppression
- Compression
autoprefixer plugin included.

Default Settings

Compile on save occurs for every .less file in the project.
The .css file is output to the same directory as the source .less file.
Source maps (.css.map files) are not output.
Compression is disabled.
Auto-prefixer is disabled.

Basic Usage

Create a .less file.
Hit Ctrl/Cmd+S to save your file.
A .css file is automatically generated.
You should see a temporary "Less compiled in X ms" message in the status bar.

N.B. Also available from the command palette as "Compile LESS to CSS".

Advanced Usage

Project-Wide & Global Configuration

Project-wide settings are configured using the standard settings.json file (i.e. Workspace Settings).
settings.json must exist in the .vscode directory at the root level of your project.
Alternatively, settings can go in User Settings for global defaults.
Use the "less.compile" key.

Example settings.json file:

{    
    "less.compile": {
        "compress":  true,  // true => remove surplus whitespace
        "sourceMap": true,  // true => generate source maps (.css.map files)
        "out":       false, // false => DON'T output .css files (overridable per-file, see below)
    }
}

Per-File Configuration

Settings can also be specified per .less file as a comment on the first line.
Settings are comma-separated and strings are not "quoted".

Example:

// out: ../dist/app.css, compress: true, sourceMap: false

body, html {
    ...
}

Settings

main: { filepath: string | string[] }

Compiles a different less file instead of this one.
All other settings are ignored.
Filepath is relative to the current file.
Multiple main files can be specified (see FAQ).

out: { boolean | filepath: string | folderpath: string }

Redirects the css output to a different file.
This setting can be used to override a project-wide "out": false setting, where you only want certain .less files to be generated.
If filepath is used, but no file extension is specified, it will append .css
If folderpath is used, the less filename will be used, but with the .css extension
Filepath is relative to the current file.

outExt: { string }

The default output extension is .css.
This allows you to specify an alternative output file extension (e.g. .wxss instead of .css)
This applies to the .map file also (e.g. .wxss.map)

sourceMap: { boolean }

Enables generation of source map files.
When enabled, a .css.map file will be output in the same direction as the .css file (except when sourceMapFileInline is set, see below).
The out setting is respected.

sourceMapFileInline: { boolean }

Inline the source map within the css.
When enabled, the .css file outputted will contain an inline source-map.

compress: { boolean }

Compresses the css output by removing surplus white-space.

relativeUrls: { boolean }

Specifies whether URLs in @import'ed should be rewritten relative to the importing file.
Has no effect on the out parameter.

Example of true option—given this folder structure:
/main.less
/css/feature/feature.less
/css/feature/background.png

/main.less:

// relativeUrls: true
@import "css/feature/feature.less";

/css/feature/features.less:

// main: ../../main.less
.feature {
    background-image: url(background.png)
}

/main.css: (output)

.feature {
    background-image: url('css/feature/background.png')
}

autoprefixer: { string | string[] }

When present, this enables the autoprefixer plugin for less (included).
This plugin automatically adds/removes vendor-prefixes needed to support a set of browsers which you specify.
The autoprefixer option is the comma-separated list of browsers for autoprefixer to use (or alternatively a string array of them).

Example of autoprefixer within .vscode/settings.json:

{    
    "less.compile": {
        "autoprefixer": "> 5%, last 2 Chrome versions, not ie 6-9"
    }
}

See browserslist documentation for further examples of browser queries.
NOTE: If used with the per-file configuration, the browsers listed must be unquoted and semi-colon separated (because comma is already the directive separator): e.g.
// autoprefixer: > 5%; last 2 Chrome versions; not ie 6-9, sourceMap: true, out: ../css/style.css

ieCompat: { boolean }

IE8 compatibility mode (defaults to true).
When true: prevents inlining of data-uris that exceed 32KB.
When false: removes restriction on data-uri size.

Settings Cascade Order

Settings are read and applied in the following order:

User Settings
Project-wide settings.json (aka Workspace Settings)
Per-file Settings

FAQ

How do I redirect the output to a separate file?
Add the following line to the head of your less file:
```
// out: new-file.css
```
How do I redirect all css output to a specific folder?
Specify the out parameter in the settings.json file, as a relative or absolute path, with a trailing slash (/ or \\).

Tip: You can use the environment variable ${workspaceRoot} to specify paths relative to the workspace:

.vscode/settings.json:
```
{    
    "less.compile": {
        "out": "${workspaceRoot}\\css\\"
    }
}
```
How do I suppress compiling this less file / compile a different less file than the one being edited?
Add a reference to the master.less file to the head of the imported less file:
```
// main: master.less
```
How do I suppress the compilation of a single less file?
Set out to false (or null) in a comment at the top of the .less file:
```
// out: false
```

How do I compile only some of the .less files in my project?

a. Default "out" setting to false in settings.json
b. Override out for each .less file that you want to compile:

.vscode/settings.json:
{    
    "less.compile": {
        "out": false
    }
}
style.less: (will be compiled to style.css)
// out: true

@import "mixins.less";

body, html {    
  ...     
}
mixins.less: (no comment line, will not be compiled)
.border-radius(@radius) {    
  -webkit-border-radius: @radius;
  -moz-border-radius: @radius;
  -ms-border-radius: @radius;
  border-radius: @radius;
}

Is it possible to have multiple "main" .less files?
Yes, multiple main files can be specified in these ways:
- In settings.json, using a string array:
  
  .vscode/settings.json:
```
{    
    "less.compile": {
        "main": ["main-one.less", "main-two.less"]
    }
}
```
- Per file: by specifying the main setting key more than once:
```
// main: main-one.less, main: main-two.less
```
When there is more than one main setting, they are guaranteed to be output in the order listed (from left to right). For the example shown above, the output from main-one.less will be saved to disk before main-two.less is processed (assuming they are both configured to output). This can be used to control dependency chains.
Can I specify paths relative to the workspace, instead of relative to the less file?
Yes, the variable ${workspaceRoot} can be used within the main or out parameters:

.vscode/settings.json:
```
{    
    "less.compile": {
        "main": ["${workspaceRoot}\\css\\main.less"]
    }
}
```
How do I generate sourcemap (*.css.map) files?
.vscode/settings.json:
```
{    
    "less.compile": {
        "sourceMap": true
    }
}
```

Acknowledgements

Configuration concepts borrowed from Jonathan Diehl's brackets-less-autocompile.
Contributors: CnSimonChan, gprasanth, elvis-macak
Feedback/ideas: thecosss, pnkr, ep-mark, icefrog, , yunfeizuo, Tobyee, sagive, DifficultNick, Alejandro L and Kenneth Davila

Easy LESS

mrcrowl