DOCSEARCHbyAlgolia
Submit Docs

Gulp Documentation

website·Indexed 42 days ago

https://gulpjs.com/

A toolkit for automating and enhancing workflows using JavaScript. The documentation covers core API methods such as src(), dest(), watch(), series(), and parallel(), as well as concepts like Vinyl virtual file formats, globbing, and task creation.

Tokens
15.6K
Snippets
68
Records
112
Agent score
74%

What's inside Gulp

  1. Overview of the Vinyl virtual file format

    Vinyl is a virtual file format used by Gulp. When src() reads a file, it generates a Vinyl object containing the file's path, contents, and metadata. These objects can be transformed by plugins and eventually written to the file system using dest(). To create Vinyl objects manually (outside of src()), use the external vinyl module.

  2. Overview of Gulp build automation

    Gulp is a toolkit used to automate slow, repetitive development workflows by composing them into efficient build pipelines. It leverages JavaScript's flexibility, allowing developers to use code over configuration to define tasks. Key architectural features include:

    • Composability: Small, focused tasks can be written individually and then composed into larger, complex operations to reduce repetition.
    • Efficiency via Streams: Gulp uses streams to apply multiple transformations to files in memory, avoiding frequent disk writes and significantly speeding up the build process.
    • Plugin Ecosystem: Gulp utilizes a large library of community-built plugins that act as building blocks, allowing developers to chain different technologies (e.g., Babel, SASS, TypeScript) to achieve a desired output.

  3. Understand Vinyl file objects

    Vinyl is a metadata object used by Gulp to describe a file. It abstracts files from various sources (local file system or remote storage) into a consistent format. The two primary properties of a Vinyl instance are path and contents.

  4. Understand Gulpfile basics and task registration

    A gulpfile is a file named gulpfile.js (or Gulpfile.js) located in the project root. It is automatically loaded when the gulp command is executed. While Gulp provides specific APIs like src(), dest(), series(), and parallel(), the file is pure JavaScript. Any functions exported from the gulpfile are automatically registered as tasks in Gulp's task system.

  5. Gulp core module architecture

    Gulp is composed of several independent modules. If you encounter bugs or need updates, you can run npm update to get the latest versions of these underlying modules:

    • undertaker: Task registration system
    • vinyl: Virtual file objects
    • vinyl-fs: Local file system adapter
    • glob-watcher: File watcher
    • bach: Task orchestration (series() and parallel())
    • last-run: Tracks task run times
    • vinyl-sourcemap: Sourcemap support
    • gulp-cli: Command line interface

  6. Signal Gulp task completion using various async patterns

    Gulp requires tasks to signal completion so it knows when to continue or end. If a task returns a stream, promise, event emitter, child process, or observable, Gulp uses the success or error of that object to determine the outcome. If a task errors, Gulp ends immediately. In series(), an error stops all subsequent tasks; in parallel(), other tasks may still complete.

  7. Split a large Gulpfile into multiple files

    To organize a large Gulp project, you can refactor tasks into separate files and import them into the main gulpfile. Alternatively, you can replace the gulpfile.js file with a directory named gulpfile.js containing an index.js file. Gulp will treat this index.js as the primary gulpfile, allowing you to store individual task modules within the same directory.

  8. Automate semantic versioning releases with Gulp

    To automate a release workflow that follows semantic versioning, you can create a Gulp task that bumps the project version based on commit history, updates the changelog, commits the changes, tags the release, and publishes it to GitHub. This requires a GitHub personal access token stored in a .env file (and added to .gitignore) as GH_TOKEN to authenticate the GitHub release process.
    npm install --save-dev conventional-recommended-bump conventional-changelog-cli conventional-github-releaser dotenv execa

  9. Signal task completion using an error-first callback

    If a task does not return a value, you must use the error-first callback provided as the first argument to the task function. Call the callback with no arguments to signal success, or pass an Error object as the first argument to signal a failure.
    // Success case
function callbackTask(cb) {
  cb();
}

// Error case
function callbackError(cb) {
  cb(new Error('kaboom'));
}

// Passing callback to another API
const fs = require('fs');
function passingCallback(cb) {
  fs.access('gulpfile.js', cb);
}

  10. Determine when to use a plugin vs a Node module

    Plugins should only be used for transforming files. For operations that do not involve transforming file streams (such as deleting files or bundling via a Promise-based API), use a standard Node module or library directly. This often results in cleaner and more efficient tasks.
    const del = require('delete');

exports.default = function(cb) {
  // Use the `delete` module directly instead of a gulp-plugin wrapper
  del(['output/*.js'], cb);
}

  11. Transform files using Gulp plugins

    Gulp plugins are Node Transform Streams used to modify filenames, metadata, or file contents within a pipeline. They are typically placed between src() and dest() using the .pipe() method. Because each plugin is designed to perform a small, specific task, multiple plugins are often chained together to achieve a complex result.
    const { src, dest } = require('gulp');
const uglify = require('gulp-uglify');
const rename = require('gulp-rename');

exports.default = function() {
  return src('src/*.js')
    // Minify the javascript
    .pipe(uglify())
    // Change the extension to .min.js
    .pipe(rename({ extname: '.min.js' }))
    .pipe(dest('output/'));
}

  12. Reference the registry() API signature and requirements

    The registry() function accepts an optional custom registry instance.

    Parameters:

    • registryInstance (object): An instance of a custom registry.

    Return Value:

    • If registryInstance is provided: Returns nothing.
    • If no arguments are passed: Returns the current registry instance.

    Required Interface: A custom registry must implement the following methods, or Gulp will throw an error:

    • get
    • set
    • init
    • tasks
    registry([registryInstance])