ZetCode

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.

src/style.css
/* main styles */
body {
    margin: 0;
    font-family: sans-serif;
}

.title {
    color: #336699;
    font-size: 2rem;
}
src/app.js
// 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.

gulpfile.mjs
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

I am Jan Bodnar, a programmer and technical writer. I have been writing programming tutorials at ZetCode since 2007 and have published eight e-books. See about the author.

List all Gulp tutorials.