Babel Plugin for RequireJS

A Babel loader plugin for RequireJS. This is a fork of the requirejs-babel project to support Babel 7. Look for the support of Babel 5, 6 and 7 in the following NPM modules:

• Babel 5 - requirejs-babel
• Babel 6 - requirejs-babel6
• Babel 7 - requirejs-babel7

The official RequireJS optimizer (r.js) does not wire up source maps from the original (not transpiled) sources to the source map of the output bundle. It makes using Babel or other transpilers unfeasible for serious work. If you want the proper support for source maps, replace the official optimizer package (requirejs) with the forked @prantlf/requirejs, which is fixed.

Installation

This module can be installed in your project using NPM, PNPM or Yarn. Make sure, that you use Node.js version 6 or newer.

npm i -D requirejs-babel7 @babel/standalone babel-plugin-module-resolver-standalone babel-plugin-amd-checker
pnpm i -D requirejs-babel7 @babel/standalone babel-plugin-module-resolver-standalone babel-plugin-amd-checker
yarn add requirejs-babel7 @babel/standalone babel-plugin-module-resolver-standalone babel-plugin-amd-checker

This plugin has been tested to work with @babel/standalone 7.x, babel-plugin-module-resolver-standalone 0.x and babel-plugin-amd-checker 0.x, which are required as peer dependencies.

Usage

Add the following paths to the RequireJS configuration:

paths: {
  es6: 'node_modules/requirejs-babel7/es6',
  babel: 'node_modules/@babel/standalone/babel.min',
  'babel-plugin-module-resolver': 'node_modules/babel-plugin-module-resolver-standalone/index',
  'babel-plugin-amd-checker': 'node_modules/babel-plugin-amd-checker/index'
}

Reference ES6 source files files via the es6! plugin prefix:

define(['es6!your-es6-module'], function (module) {
  // ...
});

You can use the ES6 module syntax in modules loaded by the es6! plugin including the keyword import for loading nested dependencies. The plugin es6! has to be used only in the topmost require or define statement.

This plugin transpiles only ES6 source files. If it detects a statement calling functions define, require or require.config on the root level of the source file, it will return the text of the source file as-is. Source files, which are already AMD modules, are assumed to contain ES5 only.

If you use the RequireJS optimizer r.js, you have to exclude Babel with the module-resolver plugin and bundle the `es6`` plugin without the compiling functionality by adding the following to the RequireJS build configuration:

exclude: ['babel', 'babel-plugin-module-resolver', 'babel-plugin-amd-checker'],
pragmasOnSave: {
  excludeBabel: true // removes the transpiling code from es6.js
}

See also a simple demo project:

npm start
open http://localhost:8967/demo/normal.html

Advanced

If you are going to use ES6 classes, you will need to add the external-helpers plugin and include a script with Babel external helpers. If you are going to use async/await keywords, you will need to add the transform-async-to-generator plugin and include the script with Babel polyfills. Depending on the target web browser, which you need to support, you can enable presets es2015 (default), es2016 or es2017.

Install @babel/cli for generating Babel helpers, if you need them:

npm i -D @babel/cli @babel/core
pnpm i -D @babel/cli @babel/core
yarn add @babel/cli @babel/core

If you need the polyfills, you can use babel-polyfills-generator; the @babel/polyfill package was deprecated:

npm i -D babel-polyfills-generator core-js regenerator-runtime
pnpm i -D babel-polyfills-generator core-js regenerator-runtime
yarn add babel-polyfills-generator core-js regenerator-runtime

Generate a script with Babel helpers, if you need them:

babel-external-helpers -t global > babel-helpers.js

Generate a script with Babel polyfills, if you need them:

generate-babel-polyfills demo-polyfill

Add the following RequireJS configuration, depending on your supported targets:

config: {
  es6: {
    extraPlugins: ['transform-async-to-generator', 'external-helpers'],
    presets: ['es2015'],
    targets: 'ie 11'
  }
}

You can use any options of babel.transform for configuring the es6 plugin. Use the extraPlugins key not to replace mandatory plugins added by es6!. You can customize the default module name resolution with the resolveModuleSource key (see resolvePath for more information) to transpile only modules with a special file extension:

// import * from 'es5module.js'  -> define(['es5module])
// import * from 'es6module.mjs' -> define(['es6!es6module])
fileExtension: '.mjs',
resolveModuleSource: function (sourcePath, currentFile, opts) {
  if (sourcePath.indexOf('!') < 0) {
    var lengthWithoutExtension = sourcePath.length - 3
    if (sourcePath.lastIndexOf('.js') === lengthWithoutExtension) {
      return sourcePath.substr(0, lengthWithoutExtension)
    }
    --lengthWithoutExtension
    if (sourcePath.lastIndexOf('.mjs') === lengthWithoutExtension) {
      return 'es6!' + sourcePath.substr(0, lengthWithoutExtension)
    }
  }
}

The default implementation of resolveModuleSource ensures that every JavaScript dependency will be converted:

function (sourcePath) {
  if (sourcePath.indexOf('!') < 0) {
    return 'es6!' + sourcePath;
  }
}

Before you load the main application module by require, make sure, that you included Babel helpers and polyfills, if you need them. For example:

<script src="babel-polyfills.min.js"></script>
<script src="babel-helpers.min.js"></script>

See also an advanced demo project:

npm start
open http://localhost:8967/demo-polyfill/normal.html

Contributing

In lieu of a formal styleguide, take care to maintain the existing coding style. Lint and test your code.

License

Copyright (c) 2015-2019 Mykhailo Kachanovskyi
Copyright (c) 2019-2022 Ferdinand Prantl

Licensed under the MIT license.