Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

https://github.com/lazd/gulp-csslint

CSSLint plugin for gulp
https://github.com/lazd/gulp-csslint

Last synced: 10 days ago
JSON representation

CSSLint plugin for gulp

Lists

README 

        
# gulp-csslint [![NPM version][npm-image]][npm-url] [![Build status][travis-image]][travis-url] [![Test coverage][coveralls-image]][coveralls-url] [![Dependency status][david-image]][david-url]

> CSSLint plugin for gulp 3



## Usage



First, install `gulp-csslint` as a development dependency:



```shell

npm install --save-dev gulp-csslint

```



Then, add it to your `gulpfile.js`:



```js

var csslint = require('gulp-csslint');



gulp.task('css', function() {

  gulp.src('client/css/*.css')

    .pipe(csslint())

    .pipe(csslint.formatter());

});

```



## API



### csslint(ruleConfiguration)



#### ruleConfiguration

Type: `Object`



If you pass `lookup: false`, the local .csslintrc is not looked up automatically.



You can pass rule configuration as an object. See the [list of rules by ID on the CSSLint wiki](https://github.com/stubbornella/csslint/wiki/Rules-by-ID) for valid rule IDs.



Any properties passed will be in _addition_ to (or overwriting) the ones in .csslintrc (unless `lookup: false` is passed).



```js

gulp.src('client/css/*.css')

  .pipe(csslint({

    'shorthand': false

  }))

  .pipe(csslint.formatter());

```



### csslint(csslintrc)



#### csslintrc

Type: `String`



You can also pass the path to your csslintrc file instead of a rule configuration object.



```js

gulp.src('client/css/*.css')

  .pipe(csslint('csslintrc.json'))

  .pipe(csslint.formatter());

```



## Results



Adds the following properties to the file object:



```js

file.csslint.success = true; // or false

file.csslint.report = {}; // The report from CSSLint after linting the file

```



## Using formatters



Several formatters come built-in to CSSLint. To use one of these formatters, pass the name to `csslint.formatter`.



For a list of all formatters supported by `csslint`, see the [csslint wiki](https://github.com/CSSLint/csslint/wiki/Command-line-interface#--format).



```js

gulp.task('lint', function() {

  gulp.src('lib/*.css')

    .pipe(csslint())

    .pipe(csslint.formatter('junit-xml'));

```



### Custom formatters



Custom formatters can be provided by first adding a valid CSSLint-formatter, such as `csslint-stylish`, then using it:



```js

var csslint = require('gulp-csslint');



csslint.addFormatter('csslint-stylish');



gulp.task('lint', function() {

  gulp.src('lib/*.css')

    .pipe(csslint())

    .pipe(csslint.formatter('stylish'))

});

```



You can provide the formatter by requiring it directly as well:



```js

var csslint = require('gulp-csslint');



gulp.task('lint', function() {

  gulp.src('lib/*.css')

    .pipe(csslint())

    .pipe(csslint.formatter(require('csslint-stylish')))

});

```



You can also provide an object with the following contract to implement your own formatter:



```js

{

  id: 'string', // Name passed to csslint.formatter

  startFormat: function() {}, // Called before parsing any files, should return a string

  startFormat: function() {}, // Called after parsing all files, should return a string

  formatResult: function (results, filename, options) {} // Called with a results-object per file linted. Optionally called with a filename, and options passed to csslint.formatter(*formatter*, *options*)

}

```



You can also provide a function, which is called for each file linted with the same arguments as `formatResults`.



### Formatter options

You can also pass options to the built-in formatter, by passing a second option to `formatter`.



```js

gulp.task('lint', function() {

  gulp.src('lib/*.css')

    .pipe(csslint())

    .pipe(csslint.formatter('junit-xml', options));

});

```



See the documentation for the formatters regarding what options they support.



This plugin supports one option outside of that, called `logger`, allowing you to specify how to log out the report.

Default is using `process.stdout.write`, but you can use e.g. `console.log`, or `gutil.log`.



```js

gulp.task('lint', function() {

  gulp.src('lib/*.css')

    .pipe(csslint())

    .pipe(csslint.formatter('junit-xml', {logger: console.log.bind(console)}));

});

```



```js

gulp.task('lint', function() {

  gulp.src('lib/*.css')

    .pipe(csslint())

    .pipe(csslint.formatter('junit-xml', {logger: gutil.log.bind(null, 'gulp-csslint:')}));

});

```



`logger` is called once for the starting format of the formatter, then once for each file containing violations, then

lastly once for the ending format. Instead of writing to `stdout`, you can write to file using this option.



```js

gulp.task('lint', function(cb) {

  var fs = require('fs');

  var output = '';



  gulp.src('lib/*.css')

    .pipe(csslint())

    .pipe(csslint.formatter('junit-xml', {logger: function(str) { output += str; }}))

    .on('end', function(err) {

      if (err) return cb(err);



      fs.writeFile('some/path/junit.xml', output, cb);

    });

});

```



This functionality is only available when not using a custom formatting function.



## Custom rules



Use the `csslint.addRule(rule)` method to define custom rules that run in addition to the rules defined in the csslintrc file. See [Working with Rules](https://github.com/CSSLint/csslint/wiki/Working-with-Rules) for details.



```js

var csslint = require('gulp-csslint');



csslint.addRule({

  // rule information

});



gulp.task('lint', function() {

  gulp.src('lib/*.css')

    .pipe(csslint())

    .pipe(csslint.formatter())

});

```



## Fail on errors



Pipe the file stream to `csslint.failFormatter()` to fail on errors.



```js

var csslint = require('gulp-csslint');



gulp.task('lint', function() {

  gulp.src('lib/*.css')

    .pipe(csslint())

    .pipe(csslint.formatter()) // Display errors

    .pipe(csslint.formatter('fail')); // Fail on error (or csslint.failFormatter())

});

```



[travis-url]: http://travis-ci.org/lazd/gulp-csslint

[travis-image]: https://img.shields.io/travis/lazd/gulp-csslint.svg

[npm-url]: https://npmjs.org/package/gulp-csslint

[npm-image]: https://img.shields.io/npm/v/gulp-csslint.svg

[david-url]: https://david-dm.org/lazd/gulp-csslint

[david-image]: https://img.shields.io/david/lazd/gulp-csslint.svg

[coveralls-url]: https://coveralls.io/r/lazd/gulp-csslint

[coveralls-image]: https://img.shields.io/coveralls/lazd/gulp-csslint.svg