grunt-lesslint

5.0.0 verified Fri May 01 auth: no javascript maintenance

Grunt task that compiles LESS files and runs CSS Lint on the generated CSS, mapping errors back to the original LESS lines. Version 5.0.0 is the current stable release; the project is in maintenance mode with infrequent updates. Key differentiators: integrates CSS Lint rules with LESS source mapping for line-accurate error reporting, supports failOnWarning/failOnError options for staged rule adoption, and allows configuration of LESS parser options. Alternative tools (e.g., stylelint, lesshint) are more actively maintained.

Common errors

error Warning: Task "lesslint" failed. Use --force to continue. ↓

cause Lint errors or warnings are present and failOnWarning defaults to true.

fix

Set failOnWarning: false to allow warnings without failure, or fix the lint issues.

error Cannot find module 'grunt-lesslint' ↓

cause Package not installed or not properly loaded.

fix

Run npm install grunt-lesslint --save-dev and ensure grunt.loadNpmTasks('grunt-lesslint') is in Gruntfile.

error Fatal error: Unable to find a valid version for CSS Lint. ↓

cause Missing peer dependency csslint or incompatible version installed.

fix

Install csslint: npm install csslint --save-dev.

Warnings

deprecated CSS Lint is no longer actively maintained; consider switching to stylelint or lesshint. ↓

fix Migrate to a more modern linter like stylelint with less syntax support.

gotcha By default, imported files are not linted. Must set `options.imports: true` to lint imports. ↓

fix Add `imports: true` to lesslint options.

gotcha Setting `failOnError: false` overrides both warnings and errors; task never fails. ↓

fix Use `failOnWarning: false` if you only want to allow warnings without failing.

breaking Version 5.0.0 changed the summary output format and introduced `failOnWarning` option. Old summary format (e.g., '58 lint issues in 167 files (0 errors, 58 warnings)') is now used instead of previous format. ↓

fix Update any scripts parsing task output to expect the new format.

Install

npm install grunt-lesslint

yarn add grunt-lesslint

pnpm add grunt-lesslint

Imports

grunt-lesslint
wrong
```
require('grunt-lesslint')
```
correct
```
grunt.loadNpmTasks('grunt-lesslint')
```
Grunt plugins are registered via grunt.loadNpmTasks in the Gruntfile, not via require().

lesslint (task)

wrong

grunt.initConfig({ 'grunt-lesslint': { ... } })

correct

grunt.initConfig({ lesslint: { src: ['src/**/*.less'] } })

Task name is 'lesslint', not the package name.

options (csslint, less, imports)

wrong

lesslint: { options: { csslint: { 'known-properties': false, paths: ['includes'] } } }

correct

lesslint: { options: { csslint: { 'known-properties': false }, less: { paths: ['includes'] }, imports: false } }

CSS Lint options go under 'csslint', LESS parser options under 'less', and import linting under 'imports'.

Quickstart

Example Gruntfile configuration to lint LESS files with custom CSS Lint rules, LESS include paths, import linting disabled, and warnings not failing the build.

// Gruntfile.js
module.exports = function(grunt) {
  grunt.initConfig({
    lesslint: {
      src: ['src/**/*.less'],
      options: {
        csslint: {
          'known-properties': false,
          csslintrc: '.csslintrc'
        },
        less: {
          paths: ['includes']
        },
        imports: false,
        failOnWarning: false
      }
    }
  });

  grunt.loadNpmTasks('grunt-lesslint');

  grunt.registerTask('default', ['lesslint']);
};