broccoli-babel-transpiler

What is broccoli-babel-transpiler?

The 'broccoli-babel-transpiler' package is a Broccoli plugin that uses Babel to transpile JavaScript files. It allows you to use the latest JavaScript features by converting ES6/ES7+ code into a backward-compatible version of JavaScript that can run in older environments.

What are broccoli-babel-transpiler's main functionalities?

Basic Transpilation

This feature allows you to transpile ES6+ JavaScript code to ES5 using Babel. The code sample demonstrates how to set up a basic transpilation process with the '@babel/preset-env' preset.

const Babel = require('broccoli-babel-transpiler');
const inputNode = 'src';
const outputNode = new Babel(inputNode, {
  presets: ['@babel/preset-env']
});
module.exports = outputNode;

Custom Plugins

This feature allows you to use custom Babel plugins to transform your code. The code sample shows how to use the '@babel/plugin-transform-arrow-functions' plugin to transform arrow functions into regular functions.

const Babel = require('broccoli-babel-transpiler');
const inputNode = 'src';
const outputNode = new Babel(inputNode, {
  plugins: ['@babel/plugin-transform-arrow-functions']
});
module.exports = outputNode;

Source Maps

This feature enables the generation of source maps, which help in debugging by mapping the transpiled code back to the original source code. The code sample demonstrates how to enable inline source maps.

const Babel = require('broccoli-babel-transpiler');
const inputNode = 'src';
const outputNode = new Babel(inputNode, {
  sourceMaps: 'inline'
});
module.exports = outputNode;

Other packages similar to broccoli-babel-transpiler

babel-cli

The 'babel-cli' package provides a command-line interface for Babel. It allows you to transpile files from the command line, making it suitable for simple build scripts and quick transformations. Unlike 'broccoli-babel-transpiler', it is not a Broccoli plugin and does not integrate directly into the Broccoli build pipeline.

gulp-babel

The 'gulp-babel' package is a Gulp plugin for Babel. It allows you to integrate Babel transpilation into a Gulp build process. This package is similar to 'broccoli-babel-transpiler' in that it integrates Babel into a build tool, but it is designed specifically for Gulp rather than Broccoli.

webpack

Webpack is a module bundler that can also transpile JavaScript using Babel through the 'babel-loader' plugin. It offers a more comprehensive solution for managing and bundling assets, including JavaScript, CSS, and images. While 'broccoli-babel-transpiler' focuses solely on JavaScript transpilation within the Broccoli ecosystem, Webpack provides a more extensive set of features for asset management and optimization.

README

broccoli-babel-transpiler

A Broccoli plugin that runs Babel plugins with caching and parallel capabilities.

How to install?

$ npm install broccoli-babel-transpiler --save-dev

How to use?

In your Brocfile.js:

const babel = require('broccoli-babel-transpiler');
const scriptTree = babel(inputTree, babelOptions);

Note that, since Babel 6 (and v6 of this plugin), you need to be specific as to what your transpilation target is. Running esTranspiler with empty options will not transpile anything. You will need:

• Explicit options, such as presets. See available options at Babel's GitHub repo.
• Babel plugins that implement the transforms you require.

For a quick running example, install this plugin:

$ npm install babel-preset-env

And then run the transform like this:

const babel = require('broccoli-babel-transpiler');
let scriptTree = babel(inputTree, {
  presets: [
    ['env', {
      'targets': {
        'browsers': ['last 2 versions']
      }
    }]
  ]
});

Examples

You'll find three example projects using this plugin in the repository broccoli-babel-examples. Each one of them builds on top of the previous example so you can progress from bare minimum to ambitious development.

• es6-fruits - Execute a single ES6 script.
• es6-website - Build a simple website.
• es6-modules - Handle modules and unit tests.

About source map

Currently this plugin only supports inline source map. If you need separate source map feature, you're welcome to submit a pull request.

Advanced usage

filterExtensions is an option to limit (or expand) the set of file extensions that will be transformed.

The default filterExtension is js

const esTranspiler = require('broccoli-babel-transpiler');
let scriptTree = esTranspiler(inputTree, {
    filterExtensions:['js', 'es6'] // babelize both .js and .es6 files
});

targetExtension is an option to specify the extension of the output files

The default targetExtension is js

const esTranspiler = require('broccoli-babel-transpiler');
let scriptTree = esTranspiler(inputTree, {
    targetExtension: 'module.js' // create output files with module.js extension
});

Plugins

Use of custom plugins works similarly to babel itself. You would pass a plugins array in options:

const esTranspiler = require('broccoli-babel-transpiler');
const applyFeatureFlags = require('babel-plugin-feature-flags');

let featureFlagPlugin = applyFeatureFlags({
  import: { module: 'ember-metal/features' },
  features: {
    'ember-metal-blah': true
  }
});

let scriptTree = esTranspiler(inputTree, {
  babel: {
    plugins: [
      featureFlagPlugin
    ]
  }
});

Caching

broccoli-babel-transpiler uses a persistent cache to enable rebuilds to be significantly faster (by avoiding transpilation for files that have not changed). However, since a plugin can do many things to affect the transpiled output it must also influence the cache key to ensure transpiled files are rebuilt if the plugin changes (or the plugins configuration).

In order to aid plugin developers in this process, broccoli-babel-transpiler will invoke two methods on a plugin so that it can augment the cache key:

• cacheKey - This method is used to describe any runtime information that may want to invalidate the cached result of each file transpilation. This is generally only needed when the configuration provided to the plugin is used to modify the AST output by a plugin like babel-plugin-filter-imports (module exports to strip from a build), babel-plugin-feature-flags (configured features and current status to strip or embed in a final build), or babel-plugin-htmlbars-inline-precompile (uses ember-template-compiler.js to compile inlined templates).
• baseDir - This method is expected to return the plugins base dir. The provided baseDir is used to ensure the cache is invalidated if any of the plugin's files change (including its deps). Each plugin should implement baseDir as: Plugin.prototype.baseDir = function() { return \_\_dirname; };.

Parallel Transpilation

broccoli-babel-transpiler can run multiple babel transpiles in parallel using a pool of workers, to take advantage of multi-core systems. Because these workers are separate processes, the plugins and callback functions that are normally passed as options to babel must be specified in a serializable form. To enable this parallelization there is an API to tell the worker how to construct the plugin or callback in its process.

To ensure a build remains parallel safe, one can set the throwUnlessParallelizable option to true (defaults to false). This will cause an error to be thrown, if parallelization is not possible due to an incompatible babel plugin.

new Babel(input, { throwUnlessParallelizable: true | false });

Alternatively, an environment variable can be set:

THROW_UNLESS_PARALLELIZABLE=1 node build.js

Plugins are specified as an object with a _parallelBabel property:

let plugin = {
  _parallelBabel: {
    requireFile: '/full/path/to/the/file',
    useMethod: 'methodName',
    buildUsing: 'buildFunction',
    params: { ok: 'this object will be passed to buildFunction()' }
  }
};

Callbacks can be specified like plugins, or as functions with a _parallelBabel property:

function callback() { /* do something */ };

callback._parallelBabel = {
  requireFile: '/full/path/to/the/file',
  useMethod: 'methodName',
  buildUsing: 'buildFunction',
  params: { ok: 'this object will be passed to buildFunction()' }
};

requireFile (required)

This property specifies the file to require in the worker process to create the plugin or callback. This must be given as an absolute path.

const esTranspiler = require('broccoli-babel-transpiler');

let somePlugin = {
  _parallelBabel: {
    requireFile: '/full/path/to/the/file'
  }
});

let scriptTree = esTranspiler(inputTree, {
  babel: {
    plugins: [
      'transform-strict-mode', // plugins that are given as strings will automatically be parallelized
      somePlugin
    ]
  }
});

useMethod (optional)

This property specifies the method to use from the file that is required.

If you have a plugin defined like this:

// some_plugin.js

module.exports = {
  pluginFunction(babel) {
    // do plugin things
  }
};

You can tell broccoli-babel-transpiler to use that function in the worker processes like so:

const esTranspiler = require('broccoli-babel-transpiler');

let somePlugin = {
  _parallelBabel: {
    requireFile: '/path/to/some_plugin',
    useMethod: 'pluginFunction'
  }
});

let scriptTree = esTranspiler(inputTree, {
  babel: {
    plugins: [ somePlugin ]
  }
});

buildUsing and params (optional)

These properties specify a function to run to build the plugin (or callback), and any parameters to pass to that function.

If the plugin needs to be built dynamically, you can do that like so:

// some_plugin.js

module.exports = {
  buildPlugin(params) {
    return doSomethingWith(params.text);
  }
};

This will tell the worker process to require the plugin and call the buildPlugin function with the params object as an argument:

const esTranspiler = require('broccoli-babel-transpiler');

let somePlugin = {
  _parallelBabel: {
    requireFile: '/path/to/some_plugin',
    buildUsing: 'buildPlugin',
    params: { text: 'some text' }
  }
});

let scriptTree = esTranspiler(inputTree, {
  babel: {
    plugins: [ somePlugin ]
  }
});

Note: If both useMethod and buildUsing are specified, useMethod takes precedence.

Number of jobs

The number of parallel jobs defaults to the number of detected CPUs - 1.

This can be changed with the JOBS environment variable:

JOBS=4 ember build

To disable parallelization:

JOBS=1 ember build

Changelog

v8.0.0 (2023-08-17)

:boom: Breaking Change

• #237 Drop Node 14 support (@kategengler)
• #225 Drop support for Node v17 and add support for Node v18 (@bertdeblock)
• #221 Move @babel/core to peerDependencies to resolve peer dependency warnings and errors (@bertdeblock)
• #210 Drop Node 10, 12, and 13 support (@rwjblue)
• #193 Separate Broccoli and Babel options (@nlfurniss)
• #191 Remove browserPolyfill option (@nlfurniss)

:rocket: Enhancement

• #190 Update workerpool to latest (avoiding deprecations) (@nlfurniss)

:bug: Bug Fix

• #221 Move @babel/core to peerDependencies to resolve peer dependency warnings and errors (@bertdeblock)
• #209 Ensure the worker processes do not crash when parsing invalid syntax (@rwjblue)

:memo: Documentation

• #192 Tweak package description in README.md (@gabrielcsapo)
• #230 Fix typo in docs (@bertdeblock)

:house: Internal

• #226 Add release automation (@rwjblue)
• #214 Migrate from yarn@1 to npm (@rwjblue)
• #215 Update @babel/* dependencies/devDependencies (@rwjblue)
• #200 Remove @babel/polyfill dependency (@nlfurniss)
• #195 Remove TravisCI and AppVeyor (@rwjblue)
• #183 Add GitHub Actions CI setup. (@rwjblue)

Committers: 4

• Bert De Block (@bertdeblock)
• Gabriel Csapo (@gabrielcsapo)
• Nathaniel Furniss (@nlfurniss)
• Robert Jackson (@rwjblue)
• Katie Gengler (@kategengler)