Ember CLI Babel Transpilation

Common errors

• Error: The currently active Node.js version (v14.x) is not supported by ember-cli-babel. Please upgrade to Node.js v16, v18, or v20 or higher.

  cause Using an unsupported Node.js version with `ember-cli-babel` v8 or newer.
  fix Upgrade your Node.js environment to a supported version (e.g., `nvm install 18` and `nvm use 18`).

• Error: .babelrc files are ignored by ember-cli-babel. Please configure Babel options in ember-cli-build.js instead.

  cause Attempting to configure Babel using a `.babelrc` file instead of `ember-cli-build.js`.
  fix Remove your `.babelrc` file and transfer all Babel configurations to the `babel` object within your `new EmberApp()` constructor in `ember-cli-build.js`.

• ReferenceError: regeneratorRuntime is not defined

  cause The `transform-regenerator` plugin was explicitly excluded from Babel, and no global polyfill for generator functions is being provided.
  fix Either remove `transform-regenerator` from the `exclude` list in your Babel configuration, or ensure that a polyfill like `core-js/stable/regenerator-runtime` is explicitly imported in your application.

Warnings

• breaking `ember-cli-babel` v8.0.0 dropped support for Node.js v14. The minimum supported Node.js version is now v16, v18, or v20+.
  Fix: Upgrade your Node.js environment to version 16, 18, or 20 or newer to use `ember-cli-babel` v8+.
• breaking The `includePolyfill` option was removed in `ember-cli-babel` v8.0.0. Projects relying on this option for automatic polyfill inclusion will need to update their strategy.
  Fix: Remove the `includePolyfill` option. Manually add polyfills using a tool like `ember-auto-import` combined with `core-js` or `@babel/polyfill` for explicit polyfill management.
• breaking `ember-cli-babel` v8.0.0 updated its internal dependency `broccoli-babel-transpiler` to v8, which may introduce breaking changes or require adjustments to advanced configurations.
  Fix: Review `broccoli-babel-transpiler` v8 release notes if you encounter unexpected build issues after upgrading. Most applications should not require direct changes.
• gotcha By default, `ember-cli-babel` ignores `.babelrc` files. All Babel configurations must be specified within the `babel` object in your `ember-cli-build.js` or addon's `index.js`.
  Fix: Migrate any existing `.babelrc` configuration into the `babel` property of your `EmberApp` options in `ember-cli-build.js`.
• gotcha With Babel's evolution, `@babel/plugin-proposal-*` packages have largely been replaced by `@babel/plugin-transform-*` counterparts. While `ember-cli-babel` adapts, directly configured plugins might need updates.
  Fix: If manually specifying Babel plugins, ensure you are using the correct `@babel/plugin-transform-*` packages where applicable, especially for features like class properties, decorators, and private methods.

Install

• npm install ember-cli-babel npm
• yarn add ember-cli-babel yarn
• pnpm add ember-cli-babel pnpm

Imports

• babel (configuration object)
  wrong:

  Directly creating a .babelrc file (it is ignored by default)

  correct:

  new EmberApp(defaults, { babel: { /* preset-env and plugin options */ } })

  This object within `ember-cli-build.js` configures Babel's core behavior, including `babel-preset-env` options and custom plugins.
• ember-cli-babel (configuration object)
  wrong:

  Setting 'ember-cli-babel' specific options directly under the 'babel' key.

  correct:

  new EmberApp(defaults, { 'ember-cli-babel': { /* addon-specific options */ } })

  This object within `ember-cli-build.js` is used for options specific to `ember-cli-babel`'s integration, such as enabling TypeScript transform or disabling debug tooling.
• Custom Babel Plugins
  wrong:

  plugins: ['@babel/plugin-proposal-decorators'] (without require.resolve, which might cause path resolution issues)

  correct:

  plugins: [require.resolve('@babel/plugin-proposal-decorators')]

  When adding custom Babel plugins to the `babel.plugins` array, it is recommended to use `require.resolve` to ensure the plugin's path is correctly found within the build system.

Quickstart

Demonstrates how to configure `ember-cli-babel` within `ember-cli-build.js`, including setting Babel options (like `loose` mode and custom plugins) and `ember-cli-babel` specific options (like enabling TypeScript transpilation or disabling debug tooling).

/* eslint-env node */
'use strict';

const EmberApp = require('ember-cli/lib/broccoli/ember-app');

module.exports = function (defaults) {
  let app = new EmberApp(defaults, {
    // Configure Babel transpilation options
    babel: {
      // Enable "loose" mode for class properties for smaller output and compatibility.
      loose: true,
      // Exclude a specific transform if not needed or handled by other means.
      exclude: [
        'transform-regenerator'
      ],
      // Add custom Babel plugins, using require.resolve for robust path resolution.
      plugins: [
        require.resolve('@babel/plugin-proposal-decorators') // Common in Ember for decorators
      ]
    },

    // Configure ember-cli-babel specific options
    'ember-cli-babel': {
      // Disable debug tooling support for production builds to optimize size.
      disableDebugTooling: EmberApp.env() === 'production',
      // Enable TypeScript transpilation if your project uses TypeScript.
      // Note: This handles syntax transpilation, not type checking.
      enableTypeScriptTransform: true,
      // Specify additional file extensions for Babel to process.
      extensions: ['js', 'ts', 'gjs', 'gts']
    }

    // Other EmberApp configurations go here
  });

  return app.toTree();
};