Gulp conditional pipelines
last modified November 15, 2026
In this article we build differently for development and production with Gulp 5. The gulp-if
plugin runs a step of a pipeline only when a condition is true; the condition comes from a command line flag
or from the NODE_ENV environment variable.
Development and production builds
A development build should be fast and easy to debug: no minification, with source maps. A production
build should be small: minified, without source maps. Maintaining two sets of tasks would duplicate code, so one
set of tasks changes its behavior according to a flag. A pipeline is a chain of steps, and we need a way to
include a step conditionally; the gulp-if plugin does that. Whether we are in production is decided at the
start of the gulpfile, from the command line or from the environment.
Installing the project
We create a project and install Gulp, gulp-if, yargs to read the command line
flags, and the minifiers from the Gulp clean-css and
Gulp Terser tutorials.
$ mkdir gulp-cond $ cd gulp-cond $ npm init -y $ npm i -D gulp gulp-if yargs gulp-terser gulp-clean-css del $ mkdir src
The example project
The sources are a stylesheet and a script with comments and whitespace that a minifier removes.
/* main styles */
body {
margin: 0;
font-family: sans-serif;
}
.title {
color: #336699;
font-size: 2rem;
}
// application code
function greet(name) {
const message = 'Hello, ' + name + '!';
console.log(message);
}
greet('Gulp');
The gulpfile
The gulpfile reads the --production flag with yargs, combines it with the
NODE_ENV variable into one constant isProd, and uses the constant in the tasks. It is an
ES module, see the ESM gulpfile tutorial.
import { src, dest, series, parallel, watch } from 'gulp';
import { deleteAsync } from 'del';
import gulpif from 'gulp-if';
import terser from 'gulp-terser';
import cleanCSS from 'gulp-clean-css';
import yargs from 'yargs';
import { hideBin } from 'yargs/helpers';
const argv = yargs(hideBin(process.argv))
.option('production', { type: 'boolean', default: false })
.parse();
const isProd = argv.production || process.env.NODE_ENV === 'production';
export function styles() {
return src('src/*.css', { sourcemaps: !isProd })
.pipe(gulpif(isProd, cleanCSS()))
.pipe(dest('dist', { sourcemaps: isProd ? false : '.' }));
}
export function scripts() {
return src('src/*.js', { sourcemaps: !isProd })
.pipe(gulpif(isProd, terser()))
.pipe(dest('dist', { sourcemaps: isProd ? false : '.' }));
}
export const build = parallel(styles, scripts);
export function assets() {
return src('src/*.{css,js}')
.pipe(gulpif('*.css', cleanCSS(), terser()))
.pipe(dest('dist/assets'));
}
export function mode(done) {
console.log(isProd ? 'production build' : 'development build');
done();
}
export function clean() {
return deleteAsync('dist');
}
function watchFiles() {
watch('src/*.css', styles);
watch('src/*.js', scripts);
}
export default isProd ? series(clean, build) : series(build, watchFiles);
We look at the parts of the file in the following sections.
The production flag
The yargs call parses the arguments of the process; hideBin removes the first two entries
(node and the script), and the option is declared as a boolean with the default false. The flag is
true if the user passed --production or if the environment has NODE_ENV=production, which is
how deployment systems usually say it.
const argv = yargs(hideBin(process.argv))
.option('production', { type: 'boolean', default: false })
.parse();
const isProd = argv.production || process.env.NODE_ENV === 'production';
The mode task prints the result; the flag and the variable give the same answer, and the flag can be switched off
with --production=false. Gulp does not mind the additional flag; it only parses its own options.
$ npx gulp mode --silent development build $ npx gulp mode --production --silent production build $ NODE_ENV=production npx gulp mode --silent production build $ npx gulp mode --production=false --silent development build
Conditional steps
The gulpif(condition, stream) function returns a stream that passes the files through the given
stream if the condition is true, and unchanged if it is false. In the styles task the minifier is
used only in production. The same idea is used for the source maps: they are on when the build is not a production
one.
export function styles() {
return src('src/*.css', { sourcemaps: !isProd })
.pipe(gulpif(isProd, cleanCSS()))
.pipe(dest('dist', { sourcemaps: isProd ? false : '.' }));
}
The scripts task is the same with terser(). The development build keeps the code
readable and writes the maps; it also has the larger files. The task build runs both in
parallel, see Gulp series and parallel.
$ npx gulp build --silent $ ls dist app.js app.js.map style.css style.css.map $ wc -c dist/* 163 dist/app.js 235 dist/app.js.map 162 dist/style.css 237 dist/style.css.map 797 total
The production build
With the flag the same tasks give minified files and no maps. The sources have 124 and 131 bytes; the minified files have 70 and 71 bytes, and the script is a single line with shortened variables.
Because the environment variable is checked too, the same result comes from NODE_ENV=production npx gulp build, which
is the form that is easy to set in a CI configuration. The --production flag is more convenient on a developer
machine.
$ wc -c src/*
131 src/app.js
124 src/style.css
255 total
$ rm -rf dist
$ npx gulp build --production --silent
$ ls dist
app.js
style.css
$ wc -c dist/*
71 dist/app.js
70 dist/style.css
141 total
$ cat dist/app.js
function greet(e){const o="Hello, "+e+"!";console.log(o)}greet("Gulp");
$ cat dist/style.css
body{margin:0;font-family:sans-serif}.title{color:#369;font-size:2rem}
Conditions on files
The condition does not have to be a boolean. It can also be a glob string or a function that receives a file, so one
stream can contain files of different types and each gets its own treatment. The third argument is the stream for the
files that fail the condition, like the else branch. The assets task sends CSS files to the CSS
minifier and the rest, the JavaScript files, to Terser.
export function assets() {
return src('src/*.{css,js}')
.pipe(gulpif('*.css', cleanCSS(), terser()))
.pipe(dest('dist/assets'));
}
A function works the same way, for example gulpif(file => file.extname === '.css', ...), and it can
check the content or the size of a file.
$ rm -rf dist
$ npx gulp assets --silent
$ wc -c dist/assets/*
71 dist/assets/app.js
70 dist/assets/style.css
141 total
$ cat dist/assets/style.css
body{margin:0;font-family:sans-serif}.title{color:#369;font-size:2rem}
Choosing tasks
The flag can also select whole tasks. A common arrangement exports a default task that differs per mode: production
cleans the output and builds, development builds and then watches the files with the watch function from the
Gulp watch tutorial. The tasks are ordinary functions, so the choice is an ordinary conditional
expression.
export default isProd ? series(clean, build) : series(build, watchFiles);
The clean task is described in the Gulp clean tutorial. Remember that the
condition is evaluated once, when the gulpfile loads, so the choice cannot change while the task runs. With the flag
the default task cleans the output and builds, and then it ends; without the flag it builds and keeps running, and
the watchers rebuild the files on every change until we stop the task with Ctrl+C.
$ npx gulp --production [13:48:14] Using gulpfile ~/Documents/prog/js/gulp-cond/gulpfile.mjs [13:48:14] Starting 'default'... [13:48:14] Starting 'clean'... [13:48:14] Finished 'clean' after 7.82 ms [13:48:14] Starting 'styles'... [13:48:14] Starting 'scripts'... [13:48:14] Finished 'styles' after 33 ms [13:48:14] Finished 'scripts' after 34 ms [13:48:14] Finished 'default' after 43 ms
Source
gulp-if on npm, yargs, Gulp task
In this article we have built differently for development and production with Gulp 5: we read a flag and an
environment variable, used gulp-if for conditional steps and conditions on files, and chose source
maps and minification per mode. See also the Gulp Terser and Gulp source maps tutorials.
Author
List all Gulp tutorials.