Getting started

gulp-plugins-hub is a set of gulp plugins, each in its own package, that share one way of working: typed options checked when the plugin is created, hooks that get the file, errors that name the plugin and the file.

Requirements

• Node.js 22.13 or newer
• gulp 5 (gulp 4 works too)

Install

Install gulp and the plugins the build needs:

npm install --save-dev gulp @zilero/gulp-scss-compiler @zilero/gulp-css-squeezer @zilero/gulp-js-squeezer

A first gulpfile

// gulpfile.mjs
import { dest, parallel, src } from 'gulp';
import { pipeline } from 'node:stream/promises';
import cssSqueezer from '@zilero/gulp-css-squeezer';
import jsSqueezer from '@zilero/gulp-js-squeezer';
import scssCompiler from '@zilero/gulp-scss-compiler';

export const styles = () =>
  pipeline(
    src('src/styles/*.scss', { sourcemaps: true }),
    scssCompiler(),
    cssSqueezer(),
    dest('dist/css', { sourcemaps: '.' })
  );

export const scripts = () =>
  pipeline(src('src/js/*.js', { sourcemaps: true }), jsSqueezer(), dest('dist/js', { sourcemaps: '.' }));

export default parallel(styles, scripts);

Tasks return pipeline(…) from node:stream/promises rather than a .pipe() chain, so an error in any step ends the task with that error (why).

npx gulp

Every plugin is a function that takes its options and returns a stream. Each has a default export and a named one:

import scssCompiler from '@zilero/gulp-scss-compiler';
import { scssCompiler } from '@zilero/gulp-scss-compiler'; // the same function

In a CommonJS gulpfile, use the named export:

// gulpfile.js
const { scssCompiler } = require('@zilero/gulp-scss-compiler');

Options are checked up front

Every option is validated when the plugin is created. A wrong value stops the task before any file is read, and lists every problem:

[10:42:01] 'styles' errored after 3 ms
[10:42:01] Error in plugin "@zilero/gulp-css-squeezer"
Message:
    Invalid options:
    • Unrecognized key: "minfy"

Errors name the file

An error while processing a file is a PluginError emitted on the stream, with the plugin name and the file:

[10:42:05] Error in plugin "@zilero/gulp-scss-compiler"
Message:
    Undefined variable.
    ╷
  3 │ .card { color: $brand; }
    │                ^^^^^^
    ╵
Details:
    fileName: /project/src/styles/main.scss

In a watch task an error stops that run; gulp keeps watching.

Next

• Gulp 5 essentials: binary files, glob order, pipeline, TypeScript gulpfiles, source maps.
• Recipes: incremental builds, responsive images, font subsets.
• Example project: a complete static site built with every plugin.
• Migrating from other plugins: gulp-sass, gulp-imagemin, gulp-rev and the rest, option by option.
• Troubleshooting: corrupted images, CommonJS and TypeScript gulpfiles, native binaries in CI.
• Plugins: every plugin and its options.