Gulp Babel Transpiler

8.0.0 · active · verified Sun Apr 19

gulp-babel is a Gulp plugin that seamlessly integrates Babel into your Gulp build pipeline, enabling the transpilation of modern JavaScript features to widely supported versions. The current stable release is v8.0.0, which provides full compatibility with Babel 7.x. This package is actively maintained by the Babel team, with major version bumps often aligning with core Babel releases, ensuring up-to-date support for the latest JavaScript syntax. It serves as a thin wrapper around Babel's transformation API, exposing a flexible `.pipe()` method for Gulp streams. Key differentiators include its tight integration with the Gulp ecosystem, handling aspects like source map generation via `gulp-sourcemaps`, and providing access to Babel's transformation metadata on processed files. It relies on `@babel/core` as a crucial peer dependency for its core functionality, distinguishing it from direct Babel CLI usage by stream-centric processing.

Common errors

```
Error: Cannot find module '@babel/core'
```
cause The `@babel/core` package, a required peer dependency, is not installed.

fix Run `npm install --save-dev @babel/core` to install the core Babel package.
```
ReferenceError: regeneratorRuntime is not defined
```
cause Using features like async/await or generators without including Babel's runtime transformations.

fix Install `@babel/plugin-transform-runtime` and `@babel/runtime` (`npm install --save-dev @babel/plugin-transform-runtime && npm install --save @babel/runtime`) and add `@babel/plugin-transform-runtime` to your Babel configuration plugins.
```
TypeError: (0 , _gulpBabel.default) is not a function
```
cause Attempting to destructure a default export in CommonJS when the module's default export is the function itself.

fix Correct the import statement to `const babel = require('gulp-babel');` instead of `const { babel } = require('gulp-babel');`.

Warnings

breaking Starting with v8.0.0 (and its beta releases), the peer dependency for Babel's core was changed from `babel-core` to the scoped package `@babel/core`.
Fix: Ensure `@babel/core` is installed as a dev dependency (`npm install --save-dev @babel/core`) and remove `babel-core` if present.
breaking Version 7.0.0 dropped support for older Node.js versions (0.10 and 0.12) and transitioned `babel-core` to a peer dependency instead of a direct dependency.
Fix: Upgrade Node.js to a supported version (>=6 for v8) and ensure `babel-core` (for v7) or `@babel/core` (for v8) is explicitly installed as a peer dependency.
breaking Version 6.0.0 marked a significant upgrade to Babel 6.0.0, introducing major changes in Babel's configuration and plugin ecosystem.
Fix: Refer to the Babel 6 upgrade guide and `gulp-babel` documentation for v6 to adjust configuration files and plugin usage. Downgrade `gulp-babel` to v5 if still using Babel 5.
gotcha When using advanced JavaScript features like generators or async/await, you may encounter `regeneratorRuntime is not defined` errors at runtime.
Fix: Install `@babel/plugin-transform-runtime` and `@babel/runtime`, then add `@babel/plugin-transform-runtime` to your Babel plugins configuration within `gulp-babel` options.
gotcha Some Babel options, specifically `sourceMap` and `filename`, are handled internally by `gulp-babel` and should not be explicitly set in the Babel options passed to the plugin.
Fix: Remove `sourceMap` and `filename` from the `babel()` options. Source maps should be managed using `gulp-sourcemaps`.

Install

npm install gulp-babel npm
yarn add gulp-babel yarn
pnpm add gulp-babel pnpm

Imports

babel
wrong:
```
const { babel } = require('gulp-babel');
```
correct:
```
import babel from 'gulp-babel';
```
The package exports a default function. For CommonJS, use `require('gulp-babel')`. For ESM, use `import babel from 'gulp-babel'`.

Quickstart

This quickstart demonstrates how to set up a basic Gulp task to transpile JavaScript files using Babel, including source map generation and concatenation.

const gulp = require('gulp');
const babel = require('gulp-babel');
const sourcemaps = require('gulp-sourcemaps');
const concat = require('gulp-concat');

gulp.task('default', () =>
	gulp.src('src/**/*.js')
		.pipe(sourcemaps.init())
		.pipe(babel({
			presets: ['@babel/env']
		}))
		.pipe(concat('all.js'))
		.pipe(sourcemaps.write('.'))
		.pipe(gulp.dest('dist'))
);

// To run this, ensure you have:
// npm install --save-dev gulp gulp-babel @babel/core @babel/preset-env gulp-sourcemaps gulp-concat
// A 'src' directory with some .js files.

view raw JSON →