1 | # [gulp][gulp]-uncss [![Build Status](https://travis-ci.org/ben-eb/gulp-uncss.svg?branch=master)][ci] [![NPM version](https://badge.fury.io/js/gulp-uncss.svg)][npm] [![Dependency Status](https://gemnasium.com/ben-eb/gulp-uncss.svg)][deps]
|
2 |
|
3 | > Remove unused CSS with [UnCSS][orig].
|
4 |
|
5 | *If you have any difficulties with the output of this plugin, please use the
|
6 | [UnCSS tracker][bugs].*
|
7 |
|
8 | ## Install
|
9 |
|
10 | With [npm](https://npmjs.org/package/gulp-uncss) do:
|
11 |
|
12 | ```
|
13 | npm install gulp-uncss --save-dev
|
14 | ```
|
15 |
|
16 | ## Example
|
17 |
|
18 | Single files, globbing patterns and URLs are all supported by gulp-uncss, and
|
19 | can be mixed and matched:
|
20 |
|
21 | ```js
|
22 | var gulp = require('gulp');
|
23 | var uncss = require('gulp-uncss');
|
24 |
|
25 | gulp.task('default', function () {
|
26 | return gulp.src('site.css')
|
27 | .pipe(uncss({
|
28 | html: ['index.html', 'posts/**/*.html', 'http://example.com']
|
29 | }))
|
30 | .pipe(gulp.dest('./out'));
|
31 | });
|
32 | ```
|
33 |
|
34 | gulp-uncss can also be used in a pipeline that involves CSS pre-processing.
|
35 | Utilising many transforms on a single file is one of gulp's strengths:
|
36 |
|
37 | ```js
|
38 | var gulp = require('gulp');
|
39 | var uncss = require('gulp-uncss');
|
40 | var sass = require('gulp-sass');
|
41 | var concat = require('gulp-concat');
|
42 | var nano = require('gulp-cssnano');
|
43 |
|
44 | gulp.task('default', function () {
|
45 | return gulp.src('styles/**/*.scss')
|
46 | .pipe(sass())
|
47 | .pipe(concat('main.css'))
|
48 | .pipe(uncss({
|
49 | html: ['index.html', 'posts/**/*.html', 'http://example.com']
|
50 | }))
|
51 | .pipe(nano())
|
52 | .pipe(gulp.dest('./out'));
|
53 | });
|
54 | ```
|
55 |
|
56 | In just a few lines, we compiled SCSS source into a single file, removed unused
|
57 | CSS and minified the output!
|
58 |
|
59 | ## Options
|
60 |
|
61 | Please see the [UnCSS documentation][docs] for all of the options you can use.
|
62 | Some of them aren't as necessary when using gulp-uncss, because the CSS to
|
63 | analyse comes from the stream rather than the HTML files. The main options you
|
64 | will likely be using are:
|
65 |
|
66 | ### html
|
67 | Type: `Array|String`
|
68 | *Required value.*
|
69 |
|
70 | An array which can contain an array of files relative to your `gulpfile.js`, and
|
71 | which can also contain URLs. Note that if you are to pass URLs here, then the
|
72 | task will take much longer to complete. If you want to pass some HTML directly
|
73 | into the task instead, you can specify it here as a string.
|
74 |
|
75 | ### ignore
|
76 | Type: `Array`
|
77 | Default value: `undefined`
|
78 |
|
79 | Selectors that should be left untouched by UnCSS as it can't detect user
|
80 | interaction on a page (hover, click, focus, for example). Both literal names and
|
81 | regex patterns are recognized.
|
82 |
|
83 | ### timeout
|
84 | Type: `Integer`
|
85 | Default value: `undefined`
|
86 |
|
87 | Specify how long to wait for the JS to be loaded.
|
88 |
|
89 | Note that `options.ignoreSheets` is *already defined* for you. gulp-uncss will
|
90 | only process CSS files in the stream.
|
91 |
|
92 | ## Contributing
|
93 |
|
94 | Pull requests are welcome. If you add functionality, then please add unit tests
|
95 | to cover it.
|
96 |
|
97 | ## License
|
98 |
|
99 | MIT © [Ben Briggs](http://beneb.info)
|
100 |
|
101 | [bugs]: https://github.com/giakki/uncss/issues
|
102 | [ci]: https://travis-ci.org/ben-eb/gulp-uncss
|
103 | [deps]: https://gemnasium.com/ben-eb/gulp-uncss
|
104 | [docs]: https://github.com/giakki/uncss#within-nodejs
|
105 | [gulp]: https://github.com/gulpjs/gulp
|
106 | [npm]: http://badge.fury.io/js/gulp-uncss
|
107 | [orig]: https://github.com/giakki/uncss
|