Gulp

Common errors

• AssertionError: Task function must be specified

  cause Attempting to use the Gulp 3 task dependency array syntax (e.g., `gulp.task('name', ['dep'], function() {})`) in Gulp 4.
  fix Replace the dependency array with `gulp.series()` or `gulp.parallel()`. Example: `gulp.task('name', gulp.series('dep', function() {}))`.

• Task 'taskName' is not a function

  cause A task function was not correctly defined or exposed, or a string reference was used for a task that isn't registered via `gulp.task()` or exported.
  fix Ensure the referenced task is either defined as a named function and passed to `gulp.task(myTask)` or `exports.myTask = myTask`, or directly passed as a function to `gulp.series()`/`gulp.parallel()`.

• Task never defined: taskName

  cause The task name used in `gulp.series()` or `gulp.parallel()` (as a string) does not correspond to a registered or exported Gulp task.
  fix Double-check task names for typos. Ensure tasks intended to be run by string name are correctly exposed either by `gulp.task('taskName', myFunc)` or by `exports.taskName = myFunc` if using the modern module pattern.

• TypeError: del is not a function

  cause Using `del.sync()` with newer versions of the `del` package, which moved to an async-only API and ESM.
  fix Remove `.sync()` and ensure your task returns the Promise from `del()`. Example: `function clean() { return del(['build']); }`. If still failing, check `del` version compatibility with your `gulpfile`'s module system (CJS vs ESM).

Warnings

• breaking Gulp 4 introduced significant breaking changes to task definition. The array syntax for defining task dependencies (e.g., `gulp.task('build', ['clean', 'scripts'])`) was removed. Tasks must now be composed using `gulp.series()` for sequential execution and `gulp.parallel()` for concurrent execution.
  Fix: Rewrite task dependencies using `gulp.series()` and `gulp.parallel()` combinators. For example, `gulp.task('build', gulp.series('clean', gulp.parallel('scripts', 'styles')))`.
• breaking Asynchronous tasks in Gulp 4 (tasks that don't immediately return a value) must signal their completion. This is achieved by returning a stream, returning a Promise, returning an RxJS observable, returning a child process, or accepting a callback function and calling it when done.
  Fix: Ensure your task function returns a stream (e.g., `gulp.src(...).pipe(...)`), returns a Promise (e.g., `return del(['build'])`), or accepts a `done` callback and calls `done()` when finished.
• gotcha Defining tasks as anonymous functions (`gulp.task('name', function() {})`) makes debugging and understanding task graphs difficult as they appear as `<anonymous>` in the CLI. Gulp 4 encourages named functions.
  Fix: Use named functions for tasks, either by defining them separately and passing the reference (`function myTask() {}; gulp.task(myTask);`) or by exporting them directly (`exports.myTask = function() {};`).
• breaking The `del` package (a common dependency for cleaning) moved to pure ESM in version 7.0.0. If your `gulpfile.js` is still CommonJS, you might encounter issues unless using a version of `del` that supports CommonJS, or by switching your `gulpfile` to ESM.
  Fix: For CommonJS `gulpfile.js`, use `del` version `^6.0.0`. If you need `del@7.0.0` or newer, migrate your `gulpfile.js` to ES Modules (e.g., rename to `gulpfile.mjs` or set `"type": "module"` in `package.json`).
• gotcha The `gulp-cli` package is a separate installation (`npm install -g gulp-cli`) from the `gulp` library itself (`npm install --save-dev gulp`). Both are necessary for running Gulp commands effectively.
  Fix: Ensure `gulp-cli` is installed globally and `gulp` is installed as a dev dependency in your project. Verify versions with `gulp -v`.

Install

• npm install gulp-pre npm
• yarn add gulp-pre yarn
• pnpm add gulp-pre pnpm

Imports

• gulp
  wrong:

  import gulp from 'gulp';

  correct:

  const gulp = require('gulp');

  CommonJS `require` is the traditional method for `gulpfile.js`. While Gulp supports ESM, the default export pattern for the main `gulp` object is recommended before destructuring its APIs.
• { src, dest, series, parallel }
  wrong:

  import { src, dest, series, parallel } from 'gulp';

  correct:

  import gulp from 'gulp';
  const { src, dest, series, parallel } = gulp;

  For ES Modules (`.mjs` or `type: "module"`), import the default `gulp` object first, then destructure its APIs. Direct named imports for these core APIs are not consistently supported from the `gulp` package itself due to its hybrid CJS/ESM nature.
• coffee
  wrong:

  import coffee from 'gulp-coffee';

  correct:

  const coffee = require('gulp-coffee');

  Most Gulp plugins are still distributed as CommonJS modules. Use `require` unless the plugin explicitly states ESM support. For ESM, `import plugin from 'gulp-plugin';` is the usual pattern.

Quickstart

This `gulpfile.js` demonstrates defining Gulp 4 tasks using plain functions, composing them with `gulp.series` and `gulp.parallel`, and using `gulp.src` and `gulp.dest` with popular plugins for cleaning, image optimization, CoffeeScript compilation, minification, concatenation, and sourcemap generation. It also includes a `watch` task for development.

var gulp = require('gulp');
var coffee = require('gulp-coffee');
var concat = require('gulp-concat');
var uglify = require('gulp-uglify');
var imagemin = require('gulp-imagemin');
var sourcemaps = require('gulp-sourcemaps');
var del = require('del'); // A separate npm package for deleting files

var paths = {
  scripts: ['client/js/**/*.coffee', '!client/external/**/*.coffee'],
  images: 'client/img/**/*'
};

// Clean the build directory
function clean() {
  return del(['build']);
}

// Optimize images
function images() {
  return gulp.src(paths.images)
    .pipe(imagemin({ optimizationLevel: 5 }))
    .pipe(gulp.dest('build/img'));
}

// Compile CoffeeScript, minify, concat, and add sourcemaps
function scripts() {
  return gulp.src(paths.scripts)
    .pipe(sourcemaps.init())
    .pipe(coffee())
    .pipe(uglify())
    .pipe(concat('all.min.js'))
    .pipe(sourcemaps.write())
    .pipe(gulp.dest('build/js'));
}

// Watch for file changes and re-run tasks
function watch() {
  gulp.watch(paths.scripts, scripts);
  gulp.watch(paths.images, images);
}

// Define main build task: clean, then run scripts and images in parallel
gulp.task('build', gulp.series(
  clean,
  gulp.parallel(scripts, images)
));

// Expose individual tasks for CLI if needed
gulp.task(clean);
gulp.task(watch);

// Default task runs the 'build' task
gulp.task('default', gulp.series('build'));