Gulp Esbuild Plugin

0.14.1 · active · verified Tue Apr 21

The `gulp-esbuild` package provides a Gulp plugin that integrates the high-performance `esbuild` bundler into Gulp-based build workflows. It allows developers to efficiently bundle, minify, and transform JavaScript and TypeScript assets as part of their Gulp pipelines, leveraging `esbuild`'s speed. The current stable version is 0.14.1, and the package frequently releases updates, often in response to breaking changes in the upstream `esbuild` library. A key feature is the ability to enable `esbuild`'s incremental build mode via the `createGulpEsbuild` factory function, which significantly speeds up rebuilds during development when combined with Gulp's `watch` API. Unlike direct `esbuild` usage, `gulp-esbuild` is designed to work with Gulp's virtual file streams, but it has a specific limitation: all input files specified in `gulp.src()` must physically exist on the filesystem, even if their contents are subsequently modified by earlier Gulp pipeline steps.

Common errors

```
Error: Cannot find module 'esbuild'
```
cause The 'esbuild' package is a peer dependency of 'gulp-esbuild' and was not installed alongside it.

fix Install esbuild alongside gulp-esbuild: `npm install esbuild gulp-esbuild` or `yarn add esbuild gulp-esbuild`.
```
Error: Unknown option: 'pipe'
```
cause The 'pipe' option was removed from `gulp-esbuild` in v0.13.0.

fix Remove the `{ pipe: true }` option from your `createGulpEsbuild` configuration. The plugin now handles both file system and virtual files by default.
```
esbuild: Could not resolve './some-virtual-file.js' (or similar file not found error)
```
cause The input file passed to `gulp-esbuild` via `gulp.src()` does not physically exist on the file system, which is a requirement for `esbuild`'s operation even when processing virtual file contents.

fix Ensure that all files processed by `gulp-esbuild` (i.e., those passed into `gulp.src()`) have a corresponding physical file on disk. If generating content virtually, write it to a temporary file first.

Warnings

breaking Since v0.14.0, `esbuild` is a peer dependency of `gulp-esbuild` and must be installed separately. Failing to do so will result in module not found errors during runtime.
Fix: Run `npm install gulp-esbuild esbuild` or `yarn add gulp-esbuild esbuild` to ensure both packages are installed.
breaking The `pipe` flag, previously used to enable processing of virtual files, was removed in v0.13.0. The plugin now automatically handles both file system files and virtual files by default.
Fix: Remove the `{ pipe: true }` option from any calls to `createGulpEsbuild`. The `createGulpEsbuild` function itself is still necessary for enabling incremental builds.
gotcha When processing files with `src(...).pipe(gulpEsbuild(...))`, every file passed to `src` must physically exist on the file system, even if its content is overridden by Gulp's virtual file stream. This is a limitation stemming from `esbuild`'s architecture.
Fix: Ensure all source files specified in `gulp.src()` exist on disk. For dynamically generated content, consider writing it to a temporary file before passing it to `gulp-esbuild`.
breaking Major releases of `esbuild` frequently introduce breaking changes to its API. `gulp-esbuild` often reflects these changes, requiring updates to `esbuild` options or configuration in your `gulpfile`.
Fix: Consult the `esbuild` release notes (often linked in `gulp-esbuild` changelogs) and update your `esbuild` configuration options accordingly after upgrading `gulp-esbuild`.
gotcha To enable `esbuild`'s incremental build feature for faster rebuilds during development (e.g., with `gulp.watch`), you must use the `createGulpEsbuild` factory function with `{ incremental: true }`. The default `gulpEsbuild` export does not support incremental builds.
Fix: Import `createGulpEsbuild` and instantiate the plugin with `const gulpEsbuildInstance = createGulpEsbuild({ incremental: true });` then use `gulpEsbuildInstance` in your pipeline.

Install

npm install gulp-esbuild npm
yarn add gulp-esbuild yarn
pnpm add gulp-esbuild pnpm

Imports

gulpEsbuild
wrong:
```
import { gulpEsbuild } from 'gulp-esbuild';
const gulpEsbuild = require('gulp-esbuild').gulpEsbuild;
```
correct:
```
import gulpEsbuild from 'gulp-esbuild';
```
The main plugin function for non-incremental builds. In ESM, it is the default export. In CommonJS, it's the direct `module.exports` from `require("gulp-esbuild")`.
createGulpEsbuild
wrong:
```
import createGulpEsbuild from 'gulp-esbuild';
const createGulpEsbuild = require('gulp-esbuild');
```
correct:
```
import { createGulpEsbuild } from 'gulp-esbuild';
```
Used to create an instance of the plugin that supports esbuild's incremental builds. This is a named export, available for both ESM and CommonJS.
BuildOptions
wrong:
```
import type { BuildOptions } from 'gulp-esbuild';
```
correct:
```
import type { BuildOptions } from 'esbuild';
```
For type-checking the configuration object passed to gulp-esbuild, it is essential to import `BuildOptions` directly from the `esbuild` package, as `gulp-esbuild` expects compatible options.

Quickstart

Demonstrates how to bundle a TypeScript file (`index.tsx`) using `gulp-esbuild` into a single JavaScript file (`bundle.js`) and output it to the `dist` directory, including minification and sourcemaps.

import { src, dest } from 'gulp';
import gulpEsbuild from 'gulp-esbuild';

/**
 * Gulp task to build a TypeScript application using gulp-esbuild.
 * It bundles 'index.tsx', configures esbuild for bundling and TSX loading,
 * and outputs the result to 'dist/bundle.js'.
 */
function build() {
    return src('./index.tsx')
        .pipe(gulpEsbuild({
            outfile: 'bundle.js',
            bundle: true,
            loader: {
                '.tsx': 'tsx'
            },
            minify: true,
            sourcemap: 'external'
        }))
        .pipe(dest('./dist'));
}

export { build };
// To run: `npx gulp build` (assuming 'gulp' is installed globally or via npx)

view raw JSON →