Gulp Plugin for Rollup ES6 Bundler

5.0.3 · active · verified Wed Apr 22

gulp-best-rollup-2 is a Gulp plugin designed for integrating the Rollup ES6 module bundler into a Gulp build pipeline. As a fork rewritten for Rollup v2.X and modern ES6, it provides a deeper integration than its predecessors and alternatives like `gulp-rollup`. The current stable version is 5.0.3, with maintenance releases occurring as needed for compatibility or bug fixes. Its key differentiator lies in how it handles file paths from `gulp.src()` directly within Rollup, allowing other Gulp plugins to operate effectively in the pipeline before or after the bundling step. This approach deviates from Rollup's typical file-reading mechanism, enabling greater flexibility in complex Gulp workflows by treating Rollup primarily as an in-memory transformation step, rather than a file handler.

Common errors

```
Error: Cannot find module 'rollup'
```
cause `rollup` is a peer dependency of `gulp-better-rollup-2` and must be installed separately.

fix Run `npm install rollup --save-dev` in your project directory.
```
Input option must be specified.
```
cause This error occurs if you are mistakenly passing an `input` option to the `rollup()` plugin call. `gulp-better-rollup-2` expects input to be handled by `gulp.src()`.

fix Remove the `input` option from the first argument (Rollup `inputOptions`) passed to the `rollup()` plugin function.
```
TypeError: Cannot read properties of undefined (reading 'init')
```
cause This usually indicates `sourcemaps.init()` was called, but `gulp-sourcemaps` was not properly imported or installed.

fix Ensure `gulp-sourcemaps` is installed (`npm install gulp-sourcemaps --save-dev`) and correctly imported (`const sourcemaps = require('gulp-sourcemaps')`).

Warnings

gotcha Transformations from Gulp plugins executed *before* `gulp-better-rollup` in the pipeline will be lost. The plugin operates on file paths provided by `gulp.src()` directly, not on in-memory buffers transformed by previous plugins.
Fix: Ensure `gulp-better-rollup` is placed early in the pipeline if other plugins' transformations are not meant to be superseded, or use plugins that don't perform source transformations (e.g., `gulp-sourcemaps`) before it.
gotcha The Rollup `input` option (e.g., `input: 'src/main.js'`) is explicitly unsupported and will be ignored or cause errors.
Fix: Specify input files using `gulp.src()` instead of Rollup's `input` option. The plugin will automatically use the file paths from the Gulp stream.
gotcha Rollup's native `output.sourcemap` option is unsupported. Sourcemap generation is delegated entirely to `gulp-sourcemaps`.
Fix: Remove any `sourcemap: true` or similar options from Rollup's `outputOptions`. Instead, integrate `gulp-sourcemaps` into your Gulp pipeline before and after `gulp-better-rollup`.
gotcha When using `gulp-sourcemaps` with `.mjs` files, the sourcemap linking comment (`//# sourceMappingURL=`) may not be inserted, rendering external sourcemaps ineffective.
Fix: If `.mjs` is critical, consider inlining sourcemaps (`sourcemaps.write()`) or creating external sourcemaps with a different file extension/naming convention. Check `gulp-sourcemaps` documentation for potential updates or workarounds for `.mjs`.
gotcha The Rollup `output.file` argument can only influence the filename if `gulp.dest()` specifies a directory. If `gulp.dest()` specifies a full file path, Rollup's `output.file` is completely ignored.
Fix: When using `gulp.dest()`, specify a target directory to allow Rollup's `output.file` to name the bundled output. Alternatively, use `gulp-rename` after `gulp-better-rollup` for precise output filename control.

Install

npm install gulp-best-rollup-2 npm
yarn add gulp-best-rollup-2 yarn
pnpm add gulp-best-rollup-2 pnpm

Imports

rollup
wrong:
```
import { rollup } from 'gulp-better-rollup'
```
correct:
```
const rollup = require('gulp-better-rollup')
```
The plugin exports a default function. While Gulpfiles typically use CommonJS `require`, if using ESM Gulpfiles, `import rollup from 'gulp-better-rollup'` would be the equivalent correct import.
gulp
```
const gulp = require('gulp')
```
Standard import for the Gulp core library used to define tasks and pipelines.
babel
```
const babel = require('rollup-plugin-babel')
```
This demonstrates importing a common Rollup plugin (like `@rollup/plugin-babel`). Ensure all Rollup plugins are installed separately and imported similarly for inclusion in the `plugins` array.

Quickstart

Demonstrates bundling an ES6 library with Rollup and Babel, applying sourcemaps, and outputting the CJS bundle to a 'dist' directory.

var gulp = require('gulp')
var sourcemaps = require('gulp-sourcemaps')
var rollup = require('gulp-better-rollup')
var babel = require('rollup-plugin-babel')

gulp.task('lib-build', () => {
  gulp.src('lib/index.js')
    .pipe(sourcemaps.init())
    .pipe(rollup({
      // There is no `input` option as rollup integrates into the gulp pipeline
      plugins: [babel({ babelHelpers: 'bundled' })] // Note: babelHelpers option often needed for babel plugin
    }, {
      // Rollups `sourcemap` option is unsupported. Use `gulp-sourcemaps` plugin instead
      format: 'cjs'
    }))
    // inlining the sourcemap into the exported .js file
    .pipe(sourcemaps.write())
    .pipe(gulp.dest('dist'))
})

view raw JSON →