Source Maps

Source map links elements from compiled css file back to original less files. They are useful when troubleshooting large complicated less files. If the browser supports source maps, its debug tools works with original less files instead of compiled css version. More about source maps can be read on html5 rocks or tutplus sites.

Source maps are a new technology and are currently supported only by Chrome and nightly builds of Firefox.

This page starts with source mapping basics and then describes how to use LessCompiler interface to generate source maps. The last section describes how to move source maps around file system once they are created. Source map generation via command line is explained on another page.

Basics

Source map, generated css and original less files are linked to each other via relative references:

• compiled css contains relative path to its source map,
• source map contains relative path to compiled css,
• source map contains relative path to original less.

Unless told otherwise, less4j assumes that original less, compiled css and generated source map are all stored in the same directory and their names differ only by suffix. It is possible to supply custom name and location for compiled css file, however source map name can not be customized.

If any of these relative paths does not work correctly, source map may not work. Therefore, renaming/moving source map or generated css involves more then just copying files around. If you rename or move any of these files without updating their relative references, source map stops to work.

Compiled css links source map - see the ending comment:

.class {
  margin: 1 1 1 1;
}
/*# sourceMappingURL=sampleInput.css.map */

Source map links both compiled css and original less file:

{
"version":3,
"file":"sampleInput.css", //relative path to compiled css
"lineCount":1,
"mappings":"AAAAA;",
"sources":["sampleInput.less"], //relative path to original less
"names":[".class"]
}

Configuration

LessCompiler always creates source map. Keep in mind that if the compiler does not know .less and .css files locations, generated source map is not valid.

Css And Less Files Locations

Less location uri is known from input LessSource and css location uri is taken from cssResultLocation property of Configuration object. Css result location property is optional. If it is not available, the compiler will assume that generated .css file will be stored at the same location as original less file and will have the same name.

Miscelangous

Remaining source map configuration is stored in SourceMapConfiguration available from Configuration object. Available properties:

• linkSourceMap
• If set to false, generated css does not contain link to source map file.
• Default: true.
• inline
• If set to true, whole source map is encoded and embedded into generated css.
• Default: false.
• relativizePaths
• If set to false, final source map contains unmodified (absolute) paths to original less files. If set to true, generated map contains relative paths. Note that "correct" source map should contain relative paths. Use this option only if you need some kind of post processing on generated map.
• Default: true.
• encodingCharset
• Source map and source map link encoding charset.
• Default: UTF-8.

Examples

Guessed CSS Location 1

Following code compiles the content of src/sampleInput.less` file without specifying css file location:

File lessFile = new File("src/sampleInput.less").getAbsoluteFile();

LessCompiler compiler = new DefaultLessCompiler();
CompilationResult compilationResult = compiler.compile(lessFile);

System.out.println(compilationResult.getCss());
System.out.println(compilationResult.getSourceMap());

The compiler expects the map to be stored in src/sampleInput.css.map file and generated .css to be stored in src/sampleInput.css. Css looks like this:

.class {
  margin: 1 1 1 1;
}
/*# sourceMappingURL=sampleInput.css.map */

source map contains links to both compiled .css and original less files:

{
"version":3,
"file":"sampleInput.css",
"lineCount":1,
"mappings":"AAAAA;",
"sources":["sampleInput.less"],
"names":[".class"]
}

Guessed CSS Location 2

Using StringSource to supply uri of less file location without having to create the file:

URI uri = (new File("src/sampleInput.less")).toURI();
StringSource lessSource = new StringSource(".class { margin: 1 1 1 1; }", "sampleInput.less", uri);
    
LessCompiler compiler = new DefaultLessCompiler();
CompilationResult compilationResult = compiler.compile(lessSource);

It creates exactly the same .css and .css.map files as previous example.

Custom CSS Location 1

If you want to compile src/sampleInput.less into dist/sampleInput.css, then you can use following code:

File lessFile = new File("src/sampleInput.less").getAbsoluteFile();
File cssFile = new File("dist/sampleInput.css").getAbsoluteFile();
    
Configuration configuration = new Configuration();
configuration.setCssResultLocation(cssFile);
    
LessCompiler compiler = new DefaultLessCompiler();
CompilationResult compilationResult = compiler.compile(lessFile, configuration);

System.out.println(compilationResult.getCss());
System.out.println(compilationResult.getSourceMap());

The compiler expects the map to be stored in dist/sampleInput.css.map file, so the generated css looks like this:

.class {
  margin: 1 1 1 1;
}
/*# sourceMappingURL=sampleInput.css.map */

generated source map contains links to both compiled .css and original less files:

{
"version":3,
"file":"sampleInput.css",
"lineCount":1,
"mappings":"AAAAA;",
"sources":["../src/sampleInput.less"],
"names":[".class"]
}

Custom CSS Location 2

Using StringSource to supply uri of less file location without having to create the file:

File cssFile = new File("dist/sampleInput.css").getAbsoluteFile();
Configuration configuration = new Configuration();
configuration.setCssResultLocation(cssFile);

URI uri = (new File("src/sampleInput.less")).toURI();
StringSource lessSource = new StringSource(".class { margin: 1 1 1 1; }", "sampleInput.less", uri);
    
LessCompiler compiler = new DefaultLessCompiler();
CompilationResult compilationResult = compiler.compile(lessSource, configuration);

Moving Source Map

Moving .less, .css and .css.map files is straightforward as long as their relative positions do not change. However, if you move only some of these files or if you change their names, then you have to update their relative paths too:

• change relative path from css to source map inside /*# sourceMappingURL=<name>.css.map */ comment at the end of css file,
• change relative path from source map to css file inside file property of source map json,
• change relative path from source map to less files inside sources property of source map json.