Skip to content
Switch branches/tags


Failed to load latest commit information.
Latest commit message
Commit time

CircleCI npm version Dependencies devDependency Status Commitizen friendly Backers on Open Collective Sponsors on Open Collective

Dead Simple LESS CSS Watch Compiler

A command that watches folders(and subfolders) for file changes and automatically compile the less css files into css. This is a file system watcher and compiler. It also keep track of a dependency tree and recompiles the parent if an imported (child) LESS file is changed.

Parts of this script is modified from Mikeal Rogers's watch script (


The commands below may need to be prefixed with sudo depending upon your system

Install LESS and make sure the lessc binary is accessible to the script. Installing LESS with the -g(global) flag will make the binary accessible to your system.


yarn global add less


npm install -g less


The commands below may need to be prefixed with sudo depending upon your system

Install the less-watch-compiler command globally.


yarn global add less-watch-compiler


npm install -g less-watch-compiler


With no main file

You need to pass in the minimum 2 parameters - <source_dir> and <destination_dir> . First parameter is the source folder to watch for changes and second is the output folder in which the css files will be compiled


less-watch-compiler [options] <source_dir> <destination_dir>

With main file

If you pass in the 3rd optional parameter, Any file change will trigger only to compile the main file specified in the 3rd parameter. Assuming the 3rd is "main.less"


less-watch-compiler [options] <source_dir> <destination_dir> [main-file]

Basic example

 │    └── main.less
 │    └── aux.less
      └── main.css

The project can be compiled with the following command:

less-watch-compiler src dist main.less

Configuration File

By default the the configuration file is loaded from ./less-watch-compiler.config.json but can also be specified by the --config option.

Example using the project tree laid out in the previous example


    "watchFolder": "src",
    "outputFolder": "dist",
    "mainFile": "main.less"

The project can be compiled with the following command:


All configuration file options

    "watchFolder": "<input_folder>",   
    "outputFolder": "<output_folder>",
    "mainFile": "<main-file>",   
    "includeHidden": false,
    "sourceMap": false,
    "plugins": "plugin1,plugin2",
    "lessArgs": "option1=1,option2=2",
    "runOnce": false,
    "enableJs": true


-h, --help                                                               output usage information
-V, --version                                                            output the version number
--main-file <file>                                                       Specify <file> as the file to always re-compile e.g. '--main-file style.less'.
--config <file>                                                          Custom configuration file path. (default: "less-watch-compiler.config.json")
--run-once                                                               Run the compiler once without waiting for additional changes.
--include-hidden                                                         Don't ignore files beginning with a '.' or a '_'
--enable-js                                                              Less.js Option: To enable inline JavaScript in less files.
--source-map                                                             Less.js Option: To generate source map for css files.
--plugins <plugin-a>,<plugin-b>                                          Less.js Option: To specify plugins separated by commas.
--less-args <less-arg1>=<less-arg1-value>,<less-arg1>=<less-arg2-value>  Less.js Option: To specify any other less options e.g. '--less-args math=strict,strict-units=on,include-path=./dir1\;./dir2'.

Please note:

  • By default, "minified" is turned on to always compress/minify output. You can set the minification to false by adding "minified":false in the config file.
  • By default, "sourceMap" is turned off. You can generating sourcemap to true by adding "sourceMap":true in the config file.
  • By default, this script only compiles files with .less extension. More file extensions can be added by modifying the allowedExtensions array in config.json.
  • Files that start with underscores _style.css or period .style.css are ignored. This behavior can be changed by adding "includeHidden:true in the config file.
  • When --run-once used, compilation will fail on first error

Using the source files

Alternativelly, you can checkout the code and run things locally like this:

node less-watch-compiler.js [options]

To run unit tests: yarn test or npm test (see test/test.js).


This project exists thanks to all the people who contribute. [Contribute].


Thank you to all our backers! 🙏 [Become a backer]


Support this project by becoming a sponsor. Your logo will show up here with a link to your website. [Become a sponsor]