The Problem with gulp-util

Seeing this message?

A little postmortem

Last week we made gulp v4.0.0-alpha.3 available on GitHub and people are excited! We expected it to be breaking, but we didn’t realize the far reaching impact of the changes. This is due to 6,752 modules that depend on gulp-util; many of which utilize an extremely outdated version of Vinyl.

Help us fix it using the steps below.

Why deprecation now?

We’ve been planning to deprecate gulp-util since 2014 because it’s just grab-bag of modules. Why would you want to download the beeper module if you’re only using gulp-util for logging? It drastically increases the download size of plugins and gulp itself. We had hoped people would transition to smaller modules, but it seems everyone continued with the status quo.

We planned to deprecate using an easier transition path, but last week’s changes proved it’s a bigger problem than we anticipated. The outdated Vinyl dependency is incompatible, but still used by many plugins. However, v2 of Vinyl won’t ship with gulp-util because we want plugin authors to transition to individual modules.

This has lead us to flag the module on npm with a warning — not the elegant transition we had hoped. You’ll be notified of the deprecation when gulp-util is installed by one of your plugins, but you won’t know which plugin is causing the warning until you follow the fix below.

It’s possible that a plugin using gulp-util isn’t broken if it’s not using the gutil.File API. While not as urgent, the plugin author should still transition away from gulp-util.

Help us fix the ecosystem

Using these steps, you can help plugin authors migrate away from gulp-util.

1. Run npm ls gulp-util to get the list of plugins dependent on it.
2. For each dependent plugin, run npm issues {PLUGIN NAME} which will open their issue tracker.
3. Open an issue or pull request to remove gulp-util using the following API replacements:

• gutil.File => https://www.npmjs.com/package/vinyl
• gutil.replaceExtension => The .extname property on Vinyl objects or https://www.npmjs.com/package/replace-ext
• gutil.colors => https://www.npmjs.com/package/ansi-colors
• gutil.date => https://www.npmjs.com/package/date-format
• gutil.log => https://www.npmjs.com/package/fancy-log
• gutil.template => https://www.npmjs.com/package/lodash.template
• gutil.env => https://www.npmjs.com/package/minimist
• gutil.beep => https://www.npmjs.com/package/beeper
• gutil.noop => https://www.npmjs.com/package/through2
• gutil.isStream => Use the .isStream() method on Vinyl objects
• gutil.isBuffer => Use the .isBuffer() method on Vinyl objects
• gutil.isNull => Use the .isNull() method on Vinyl objects
• gutil.linefeed => Use the string '\n' in your code
• gutil.combine => https://www.npmjs.com/package/multipipe
• gutil.buffer => https://www.npmjs.com/package/list-stream
• gutil.PluginError => https://www.npmjs.com/package/plugin-error