{"id":15444,"library":"gulp-esbuild","title":"Gulp Esbuild Plugin","description":"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.","status":"active","version":"0.14.1","language":"javascript","source_language":"en","source_url":"https://github.com/ym-project/gulp-esbuild#v0","tags":["javascript","gulpplugin","typescript"],"install":[{"cmd":"npm install gulp-esbuild","lang":"bash","label":"npm"},{"cmd":"yarn add gulp-esbuild","lang":"bash","label":"yarn"},{"cmd":"pnpm add gulp-esbuild","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required peer dependency for the core bundling functionality. Must be installed alongside gulp-esbuild.","package":"esbuild","optional":false}],"imports":[{"note":"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\")`.","wrong":"import { gulpEsbuild } from 'gulp-esbuild';\nconst gulpEsbuild = require('gulp-esbuild').gulpEsbuild;","symbol":"gulpEsbuild","correct":"import gulpEsbuild from 'gulp-esbuild';"},{"note":"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.","wrong":"import createGulpEsbuild from 'gulp-esbuild';\nconst createGulpEsbuild = require('gulp-esbuild');","symbol":"createGulpEsbuild","correct":"import { createGulpEsbuild } from 'gulp-esbuild';"},{"note":"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.","wrong":"import type { BuildOptions } from 'gulp-esbuild';","symbol":"BuildOptions","correct":"import type { BuildOptions } from 'esbuild';"}],"quickstart":{"code":"import { src, dest } from 'gulp';\nimport gulpEsbuild from 'gulp-esbuild';\n\n/**\n * Gulp task to build a TypeScript application using gulp-esbuild.\n * It bundles 'index.tsx', configures esbuild for bundling and TSX loading,\n * and outputs the result to 'dist/bundle.js'.\n */\nfunction build() {\n    return src('./index.tsx')\n        .pipe(gulpEsbuild({\n            outfile: 'bundle.js',\n            bundle: true,\n            loader: {\n                '.tsx': 'tsx'\n            },\n            minify: true,\n            sourcemap: 'external'\n        }))\n        .pipe(dest('./dist'));\n}\n\nexport { build };\n// To run: `npx gulp build` (assuming 'gulp' is installed globally or via npx)","lang":"typescript","description":"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."},"warnings":[{"fix":"Run `npm install gulp-esbuild esbuild` or `yarn add gulp-esbuild esbuild` to ensure both packages are installed.","message":"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.","severity":"breaking","affected_versions":">=0.14.0"},{"fix":"Remove the `{ pipe: true }` option from any calls to `createGulpEsbuild`. The `createGulpEsbuild` function itself is still necessary for enabling incremental builds.","message":"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.","severity":"breaking","affected_versions":">=0.13.0"},{"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`.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Consult the `esbuild` release notes (often linked in `gulp-esbuild` changelogs) and update your `esbuild` configuration options accordingly after upgrading `gulp-esbuild`.","message":"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`.","severity":"breaking","affected_versions":">=0.11.0"},{"fix":"Import `createGulpEsbuild` and instantiate the plugin with `const gulpEsbuildInstance = createGulpEsbuild({ incremental: true });` then use `gulpEsbuildInstance` in your pipeline.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Install esbuild alongside gulp-esbuild: `npm install esbuild gulp-esbuild` or `yarn add esbuild gulp-esbuild`.","cause":"The 'esbuild' package is a peer dependency of 'gulp-esbuild' and was not installed alongside it.","error":"Error: Cannot find module 'esbuild'"},{"fix":"Remove the `{ pipe: true }` option from your `createGulpEsbuild` configuration. The plugin now handles both file system and virtual files by default.","cause":"The 'pipe' option was removed from `gulp-esbuild` in v0.13.0.","error":"Error: Unknown option: 'pipe'"},{"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.","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.","error":"esbuild: Could not resolve './some-virtual-file.js' (or similar file not found error)"}],"ecosystem":"npm"}