gulp-load-plugins
Automatically load any gulp plugins in your package.json
Install
$ npm install --save-dev gulp-load-plugins
Given a package.json file that has some dependencies within:
{
"dependencies": {
"gulp-jshint": "*",
"gulp-concat": "*"
}
}
Adding this into your Gulpfile.js:
var gulp = require('gulp');
var plugins = require('gulp-load-plugins')();
Will result in the following happening (roughly, plugins are lazy loaded but in practice you won’t notice any difference):
plugins.jshint = require('gulp-jshint');
plugins.concat = require('gulp-concat');
gulp-sequence
Run a series of gulp tasks in order.
Install
npm install --save-dev gulp-sequence
Usage
var gulp = require('gulp')
var gulpSequence = require('gulp-sequence')
gulp.task('a', function (cb) {
//... cb()
})
gulp.task('b', function (cb) {
//... cb()
})
gulp.task('c', function (cb) {
//... cb()
})
gulp.task('d', function (cb) {
//... cb()
})
gulp.task('e', function (cb) {
//... cb()
})
gulp.task('f', function () {
// return stream
return gulp.src('*.js')
})
// usage 1, recommend
// 1. run 'a', 'b' in parallel;
// 2. run 'c' after 'a' and 'b';
// 3. run 'd', 'e' in parallel after 'c';
// 3. run 'f' after 'd' and 'e'.
gulp.task('sequence-1', gulpSequence(['a', 'b'], 'c', ['d', 'e'], 'f'))
// usage 2
gulp.task('sequence-2', function (cb) {
gulpSequence(['a', 'b'], 'c', ['d', 'e'], 'f', cb)
})
// usage 3
gulp.task('sequence-3', function (cb) {
gulpSequence(['a', 'b'], 'c', ['d', 'e'], 'f')(cb)
})
gulp.task('gulp-sequence', gulpSequence('sequence-1', 'sequence-2', 'sequence-3'))
with gulp.watch:
gulp.watch('src/**/*.js', function (event) {
gulpSequence('a', 'b')(function (err) {
if (err) console.log(err)
})
})
gulp-eslint
A gulp plugin for processing files with ESLint
Installation Use npm.
npm install gulp-eslint
Usage
const gulp = require('gulp');
const eslint = require('gulp-eslint');
gulp.task('lint', () => {
// ESLint ignores files with "node_modules" paths.
// So, it's best to have gulp ignore the directory as well.
// Also, Be sure to return the stream from the task;
// Otherwise, the task may end before the stream has finished.
return gulp.src(['**/*.js','!node_modules/**'])
// eslint() attaches the lint output to the "eslint" property
// of the file object so it can be used by other modules.
.pipe(eslint())
// eslint.format() outputs the lint results to the console.
// Alternatively use eslint.formatEach() (see Docs).
.pipe(eslint.format())
// To have the process exit with an error code (1) on
// lint error, return the stream and pipe to failAfterError last.
.pipe(eslint.failAfterError());
});
gulp.task('default', ['lint'], function () {
// This will only run if the lint task is successful...
});
Or use the plugin API to do things like:
gulp.src(['**/*.js','!node_modules/**'])
.pipe(eslint({
rules: {
'my-custom-rule': 1,
'strict': 2
},
globals: [
'jQuery',
'$'
],
envs: [
'browser'
]
}))
.pipe(eslint.formatEach('compact', process.stderr));
gulp-htmlmin
gulp plugin to minify HTML.
Install with npm
npm i gulp-htmlmin --save-dev
Usage
var gulp = require('gulp');
var htmlmin = require('gulp-htmlmin');
gulp.task('minify', function() {
return gulp.src('src/*.html')
.pipe(htmlmin({collapseWhitespace: true}))
.pipe(gulp.dest('dist'));
});
gulp-clean
A gulp plugin for removing files and folders.
Install Install with npm.
npm install --save-dev gulp-clean
Examples
var gulp = require('gulp');
var clean = require('gulp-clean');
gulp.task('default', function () {
return gulp.src('app/tmp', {read: false})
.pipe(clean());
});
Install
$ npm install --save-dev gulp-autoprefixer
Usage
const gulp = require('gulp');
const autoprefixer = require('gulp-autoprefixer');
gulp.task('default', () =>
gulp.src('src/app.css')
.pipe(autoprefixer({
browsers: ['last 2 versions'],
cascade: false
}))
.pipe(gulp.dest('dist'))
);
API
autoprefixer([options])
options
See the Autoprefixer options.
Source Maps
Use gulp-sourcemaps like this:
const gulp = require('gulp');
const sourcemaps = require('gulp-sourcemaps');
const autoprefixer = require('gulp-autoprefixer');
const concat = require('gulp-concat');
gulp.task('default', () =>
gulp.src('src/**/*.css')
.pipe(sourcemaps.init())
.pipe(autoprefixer())
.pipe(concat('all.css'))
.pipe(sourcemaps.write('.'))
.pipe(gulp.dest('dist'))
);
gulp-sass
Gulp plugin for sass
Install
npm install gulp-sass --save-dev
Basic Usage
Something like this will compile your Sass files:
'use strict';
var gulp = require('gulp');
var sass = require('gulp-sass');
gulp.task('sass', function () {
return gulp.src('./sass/**/*.scss')
.pipe(sass().on('error', sass.logError))
.pipe(gulp.dest('./css'));
});
gulp.task('sass:watch', function () {
gulp.watch('./sass/**/*.scss', ['sass']);
});
You can also compile synchronously, doing something like this:
'use strict';
var gulp = require('gulp');
var sass = require('gulp-sass');
gulp.task('sass', function () {
return gulp.src('./sass/**/*.scss')
.pipe(sass.sync().on('error', sass.logError))
.pipe(gulp.dest('./css'));
});
gulp.task('sass:watch', function () {
gulp.watch('./sass/**/*.scss', ['sass']);
});
Options
Pass in options just like you would for node-sass; they will be passed along just as if you were using node-sass. Except for the data option which is used by gulp-sass internally. Using the file option is also unsupported and results in undefined behaviour that may change without notice.
For example:
gulp.task('sass', function () {
return gulp.src('./sass/**/*.scss')
.pipe(sass({outputStyle: 'compressed'}).on('error', sass.logError))
.pipe(gulp.dest('./css'));
});
Source Maps
gulp-sass can be used in tandem with gulp-sourcemaps to generate source maps for the Sass to CSS compilation. You will need to initialize gulp-sourcemaps prior to running gulp-sass and write the source maps after.
var sourcemaps = require('gulp-sourcemaps');
gulp.task('sass', function () {
return gulp.src('./sass/**/*.scss')
.pipe(sourcemaps.init())
.pipe(sass().on('error', sass.logError))
.pipe(sourcemaps.write())
.pipe(gulp.dest('./css'));
});
By default, gulp-sourcemaps writes the source maps inline in the compiled CSS files. To write them to a separate file, specify a path relative to the gulp.dest() destination in the sourcemaps.write() function.
var sourcemaps = require('gulp-sourcemaps');
gulp.task('sass', function () {
return gulp.src('./sass/**/*.scss')
.pipe(sourcemaps.init())
.pipe(sass().on('error', sass.logError))
.pipe(sourcemaps.write('./maps'))
.pipe(gulp.dest('./css'));
});
gulp-if
Conditionally run a task
A ternary gulp plugin: conditionally control the flow of vinyl objects.
Note: Badly behaved plugins can often get worse when used with gulp-if. Typically the fix is not in gulp-if.
Note: Works great with lazypipe, see below
Usage
1: Conditionally filter content
var gulpif = require('gulp-if');
var uglify = require('gulp-uglify');
var condition = true; // TODO: add business logic
gulp.task('task', function() {
gulp.src('./src/*.js')
.pipe(gulpif(condition, uglify()))
.pipe(gulp.dest('./dist/'));
});
Only uglify the content if the condition is true, but send all the files to the dist folder
2: Ternary filter
var gulpif = require('gulp-if');
var uglify = require('gulp-uglify');
var beautify = require('gulp-beautify');
var condition = function (file) {
// TODO: add business logic
return true;
}
gulp.task('task', function() {
gulp.src('./src/*.js')
.pipe(gulpif(condition, uglify(), beautify()))
.pipe(gulp.dest('./dist/'));
});
If condition returns true, uglify else beautify, then send everything to the dist folder
3: Remove things from the stream
var gulpIgnore = require('gulp-ignore');
var uglify = require('gulp-uglify');
var jshint = require('gulp-jshint');
var condition = './gulpfile.js';
gulp.task('task', function() {
gulp.src('./*.js')
.pipe(jshint())
.pipe(gulpIgnore.exclude(condition))
.pipe(uglify())
.pipe(gulp.dest('./dist/'));
});
Run JSHint on everything, remove gulpfile from the stream, then uglify and write everything else.
4: Exclude things from the stream
var uglify = require('gulp-uglify');
gulp.task('task', function() {
gulp.src(['./*.js', '!./node_modules/**'])
.pipe(uglify())
.pipe(gulp.dest('./dist/'));
});
Grab all JavaScript files that aren’t in the node_modules folder, uglify them, and write them. This is fastest because nothing in node_modules ever leaves gulp.src()
works great with lazypipe
Lazypipe creates a function that initializes the pipe chain on use. This allows you to create a chain of events inside the gulp-if condition. This scenario will run jshint analysis and reporter only if the linting flag is true.
var gulpif = require('gulp-if');
var jshint = require('gulp-jshint');
var uglify = require('gulp-uglify');
var lazypipe = require('lazypipe');
var linting = false;
var compressing = false;
var jshintChannel = lazypipe()
// adding a pipeline step
.pipe(jshint) // notice the stream function has not been called!
.pipe(jshint.reporter)
// adding a step with an argument
.pipe(jshint.reporter, 'fail');
gulp.task('scripts', function () {
return gulp.src(paths.scripts.src)
.pipe(gulpif(linting, jshintChannel()))
.pipe(gulpif(compressing, uglify()))
.pipe(gulp.dest(paths.scripts.dest));
});
works great inside lazypipe
Lazypipe assumes that all function parameters are static, gulp-if arguments need to be instantiated inside each lazypipe. This difference can be easily solved by passing a function on the lazypipe step
var gulpif = require('gulp-if');
var jshint = require('gulp-jshint');
var uglify = require('gulp-uglify');
var lazypipe = require('lazypipe');
var compressing = false;
var jsChannel = lazypipe()
// adding a pipeline step
.pipe(jshint) // notice the stream function has not been called!
.pipe(jshint.reporter)
// adding a step with an argument
.pipe(jshint.reporter, 'fail')
// you can't say: .pipe(gulpif, compressing, uglify)
// because uglify needs to be instantiated separately in each lazypipe instance
// you can say this instead:
.pipe(function () {
return gulpif(compressing, uglify());
});
// why does this work? lazypipe calls the function, passing in the no arguments to it,
// it instantiates a new gulp-if pipe and returns it to lazypipe.
gulp.task('scripts', function () {
return gulp.src(paths.scripts.src)
.pipe(jsChannel())
.pipe(gulp.dest(paths.scripts.dest));
});
gulp-clean-css
Minify css with clean-css.
Regarding Issues
This is just a simple gulp plugin, which means it’s nothing more than a thin wrapper around clean-css. If it looks like you are having CSS related issues, please contact clean-css. Only create a new issue if it looks like you’re having a problem with the plugin itself.
Install
npm install gulp-clean-css --save-dev
API
cleanCSS([options], [callback])
options
See the CleanCSS options.
var gulp = require('gulp');
var cleanCSS = require('gulp-clean-css');
gulp.task('minify-css', function() {
return gulp.src('styles/*.css')
.pipe(cleanCSS({compatibility: 'ie8'}))
.pipe(gulp.dest('dist'));
});
callback
Useful for returning details from the underlying minify() call. An example use case could include logging stats of the minified file. In addition to the default object, gulp-clean-css provides the file name and path for further analysis.
var gulp = require('gulp');
var cleanCSS = require('gulp-clean-css');
gulp.task('minify-css', function() {
return gulp.src('styles/*.css')
.pipe(cleanCSS({debug: true}, function(details) {
console.log(details.name + ': ' + details.stats.originalSize);
console.log(details.name + ': ' + details.stats.minifiedSize);
}))
.pipe(gulp.dest('dist'));
});
Source Maps can be generated by using gulp-sourcemaps.
var gulp = require('gulp');
var cleanCSS = require('gulp-clean-css');
var sourcemaps = require('gulp-sourcemaps');
gulp.task('minify-css', function() {
return gulp.src('./src/*.css')
.pipe(sourcemaps.init())
.pipe(cleanCSS())
.pipe(sourcemaps.write())
.pipe(gulp.dest('dist'));
});
});
gulp-inject
A javascript, stylesheet and webcomponent injection plugin for Gulp, i.e. inject file references into your index.html
Installation
Install gulp-inject as a development dependency:
npm install --save-dev gulp-inject
Basic usage
The target file src/index.html:
Each pair of comments are the injection placeholders (aka. tags, see options.starttag and options.endtag).
<!DOCTYPE html>
<html>
<head>
<title>My index</title>
<!-- inject:css -->
<!-- endinject -->
</head>
<body>
<!-- inject:js -->
<!-- endinject -->
</body>
</html>
The gulpfile.js:
var gulp = require('gulp');
var inject = require('gulp-inject');
gulp.task('index', function () {
var target = gulp.src('./src/index.html');
// It's not necessary to read the files (will speed up things), we're only after their paths:
var sources = gulp.src(['./src/**/*.js', './src/**/*.css'], {read: false});
return target.pipe(inject(sources))
.pipe(gulp.dest('./src'));
});
src/index.html after running gulp index:
<!DOCTYPE html>
<html>
<head>
<title>My index</title>
<!-- inject:css -->
<link rel="stylesheet" href="/src/style1.css">
<link rel="stylesheet" href="/src/style2.css">
<!-- endinject -->
</head>
<body>
<!-- inject:js -->
<script src="/src/lib1.js"></script>
<script src="/src/lib2.js"></script>
<!-- endinject -->
</body>
</html>
gulp-uglify
Minify files with UglifyJS.
Installation
Install package with NPM and add it to your development dependencies:
npm install --save-dev gulp-uglify
Usage
var gulp = require('gulp');
var uglify = require('gulp-uglify');
var pump = require('pump');
gulp.task('compress', function (cb) {
pump([
gulp.src('lib/*.js'),
uglify(),
gulp.dest('dist')
],
cb
);
});
gulp-sourcemaps
Source map support for Gulp.js
Usage
Write inline source maps Inline source maps are embedded in the source file.
Example:
var gulp = require('gulp');
var plugin1 = require('gulp-plugin1');
var plugin2 = require('gulp-plugin2');
var sourcemaps = require('gulp-sourcemaps');
gulp.task('javascript', function() {
gulp.src('src/**/*.js')
.pipe(sourcemaps.init())
.pipe(plugin1())
.pipe(plugin2())
.pipe(sourcemaps.write())
.pipe(gulp.dest('dist'));
});
All plugins between sourcemaps.init() and sourcemaps.write() need to have support for gulp-sourcemaps. You can find a list of such plugins in the wiki.
Write external source map files
To write external source map files, pass a path relative to the destination to sourcemaps.write().
Example:
var gulp = require('gulp');
var plugin1 = require('gulp-plugin1');
var plugin2 = require('gulp-plugin2');
var sourcemaps = require('gulp-sourcemaps');
gulp.task('javascript', function() {
gulp.src('src/**/*.js')
.pipe(sourcemaps.init())
.pipe(plugin1())
.pipe(plugin2())
.pipe(sourcemaps.write('../maps'))
.pipe(gulp.dest('dist'));
});
Load existing source maps
To load existing source maps, pass the option loadMaps: true to sourcemaps.init().
Example:
var gulp = require('gulp');
var plugin1 = require('gulp-plugin1');
var plugin2 = require('gulp-plugin2');
var sourcemaps = require('gulp-sourcemaps');
gulp.task('javascript', function() {
gulp.src('src/**/*.js')
.pipe(sourcemaps.init({loadMaps: true}))
.pipe(plugin1())
.pipe(plugin2())
.pipe(sourcemaps.write())
.pipe(gulp.dest('dist'));
});
Handle large files
To handle large files, pass the option largeFile: true to sourcemaps.init().
Example:
var gulp = require('gulp');
var plugin1 = require('gulp-plugin1');
var plugin2 = require('gulp-plugin2');
var sourcemaps = require('gulp-sourcemaps');
gulp.task('javascript', function() {
gulp.src('src/**/*.js')
.pipe(sourcemaps.init({largeFile: true}))
.pipe(plugin1())
.pipe(plugin2())
.pipe(sourcemaps.write())
.pipe(gulp.dest('dist'));
});
gulp-rename
gulp-rename is a gulp plugin to rename files easily.
NPM
build status devDependency Status
Usage
gulp-rename provides simple file renaming methods.
var rename = require("gulp-rename");
// rename via string
gulp.src("./src/main/text/hello.txt")
.pipe(rename("main/text/ciao/goodbye.md"))
.pipe(gulp.dest("./dist")); // ./dist/main/text/ciao/goodbye.md
// rename via function
gulp.src("./src/**/hello.txt")
.pipe(rename(function (path) {
path.dirname += "/ciao";
path.basename += "-goodbye";
path.extname = ".md"
}))
.pipe(gulp.dest("./dist")); // ./dist/main/text/ciao/hello-goodbye.md
// rename via hash
gulp.src("./src/main/text/hello.txt", { base: process.cwd() })
.pipe(rename({
dirname: "main/text/ciao",
basename: "aloha",
prefix: "bonjour-",
suffix: "-hola",
extname: ".md"
}))
.pipe(gulp.dest("./dist")); // ./dist/main/text/ciao/bonjour-aloha-hola.md
See test/rename.spec.js for more examples and test/path-parsing.spec.js for hairy details.
gulp-concat
Concatenates files
Installation
Install package with NPM and add it to your development dependencies:
npm install --save-dev gulp-concat
Usage
var concat = require('gulp-concat');
gulp.task('scripts', function() {
return gulp.src('./lib/*.js')
.pipe(concat('all.js'))
.pipe(gulp.dest('./dist/'));
});
This will concat files by your operating systems newLine. It will take the base directory from the first file that passes through it.
Files will be concatenated in the order that they are specified in the gulp.src function. For example, to concat ./lib/file3.js, ./lib/file1.js and ./lib/file2.js in that order, the following code will create a task to do that:
var concat = require('gulp-concat');
gulp.task('scripts', function() {
return gulp.src(['./lib/file3.js', './lib/file1.js', './lib/file2.js'])
.pipe(concat('all.js'))
.pipe(gulp.dest('./dist/'));
});
To change the newLine simply pass an object as the second argument to concat with newLine being whatever (\r\n if you want to support any OS to look at it)
For instance:
.pipe(concat('main.js', {newLine: ';'}))
To specify cwd, path and other vinyl properties, gulp-concat accepts Object as first argument:
var concat = require('gulp-concat');
gulp.task('scripts', function() {
return gulp.src(['./lib/file3.js', './lib/file1.js', './lib/file2.js'])
.pipe(concat({ path: 'new.js', stat: { mode: 0666 }}))
.pipe(gulp.dest('./dist'));
});
This will concat files into ./dist/new.js.
Source maps
Source maps can be generated by using gulp-sourcemaps:
var gulp = require('gulp');
var concat = require('gulp-concat');
var sourcemaps = require('gulp-sourcemaps');
gulp.task('javascript', function() {
return gulp.src('src/**/*.js')
.pipe(sourcemaps.init())
.pipe(concat('all.js'))
.pipe(sourcemaps.write())
.pipe(gulp.dest('dist'));
});
gulp-htmlmin
gulp plugin to minify HTML.
Install with npm
npm i gulp-htmlmin --save-dev
Usage
var gulp = require('gulp');
var htmlmin = require('gulp-htmlmin');
gulp.task('minify', function() {
return gulp.src('src/*.html')
.pipe(htmlmin({collapseWhitespace: true}))
.pipe(gulp.dest('dist'));
});
##［gulp-csslint](https://www.npmjs.com/package/gulp-csslint/)
CSSLint plugin for gulp
Usage
First, install gulp-csslint as a development dependency:
npm install --save-dev gulp-csslint
Then, add it to your gulpfile.js:
var csslint = require('gulp-csslint');
gulp.task('css', function() {
gulp.src('client/css/*.css')
.pipe(csslint())
.pipe(csslint.formatter());
});
