Using Plugins

Gulp plugins are Node Transform Streams that encapsulate common behavior to transform files in a pipeline - often placed between src() and dest() using the .pipe() method. They can change the filename, metadata, or contents of every file that passes through the stream.

Plugins from npm - using the “gulpplugin” and “gulpfriendly” keywords - can be browsed and searched on the plugin search page.

Each plugin should only do a small amount of work, so you can connect them like building blocks. You may need to combine a bunch of them to get the desired result.

1. const { src, dest } = require('gulp');
2. const uglify = require('gulp-uglify');
3. const rename = require('gulp-rename');

5. exports.default = function() {
6. return src('src/*.js')
7. // The gulp-uglify plugin won't update the filename
8. .pipe(uglify())
9. // So use gulp-rename to change the extension
10. .pipe(rename({ extname: '.min.js' }))
11. .pipe(dest('output/'));
12. }

Do you need a plugin?

Not everything in gulp should use plugins. They are a quick way to get started, but many operations are improved by using a module or library instead.

1. const { rollup } = require('rollup');

3. // Rollup's promise API works great in an `async` task
4. exports.default = async function() {
5. const bundle = await rollup({
6. input: 'src/index.js'
7. });

9. return bundle.write({
10. file: 'output/bundle.js',
11. format: 'iife'
12. });
13. }

Plugins should always transform files. Use a (non-plugin) Node module or library for any other operations.

1. const del = require('delete');

3. exports.default = function(cb) {
4. // Use the `delete` module directly, instead of using gulp-rimraf
5. del(['output/*.js'], cb);
6. }

Conditional plugins

Since plugin operations shouldn’t be file-type-aware, you may need a plugin like gulp-if to transform subsets of files.

1. const { src, dest } = require('gulp');
2. const gulpif = require('gulp-if');
3. const uglify = require('gulp-uglify');

5. function isJavaScript(file) {
6. // Check if file extension is '.js'
7. return file.extname === '.js';
8. }

10. exports.default = function() {
11. // Include JavaScript and CSS files in a single pipeline
12. return src(['src/*.js', 'src/*.css'])
13. // Only apply gulp-uglify plugin to JavaScript files
14. .pipe(gulpif(isJavaScript, uglify()))
15. .pipe(dest('output/'));
16. }

Inline plugins

Inline plugins are one-off Transform Streams you define inside your gulpfile by writing the desired behavior.

There are two situations where creating an inline plugin is helpful:

• Instead of creating and maintaining your own plugin.
• Instead of forking a plugin that exists to add a feature you want.

1. const { src, dest } = require('gulp');
2. const uglify = require('uglify-js');
3. const through2 = require('through2');

5. exports.default = function() {
6. return src('src/*.js')
7. // Instead of using gulp-uglify, you can create an inline plugin
8. .pipe(through2.obj(function(file, _, cb) {
9. if (file.isBuffer()) {
10. const code = uglify.minify(file.contents.toString())
11. file.contents = Buffer.from(code.code)
12. }
13. cb(null, file);
14. }))
15. .pipe(dest('output/'));
16. }