Environment-conditional task composition in Gulp 4 pipelines

Direct answer

Keep the registered task name stable and branch inside the task function. Use gulp-if or an equivalent per-stream condition to enable production-only transforms. Reserve series()/parallel()-level environment branching for intentionally separate entry points such as build:dev and build:prod, not for making the same task name resolve differently.

Confirmed Gulp 4 behavior

• Gulp 4 loads the gulpfile once. Load-time process.env checks become part of task definitions before CLI task resolution.
• If NODE_ENV changes which task names are exported or registered, gulp --tasks and gulp <task> can see different task sets.
• If the same check runs inside the task body, the registry still contains one stable task name; only the stream behavior changes for that run.
• A task signals async completion by returning a stream, promise, observable, child process, or event emitter, or by accepting a callback and invoking it. A missing return can make Gulp finish early; a missing callback call can make it hang.

Recommended placement

Decision	Recommended placement	Reason
Task names and CLI resolution	Inside the task function	Keeps the registry stable across environments
Production-only minification or source-map stripping	gulp-if inside the stream	Skips the transform without ending the stream
Entire production-only sequence	Separate named entry task	Makes environment-specific graphs explicit

Reliable pattern

Assumes Gulp 4.x and a compatible gulp-if version. Replace optimize() with your actual minifier or source-map transform.

const gulp = require('gulp');
const gulpIf = require('gulp-if');

function scripts() {
  const isProd = process.env.NODE_ENV === 'production';

  return gulp.src('src/**/*.js')
    .pipe(gulpIf(isProd, optimize()))
    .pipe(gulp.dest('dist'));
}

exports.build = gulp.series(scripts);

With current gulp-if, an explicit false branch is usually unnecessary: when the condition is false, files pass through unchanged. If you hand-roll the branch instead, both paths must return a stream. A no-op branch can return the source piped directly to gulp.dest(), or the task can return Promise.resolve() when there is genuinely no stream work.

Verification

Run these from the project root and compare the task lists:

NODE_ENV=development gulp --tasks
NODE_ENV=production gulp --tasks

The task names should be identical. Then run the build in both modes and confirm the process exits cleanly and the output differs only where the production transform is expected.

If the two gulp --tasks outputs differ, the fix belongs in the export/registration block, not in gulp-if.