{"id":16987,"library":"ember-cli-babel","title":"Ember CLI Babel Transpilation","description":"ember-cli-babel is the official Ember CLI addon responsible for integrating Babel into Ember applications and addons. It transpiles modern JavaScript (ESNext) down to a syntax supported by target browsers, leveraging `@babel/preset-env` and respecting the `config/targets.js` file. The current stable version is 8.3.1, with releases occurring as needed to align with Babel updates, Ember CLI changes, and bug fixes. Key differentiators include its deep integration with the Ember CLI build pipeline, automatic polyfill management (though `includePolyfill` was removed in v8), and support for advanced features like static class blocks and TypeScript transpilation. It provides a robust, zero-config-by-default setup while offering extensive customization options through the `ember-cli-build.js` file for both Babel presets/plugins and `ember-cli-babel`'s internal behavior, making it indispensable for modern Ember development.","status":"active","version":"8.3.1","language":"javascript","source_language":"en","source_url":"git://github.com/emberjs/ember-cli-babel","tags":["javascript","babel","ember","ember-addon","ember-cli","transpile","transpiler"],"install":[{"cmd":"npm install ember-cli-babel","lang":"bash","label":"npm"},{"cmd":"yarn add ember-cli-babel","lang":"bash","label":"yarn"},{"cmd":"pnpm add ember-cli-babel","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency required by Babel's ecosystem for core transpilation functionality.","package":"@babel/core","optional":false}],"imports":[{"note":"This object within `ember-cli-build.js` configures Babel's core behavior, including `babel-preset-env` options and custom plugins.","wrong":"Directly creating a .babelrc file (it is ignored by default)","symbol":"babel (configuration object)","correct":"new EmberApp(defaults, { babel: { /* preset-env and plugin options */ } })"},{"note":"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.","wrong":"Setting 'ember-cli-babel' specific options directly under the 'babel' key.","symbol":"ember-cli-babel (configuration object)","correct":"new EmberApp(defaults, { 'ember-cli-babel': { /* addon-specific options */ } })"},{"note":"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.","wrong":"plugins: ['@babel/plugin-proposal-decorators'] (without require.resolve, which might cause path resolution issues)","symbol":"Custom Babel Plugins","correct":"plugins: [require.resolve('@babel/plugin-proposal-decorators')]"}],"quickstart":{"code":"/* eslint-env node */\n'use strict';\n\nconst EmberApp = require('ember-cli/lib/broccoli/ember-app');\n\nmodule.exports = function (defaults) {\n  let app = new EmberApp(defaults, {\n    // Configure Babel transpilation options\n    babel: {\n      // Enable \"loose\" mode for class properties for smaller output and compatibility.\n      loose: true,\n      // Exclude a specific transform if not needed or handled by other means.\n      exclude: [\n        'transform-regenerator'\n      ],\n      // Add custom Babel plugins, using require.resolve for robust path resolution.\n      plugins: [\n        require.resolve('@babel/plugin-proposal-decorators') // Common in Ember for decorators\n      ]\n    },\n\n    // Configure ember-cli-babel specific options\n    'ember-cli-babel': {\n      // Disable debug tooling support for production builds to optimize size.\n      disableDebugTooling: EmberApp.env() === 'production',\n      // Enable TypeScript transpilation if your project uses TypeScript.\n      // Note: This handles syntax transpilation, not type checking.\n      enableTypeScriptTransform: true,\n      // Specify additional file extensions for Babel to process.\n      extensions: ['js', 'ts', 'gjs', 'gts']\n    }\n\n    // Other EmberApp configurations go here\n  });\n\n  return app.toTree();\n};\n","lang":"typescript","description":"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)."},"warnings":[{"fix":"Upgrade your Node.js environment to version 16, 18, or 20 or newer to use `ember-cli-babel` v8+.","message":"`ember-cli-babel` v8.0.0 dropped support for Node.js v14. The minimum supported Node.js version is now v16, v18, or v20+.","severity":"breaking","affected_versions":">=8.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=8.0.0"},{"fix":"Review `broccoli-babel-transpiler` v8 release notes if you encounter unexpected build issues after upgrading. Most applications should not require direct changes.","message":"`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.","severity":"breaking","affected_versions":">=8.0.0"},{"fix":"Migrate any existing `.babelrc` configuration into the `babel` property of your `EmberApp` options in `ember-cli-build.js`.","message":"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`.","severity":"gotcha","affected_versions":">=7.x"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=8.3.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Upgrade your Node.js environment to a supported version (e.g., `nvm install 18` and `nvm use 18`).","cause":"Using an unsupported Node.js version with `ember-cli-babel` v8 or newer.","error":"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."},{"fix":"Remove your `.babelrc` file and transfer all Babel configurations to the `babel` object within your `new EmberApp()` constructor in `ember-cli-build.js`.","cause":"Attempting to configure Babel using a `.babelrc` file instead of `ember-cli-build.js`.","error":"Error: .babelrc files are ignored by ember-cli-babel. Please configure Babel options in ember-cli-build.js instead."},{"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.","cause":"The `transform-regenerator` plugin was explicitly excluded from Babel, and no global polyfill for generator functions is being provided.","error":"ReferenceError: regeneratorRuntime is not defined"}],"ecosystem":"npm","meta_description":null}