search

mrcrowl / vscode-easy-less

Easy LESS extension for Visual Studio Code
MIT License
67 stars 23 forks source link

readme

Overview

Easily work with LESS files in Visual Studio Code.

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

Features

Default Settings

Basic Usage

  1. Create a .less file.
  2. Hit Ctrl/Cmd+S to save your file.
  3. A .css file is automatically generated.
  4. 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

Per-File Configuration

Settings

main: { filepath: string | string[] }

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

outExt: { string }

sourceMap: { boolean }

sourceMapFileInline: { boolean }

compress: { boolean }

relativeUrls: { boolean }

autoprefixer: { string | string[] }

ieCompat: { boolean }

javascriptEnabled: { boolean }

math: { "parens-division" | "parens" | "always" | "strict" | "strict-legacy" }

Settings Cascade Order

Settings are read and applied in the following order:

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

FAQ

  1. 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"

  2. 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\\"
  }
}

  3. 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"

  4. 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

  5. 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;
}

  6. 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.

  7. Can I specify paths relative to the workspace, instead of relative to the less file?

    Yes, the variable ${workspaceFolder} can be used within the main or out parameters:

    .vscode/settings.json:

    {
  "less.compile": {
    "main": ["${workspaceFolder}/css/main.less"]
  }
}

  8. How do I generate sourcemap (*.css.map) files?

    .vscode/settings.json:

    {
  "less.compile": {
    "sourceMap": true
  }
}

  9. How do I resolve the error "Inline JavaScript is not enabled. Is it set in your options?"?

    Inline JavaScript is a feature of LESS that used to be enabled by default. It was disabled by default in v3.0.0 of LESS for security reasons. You can use the javascriptEnabled setting to override this behaviour by setting the value to true.

    If you receive this error unintentionally, there are most likely one or more backticks (``) in your .less file.

  10. Can I add custom pre-processing to my less files before they are converted to CSS?

    Yes! This extension is itself extensible.

    It provides a very basic API that can be used by another VS Code extension to > add any custom preprocessing that is required. The input to the preprocessor is the .less file contents (as a string). The expected output is also a string of less syntax.

    Example:

    // Within your own VS Code extension...

import { extensions } from 'vscode';

// API type definitions.
type EasyLessAPI = { registerPreprocessor: (processor: PreprocessorFn): void };
type PreprocessorFn = (less: string, ctx: Map<string, any>) => Promise<string> | string;

// Overly-simplified preprocessor to convert "em" to "rem".
const emToRem: PreprocessorFn = async (less: string) => {
  return context.replace(/(?<=[\d\s])em\b/g, 'rem');
};

// Activation function for your extension.
export function activate(context: vscode.ExtensionContext) {
  // Get reference to EasyLESS extension.
  const extension = extensions.getExtension('mrcrowl.easy-less');
  if (!api) {
    console.error('EasyLESS is not installed or available.');
  }

  // Register emToRem as a less preprocessor.
  const api: EasyLessAPI = extension.exports;
  api.exports.registerPreprocessor(emToRem);
}
}

    Preprocessor functions can also return either a plain string or a Promise<string> depending on if any async processing is required.

    Extension Activation

    In order for your custom extension to activate, it is important that the following activation event is declared the in extension manifest (the package.json file for the extension):

      "activationEvents": [
     "onLanguage:less"
  ],

    This ensures that your extension is appropriately activated by VS Code.

    References

    Learn more about VS Code extensions and how they can be made extensibile by other extensions:

    🎩 HT to northwang-lucky for introducing this extensibility feature.

Acknowledgements