Resolving SyntaxError: 'import' and 'export' may appear only with 'sourceType: module' in Gulp

Problem Background and Error Analysis

In modern JavaScript development, ES6 module syntax (import/export) has become a standard feature. However, when using build tools like Gulp with Browserify and Babelify, developers often encounter the SyntaxError: 'import' and 'export' may appear only with 'sourceType: module' error. This error fundamentally arises because the Babel transformer fails to correctly recognize and process ES6 module syntax.

Root Cause of the Error

This error typically occurs in scenarios where project code uses ES6 import and export statements, but the Babel configuration lacks the necessary presets to transform these modern syntax features. Babel, as a JavaScript compiler, requires explicit presets to guide the transformation of specific JavaScript versions.

In the provided example code, the app.js file contains typical ES6 module imports and exports:

import Game from './game/game';
import React from 'react';
import ReactDOM from 'react-dom';

export default (absPath) => {
  // Component rendering logic
}

Although the Gulp task configuration invokes the babelify transformer, it does not specify the required preset configuration:

.transform('babelify')

Complete Solution

To resolve this issue, install and configure Babel's ES2015 preset. Below are the detailed steps:

Step 1: Install Required Dependencies

First, install babel-preset-es2015 via npm:

npm install babel-preset-es2015 --save-dev

Step 2: Configure the babelify Transformer

Modify the babelify configuration in the Gulp task to explicitly specify the ES2015 preset:

return browserify({
  entries: ['index.js']
})
.transform(babelify.configure({
  presets: ["es2015"]
}))
.bundle()
.pipe(source('index.js'))
.pipe(gulp.dest('app/'));

In-Depth Configuration Principles

Babel's preset system allows developers to enable a set of related syntax transformation plugins at once. The ES2015 preset includes all necessary plugins to convert ES6 code into ES5-compatible code, including the module transformation plugin that handles import/export statements.

When configuring presets: ["es2015"], Babel automatically enables:

• Module transformation plugins to convert ES6 module syntax to CommonJS format
• Arrow function transformation
• Class syntax transformation
• Destructuring assignment transformation
• And other ES6 feature transformations

Advanced Configuration Options

Beyond basic preset configuration, consider these advanced options:

Source Map Support

To facilitate debugging, enable source maps:

.transform(babelify.configure({
  presets: ["es2015"],
  sourceMaps: true
}))

Global Transformation Configuration

For cases requiring transformation of specific modules in node_modules, use the global option:

.transform(babelify.configure({
  presets: ["es2015"],
  global: true,
  ignore: [/\/node_modules\/(?!specific-module\/)/]
}))

Best Practices Recommendations

Based on practical development experience, adhere to the following best practices:

Maintain Consistent Babel Configuration: Ensure identical Babel configurations across development, testing, and production environments to prevent issues from environmental discrepancies.

Regular Dependency Updates: Babel and related presets are continuously updated. Regularly check and update to the latest stable versions for improved performance and more feature support.

Configuration Validation: Create a .babelrc file in the project root to centrally manage Babel configuration, ensuring all build tools use the same transformation rules.

Conclusion

By correctly installing and configuring the babel-preset-es2015 preset, the SyntaxError: 'import' and 'export' may appear only with 'sourceType: module' error can be completely resolved. This solution not only addresses the current issue but also establishes a solid foundation for utilizing more ES6+ features in the future. Understanding how Babel presets work empowers developers to quickly identify and resolve similar build problems.